' # Attach passthrough forwarding actions\none relay list # List existing relay endpoints\none relay events --platform # Inspect received events\none relay deliveries --endpoint-id # Check delivery status\n```\n\nStart with `one relay platforms` to discover which platforms support relay at all, then drill into `event-types ` for the specific events. Run `one guide relay` for the full reference including `--metadata` requirements per platform.\n\n### `one skills`\n\nOptional skills for your coding agent, installed on request. The One skill itself still comes from `one init` (and `one config skills sync|status`); these commands never touch it.\n\n```bash\none skills list # the One skill and each optional skill, with where it is installed\none skills add connect # the One Connect skill, into this project\none skills add connect --global # ...or for every project on this machine\none skills add connect --agents claude-code,windsurf # link exactly these agents\none skills update [connect] # re-copy after upgrading @withone/connect\none skills remove connect # remove it and the agent folders that point at it\n```\n\nWhat `one skills add connect` does:\n\n1. **Finds the skill** in the `@withone/connect` package your project installed (`node_modules/@withone/connect/skills/one-connect`), so your agent reads the docs for the exact SDK version your code calls. If the package isn't installed yet, it downloads the latest published package from npm and checks it against the registry's integrity hash first.\n2. **Installs it** into `.agents/skills/one-connect` (read by Codex, Cursor, Amp and OpenCode) and links `.claude/skills/one-connect` for Claude Code. Windsurf, Kiro, Goose and Roo get a link when the project already has their folder (`.windsurf`, `.kiro`, `.goose`, `.roo`). Where links aren't allowed (Windows without developer mode), it uses a junction, then a copy.\n3. **Stamps** the install with the package version in `.one-skill.json`.\n4. **Keeps it fresh**: any `one` command run in the project re-copies the skill when the installed `@withone/connect` version changes. Local files only; no network.\n\nCommit `.agents/skills/one-connect` and the agent links so your team's agents share the skill. Agent mode (`--agent`) returns JSON for every subcommand.\n\n### `one guide [topic]`\n\nGet the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).\n\n```bash\none guide # full guide (all topics)\none guide overview # setup, --agent flag, discovery workflow\none guide actions # search, knowledge, execute workflow\none guide flows # multi-step API workflows\n\none --agent guide # full guide as structured JSON\none --agent guide flows # single topic as JSON\n```\n\nTopics: `overview`, `actions`, `flows`, `relay`, `cache`, `sync`, `all` (default).\n\nIn agent mode (`--agent`), the JSON response includes the guide content and an `availableTopics` array so agents can discover what sections exist.\n\n### `one flow create [key]`\n\nCreate a workflow from a JSON definition. New workflows are always saved to the folder layout at `.one/flows//flow.json` (with a `lib/` subfolder scaffolded for code modules). Use `group/key` to place flows in a subdirectory group (e.g. `.one/flows/research/company-research/flow.json`). The legacy `.one/flows/.flow.json` single-file layout is deprecated; existing legacy files continue to load and run unchanged for backward compatibility.\n\n```bash\n# From a --definition flag\none flow create welcome-customer --definition '{\"key\":\"welcome-customer\",\"name\":\"Welcome\",\"version\":\"1\",\"inputs\":{},\"steps\":[]}'\n\n# Create in a subdirectory group\none flow create research/company-research --definition @flow.json\n\n# From stdin\ncat flow.json | one flow create\n\n# Custom output path\none flow create my-flow --definition '...' -o ./custom/path.json\n```\n\n| Option | What it does |\n|--------|-------------|\n| `--definition ` | Workflow definition as a JSON string |\n| `-o, --output ` | Custom output path (default: `.one/flows//flow.json`) |\n\n### `one flow execute `\n\nExecute a workflow by key or file path. Pass inputs with repeatable `-i` flags.\n\n```bash\n# Execute with inputs\none flow execute welcome-customer \\\n -i customerEmail=jane@example.com\n\n# Dry run - resolve every step's interpolations and show what they evaluate to,\n# without executing any step (catches wiring bugs without burning API credits)\none flow execute welcome-customer --dry-run -i customerEmail=jane@example.com\n\n# Stop after a specific step (isolate where a long flow breaks)\none flow execute welcome-customer --stop-after fetch-user -i customerEmail=jane@example.com\n\n# Combine: run steps up to a point for real, then dry-resolve the suspect step\n# against the REAL accumulated output (so $.steps.* references resolve too)\none flow execute welcome-customer --dry-run --stop-after send-email -i customerEmail=jane@example.com\n\n# Verbose - show each step as it runs\none flow execute welcome-customer -v -i customerEmail=jane@example.com\n```\n\nConnection inputs with a `connection` field in the workflow definition are auto-resolved when the user has exactly one connection for that platform.\n\nPress Ctrl+C during execution to pause - the run can be resumed later with `one flow resume `.\n\n| Option | What it does |\n|--------|-------------|\n| `-i, --input ` | Input parameter (repeatable) |\n| `--dry-run` | Resolve each step's interpolations and show what they evaluate to, without executing any step. `$.input.*`/`$.env.*` resolve up front; `$.steps.*` refs are reported as deferred (they're produced at runtime). |\n| `--mock` | With `--dry-run`: execute transforms/code with realistic mock API responses |\n| `--stop-after ` | Execute steps up to and including ``, then stop (later steps are not run). Combined with `--dry-run`, runs earlier steps for real and dry-resolves `` against their output without executing it. Inspect what ran with `one flow inspect `. |\n| `--skip-validation` | Skip input validation against action schemas |\n| `--allow-bash` | Allow bash step execution (disabled by default for security) |\n| `-v, --verbose` | Show full request/response for each step |\n| `--output-file ` | Stream the full result to a file instead of stdout — for large results that would otherwise be truncated or exceed the JSON string-size limit. stdout (and `--agent` output) then carries an `outputFile` pointer instead of inline `steps`. |\n\nStep-level `if`/`unless` conditions (and `while`/`condition` steps) are null-safe: a condition that references a skipped or not-yet-run step's output (e.g. `$.steps.maybeSkipped.output.x`) evaluates to `false` rather than crashing the run.\n\n### `one flow list`\n\nList all workflows saved in `.one/flows/`.\n\n```bash\none flow list\n```\n\n### `one flow validate `\n\nValidate a workflow JSON file against the schema.\n\n```bash\none flow validate welcome-customer\n```\n\n### `one flow resume `\n\nResume a paused or failed workflow run from where it left off.\n\n```bash\none flow resume abc123\none flow resume abc123 --allow-bash # required if the flow has bash steps\n```\n\n`--allow-bash` is gated the same way as on `flow execute` — resuming doesn't\ninherit the permission from the original run, so pass it again. `one flow list`\nshows which flows need it.\n\n### `one flow runs [flowKey]`\n\nList workflow runs, optionally filtered by workflow key.\n\n```bash\none flow runs # all runs\none flow runs welcome-customer # runs for a specific workflow\n```\n\n### `one flow inspect `\n\nInspect a past (or in-progress) run's per-step outputs — post-mortem debugging without re-running the flow. Every run persists a state file that records each step's output as it completes (and is preserved on failure), so this shows exactly how far the run got and what each step produced.\n\n```bash\none flow inspect abc123 # truncates large outputs\none flow inspect abc123 --full # full, pretty-printed outputs\n```\n\nPairs with `--stop-after`: run up to a step, then `one flow inspect ` to see its output.\n\n### `one config`\n\nConfigure access control for the MCP server. Optional - full access is the default.\n\n```bash\none config\n```\n\n| Setting | Options | Default |\n|---------|---------|---------|\n| Permission level | `admin` / `write` / `read` | `admin` |\n| Connection scope | All or specific connections | All |\n| Action scope | All or specific action IDs | All |\n| Knowledge-only mode | Enable/disable execution | Off |\n\nSettings propagate automatically to all installed agent configs.\n\nRun [`one list`](#one-list) to see the effect: each connection reports an `access` field describing exactly what these settings let you run on it.\n\n#### `one config skills status` / `one config skills sync`\n\n`one init` copies the packaged skill files (`SKILL.md`, `references/`) into `~/.agents/skills/one/` and symlinks per-agent paths to that canonical directory. When the CLI self-updates, the skill files in the canonical dir would normally stay frozen at the version that was installed. To prevent stale docs, every CLI command checks a `.one-cli-version` marker in the canonical dir and silently refreshes the skill files if they don't match the running CLI version. No user action required.\n\n| Command | What it does |\n|---------|--------------|\n| `one config skills status` | Show installed skill version, current CLI version, and path |\n| `one config skills sync` | Force a re-copy of packaged skill files (for troubleshooting) |\n\nAuto-sync refuses to resurrect skills if you opted out of skill installation during `one init` — the canonical dir has to already exist.\n\n### `one update`\n\nUpdates the CLI to the latest version (`npm install -g @withone/cli@latest`).\n\nThe CLI also **auto-updates in the background**: when a newer version has been published for more than 30 minutes, the next `one` command silently kicks off a global install. This is hardened against concurrent runs — a lock file in `~/.one/` ensures at most one install runs at a time (so parallel agent invocations can't collide and wedge npm), and the lock self-heals after 10 minutes if an install ever crashes or hangs.\n\n**Scheduled runs update too.** `one sync schedule` installs a crontab entry, and cron runs jobs with a bare `PATH=/usr/bin:/bin` — where an nvm, Volta, fnm, or Homebrew `npm` does not appear. The updater therefore resolves `npm` next to the running `node` binary rather than through `PATH`, and prepends node's own directory to the install's environment. Without this a scheduled install can never upgrade itself and stays pinned to the version that created it, forever.\n\nIf an install still doesn't land — a read-only prefix, a permissions problem, a node with no npm alongside it — the CLI **says so instead of retrying invisibly**. npm's own output is appended to `~/.one/auto-update.log`, and after three consecutive failed attempts a warning goes to **stderr** (never stdout, so it can't corrupt `--agent` JSON or a piped command) telling you to run the install by hand. That notice repeats at most once a day.\n\nTo disable background auto-updates entirely (e.g. on CI or a shared agent host), set:\n\n```bash\nexport ONE_NO_AUTO_UPDATE=1\n```\n\nRun `one update` manually whenever you want to upgrade.\n\n### Telemetry\n\nEvery `actions execute` call also tells One which surface and harness made it (`x-one-source: cli`, and `x-one-agent: claude-code` or whichever agent launched the CLI), so the dashboard's Logs page can show which agent ran each action. This is the call's own record in your account, not analytics, and it is sent whether or not telemetry is on. No version, arguments or data ride with it.\n\nThe CLI collects **usage analytics** — which command was run, the CLI version, OS/arch, and whether it ran in `--agent` mode — to help us prioritize improvements. Events are linked to your One account (user id, email, name, org) so they line up with your dashboard activity. **Command arguments, inputs, connection data, and secrets are never collected** (only the command name, e.g. `actions execute`). A one-time notice is shown on first run. Commands are aggregated locally and sent as periodic, batched roll-ups in the background, so telemetry never slows down or blocks a command (and stays lightweight even under heavy automation).\n\nTo opt out, set any of:\n\n```bash\nexport ONE_NO_TELEMETRY=1 # also accepted: ONE_DISABLE_TELEMETRY=1, or the cross-tool standard DO_NOT_TRACK=1\n```\n\nTelemetry is also disabled automatically when `CI=1`. You can persist the choice by adding `\"telemetry\": \"off\"` to `~/.one/config.json`.\n\n### Project config (`.onerc`)\n\nDrop a `.onerc` file in your project root to override global settings per-project. Simple `KEY=VALUE` format; `#` for comments. Read from the current working directory (no parent lookup).\n\n| Key | Purpose |\n|-----|---------|\n| `ONE_SECRET` | API key (also honored as env var) |\n| `ONE_API_BASE` | API base URL (also honored as env var) |\n| `ONE_PERMISSIONS` | `admin` / `write` / `read` |\n| `ONE_CONNECTION_KEYS` | Comma-separated connection-key allowlist |\n| `ONE_ACTION_IDS` | Comma-separated action-ID allowlist |\n| `ONE_KNOWLEDGE_AGENT` | `true` / `false` — knowledge-only mode |\n\nPrecedence: env var > `.onerc` > `~/.one/config.json`.\n\n```bash\n# .onerc\nONE_SECRET=sk_live_xxx\nONE_API_BASE=https://development-api.withone.ai\nONE_PERMISSIONS=read\n```\n\n> ⚠️ **Add `.onerc` to your `.gitignore`.** If you put `ONE_SECRET` in it, committing the file will leak your API key. Treat `.onerc` like `.env` — never check it in.\n\n### Relocating the CLI's state (`ONE_HOME`)\n\nEverything the CLI stores — `~/.one/config.json`, the knowledge cache, memory\ndatabases, sync schedules, and the installed skill files — is rooted at your\nhome directory. Set `ONE_HOME` to put it somewhere else:\n\n```bash\nexport ONE_HOME=/srv/one-state\none whoami # now reads /srv/one-state/.one/config.json\n```\n\nUseful for containers, CI runners, and shared/multi-tenant shells where the\naccount's home directory isn't the right place for per-workspace state. It\nworks identically on every platform — unlike `HOME`, which `os.homedir()`\nignores on Windows.\n\n## The workflow\n\nThe power of One is in the workflow. Every interaction follows the same pattern:\n\n```\none list → What am I connected to?\none actions find → What do I run, and how?\none actions execute → Do it.\n```\n\nThis is the same workflow whether you're sending emails, creating CRM contacts, processing payments, managing inventory, or posting to Slack. One pattern, any platform.\n\nFor multi-step workflows that chain actions across platforms:\n\n```\none actions find → Find each action, with its schema\none flow create → Define the workflow as JSON\none flow validate → Check it\none flow execute → Run it\n```\n\nWorkflows support conditions, loops, while loops, parallel execution, transforms, code steps, sub-flows, pagination, bash steps, and file I/O. Run `one guide flows` for the full schema reference and examples.\n\n## For AI agents\n\nIf you're an AI agent with only the `one` binary (no MCP server or IDE skills), start with `one --agent guide` to get the full usage guide as structured JSON. This teaches you the complete workflow, JSON schemas, selector syntax, and more - everything you need to bootstrap yourself.\n\nIf you're an AI agent using the One MCP server, the tools map directly:\n\n| MCP Tool | CLI Command |\n|----------|------------|\n| `list_one_integrations` | `one list` + `one platforms` |\n| `find_one_actions` | `one actions find` (and `one actions load` for its `load`) |\n| `execute_one_action` | `one actions execute` |\n\nThe workflow is the same: list → find → execute. Never execute without reading the docs find returns - they contain required parameter info and platform-specific details that are critical for building correct requests.\n\n## MCP server installation\n\n`one init` handles this automatically. Here's where configs go:\n\n| Agent | Global | Project |\n|-------|--------|---------|\n| Claude Code | `~/.claude.json` | `.mcp.json` |\n| Claude Desktop | Platform-specific app support dir | - |\n| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` | - |\n| Codex | `~/.codex/config.toml` | `.codex/config.toml` |\n| Kiro | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |\n\nProject configs can be committed to your repo. Each team member runs `one init` with their own API key.\n\n## Development\n\n```bash\nnpm run dev # watch mode\nnpm run build # production build\nnpm run typecheck # type check\n```\n","readmeFilename":"README.md"}
![\"npm](\"https://img.shields.io/npm/v/%40withone%2Fcli\")
\n \n ![\"platforms\"](\"https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.withone.ai%2Fopen%2Fcount%2Fplatforms\")
\n \n ![\"tools\"](\"https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.withone.ai%2Fopen%2Fcount%2Ftools\")
\n![\"One](\"https://assets.withone.ai/banners/cli.png\")
\n\n