@picahq/cli 1.11.1 → 1.12.1

package/README.md

@@ -76,7 +76,7 @@ one flow validate welcome-customer
 one flow execute welcome-customer -i email=jane@example.com
 ```
 
-Flows are stored as JSON at `.one/flows/<key>.flow.json` and support conditions, loops, parallel steps, transforms, and more. Run `one guide flows` for the full reference.
+Workflows are stored as JSON at `.one/flows/<key>.flow.json` and support conditions, loops, parallel steps, transforms, and more. Run `one guide flows` for the full reference.
 
 ## How it works
 
@@ -201,6 +201,7 @@ one actions execute stripe <actionId> <connectionKey> \
 | `--headers <json>` | Additional request headers |
 | `--form-data` | Send as multipart/form-data |
 | `--form-url-encoded` | Send as application/x-www-form-urlencoded |
+| `--dry-run` | Show the request without executing it |
 
 ### `one guide [topic]`
 
@@ -222,7 +223,7 @@ In agent mode (`--agent`), the JSON response includes the guide content and an `
 
 ### `one flow create [key]`
 
-Create a flow from a JSON definition. Flows are saved to `.one/flows/<key>.flow.json`.
+Create a workflow from a JSON definition. Workflows are saved to `.one/flows/<key>.flow.json`.
 
 ```bash
 # From a --definition flag
@@ -237,12 +238,12 @@ one flow create my-flow --definition '...' -o ./custom/path.json
 
 | Option | What it does |
 |--------|-------------|
-| `--definition <json>` | Flow definition as a JSON string |
+| `--definition <json>` | Workflow definition as a JSON string |
 | `-o, --output <path>` | Custom output path (default: `.one/flows/<key>.flow.json`) |
 
 ### `one flow execute <key>`
 
-Execute a flow by key or file path. Pass inputs with repeatable `-i` flags.
+Execute a workflow by key or file path. Pass inputs with repeatable `-i` flags.
 
 ```bash
 # Execute with inputs
@@ -256,7 +257,7 @@ one flow execute welcome-customer --dry-run -i customerEmail=jane@example.com
 one flow execute welcome-customer -v -i customerEmail=jane@example.com
 ```
 
-Connection inputs with a `connection` field in the flow definition are auto-resolved when the user has exactly one connection for that platform.
+Connection inputs with a `connection` field in the workflow definition are auto-resolved when the user has exactly one connection for that platform.
 
 Press Ctrl+C during execution to pause — the run can be resumed later with `one flow resume <runId>`.
 
@@ -268,7 +269,7 @@ Press Ctrl+C during execution to pause — the run can be resumed later with `on
 
 ### `one flow list`
 
-List all flows saved in `.one/flows/`.
+List all workflows saved in `.one/flows/`.
 
 ```bash
 one flow list
@@ -276,7 +277,7 @@ one flow list
 
 ### `one flow validate <key>`
 
-Validate a flow JSON file against the schema.
+Validate a workflow JSON file against the schema.
 
 ```bash
 one flow validate welcome-customer
@@ -284,7 +285,7 @@ one flow validate welcome-customer
 
 ### `one flow resume <runId>`
 
-Resume a paused or failed flow run from where it left off.
+Resume a paused or failed workflow run from where it left off.
 
 ```bash
 one flow resume abc123
@@ -292,11 +293,11 @@ one flow resume abc123
 
 ### `one flow runs [flowKey]`
 
-List flow runs, optionally filtered by flow key.
+List workflow runs, optionally filtered by workflow key.
 
 ```bash
 one flow runs                    # all runs
-one flow runs welcome-customer   # runs for a specific flow
+one flow runs welcome-customer   # runs for a specific workflow
 ```
 
 ### `one config`
@@ -329,7 +330,7 @@ one actions execute         → Do it.
 
 This is the same workflow whether you're sending emails, creating CRM contacts, processing payments, managing inventory, or posting to Slack. One pattern, any platform.
 
-For multi-step workflows that chain actions across platforms, use **flows**:
+For multi-step workflows that chain actions across platforms:
 
 ```
 one actions knowledge       → Learn each action's schema
