@withone/cli 1.35.0 → 1.37.0

package/README.md

@@ -255,6 +255,7 @@ one actions execute stripe <actionId> <connectionKey> \
 | `--dry-run` | Show the request without executing it |
 | `--mock` | Return example response without making an API call |
 | `--skip-validation` | Skip input validation against the action schema |
+| `--output <path>` | Save response to a file (for binary downloads) |
 
 The CLI validates required parameters (path variables, query params, body fields) against the action schema before executing. Missing params return a clear error with the flag name and description. Pass `--skip-validation` to bypass.
 

package/dist/{chunk-HZP7NT4K.js → chunk-MNJJE4PJ.js}

@@ -11,6 +11,10 @@ import { exec, spawn } from "child_process";
 import { promisify } from "util";
 
 // src/lib/api.ts
+import { createWriteStream } from "fs";
+import { resolve } from "path";
+import { pipeline } from "stream/promises";
+import { Readable } from "stream";
 var ApiError = class extends Error {
   constructor(status, message, retryAfterSeconds) {
     super(message);
@@ -328,12 +332,45 @@ var OneApi = class {
       const text = await response.text();
       throw new ApiError(response.status, text || `HTTP ${response.status}`);
     }
+    const responseContentType = response.headers.get("content-type") || "";
+    const isExplicitJson = responseContentType.includes("application/json") || responseContentType.includes("text/");
+    if (isExplicitJson || !responseContentType) {
+      const responseText2 = await response.text();
+      const responseData = responseText2 ? JSON.parse(responseText2) : {};
+      return { requestConfig: sanitizedConfig, responseData };
+    }
+    if (args.output) {
+      const outputPath = resolve(args.output);
+      const body = response.body;
+      if (!body) {
+        throw new ApiError(0, "Response body is null \u2014 cannot save to file");
+      }
+      const nodeReadable = Readable.fromWeb(body);
+      await pipeline(nodeReadable, createWriteStream(outputPath));
+      const contentLength = response.headers.get("content-length");
+      const size = contentLength ? parseInt(contentLength, 10) : void 0;
+      return {
+        requestConfig: sanitizedConfig,
+        responseData: { saved: true, path: outputPath, size, contentType: responseContentType }
+      };
+    }
     const responseText = await response.text();
-    const responseData = responseText ? JSON.parse(responseText) : {};
-    return {
-      requestConfig: sanitizedConfig,
-      responseData
-    };
+    try {
+      const responseData = responseText ? JSON.parse(responseText) : {};
+      return { requestConfig: sanitizedConfig, responseData };
+    } catch {
+      const contentLength = response.headers.get("content-length");
+      const size = contentLength ? parseInt(contentLength, 10) : responseText.length;
+      return {
+        requestConfig: sanitizedConfig,
+        responseData: {
+          binary: true,
+          size,
+          contentType: responseContentType,
+          message: "Binary response received. Use --output <path> to save to a file."
+        }
+      };
+    }
   }
   // Webhook Relay methods
   async createRelayEndpoint(body) {
@@ -394,7 +431,7 @@ var TimeoutError = class extends Error {
   }
 };
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function replacePathVariables(path3, variables) {
   if (!path3) return path3;
@@ -532,7 +569,7 @@ function setByDotPath(obj, dotPath, value) {
 // src/lib/flow-engine.ts
 var execAsync = promisify(exec);
 function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var StepTimeoutError = class extends Error {
   errorCode = "TIMEOUT";
@@ -843,7 +880,7 @@ async function executeCodeModule(stepId, modulePath, context, options) {
   const { env: _omitEnv, ...safeContext } = context;
   void _omitEnv;
   const stdinPayload = JSON.stringify(safeContext);
-  return await new Promise((resolve, reject) => {
+  return await new Promise((resolve2, reject) => {
     const child = spawn(process.execPath, [absPath], {
       cwd: rootDir,
       stdio: ["pipe", "pipe", "pipe"]
@@ -862,11 +899,11 @@ async function executeCodeModule(stepId, modulePath, context, options) {
       }
       const trimmed = stdout.trim();
       if (trimmed === "") {
-        resolve(void 0);
+        resolve2(void 0);
         return;
       }
       try {
-        resolve(JSON.parse(stripCodeFences(trimmed)));
+        resolve2(JSON.parse(stripCodeFences(trimmed)));
       } catch (err) {
         reject(new Error(`Code module "${modulePath}" did not print valid JSON to stdout: ${err.message}`));
       }
@@ -1042,7 +1079,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-TNI7YWVY.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-OVOGDXNR.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,

package/dist/{flow-runner-TNI7YWVY.js → flow-runner-OVOGDXNR.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-HZP7NT4K.js";
+} from "./chunk-MNJJE4PJ.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   resolveFlowPath,
   saveFlow,
   validateActionInput
-} from "./chunk-HZP7NT4K.js";
+} from "./chunk-MNJJE4PJ.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2771,7 +2771,8 @@ async function actionsExecuteCommand(platform, actionId, connectionKey, options)
         headers,
         isFormData: options.formData,
         isFormUrlEncoded: options.formUrlEncoded,
-        dryRun: options.dryRun
+        dryRun: options.dryRun,
+        output: options.output
       },
       actionDetails
     );
@@ -4333,6 +4334,7 @@ async function relayCreateCommand(options) {
     if (options.description) body.description = options.description;
     if (options.eventFilters) body.eventFilters = parseJsonArg2(options.eventFilters, "--event-filters");
     if (options.tags) body.tags = parseJsonArg2(options.tags, "--tags");
+    if (options.metadata) body.metadata = parseJsonArg2(options.metadata, "--metadata");
     if (options.createWebhook) body.createWebhook = true;
     const result = await api.createRelayEndpoint(body);
     if (isAgentMode()) {
@@ -4347,6 +4349,10 @@ async function relayCreateCommand(options) {
     if (result.description) console.log(`  ${pc8.dim("Description:")} ${result.description}`);
     if (result.eventFilters?.length) console.log(`  ${pc8.dim("Events:")}      ${result.eventFilters.join(", ")}`);
     if (result.webhookPayload?.id) console.log(`  ${pc8.dim("Webhook ID:")}  ${result.webhookPayload.id}`);
+    if (result.warning) {
+      console.log();
+      console.log(`  ${pc8.yellow("\u26A0 Warning:")} ${result.warning}`);
+    }
     console.log();
   } catch (error2) {
     spinner6.stop("Failed to create relay endpoint");
@@ -8006,6 +8012,7 @@ one --agent actions execute <platform> <actionId> <key> -d '{}'  # Execute it
 - \`--dry-run\` \u2014 Preview request without executing
 - \`--mock\` \u2014 Return example response without making an API call (useful for building UI against a response shape)
 - \`--skip-validation\` \u2014 Skip input validation against the action schema
+- \`--output <path>\` \u2014 Save response to a file (for binary downloads like PDFs, images, documents)
 
 The CLI validates required parameters against the action schema before executing. If you're missing a required path variable, query param, or body field, you'll get a clear error listing what's missing and which flag to use. Pass \`--skip-validation\` to bypass.
 
@@ -8129,6 +8136,7 @@ one --agent actions execute <platform> <actionId> <connectionKey> [options]
 - \`--dry-run\` \u2014 Preview without executing
 - \`--mock\` \u2014 Return example response without making an API call
 - \`--skip-validation\` \u2014 Skip input validation against the action schema
+- \`--output <path>\` \u2014 Save response to a file (for binary downloads like PDFs, images, documents)
 
 **Do NOT** pass path or query parameters in \`-d\`. Use the correct flags.
 
@@ -8198,8 +8206,32 @@ one --agent relay deliveries --endpoint-id <id>    # Check delivery status
 2. **Get event types** \u2014 \`one --agent relay event-types <platform>\`
 3. **Get source knowledge** \u2014 understand the incoming webhook payload shape (\`{{payload.*}}\` paths)
 4. **Get destination knowledge** \u2014 understand the outgoing API body shape
-5. **Create endpoint** \u2014 with \`--create-webhook\` and \`--event-filters\`
-6. **Activate** \u2014 with passthrough action mapping source fields to destination fields
+5. **Create endpoint** \u2014 with \`--create-webhook\`, \`--event-filters\`, and \`--metadata\` if the source platform requires it
+6. **Activate** \u2014 with passthrough action mapping source fields to destination fields. **Do NOT pass \`--webhook-secret\`** when the endpoint was created with \`--create-webhook\` \u2014 the correct secret is auto-stored, and supplying a wrong one silently drops every delivery (events arrive, 0 deliveries).
+
+## Platform-Specific Metadata (\`--metadata\`)
+
+Some source platforms need extra identifiers to register a webhook. Pass these via \`--metadata '<json>'\` on \`relay create\`. Without them, \`--create-webhook\` silently fails:
+
+| Platform | Required metadata keys |
+|---|---|
+| \`github\` | \`GITHUB_OWNER\`, \`GITHUB_REPOSITORY\` |
+| \`typeform\` | \`TYPEFORM_FORM_ID\` |
+| \`stripe\` | (none) |
+| \`airtable\` | (none) |
+| \`attio\` | (none) |
+| \`google-calendar\` | (none) |
+
+Example (GitHub):
+
+\`\`\`bash
+one --agent relay create \\
+  --connection-key "live::github::default::<key>" \\
+  --event-filters '["issues","pull_request"]' \\
+  --metadata '{"GITHUB_OWNER":"my-org","GITHUB_REPOSITORY":"my-repo"}' \\
+  --description "GitHub relay" \\
+  --create-webhook
+\`\`\`
 
 ## Template Context
 
@@ -8250,6 +8282,8 @@ Any connected platform can be a destination via passthrough actions.
 2. \`relay events --platform <p>\` \u2014 check events are arriving
 3. \`relay deliveries --event-id <id>\` \u2014 check delivery status and errors
 4. \`relay event <id>\` \u2014 inspect full payload to verify template paths
+
+**If events arrive but 0 deliveries succeed**: you likely passed a wrong \`--webhook-secret\` on \`relay activate\`. When you created the endpoint with \`--create-webhook\`, the secret was registered with the source platform and stored automatically \u2014 do not pass it again on activate. Signature verification will fail silently and every event will be dropped.
 `;
 var GUIDE_CACHE = `# One Cache \u2014 Reference
 
@@ -9369,7 +9403,7 @@ 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").option("--no-cache", "Skip cache, fetch fresh from API").option("--cache-status", "Print cache metadata without fetching").action(async (platform, actionId, options) => {
   await actionsKnowledgeCommand(platform, actionId, options);
 });
-actions.command("execute [platform] [actionId] [connectionKey]").alias("x").allowUnknownOption(true).allowExcessArguments(true).description("Execute an action (or multiple with --parallel, separated by --)").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").option("--mock", "Return example response without making an API call").option("--skip-validation", "Skip input validation against the action schema").option("--parallel", "Execute multiple actions concurrently (separate actions with --)").option("--max-concurrency <n>", "Max concurrent actions when using --parallel (default: 5)", "5").action(async (platform, actionId, connectionKey, options) => {
+actions.command("execute [platform] [actionId] [connectionKey]").alias("x").allowUnknownOption(true).allowExcessArguments(true).description("Execute an action (or multiple with --parallel, separated by --)").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").option("--mock", "Return example response without making an API call").option("--skip-validation", "Skip input validation against the action schema").option("--output <path>", "Save binary response to a file (for non-JSON responses like file downloads)").option("--parallel", "Execute multiple actions concurrently (separate actions with --)").option("--max-concurrency <n>", "Max concurrent actions when using --parallel (default: 5)", "5").action(async (platform, actionId, connectionKey, options) => {
   if (options.parallel) {
     await actionsExecuteParallelCommand();
     return;
@@ -9386,7 +9420,8 @@ actions.command("execute [platform] [actionId] [connectionKey]").alias("x").allo
     formUrlEncoded: options.formUrlEncoded,
     dryRun: options.dryRun,
     mock: options.mock,
-    skipValidation: options.skipValidation
+    skipValidation: options.skipValidation,
+    output: options.output
   });
 });
 var flow = program.command("flow").alias("f").description("Create, execute, and manage multi-step workflows");
@@ -9412,7 +9447,7 @@ flow.command("scaffold [template]").description("Generate a workflow scaffold (t
   await flowScaffoldCommand(template);
 });
 var relay = program.command("relay").alias("r").description("Receive webhooks from platforms and relay them via passthrough actions");
-relay.command("create").description("Create a new relay endpoint for a connection").requiredOption("--connection-key <key>", "Connection key for the source platform").option("--description <desc>", "Description of the relay endpoint").option("--event-filters <json>", `JSON array of event types to filter (e.g. '["customer.created"]')`).option("--tags <json>", "JSON array of tags").option("--create-webhook", "Automatically register the webhook with the source platform").action(async (options) => {
+relay.command("create").description("Create a new relay endpoint for a connection").requiredOption("--connection-key <key>", "Connection key for the source platform").option("--description <desc>", "Description of the relay endpoint").option("--event-filters <json>", `JSON array of event types to filter (e.g. '["customer.created"]')`).option("--tags <json>", "JSON array of tags").option("--metadata <json>", `JSON object of platform-specific metadata required to register the webhook (e.g. GitHub: '{"GITHUB_OWNER":"org","GITHUB_REPOSITORY":"repo"}', Typeform: '{"TYPEFORM_FORM_ID":"abc"}')`).option("--create-webhook", "Automatically register the webhook with the source platform").action(async (options) => {
   await relayCreateCommand(options);
 });
 relay.command("list").alias("ls").description("List all relay endpoints").option("--limit <n>", "Max results per page").option("--page <n>", "Page number").action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/SKILL.md

@@ -87,6 +87,7 @@ Options:
 - `--dry-run` — Preview the request without executing
 - `--mock` — Return example response without making an API call (useful for building UI)
 - `--skip-validation` — Skip input validation against the action schema
+- `--output <path>` — Save response to a file (for binary downloads like PDFs, images, documents)
 
 The CLI validates required parameters before executing. Missing params return a structured error with the flag name, parameter name, and description. Pass `--skip-validation` to bypass.
 

package/skills/one/references/relay.md

@@ -52,6 +52,25 @@ one --agent relay create \
 
 Always use `--create-webhook` — it registers the webhook URL with the source platform automatically.
 
+**Some source platforms require extra identifiers via `--metadata`:**
+
+| Platform | Required metadata keys |
+|---|---|
+| `github` | `GITHUB_OWNER`, `GITHUB_REPOSITORY` |
+| `typeform` | `TYPEFORM_FORM_ID` |
+| `stripe`, `airtable`, `attio`, `google-calendar` | (none) |
+
+Without metadata, `--create-webhook` silently fails for these platforms. Example for GitHub:
+
+```bash
+one --agent relay create \
+  --connection-key "live::github::default::<key>" \
+  --event-filters '["issues","pull_request"]' \
+  --metadata '{"GITHUB_OWNER":"my-org","GITHUB_REPOSITORY":"my-repo"}' \
+  --description "GitHub relay" \
+  --create-webhook
+```
+
 ### Step 6: Activate with a passthrough action
 
 ```bash
@@ -66,6 +85,8 @@ one --agent relay activate <relay-id> --actions '[{
 }]'
 ```
 
+**Do NOT pass `--webhook-secret` on activate** when you created the endpoint with `--create-webhook`. The correct secret is registered with the source platform and stored automatically. Supplying a wrong one does not error — events arrive but every delivery is dropped during signature verification (0 deliveries). If you don't have a reason to override the secret, omit the flag.
+
 ## Template Context
 
 | Variable | Description |
@@ -177,3 +198,5 @@ one --agent relay deliveries --event-id <id>
 - Event filters on both the endpoint and individual actions must match
 - Multiple actions can be attached to a single relay endpoint
 - Missing template variables resolve to empty strings — verify `{{payload.*}}` paths against the actual payload
+- GitHub and Typeform relays require `--metadata` on create; without it `--create-webhook` silently fails
+- Never pass `--webhook-secret` on activate when the endpoint was created with `--create-webhook` — the auto-stored secret is correct, and a wrong one causes signature verification to drop every event silently