@withone/cli 1.40.0 → 1.42.0

package/README.md

@@ -349,6 +349,22 @@ one sync run stripe --full-refresh
 
 Change hooks (`onInsert`, `onUpdate`, `onChange`) fire per-page during sync — pipe to a shell command, a flow, or an event log. Root-array responses (e.g. Hacker News `/v0/topstories.json` → `[9129911, 9129199, ...]`) are supported by setting `resultsPath` to `""`, `"$"`, or `"."`; primitive elements are auto-wrapped as `{ [idField]: value }`. Run `one guide sync` for the full reference.
 
+### `one relay`
+
+Receive webhooks from platforms and forward them to any connected platform via passthrough actions.
+
+```bash
+one relay platforms                        # List relay-capable platforms + event type counts
+one relay event-types <platform>           # List supported event types for a platform
+one relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
+one relay activate <id> --actions '<json>' # Attach passthrough forwarding actions
+one relay list                             # List existing relay endpoints
+one relay events --platform <p>            # Inspect received events
+one relay deliveries --endpoint-id <id>    # Check delivery status
+```
+
+Start with `one relay platforms` to discover which platforms support relay at all, then drill into `event-types <platform>` for the specific events. Run `one guide relay` for the full reference including `--metadata` requirements per platform.
+
 ### `one guide [topic]`
 
 Get the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).

package/dist/{chunk-SSEDFOVV.js → chunk-PK2RAVAF.js}

