@withone/cli 1.16.0 → 1.17.1

package/package.json

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

package/skills/one/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: one
+description: |
+  Use the One CLI (`one`) to interact with 250+ third-party platforms — Gmail, Slack, Shopify, HubSpot, Stripe, GitHub, Notion, Salesforce, and more — through their APIs. One handles authentication, request building, and execution through a single unified interface.
+
+  TRIGGER when the user wants to:
+  - Interact with ANY third-party platform or external service (e.g., "send an email", "create a Shopify order", "look up a HubSpot contact", "post to Slack")
+  - List their connected platforms or check what integrations are available
+  - Search for what they can do on a platform (e.g., "what can I do with Gmail")
+  - Execute any API call against a connected platform
+  - Set up webhook-driven automations between platforms (e.g., "when a Stripe payment comes in, notify Slack")
+  - Build multi-step workflows that chain actions across platforms (e.g., "fetch Stripe customers and email each one")
+  - Anything involving third-party APIs, integrations, or connected apps — even if they don't mention "One" by name
+
+  DO NOT TRIGGER for:
+  - Setting up One or installing MCP (that's `one init`)
+  - Adding new connections (that's `one add <platform>`)
+  - Configuring access control (that's `one config`)
+---
+
+# One CLI
+
+You have access to the One CLI which lets you interact with 250+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
+
+## Core Workflow: search -> knowledge -> execute
+
+Always follow this sequence when the user wants to do something on a connected platform:
+
+### 1. List connections
+
+```bash
+one --agent connection list
+```
+
+Returns connected platforms with their connection keys (needed for execution) and platform names in kebab-case (needed for searching).
+
+### 2. Search for the right action
+
+```bash
+one --agent actions search <platform> "<query>" -t execute
+```
+
+- Platform names are always kebab-case: `gmail`, `hub-spot`, `ship-station`
+- Use `-t execute` when performing actions, `-t knowledge` when researching or writing code
+- If no results, broaden the query (e.g., `"list"` instead of `"list active premium customers"`)
+
+### 3. Get the action's knowledge (REQUIRED before executing)
+
+```bash
+one --agent actions knowledge <platform> <actionId>
+```
+
+This tells you exactly what parameters are required, how to structure the request, and which flags to use. Never skip this step — without it you'll guess wrong on parameters.
+
+### 4. Execute
+
+```bash
+one --agent actions execute <platform> <actionId> <connectionKey> [options]
+```
+
+Options:
+- `-d, --data <json>` — Request body (POST, PUT, PATCH)
+- `--path-vars <json>` — Path variables for URLs with `{id}` placeholders
+- `--query-params <json>` — Query parameters
+- `--headers <json>` — Additional headers
+- `--form-data` — Send as multipart/form-data
+- `--form-url-encoded` — Send as application/x-www-form-urlencoded
+- `--dry-run` — Preview the request without executing
+
+Examples:
+```bash
+# Simple GET
+one --agent actions execute shopify <actionId> <connectionKey>
+
+# POST with body data
+one --agent actions execute hub-spot <actionId> <connectionKey> \
+  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
+
+# Path variables + query params
+one --agent actions execute shopify <actionId> <connectionKey> \
+  --path-vars '{"order_id": "12345"}' \
+  --query-params '{"limit": "10"}'
+
+# Array query params (expand to repeated keys)
+one --agent actions execute gmail <actionId> <connectionKey> \
+  --path-vars '{"userId": "me", "id": "msg123"}' \
+  --query-params '{"format": "metadata", "metadataHeaders": ["From", "Subject", "Date"]}'
+```
+
+## Error Handling
+
+All errors return JSON: `{"error": "message"}`. Parse output as JSON and check for the `error` key.
+
+## Important Rules
+
+- Always use `--agent` flag for structured JSON output
+- Platform names are always kebab-case (`hub-spot` not `HubSpot`)
+- Always use the exact action ID from search results — never guess or construct them
+- Always read knowledge before executing — it has required params, validation rules, and caveats
+- JSON values passed to `-d`, `--path-vars`, `--query-params` must be valid JSON (use single quotes around JSON to avoid shell escaping)
+- Do NOT pass path or query parameters inside the `-d` body flag
+
+## Beyond Single Actions
+
+One also supports more advanced patterns. Read the relevant reference file before using these:
+
+- **Webhook Relay** — Receive webhooks from a platform and forward to another (e.g., Stripe event -> Slack message). Read `references/relay.md` in this skill's directory for the full workflow.
+- **Multi-step Workflows** — Chain actions across platforms as JSON workflow files (like n8n/Zapier but file-based). Read `references/flows.md` in this skill's directory for the schema and examples.
+
+## Adding New Connections
+
+If the user needs a platform that isn't connected yet, tell them to run:
+```bash
+one add <platform>
+```
+This is interactive and opens the browser for OAuth. After connecting, the platform will appear in `one --agent connection list`.

package/skills/one/references/flows.md

@@ -0,0 +1,278 @@
+# One Workflows — Multi-Step API Workflows
+
+Workflows chain actions across platforms as JSON files stored at `.one/flows/<key>.flow.json`. Like n8n/Zapier but file-based.
+
+## Building a Workflow
+
+### Step 0: Design first
+
+Before touching CLI commands:
+1. Clarify the end goal — what output does the user need?
+2. Map every step required to deliver that output
+3. Identify where AI analysis is needed (summarization, scoring, classification)
+4. Write the step sequence as a plain list before constructing JSON
+
+Common mistake: jumping straight to `actions search` and building a raw data pipe. Design first.
+
+### Step 1: Discover connections
+
+```bash
+one --agent connection list
+```
+
+### Step 2: Get knowledge for EACH action
+
+```bash
+one --agent actions search <platform> "<query>" -t execute
+one --agent actions knowledge <platform> <actionId>
+```
+
+You MUST call knowledge for every action in the workflow — it tells you the exact body structure, required fields, and path variables.
+
+### Step 3: Build the workflow JSON
+
+### Step 4: Create
+
+```bash
+one --agent flow create <key> --definition '<json>'
+```
+
+Or write directly to `.one/flows/<key>.flow.json`.
+
+### Step 5: Validate
+
+```bash
+one --agent flow validate <key>
+```
+
+### Step 6: Execute
+
+```bash
+one --agent flow execute <key> -i connectionKey=xxx -i param=value
+```
+
+## Workflow JSON Schema
+
+```json
+{
+  "key": "welcome-customer",
+  "name": "Welcome New Customer",
+  "description": "Look up Stripe customer, send welcome email",
+  "version": "1",
+  "inputs": {
+    "stripeConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Stripe connection key",
+      "connection": { "platform": "stripe" }
+    },
+    "customerEmail": {
+      "type": "string",
+      "required": true
+    }
+  },
+  "steps": [...]
+}
+```
+
+### Input Fields
+
+| Field | Description |
+|---|---|
+| `type` | `string`, `number`, `boolean`, `object`, `array` |
+| `required` | Whether input must be provided (default: true) |
+| `default` | Default value if not provided |
+| `description` | Human-readable description |
+| `connection` | `{ "platform": "gmail" }` — enables auto-resolution |
+
+Connection inputs with a `connection` field auto-resolve if the user has exactly one connection for that platform.
+
+## Selector Syntax
+
+| Pattern | Resolves To |
+|---|---|
+| `$.input.connectionKey` | Input value |
+| `$.steps.stepId.response` | Full API response from a step |
+| `$.steps.stepId.response.data[0].email` | Nested field with array index |
+| `$.steps.stepId.response.data[*].id` | Wildcard — maps array to field |
+| `$.env.MY_VAR` | Environment variable |
+| `$.loop.item` | Current loop item |
+| `$.loop.i` | Current loop index |
+| `"Hello {{$.steps.getUser.response.data.name}}"` | String interpolation |
+
+A pure `$.xxx` value resolves to the raw type. A string containing `{{$.xxx}}` does string interpolation.
+
+## Step Types
+
+### `action` — Execute a One API action
+
+```json
+{
+  "id": "findCustomer",
+  "type": "action",
+  "action": {
+    "platform": "stripe",
+    "actionId": "conn_mod_def::xxx::yyy",
+    "connectionKey": "$.input.stripeConnectionKey",
+    "data": { "query": "email:'{{$.input.customerEmail}}'" }
+  }
+}
+```
+
+### `transform` — JS expression (implicit return)
+
+```json
+{
+  "id": "extractNames",
+  "type": "transform",
+  "transform": { "expression": "$.steps.findCustomer.response.data.map(c => c.name)" }
+}
+```
+
+### `code` — Multi-line JS (explicit return, async, supports await)
+
+```json
+{
+  "id": "processData",
+  "type": "code",
+  "code": {
+    "source": "const customers = $.steps.list.response.data;\nreturn customers.map(c => ({...c, tier: c.spend > 1000 ? 'gold' : 'silver'}));"
+  }
+}
+```
+
+### `condition` — If/then/else branching
+
+```json
+{
+  "id": "checkFound",
+  "type": "condition",
+  "condition": {
+    "expression": "$.steps.find.response.data.length > 0",
+    "then": [{ "id": "sendEmail", "type": "action", "action": {...} }],
+    "else": [{ "id": "logNotFound", "type": "transform", "transform": { "expression": "'Not found'" } }]
+  }
+}
+```
+
+### `loop` — Iterate over an array
+
+```json
+{
+  "id": "processOrders",
+  "type": "loop",
+  "loop": {
+    "over": "$.steps.listOrders.response.orders",
+    "as": "order",
+    "maxConcurrency": 5,
+    "steps": [...]
+  }
+}
+```
+
+### `parallel` — Run steps concurrently
+
+```json
+{
+  "id": "lookups",
+  "type": "parallel",
+  "parallel": { "maxConcurrency": 5, "steps": [...] }
+}
+```
+
+### `file-read` / `file-write` — Filesystem access
+
+```json
+{ "id": "read", "type": "file-read", "fileRead": { "path": "./data/config.json", "parseJson": true } }
+{ "id": "write", "type": "file-write", "fileWrite": { "path": "./output/results.json", "content": "$.steps.transform.output" } }
+```
+
+### `while` — Condition-driven loop (do-while)
+
+```json
+{
+  "id": "paginate",
+  "type": "while",
+  "while": {
+    "condition": "$.steps.paginate.output.lastResult.nextPageToken != null",
+    "maxIterations": 50,
+    "steps": [...]
+  }
+}
+```
+
+### `flow` — Execute a sub-flow
+
+```json
+{
+  "id": "enrich",
+  "type": "flow",
+  "flow": { "key": "enrich-customer", "inputs": { "email": "$.steps.get.response.email" } }
+}
+```
+
+### `paginate` — Auto-collect paginated results
+
+```json
+{
+  "id": "allMessages",
+  "type": "paginate",
+  "paginate": {
+    "action": { "platform": "gmail", "actionId": "...", "connectionKey": "$.input.gmailKey" },
+    "pageTokenField": "nextPageToken",
+    "resultsField": "messages",
+    "inputTokenParam": "queryParams.pageToken",
+    "maxPages": 10
+  }
+}
+```
+
+### `bash` — Shell commands (requires `--allow-bash`)
+
+```json
+{
+  "id": "analyze",
+  "type": "bash",
+  "bash": { "command": "cat /tmp/data.json | claude --print 'Analyze this' --output-format json", "timeout": 180000, "parseJson": true }
+}
+```
+
+## Error Handling
+
+```json
+{ "onError": { "strategy": "retry", "retries": 3, "retryDelayMs": 1000 } }
+```
+
+Strategies: `fail` (default), `continue`, `retry`, `fallback`.
+
+Conditional execution: `"if": "$.steps.find.response.data.length > 0"`
+
+## AI-Augmented Pattern: file-write -> bash -> code
+
+When raw data needs analysis, use this pattern:
+1. `file-write` — save data to temp file (API responses are too large to inline)
+2. `bash` — call `claude --print` to analyze (set timeout to 180000+, use `--output-format json`)
+3. `code` — parse and structure the AI output for downstream steps
+
+## CLI Commands
+
+```bash
+one --agent flow create <key> --definition '<json>'
+one --agent flow list
+one --agent flow validate <key>
+one --agent flow execute <key> -i key=value
+one --agent flow execute <key> --dry-run -i key=value
+one --agent flow execute <key> --dry-run --mock -i key=value
+one --agent flow execute <key> --allow-bash -i key=value
+one --agent flow runs [flowKey]
+one --agent flow resume <runId>
+```
+
+## Important Notes
+
+- Connection keys are inputs, not hardcoded — makes workflows portable
+- Action IDs in examples are placeholders — always use `actions search` to find real IDs
+- Code steps support `require('crypto')`, `require('buffer')`, `require('url')`, `require('path')` — `fs`, `http`, `child_process` are blocked
+- Bash steps require `--allow-bash` flag
+- State is persisted after every step — resume picks up where it left off
+- For bash+Claude steps, always set timeout to 180000+ and run sequentially (not in parallel)

package/skills/one/references/relay.md

@@ -0,0 +1,179 @@
+# One Webhook Relay
+
+Webhook relay receives webhooks from a source platform and forwards the event data to a destination platform using passthrough actions with Handlebars templates — no middleware, no code needed.
+
+## Supported Source Platforms
+
+Only these platforms can send webhooks: **Airtable**, **Attio**, **GitHub**, **Google Calendar**, **Stripe**. Any connected platform can be a destination.
+
+## Workflow
+
+### Step 1: Discover connections
+
+```bash
+one --agent connection list
+```
+
+Identify source (sends webhooks) and destination (receives forwarded data). Note both connection keys.
+
+### Step 2: Get event types
+
+```bash
+one --agent relay event-types <source-platform>
+```
+
+### Step 3: Get source knowledge (understand the incoming payload)
+
+```bash
+one --agent actions search <source-platform> "<event description>" -t knowledge
+one --agent actions knowledge <source-platform> <actionId>
+```
+
+The knowledge tells you the webhook payload structure — these fields become `{{payload.*}}` in your templates.
+
+### Step 4: Get destination knowledge (understand the outgoing API)
+
+```bash
+one --agent actions search <dest-platform> "<what you want to do>" -t execute
+one --agent actions knowledge <dest-platform> <actionId>
+```
+
+The knowledge tells you required body fields — these become the keys in your passthrough action's `body`.
+
+### Step 5: Create the relay endpoint
+
+```bash
+one --agent relay create \
+  --connection-key <source-connection-key> \
+  --description "Forward <event> from <source> to <dest>" \
+  --event-filters '["event.type"]' \
+  --create-webhook
+```
+
+Always use `--create-webhook` — it registers the webhook URL with the source platform automatically.
+
+### Step 6: Activate with a passthrough action
+
+```bash
+one --agent relay activate <relay-id> --actions '[{
+  "type": "passthrough",
+  "actionId": "<destination-action-id>",
+  "connectionKey": "<destination-connection-key>",
+  "body": {
+    "field": "{{payload.path.to.value}}"
+  },
+  "eventFilters": ["event.type"]
+}]'
+```
+
+## Template Context
+
+| Variable | Description |
+|---|---|
+| `{{relayEventId}}` | Unique relay event ID |
+| `{{platform}}` | Source platform name |
+| `{{eventType}}` | Webhook event type |
+| `{{payload}}` | Full incoming webhook body |
+| `{{timestamp}}` | When event was received |
+| `{{connectionId}}` | Source connection UUID |
+
+Access nested fields with dot notation: `{{payload.data.object.email}}`
+
+Use `{{json payload}}` to embed a full object as a JSON string.
+
+## Action Types
+
+### `passthrough` — Forward to another platform's API (primary)
+
+```json
+{
+  "type": "passthrough",
+  "actionId": "<action-id>",
+  "connectionKey": "<dest-connection-key>",
+  "body": { "channel": "#alerts", "text": "New: {{payload.data.object.name}}" },
+  "eventFilters": ["customer.created"]
+}
+```
+
+The `body`, `headers`, and `query` fields all support Handlebars templates.
+
+### `url` — Forward raw event to a URL
+
+```json
+{
+  "type": "url",
+  "url": "https://your-app.com/webhooks/handler",
+  "secret": "optional-signing-secret",
+  "eventFilters": ["customer.created"]
+}
+```
+
+### `agent` — Send to an agent
+
+```json
+{
+  "type": "agent",
+  "agentId": "<agent-uuid>",
+  "eventFilters": ["customer.created"]
+}
+```
+
+## Complete Example: Stripe customer.created -> Slack message
+
+```bash
+# 1. Get connections
+one --agent connection list
+# stripe: live::stripe::default::abc123, slack: live::slack::default::xyz789
+
+# 2. Get event types
+one --agent relay event-types stripe
+
+# 3. Get Slack send message action
+one --agent actions search slack "send message" -t execute
+one --agent actions knowledge slack <actionId>
+
+# 4. Create relay
+one --agent relay create \
+  --connection-key "live::stripe::default::abc123" \
+  --description "Notify Slack on new Stripe customers" \
+  --event-filters '["customer.created"]' \
+  --create-webhook
+
+# 5. Activate
+one --agent relay activate <relay-id> --actions '[{
+  "type": "passthrough",
+  "actionId": "<slack-send-message-action-id>",
+  "connectionKey": "live::slack::default::xyz789",
+  "body": {
+    "channel": "#alerts",
+    "text": "New Stripe customer: {{payload.data.object.name}} ({{payload.data.object.email}})"
+  },
+  "eventFilters": ["customer.created"]
+}]'
+```
+
+## Management Commands
+
+```bash
+one --agent relay list [--limit <n>] [--page <n>]
+one --agent relay get <id>
+one --agent relay update <id> [--actions <json>] [--description <desc>]
+one --agent relay delete <id>
+one --agent relay events [--platform <p>] [--event-type <t>] [--limit <n>]
+one --agent relay event <id>
+one --agent relay deliveries --endpoint-id <id>
+one --agent relay deliveries --event-id <id>
+```
+
+## Debugging
+
+1. Check endpoint is active: `one --agent relay get <id>` — verify `active: true`
+2. Check events arriving: `one --agent relay events --platform <p> --limit 5`
+3. Check delivery status: `one --agent relay deliveries --event-id <id>`
+4. Inspect payload: `one --agent relay event <id>` — verify template paths
+
+## Important Notes
+
+- 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