@@ -338,7 +339,7 @@ one flow validate           → Check it
 one flow execute            → Run it
 ```
 
-Flows support conditions, loops, parallel execution, transforms, code steps, and file I/O. Run `one guide flows` for the full schema reference and examples.
+Workflows support conditions, loops, parallel execution, transforms, code steps, and file I/O. Run `one guide flows` for the full schema reference and examples.
 
 ## For AI agents
 

package/dist/index.js

@@ -483,6 +483,12 @@ var OneApi = class {
       ) : void 0,
       data: requestData
     };
+    if (args.dryRun) {
+      return {
+        requestConfig: sanitizedConfig,
+        responseData: null
+      };
+    }
     const response = await fetch(fullUrl, fetchOpts);
     if (!response.ok) {
       const text4 = await response.text();
@@ -593,7 +599,7 @@ QUERY PARAMS: {{QUERY_PARAMS}}`;
 import open from "open";
 var ONE_APP_URL = "https://app.withone.ai";
 function getConnectionUrl(platform) {
-  return `${ONE_APP_URL}/connections?#open=${platform}`;
+  return `${ONE_APP_URL}/?#open=${platform}`;
 }
 function getApiKeyUrl() {
   return `${ONE_APP_URL}/settings/api-keys`;
@@ -1841,7 +1847,7 @@ async function actionsExecuteCommand(platform, actionId, connectionKey, options)
     const queryParams = options.queryParams ? parseJsonArg(options.queryParams, "--query-params") : void 0;
     const headers = options.headers ? parseJsonArg(options.headers, "--headers") : void 0;
     const execSpinner = createSpinner();
-    execSpinner.start("Executing action...");
+    execSpinner.start(options.dryRun ? "Building request..." : "Executing action...");
     const result = await api.executePassthroughRequest(
       {
         platform,
@@ -1852,18 +1858,22 @@ async function actionsExecuteCommand(platform, actionId, connectionKey, options)
         queryParams,
         headers,
         isFormData: options.formData,
-        isFormUrlEncoded: options.formUrlEncoded
+        isFormUrlEncoded: options.formUrlEncoded,
+        dryRun: options.dryRun
       },
       actionDetails
     );
-    execSpinner.stop("Action executed successfully");
+    execSpinner.stop(options.dryRun ? "Dry run \u2014 request not sent" : "Action executed successfully");
     if (isAgentMode()) {
       json({
+        dryRun: options.dryRun || false,
         request: {
           method: result.requestConfig.method,
-          url: result.requestConfig.url
+          url: result.requestConfig.url,
+          headers: options.dryRun ? result.requestConfig.headers : void 0,
+          data: options.dryRun ? result.requestConfig.data : void 0
         },
-        response: result.responseData
+        response: options.dryRun ? void 0 : result.responseData
       });
       return;
     }
@@ -1874,9 +1884,19 @@ async function actionsExecuteCommand(platform, actionId, connectionKey, options)
         `  ${result.requestConfig.method} ${result.requestConfig.url}`
       )
     );