@@ -442,6 +442,9 @@ var OneApi = class {
   async listRelayEventTypes(platform) {
     return this.requestFull({ path: "/webhooks/relay/event-types", queryParams: { platform } });
   }
+  async listRelayPlatforms() {
+    return this.requestFull({ path: "/webhooks/relay/platforms" });
+  }
   async waitForConnection(platform, timeoutMs = 5 * 60 * 1e3, pollIntervalMs = 5e3, onPoll) {
     const startTime = Date.now();
     const existingConnections = await this.listConnections();
@@ -811,7 +814,29 @@ async function executeActionStep(step, context, api, permissions, allowedActionI
   const action = step.action;
   const platform = resolveValue(action.platform, context);
   const actionId = resolveValue(action.actionId, context);
-  const connectionKey = resolveValue(action.connectionKey, context);
+  const hasKey = action.connectionKey !== void 0 && action.connectionKey !== null && action.connectionKey !== "";
+  const hasRef = !!action.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      `Action step "${step.id}" has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    );
+  }
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      `Action step "${step.id}" must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").`
+    );
+  }
+  let connectionKey;
+  if (hasKey) {
+    connectionKey = resolveValue(action.connectionKey, context);
+  } else {
+    const ref = resolveValue(action.connection, context);
+    if (!context._connections) {
+      context._connections = await api.listConnections();
+    }
+    const conn = await api.resolveConnection(ref, context._connections);
+    connectionKey = conn.key;
+  }
   const data = action.data ? resolveValue(action.data, context) : void 0;
   const pathVars = action.pathVars ? resolveValue(action.pathVars, context) : void 0;
   const queryParams = action.queryParams ? resolveValue(action.queryParams, context) : void 0;
@@ -1115,7 +1140,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-2KVAPP6E.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-Y2CXXU3U.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1661,7 +1686,8 @@ var FLOW_SCHEMA = {
       fields: {
         platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
         actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
-        connectionKey: { type: "string", required: true, description: "Connection key (use $.input selector)" },
+        connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
+        connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
         data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
         pathVars: { type: "object", required: false, description: "URL path variables" },
         queryParams: { type: "object", required: false, description: "Query parameters" },
@@ -1674,7 +1700,7 @@ var FLOW_SCHEMA = {
         action: {
           platform: "stripe",
           actionId: "conn_mod_def::xxx::yyy",
-          connectionKey: "$.input.stripeConnectionKey",
+          connection: { platform: "stripe" },
           data: { query: "email:'{{$.input.customerEmail}}'" }
         }
       }
@@ -1723,7 +1749,7 @@ var FLOW_SCHEMA = {
         type: "condition",
         condition: {
           expression: "$.steps.search.response.data.length > 0",
-          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey", data: { text: "Found!" } } }],
+          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" }, data: { text: "Found!" } } }],
           else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
         }
       }
@@ -1747,7 +1773,7 @@ var FLOW_SCHEMA = {
         loop: {
           over: "$.steps.listOrders.response.data",
           as: "order",
-          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey", data: { amount: "$.loop.order.total" } } }]
+          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" }, data: { amount: "$.loop.order.total" } } }]
         }
       }
     },
@@ -1765,8 +1791,8 @@ var FLOW_SCHEMA = {
         type: "parallel",
         parallel: {
           steps: [
-            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey" } },
-            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey" } }
+            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" } } },
+            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" } } }
           ]
         }
       }
@@ -1818,7 +1844,7 @@ var FLOW_SCHEMA = {
         while: {
           condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
           maxIterations: 50,
-          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey" } }]
+          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" } } }]
         }
       }
     },
@@ -1842,7 +1868,7 @@ var FLOW_SCHEMA = {
       configKey: "paginate",
       description: "Auto-paginate API results into a single array",
       fields: {
-        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, connectionKey)" },
+        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, plus exactly one of `connection` or `connectionKey`)" },
         pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
         resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
         inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
@@ -1853,7 +1879,7 @@ var FLOW_SCHEMA = {
         name: "Fetch all Gmail messages",
         type: "paginate",
         paginate: {
-          action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey", queryParams: { maxResults: 100 } },
+          action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" }, queryParams: { maxResults: 100 } },
           pageTokenField: "nextPageToken",
           resultsField: "messages",
           inputTokenParam: "queryParams.pageToken",
@@ -2051,12 +2077,6 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
   "description": "What this flow does",
   "version": "1",
   "inputs": {
-    "connectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Platform connection key",
-      "connection": { "platform": "stripe" }
-    },
     "param": {
       "type": "string",
       "required": true,
@@ -2071,7 +2091,7 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
       "action": {
         "platform": "stripe",
         "actionId": "conn_mod_def::xxx::yyy",
-        "connectionKey": "$.input.connectionKey",
+        "connection": { "platform": "stripe" },
         "data": { "query": "{{$.input.param}}" }
       }
     }
@@ -2165,13 +2185,13 @@ Pipes can be applied to any value (objects/arrays are JSON-stringified first for
 
 ### When to use bare selectors vs \`{{...}}\` interpolation
 
-- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
+- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, the \`tag\` (or \`platform\`) inside \`connection\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
 - **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
 - **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
 
 ### Selectors vs expressions
 
-Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
+Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`, \`connection.tag\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
 
 \`\`\`json
 { "inputs": { "maxResults": { "type": "number", "default": 10 } } }
@@ -2291,9 +2311,30 @@ A \`flow\` step's \`flow.key\` accepts selectors and Handlebars interpolations,
 
 Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
 
-## Input Connection Auto-Resolution
+## Connection Resolution \u2014 late-bound by default
+
+Action steps reference a platform connection in one of two forms:
+
+\`\`\`json
+// preferred \u2014 late-bound, survives re-auth
+"connection": { "platform": "gmail" }
 
-When an input has \`"connection": { "platform": "stripe" }\`, the flow engine can automatically resolve the connection key at execution time. If the user has exactly one connection for that platform, the engine fills in the key without requiring \`-i connectionKey=...\`. If multiple connections exist, the user must specify which one. This is metadata for tooling \u2014 it does not affect the flow JSON structure, but it makes execution more convenient.
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 works for backwards compat, breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The engine resolves the \`connection\` ref once per flow run (cached for the run's lifetime) by calling \`listConnections\` and matching on platform + optional tag. Resolution errors fail the step with a clear message \u2014 \`No connection found for platform "X"\`, \`Multiple "X" connections found (tags: ...). Add a "tag" field\`, or \`No "X" connection has tag "Y"\`.
+
+Both \`platform\` and \`tag\` accept \`$.input.x\` selectors so a flow can be parameterised per-execution (e.g. multi-tenant orchestrators that pass the user's email as the tag).
+
+The validator rejects any action that sets both forms or neither, at \`flow validate\` and \`flow execute\` time.
+
+### Optional input metadata: connection-key auto-resolve (legacy)
+
+For flows that still use literal \`connectionKey\` strings via inputs, an input declaration can carry a \`"connection": { "platform": "..." }\` hint so \`flow execute\` auto-fills a single matching connection's key. New flows don't need this \u2014 switch the action's connection form to \`{ platform, tag? }\` and skip the input entirely.
 
 ## Complete Example: Fetch Data, Transform, Notify
 
@@ -2304,18 +2345,6 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
   "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
   "version": "1",
   "inputs": {
-    "crmConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "CRM platform connection key",
-      "connection": { "platform": "attio" }
-    },
-    "slackConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Slack connection key",
-      "connection": { "platform": "slack" }
-    },
     "slackChannel": {
       "type": "string",
       "required": true,
@@ -2330,7 +2359,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "attio",
         "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
-        "connectionKey": "$.input.crmConnectionKey",
+        "connection": { "platform": "attio" },
         "queryParams": { "limit": "10" }
       }
     },
@@ -2349,7 +2378,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "slack",
         "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
-        "connectionKey": "$.input.slackConnectionKey",
+        "connection": { "platform": "slack" },
         "data": {
           "channel": "$.input.slackChannel",
           "text": "{{$.steps.buildSummary.output.summary}}"

package/dist/{flow-runner-2KVAPP6E.js → flow-runner-Y2CXXU3U.js}

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

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   resolveFlowPath,
   saveFlow,
   validateActionInput
-} from "./chunk-SSEDFOVV.js";
+} from "./chunk-PK2RAVAF.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -3269,10 +3269,13 @@ function validateStepsArray(steps, pathPrefix, errors) {
           const a = value;
           if (!a.platform) errors.push({ path: `${fieldPath}.platform`, message: 'Action must have "platform"' });
           if (!a.actionId) errors.push({ path: `${fieldPath}.actionId`, message: 'Action must have "actionId"' });
-          if (!a.connectionKey) errors.push({ path: `${fieldPath}.connectionKey`, message: 'Action must have "connectionKey"' });
+          validateConnectionForm(a, fieldPath, errors);
         }
       }
     }
+    if (descriptor.type === "action") {
+      validateConnectionForm(config2, `${path17}.${configKey}`, errors);
+    }
     if (descriptor.type === "code") {
       const hasSource = typeof config2.source === "string" && config2.source.length > 0;
       const hasModule = typeof config2.module === "string" && config2.module.length > 0;
@@ -3300,6 +3303,43 @@ function validateStepsArray(steps, pathPrefix, errors) {
     }
   }
 }
+function validateConnectionForm(config2, pathPrefix, errors) {
+  const hasKey = config2.connectionKey !== void 0 && config2.connectionKey !== null && config2.connectionKey !== "";
+  const conn = config2.connection;
+  const hasRef = !!conn && typeof conn === "object" && !Array.isArray(conn) && typeof conn.platform === "string" && conn.platform.length > 0;
+  if (hasKey && hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: `Action has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    });
+    return;
+  }
+  if (!hasKey && !hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: 'Action must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").'
+    });
+    return;
+  }
+  if (hasRef) {
+    const c = conn;
+    if (c.tag !== void 0 && typeof c.tag !== "string") {
+      errors.push({
+        path: `${pathPrefix}.connection.tag`,
+        message: '"connection.tag" must be a string when set'
+      });
+    }
+    const allowed = /* @__PURE__ */ new Set(["platform", "tag"]);
+    for (const k of Object.keys(c)) {
+      if (!allowed.has(k)) {
+        errors.push({
+          path: `${pathPrefix}.connection.${k}`,
+          message: `Unknown field "${k}" in connection ref. Allowed: platform, tag.`
+        });
+      }
+    }
+  }
+}
 function detectFlatConfigHint(step, descriptor) {
   const requiredFields = Object.entries(descriptor.fields).filter(([, fd]) => fd.required).map(([name]) => name);
   const flatFields = requiredFields.filter((f) => f in step);
@@ -4107,14 +4147,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "My Workflow",
     description: "A basic workflow with a single action step",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for the platform",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "step1",
@@ -4123,7 +4156,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey",
+          connection: { platform: "PLATFORM_NAME" },
           data: {}
         }
       }
