feat: pipe separator for inline workflows (v2.4.1)

- Pipe | is now the primary separator: surf do 'go "url" | click e5 | snap'
- Much cleaner than escaped newlines
- Newlines still supported for files and heredocs

Author: nicobailon

CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog
 
+## [2.4.1] - 2026-01-22
+
+### Changed
+- **Workflow syntax** - Pipe separator `|` is now the primary way to chain commands inline:
+  `surf do 'go "https://example.com" | click e5 | screenshot'`
+  Newlines still supported for file-based workflows and heredocs.
+
 ## [2.4.0] - 2026-01-22
 
 ### Added
 - **Workflow execution** - New `surf do` command to execute multi-step browser workflows as a single operation. Reduces token overhead and improves reliability for common automation sequences.
-  - Inline workflows: `surf do 'go "https://example.com"\nclick e5\nscreenshot'`
+  - Inline workflows: `surf do 'go "url" | click e5 | screenshot'`
   - File-based workflows: `surf do --file workflow.json`
   - Dry run validation: `surf do '...' --dry-run`
   - Smart auto-waits after navigation, clicks, and form submissions

README.md

@@ -378,18 +378,17 @@ Auto-cleanup: 24 hours TTL, 200MB max.
 Execute multi-step browser automation as a single command:
 
 ```bash
-# Inline workflow (newline-separated commands)
-surf do 'go "https://example.com/login"
-type "user@example.com" --selector "input[name=email]"
-type "password123" --selector "input[name=password]"
-click --selector "button[type=submit]"
-screenshot --output /tmp/after-login.png'
+# Inline workflow (pipe-separated)
+surf do 'go "https://example.com" | click e5 | screenshot'
 
-# From JSON file (same format as --script)
-surf do --file login-workflow.json
+# Multi-step login flow
+surf do 'go "https://example.com/login" | type "user@example.com" --selector "#email" | type "pass" --selector "#password" | click --selector "button[type=submit]"'
+
+# From JSON file
+surf do --file workflow.json
 
 # Validate without executing
-surf do 'go "url"\nclick e5\nscreenshot' --dry-run
+surf do 'go "url" | click e5 | screenshot' --dry-run
 ```
 
 **Why workflows?** Instead of 6-8 separate CLI calls with LLM orchestration between each step, a workflow executes deterministically with smart auto-waits. Faster, cheaper, and more reliable.

native/cli.cjs

@@ -817,9 +817,9 @@ const TOOLS = {
           "dry-run": "Parse and validate without executing"
         },
         examples: [
-          { cmd: 'do \'go "https://example.com"\\nclick e5\\nscreenshot\'', desc: "Inline workflow" },
+          { cmd: 'do \'go "https://example.com" | click e5 | screenshot\'', desc: "Inline workflow" },
           { cmd: 'do -f login.json', desc: "From JSON file" },
-          { cmd: 'do \'go "url"\\nclick e5\' --dry-run', desc: "Validate without running" },
+          { cmd: 'do \'go "url" | click e5\' --dry-run', desc: "Validate without running" },
         ]
       },
     }

native/do-parser.cjs

@@ -206,17 +206,23 @@ function parseCommandLine(line) {
 }
 
 /**
- * Parse a multi-line workflow string into step array
- * @param {string} input - Multi-line workflow string
+ * Parse a workflow string into step array
+ * Supports pipe-separated (inline) or newline-separated (file) commands
+ * @param {string} input - Workflow string
  * @returns {Array<{ cmd: string, args: object }>}
  */
 function parseDoCommands(input) {
-  // Replace literal \n (backslash + n) with actual newlines
-  // This handles bash single-quoted strings like 'go "url"\nclick e5'
-  const normalized = input.replace(/\\n/g, '\n');
+  // Determine separator: use pipe if present, otherwise newlines
+  // Pipe is preferred for inline: 'go "url" | click e5 | screenshot'
+  // Newlines for files or heredocs
+  const hasPipe = input.includes('|');
+  const separator = hasPipe ? '|' : '\n';
+  
+  // Also handle literal \n for backwards compatibility
+  const normalized = hasPipe ? input : input.replace(/\\n/g, '\n');
 
   return normalized
-    .split('\n')
+    .split(separator)
     .map(line => line.trim())
     .filter(line => line && !line.startsWith('#'))
     .map(line => parseCommandLine(line))

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",

package.json

@@ -307,18 +307,17 @@ surf smoke --urls "..." --screenshot /tmp/smoke
 Execute multi-step browser automation as a single command with smart auto-waits:
 
 ```bash
-# Inline workflow (newline-separated commands)
-surf do 'go "https://example.com/login"
-type "user@example.com" --selector "input[name=email]"
-type "password123" --selector "input[name=password]"
-click --selector "button[type=submit]"
-screenshot --output /tmp/after-login.png'
+# Inline workflow (pipe-separated)
+surf do 'go "https://example.com" | click e5 | screenshot'
+
+# Multi-step login flow
+surf do 'go "https://example.com/login" | type "user@example.com" --selector "#email" | type "pass" --selector "#password" | click --selector "button[type=submit]"'
 
 # From JSON file
-surf do --file login-workflow.json
+surf do --file workflow.json
 
 # Validate without executing
-surf do 'go "url"\nclick e5' --dry-run
+surf do 'go "url" | click e5' --dry-run
 ```
 
 **Why use `do`?** Instead of 6-8 separate CLI calls with LLM orchestration between each, a workflow executes deterministically. Faster, cheaper, and more reliable.

skills/surf/SKILL.md

@@ -12,6 +12,17 @@ describe("parseDoCommands", () => {
     expect(steps[0].args).toEqual({});
   });
 
+  it("parses pipe-separated commands", () => {
+    const input = 'go "https://example.com" | click e5 | screenshot';
+    const steps = parser.parseDoCommands(input);
+    expect(steps).toHaveLength(3);
+    expect(steps[0].cmd).toBe("navigate");
+    expect(steps[0].args.url).toBe("https://example.com");
+    expect(steps[1].cmd).toBe("click");
+    expect(steps[1].args.ref).toBe("e5");
+    expect(steps[2].cmd).toBe("screenshot");
+  });
+
   it("parses newline-separated commands", () => {
     const input = 'go "https://example.com"\nclick e5';
     const steps = parser.parseDoCommands(input);