-    console.log();
-    console.log(pc6.bold("Response:"));
-    console.log(JSON.stringify(result.responseData, null, 2));
+    if (options.dryRun) {
+      if (result.requestConfig.data) {
+        console.log();
+        console.log(pc6.dim("Body:"));
+        console.log(pc6.dim(JSON.stringify(result.requestConfig.data, null, 2)));
+      }
+      console.log();
+      note2("Dry run \u2014 request was not sent", "Dry Run");
+    } else {
+      console.log();
+      console.log(pc6.bold("Response:"));
+      console.log(JSON.stringify(result.responseData, null, 2));
+    }
   } catch (error2) {
     spinner5.stop("Execution failed");
     error(
@@ -2355,12 +2375,42 @@ async function executeLoopStep(step, context, api, permissions, allowedActionIds
     throw new Error(`Loop "over" must resolve to an array, got ${typeof items}`);
   }
   const maxIterations = loop.maxIterations || 1e3;
-  const results = [];
+  const bounded = items.slice(0, maxIterations);
   const savedLoop = { ...context.loop };
-  for (let i = 0; i < Math.min(items.length, maxIterations); i++) {
+  if (loop.maxConcurrency && loop.maxConcurrency > 1) {
+    const results2 = new Array(bounded.length);
+    for (let batchStart = 0; batchStart < bounded.length; batchStart += loop.maxConcurrency) {
+      const batch = bounded.slice(batchStart, batchStart + loop.maxConcurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (item, batchIdx) => {
+          const i = batchStart + batchIdx;
+          const iterContext = {
+            ...context,
+            loop: {
+              [loop.as]: item,
+              item,
+              i,
+              ...loop.indexAs ? { [loop.indexAs]: i } : {}
+            },
+            steps: { ...context.steps }
+          };
+          await executeSteps(loop.steps, iterContext, api, permissions, allowedActionIds, options);
+          Object.assign(context.steps, iterContext.steps);
+          return iterContext.loop[loop.as];
+        })
+      );
+      for (let j = 0; j < batchResults.length; j++) {
+        results2[batchStart + j] = batchResults[j];
+      }
+    }
+    context.loop = savedLoop;
+    return { status: "success", output: results2, response: results2 };
+  }
+  const results = [];
+  for (let i = 0; i < bounded.length; i++) {
     context.loop = {
-      [loop.as]: items[i],
-      item: items[i],
+      [loop.as]: bounded[i],
+      item: bounded[i],
       i
     };
     if (loop.indexAs) {
@@ -2892,7 +2942,7 @@ async function autoResolveConnectionInputs(flow2, inputs, api) {
   return resolved;
 }
 async function flowCreateCommand(key, options) {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   let flow2;
   if (options.definition) {
     try {
@@ -2912,7 +2962,7 @@ async function flowCreateCommand(key, options) {
       error("Invalid JSON from stdin");
     }
   } else {
-    error("Interactive flow creation not yet supported. Use --definition <json> or pipe JSON via stdin.");
+    error("Interactive workflow creation not yet supported. Use --definition <json> or pipe JSON via stdin.");
   }
   if (key) {
     flow2.key = key;
@@ -2931,25 +2981,25 @@ ${errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
     json({ created: true, key: flow2.key, path: flowPath });
     return;
   }
-  note2(`Flow "${flow2.name}" saved to ${flowPath}`, "Created");
+  note2(`Workflow "${flow2.name}" saved to ${flowPath}`, "Created");
   outro2(`Validate: ${pc7.cyan(`one flow validate ${flow2.key}`)}
 Execute:  ${pc7.cyan(`one flow execute ${flow2.key}`)}`);
 }
 async function flowExecuteCommand(keyOrPath, options) {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   const { apiKey, permissions, actionIds } = getConfig2();
   const api = new OneApi(apiKey);
   const spinner5 = createSpinner();
-  spinner5.start(`Loading flow "${keyOrPath}"...`);
+  spinner5.start(`Loading workflow "${keyOrPath}"...`);
   let flow2;
   try {
     flow2 = loadFlow(keyOrPath);
   } catch (err) {
-    spinner5.stop("Flow not found");
+    spinner5.stop("Workflow not found");
     error(err instanceof Error ? err.message : String(err));
     return;
   }
-  spinner5.stop(`Flow: ${flow2.name} (${flow2.steps.length} steps)`);
+  spinner5.stop(`Workflow: ${flow2.name} (${flow2.steps.length} steps)`);
   const inputs = parseInputs(options.input || []);
   const resolvedInputs = await autoResolveConnectionInputs(flow2, inputs, api);
   const runner = new FlowRunner(flow2, resolvedInputs);
@@ -2980,7 +3030,7 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
   };
   const execSpinner = createSpinner();
   if (!options.verbose && !isAgentMode()) {
-    execSpinner.start("Executing flow...");
+    execSpinner.start("Executing workflow...");
   }
   try {
     const context = await runner.execute(flow2, api, permissions, actionIds, {
@@ -2990,11 +3040,11 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
     });
     process.off("SIGINT", sigintHandler);
     if (!options.verbose && !isAgentMode()) {
-      execSpinner.stop("Flow completed");
+      execSpinner.stop("Workflow completed");
     }
     if (isAgentMode()) {
       json({
-        event: "flow:result",
+        event: "workflow:result",
         runId,
         logFile: logPath,
         status: "success",
@@ -3016,12 +3066,12 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
   } catch (error2) {
     process.off("SIGINT", sigintHandler);
     if (!options.verbose && !isAgentMode()) {
-      execSpinner.stop("Flow failed");
+      execSpinner.stop("Workflow failed");
     }
     const errorMsg = error2 instanceof Error ? error2.message : String(error2);
     if (isAgentMode()) {
       json({
-        event: "flow:result",
+        event: "workflow:result",
         runId,
         logFile: logPath,
         status: "failed",
@@ -3031,18 +3081,18 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
     }
     console.log(`  ${pc7.dim(`Run ID: ${runId}`)}`);
     console.log(`  ${pc7.dim(`Log: ${logPath}`)}`);
-    error(`Flow failed: ${errorMsg}`);
+    error(`Workflow failed: ${errorMsg}`);
   }
 }
 async function flowListCommand() {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   const flows = listFlows();
   if (isAgentMode()) {
-    json({ flows });
+    json({ workflows: flows });
     return;
   }
   if (flows.length === 0) {
-    note2("No flows found in .one/flows/\n\nCreate one with: one flow create", "Flows");
+    note2("No workflows found in .one/flows/\n\nCreate one with: one flow create", "Workflows");
     return;
   }
   console.log();
@@ -3065,7 +3115,7 @@ async function flowListCommand() {
   console.log();
 }
 async function flowValidateCommand(keyOrPath) {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   const spinner5 = createSpinner();
   spinner5.start(`Validating "${keyOrPath}"...`);
   let flowData;
@@ -3075,7 +3125,7 @@ async function flowValidateCommand(keyOrPath) {
     flowData = JSON.parse(content);
   } catch (err) {
     spinner5.stop("Validation failed");
-    error(`Could not read flow: ${err instanceof Error ? err.message : String(err)}`);
+    error(`Could not read workflow: ${err instanceof Error ? err.message : String(err)}`);
   }
   const errors = validateFlow(flowData);
   if (errors.length > 0) {
@@ -3091,15 +3141,15 @@ async function flowValidateCommand(keyOrPath) {
     console.log();
     error(`${errors.length} validation error(s) found`);
   }
-  spinner5.stop("Flow is valid");
+  spinner5.stop("Workflow is valid");
   if (isAgentMode()) {
     json({ valid: true, key: flowData.key });
     return;
   }
-  note2(`Flow "${flowData.key}" passed all validation checks`, "Valid");
+  note2(`Workflow "${flowData.key}" passed all validation checks`, "Valid");
 }
 async function flowResumeCommand(runId) {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   const state = FlowRunner.loadRunState(runId);
   if (!state) {
     error(`Run "${runId}" not found`);
@@ -3113,7 +3163,7 @@ async function flowResumeCommand(runId) {
   try {
     flow2 = loadFlow(state.flowKey);
   } catch (err) {
-    error(`Could not load flow "${state.flowKey}": ${err instanceof Error ? err.message : String(err)}`);
+    error(`Could not load workflow "${state.flowKey}": ${err instanceof Error ? err.message : String(err)}`);
     return;
   }
   const runner = FlowRunner.fromRunState(state);
@@ -3126,10 +3176,10 @@ async function flowResumeCommand(runId) {
   spinner5.start(`Resuming run ${runId} (${state.completedSteps.length} steps already completed)...`);
   try {
     const context = await runner.resume(flow2, api, permissions, actionIds, { onEvent });
-    spinner5.stop("Flow completed");
+    spinner5.stop("Workflow completed");
     if (isAgentMode()) {
       json({
-        event: "flow:result",
+        event: "workflow:result",
         runId,
         logFile: runner.getLogPath(),
         status: "success",
@@ -3143,14 +3193,14 @@ async function flowResumeCommand(runId) {
     spinner5.stop("Resume failed");
     const errorMsg = error2 instanceof Error ? error2.message : String(error2);
     if (isAgentMode()) {
-      json({ event: "flow:result", runId, status: "failed", error: errorMsg });
+      json({ event: "workflow:result", runId, status: "failed", error: errorMsg });
       process.exit(1);
     }
     error(`Resume failed: ${errorMsg}`);
   }
 }
 async function flowRunsCommand(flowKey) {
-  intro2(pc7.bgCyan(pc7.black(" One Flow ")));
+  intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   const runs = FlowRunner.listRuns(flowKey);
   if (isAgentMode()) {
     json({
@@ -3167,14 +3217,14 @@ async function flowRunsCommand(flowKey) {
     return;
   }
   if (runs.length === 0) {
-    note2(flowKey ? `No runs found for flow "${flowKey}"` : "No flow runs found", "Runs");
+    note2(flowKey ? `No runs found for workflow "${flowKey}"` : "No workflow runs found", "Runs");
     return;
   }
   console.log();
   printTable(
     [
       { key: "runId", label: "Run ID" },
-      { key: "flowKey", label: "Flow" },
+      { key: "flowKey", label: "Workflow" },
       { key: "status", label: "Status" },
       { key: "startedAt", label: "Started" },
       { key: "steps", label: "Steps Done" }
@@ -3232,7 +3282,7 @@ This guide has three sections you can request individually:
 
 - **overview** \u2014 This section. Setup, flag usage, and discovery workflow.
 - **actions** \u2014 Full workflow for searching, reading docs, and executing platform actions.
-- **flows** \u2014 Building and executing multi-step API workflows (JSON-based).
+- **workflows** \u2014 Building and executing multi-step API workflows (JSON-based).
 
 ## Discovery Workflow
 
@@ -3241,9 +3291,9 @@ This guide has three sections you can request individually:
 3. \`one --agent actions knowledge <platform> <actionId>\` \u2014 Read full docs (REQUIRED before execute)
 4. \`one --agent actions execute <platform> <actionId> <connectionKey>\` \u2014 Execute the action
 
-For multi-step workflows, use flows:
+For multi-step workflows:
 1. Discover actions with the workflow above
-2. Build a flow JSON definition
+2. Build a workflow JSON definition
 3. \`one --agent flow create <key> --definition '<json>'\`
 4. \`one --agent flow execute <key> -i param=value\`
 
@@ -3343,6 +3393,7 @@ Options:
 - \`--headers <json>\` \u2014 Additional headers as JSON
 - \`--form-data\` \u2014 Send as multipart/form-data instead of JSON
 - \`--form-url-encoded\` \u2014 Send as application/x-www-form-urlencoded
+- \`--dry-run\` \u2014 Show the request that would be sent without executing it
 
 Examples:
 \`\`\`bash
@@ -3383,20 +3434,20 @@ Parse the output as JSON. If the \`error\` key is present, the command failed \u
 - If search returns no results, try broader queries (e.g., \`"list"\` instead of \`"list active premium customers"\`)
 - The execute command respects access control settings configured via \`one config\` \u2014 if execution is blocked, the user may need to adjust their permissions
 `;
-var GUIDE_FLOWS = `# One Flow \u2014 Multi-Step API Workflows
+var GUIDE_FLOWS = `# One Workflows \u2014 Multi-Step API Workflows
 
-You have access to the One CLI's flow engine, which lets you create and execute multi-step API workflows as JSON files. Flows chain actions across platforms \u2014 e.g., look up a Stripe customer, then send them a welcome email via Gmail.
+You have access to the One CLI's workflow engine, which lets you create and execute multi-step API workflows as JSON files. Workflows chain actions across platforms \u2014 e.g., look up a Stripe customer, then send them a welcome email via Gmail.
 
 ## 1. Overview
 
-- Flows are JSON files stored at \`.one/flows/<key>.flow.json\`
+- Workflows are JSON files stored at \`.one/flows/<key>.flow.json\`
 - All dynamic values (including connection keys) are declared as **inputs**
-- Each flow has a unique **key** used to reference and execute it
+- Each workflow has a unique **key** used to reference and execute it
 - Executed via \`one --agent flow execute <key> -i name=value\`
 
-## 2. Building a Flow \u2014 Step-by-Step Process
+## 2. Building a Workflow \u2014 Step-by-Step Process
 
-**You MUST follow this process to build a correct flow:**
+**You MUST follow this process to build a correct workflow:**
 
 ### Step 1: Discover connections
 
@@ -3412,20 +3463,20 @@ Find out which platforms are connected and get their connection keys.
 # Find the action ID
 one --agent actions search <platform> "<query>" -t execute
 
-# Read the full docs \u2014 REQUIRED before adding to a flow
+# Read the full docs \u2014 REQUIRED before adding to a workflow
 one --agent actions knowledge <platform> <actionId>
 \`\`\`
 
-**CRITICAL:** You MUST call \`one actions knowledge\` for every action you include in the flow. The knowledge output tells you the exact request body structure, required fields, path variables, and query parameters. Without this, your flow JSON will have incorrect data shapes.
+**CRITICAL:** You MUST call \`one actions knowledge\` for every action you include in the workflow. The knowledge output tells you the exact request body structure, required fields, path variables, and query parameters. Without this, your workflow JSON will have incorrect data shapes.
 
-### Step 3: Construct the flow JSON
+### Step 3: Construct the workflow JSON
 
-Using the knowledge gathered, build the flow JSON with:
+Using the knowledge gathered, build the workflow JSON with:
 - All inputs declared (connection keys + user parameters)
 - Each step with the correct actionId, platform, and data structure (from knowledge)
 - Data wired between steps using \`$.input.*\` and \`$.steps.*\` selectors
 
-### Step 4: Write the flow file
+### Step 4: Write the workflow file
 
 \`\`\`bash
 one --agent flow create <key> --definition '<json>'
@@ -3445,7 +3496,7 @@ one --agent flow validate <key>
 one --agent flow execute <key> -i connectionKey=xxx -i param=value
 \`\`\`
 
-## 3. Flow JSON Schema Reference
+## 3. Workflow JSON Schema Reference
 
 \`\`\`json
 {
@@ -3501,7 +3552,7 @@ one --agent flow execute <key> -i connectionKey=xxx -i param=value
 | \`description\` | string | Human-readable description |
 | \`connection\` | object | Connection metadata: \`{ "platform": "gmail" }\` \u2014 enables auto-resolution |
 
-**Connection inputs** have a \`connection\` field. If the user has exactly one connection for that platform, the engine auto-resolves it.
+**Connection inputs** have a \`connection\` field. If the user has exactly one connection for that platform, the workflow engine auto-resolves it.
 
 ## 4. Selector Syntax Reference
 
@@ -3605,6 +3656,7 @@ The \`source\` field contains a JS function body. The flow context is available
     "as": "order",
     "indexAs": "i",
     "maxIterations": 1000,
+    "maxConcurrency": 5,
     "steps": [
       {
         "id": "createInvoice",
@@ -3622,6 +3674,8 @@ The \`source\` field contains a JS function body. The flow context is available
 }
 \`\`\`
 
+- \`maxConcurrency\` (optional): When set > 1, loop iterations run in parallel batches of that size. Default is sequential (1).
+
 ### \`parallel\` \u2014 Run steps concurrently
 
 \`\`\`json
@@ -3704,20 +3758,20 @@ Skip a step based on previous results:
 }
 \`\`\`
 
-## 7. Updating Existing Flows
+## 7. Updating Existing Workflows
 
-To modify an existing flow:
+To modify an existing workflow:
 
-1. Read the flow JSON file at \`.one/flows/<key>.flow.json\`
+1. Read the workflow JSON file at \`.one/flows/<key>.flow.json\`
 2. Understand its current structure
 3. Use \`one --agent actions knowledge <platform> <actionId>\` for any new actions
 4. Modify the JSON (add/remove/update steps, change data mappings, add inputs)
-5. Write back the updated flow file
+5. Write back the updated workflow file
 6. Validate: \`one --agent flow validate <key>\`
 
 ## 8. Complete Examples
 
-### Example 1: Simple 2-step \u2014 Search Stripe customer, send Gmail email
+### Example 1: Simple 2-step workflow \u2014 Search Stripe customer, send Gmail email
 
 \`\`\`json
 {
@@ -3853,7 +3907,7 @@ To modify an existing flow:
 }
 \`\`\`
 
-### Example 3: Loop \u2014 Iterate over Shopify orders, create invoices
+### Example 3: Loop workflow \u2014 Iterate over Shopify orders, create invoices
 
 \`\`\`json
 {
@@ -3931,16 +3985,16 @@ To modify an existing flow:
 ## CLI Commands Reference
 
 \`\`\`bash
-# Create a flow
+# Create a workflow
 one --agent flow create <key> --definition '<json>'
 
-# List all flows
+# List all workflows
 one --agent flow list
 
-# Validate a flow
+# Validate a workflow
 one --agent flow validate <key>
 
-# Execute a flow
+# Execute a workflow
 one --agent flow execute <key> -i connectionKey=value -i param=value
 
 # Execute with dry run (validate only)
@@ -3949,7 +4003,7 @@ one --agent flow execute <key> --dry-run -i connectionKey=value
 # Execute with verbose output
 one --agent flow execute <key> -v -i connectionKey=value
 
-# List flow runs
+# List workflow runs
 one --agent flow runs [flowKey]
 
 # Resume a paused/failed run
@@ -3959,16 +4013,16 @@ one --agent flow resume <runId>
 ## Important Notes
 
 - **Always use \`--agent\` flag** for structured JSON output
-- **Always call \`one actions knowledge\`** before adding an action step to a flow
+- **Always call \`one actions knowledge\`** before adding an action step to a workflow
 - Platform names are **kebab-case** (e.g., \`hub-spot\`, not \`HubSpot\`)
-- Connection keys are **inputs**, not hardcoded \u2014 makes flows portable and shareable
+- Connection keys are **inputs**, not hardcoded \u2014 makes workflows portable and shareable
 - Use \`$.input.*\` for input values, \`$.steps.*\` for step results
 - Action IDs in examples (like \`STRIPE_SEARCH_CUSTOMERS_ACTION_ID\`) are placeholders \u2014 always use \`one actions search\` to find the real IDs
 `;
 var TOPICS = [
   { topic: "overview", description: "Setup, --agent flag, discovery workflow" },
   { topic: "actions", description: "Search, read docs, and execute platform actions" },
-  { topic: "flows", description: "Build and execute multi-step API workflows" },
+  { topic: "flows", description: "Build and execute multi-step workflows" },
   { topic: "all", description: "Complete guide (all topics combined)" }
 ];
 function getGuideContent(topic) {
@@ -3978,7 +4032,7 @@ function getGuideContent(topic) {
     case "actions":
       return { title: "One CLI \u2014 Agent Guide: Actions", content: GUIDE_ACTIONS };
     case "flows":
-      return { title: "One CLI \u2014 Agent Guide: Flows", content: GUIDE_FLOWS };
+      return { title: "One CLI \u2014 Agent Guide: Workflows", content: GUIDE_FLOWS };
     case "all":
       return {
         title: "One CLI \u2014 Agent Guide: Complete",
@@ -4032,12 +4086,12 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
     4. one actions execute <p> <id> <key> Execute the action
 
   Guide:
-    one guide [topic]                     Full CLI guide (topics: overview, actions, flows, all)
+    one guide [topic]                     Full CLI guide (topics: overview, actions, workflows, all)
 
-  Flows (multi-step workflows):
-    one flow list                         List saved flows
-    one flow create [key]                 Create a flow from JSON
-    one flow execute <key>                Execute a flow
+  Workflows (multi-step):
+    one flow list                         List saved workflows
+    one flow create [key]                 Create a workflow from JSON
+    one flow execute <key>                Execute a workflow
     one flow validate <key>               Validate a flow
 
   Example \u2014 send an email through Gmail:
@@ -4084,33 +4138,34 @@ actions.command("search <platform> <query>").description('Search for actions on
 actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").action(async (platform, actionId) => {
   await actionsKnowledgeCommand(platform, actionId);
 });
-actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "one list", actionId from "actions search"').option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").action(async (platform, actionId, connectionKey, options) => {
+actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "one list", actionId from "actions search"').option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").option("--dry-run", "Show request that would be sent without executing").action(async (platform, actionId, connectionKey, options) => {
   await actionsExecuteCommand(platform, actionId, connectionKey, {
     data: options.data,
     pathVars: options.pathVars,
     queryParams: options.queryParams,
     headers: options.headers,
     formData: options.formData,
-    formUrlEncoded: options.formUrlEncoded
+    formUrlEncoded: options.formUrlEncoded,
+    dryRun: options.dryRun
   });
 });
-var flow = program.command("flow").alias("f").description("Create, execute, and manage multi-step API workflows");
-flow.command("create [key]").description("Create a new flow from JSON definition").option("--definition <json>", "Flow definition as JSON string").option("-o, --output <path>", "Custom output path (default .one/flows/<key>.flow.json)").action(async (key, options) => {
+var flow = program.command("flow").alias("f").description("Create, execute, and manage multi-step workflows");
+flow.command("create [key]").description("Create a new workflow from JSON definition").option("--definition <json>", "Workflow definition as JSON string").option("-o, --output <path>", "Custom output path (default .one/flows/<key>.flow.json)").action(async (key, options) => {
   await flowCreateCommand(key, options);
 });
-flow.command("execute <keyOrPath>").alias("x").description("Execute a flow by key or file path").option("-i, --input <name=value>", "Input parameter (repeatable)", collect, []).option("--dry-run", "Validate and show execution plan without running").option("-v, --verbose", "Show full request/response for each step").action(async (keyOrPath, options) => {
+flow.command("execute <keyOrPath>").alias("x").description("Execute a workflow by key or file path").option("-i, --input <name=value>", "Input parameter (repeatable)", collect, []).option("--dry-run", "Validate and show execution plan without running").option("-v, --verbose", "Show full request/response for each step").action(async (keyOrPath, options) => {
   await flowExecuteCommand(keyOrPath, options);
 });
-flow.command("list").alias("ls").description("List all flows in .one/flows/").action(async () => {
+flow.command("list").alias("ls").description("List all workflows in .one/flows/").action(async () => {
   await flowListCommand();
 });
-flow.command("validate <keyOrPath>").description("Validate a flow JSON file").action(async (keyOrPath) => {
+flow.command("validate <keyOrPath>").description("Validate a workflow JSON file").action(async (keyOrPath) => {
   await flowValidateCommand(keyOrPath);
 });
-flow.command("resume <runId>").description("Resume a paused or failed flow run").action(async (runId) => {
+flow.command("resume <runId>").description("Resume a paused or failed workflow run").action(async (runId) => {
   await flowResumeCommand(runId);
 });
-flow.command("runs [flowKey]").description("List flow runs (optionally filtered by flow key)").action(async (flowKey) => {
+flow.command("runs [flowKey]").description("List workflow runs (optionally filtered by flow key)").action(async (flowKey) => {
   await flowRunsCommand(flowKey);
 });
 program.command("guide [topic]").description("Full CLI usage guide for agents (topics: overview, actions, flows, all)").action(async (topic) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picahq/cli",
-  "version": "1.11.1",
+  "version": "1.12.1",
   "description": "CLI for managing One",
   "type": "module",
   "files": [