@@ -4134,14 +4167,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Conditional Workflow",
     description: "Fetch data, then branch based on results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetch",
@@ -4150,7 +4176,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4184,14 +4210,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Loop Workflow",
     description: "Fetch a list, then process each item",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchList",
@@ -4200,7 +4219,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4233,14 +4252,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "AI Analysis Workflow",
     description: "Fetch data, analyze with Claude, and send results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for data source",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchData",
@@ -4249,7 +4261,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4631,6 +4643,42 @@ async function relayDeliveriesCommand(options) {
     error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
   }
 }
+async function relayPlatformsCommand() {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey, getApiBase());
+  const spinner6 = createSpinner();
+  spinner6.start("Loading relay-capable platforms...");
+  try {
+    const platforms = await api.listRelayPlatforms();
+    if (isAgentMode()) {
+      json({ platforms });
+      return;
+    }
+    spinner6.stop(`${platforms.length} relay-capable platform${platforms.length === 1 ? "" : "s"} found`);
+    if (platforms.length === 0) {
+      console.log("\n  No relay-capable platforms available.\n");
+      return;
+    }
+    console.log();
+    printTable(
+      [
+        { key: "platform", label: "Platform" },
+        { key: "eventTypeCount", label: "Event types", color: pc8.dim }
+      ],
+      platforms.map((p10) => ({ platform: p10.platform, eventTypeCount: String(p10.eventTypeCount) }))
+    );
+    console.log();
+    console.log(
+      pc8.dim(
+        `  Run ${pc8.cyan("one relay event-types <platform>")} to see the full event list for a platform.
+`
+      )
+    );
+  } catch (error2) {
+    spinner6.stop("Failed to load relay platforms");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
 async function relayEventTypesCommand(platform) {
   const { apiKey } = getConfig3();
   const api = new OneApi(apiKey, getApiBase());
@@ -7383,7 +7431,7 @@ function getApi() {
   if (!apiKey) {
     error('No API key configured. Run "one init" first.');
   }
-  return new OneApi(apiKey);
+  return new OneApi(apiKey, getApiBase());
 }
 async function syncProfilesCommand(platform) {
   const profiles = listBuiltinProfiles(platform);
@@ -8302,6 +8350,7 @@ Receive webhooks from platforms (Stripe, GitHub, Airtable, Attio, Google Calenda
 
 **Quick start:**
 \`\`\`bash
+one --agent relay platforms                                     # See relay-capable platforms
 one --agent relay event-types <platform>                        # See available events
 one --agent relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
 one --agent relay activate <id> --actions '[{"type":"passthrough","actionId":"...","connectionKey":"...","body":{...}}]'
@@ -8447,6 +8496,7 @@ Webhook relay receives events from platforms (Stripe, GitHub, Airtable, Attio, G
 ## Commands
 
 \`\`\`bash
+one --agent relay platforms                        # List relay-capable platforms + event type counts
 one --agent relay event-types <platform>          # List available events
 one --agent relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
 one --agent relay activate <id> --actions '<json>' # Add forwarding actions
@@ -8461,7 +8511,7 @@ one --agent relay deliveries --endpoint-id <id>    # Check delivery status
 
 ## Building a Relay
 
-1. **Discover connections** \u2014 identify source and destination platforms
+1. **Discover connections** \u2014 identify source and destination platforms. Use \`one --agent relay platforms\` to see which platforms support relay at all before digging into a specific one.
 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
@@ -9460,6 +9510,7 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
     one cache update-all                  Re-fetch fresh data for all cached entries
 
   Webhook Relay:
+    one relay platforms                   List platforms that support relay + event type counts
     one relay create                      Create a relay endpoint for a connection
     one relay list                        List relay endpoints
     one relay activate <id>               Activate with passthrough actions
@@ -9763,6 +9814,9 @@ relay.command("deliveries").description("List delivery attempts for an endpoint
 relay.command("event-types <platform>").description("List supported webhook event types for a platform").action(async (platform) => {
   await relayEventTypesCommand(platform);
 });
+relay.command("platforms").description("List all platforms that support webhook relay, with their event type counts").action(async () => {
+  await relayPlatformsCommand();
+});
 registerSyncCommands(program);
 var cache = program.command("cache").description("Manage the local knowledge and search cache");
 cache.command("clear [actionId]").description("Clear all cached data, or a specific action by ID").action(async (actionId) => {

package/package.json

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

package/skills/one/references/flows.md

@@ -282,12 +282,19 @@ The `if`, `unless`, `condition.expression`, `while.condition`, `transform.expres
   "action": {
     "platform": "stripe",
     "actionId": "conn_mod_def::xxx::yyy",
-    "connectionKey": "$.input.stripeConnectionKey",
+    "connection": { "platform": "stripe" },
     "data": { "query": "email:'{{$.input.customerEmail}}'" }
   }
 }
 ```
 
+**Connection forms.** Each action step sets exactly one of:
+
+- **`connection: { platform: "<name>", "tag"?: "<tag>" }`** (preferred) — late-bound, resolved at flow-execute time. Survives re-auth (which always mints a new key). Use `tag` to disambiguate when a platform has multiple connections (e.g. multi-account Gmail). Both `platform` and `tag` accept `$.input.x` selectors so flows can be parameterised per-execution.
+- **`connectionKey: "<literal-or-selector>"`** (legacy) — passes the key string straight through. Still supported for backwards compat, but breaks on re-auth and forces manual edits across every flow that references the stale key. Migrate to `connection` when convenient.
+
+The validator rejects an action that sets both forms (or neither) at `flow validate` and `flow execute` time.
+
 ### `transform` — JS expression (implicit return)
 
 ```json

package/skills/one/references/relay.md

@@ -16,6 +16,14 @@ one --agent connection list
 
 Identify source (sends webhooks) and destination (receives forwarded data). Note both connection keys.
 
+If you're unsure whether the source platform supports relay at all, list relay-capable platforms first:
+
+```bash
+one --agent relay platforms
+```
+
+This returns `[{ "platform": "<name>", "eventTypeCount": <n> }, ...]` for every platform that One can receive webhooks from. If your source isn't in the list, relay won't work for it.
+
 ### Step 2: Get event types
 
 ```bash
@@ -173,6 +181,13 @@ one --agent relay activate <relay-id> --actions '[{
 }]'
 ```
 
+## Discovery Commands
+
+```bash
+one --agent relay platforms                        # All relay-capable platforms + event type counts
+one --agent relay event-types <platform>           # Event types for a specific platform
+```
+
 ## Management Commands
 
 ```bash