cli

KO | EN

gitlite — search

#javascript #python #typescript #golang #rust #deep-learning #docker #macos #nodejs #awesome #kubernetes #pytorch #security #open-source

(★ 337)

A command-line tool to give your agents access to any app, create workflows and manage your One account.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - publish.yml
- cli.js
- - unified-memory.md
- - attioCompanies.json
  - attioPeople.json
- - meetings.json
- - gmailThreads.json
- - events.json
- - topStories.json
- - search.json
- - balanceTransactions.json
  - customers.json
- run-tests.mjs
- test-state-concurrency.mjs
- - SKILL.md
- - actions.preflight.test.ts
  - actions.ts
  - cache.ts
  - config.ts
  - connection.ts
  - flow-resume-allow-bash.test.ts
  - flow.outputfile.test.ts
  - flow.ts
  - guide.ts
  - init.ts
  - login.ts
  - logout.ts
  - mem.ts
  - onboard.ts
  - platforms.ts
  - relay.ts
  - update.ts
- - access.test.ts
  - access.ts
  - action-details.test.ts
  - action-details.ts
  - agents.test.ts
  - agents.ts
  - analytics.test.ts
  - analytics.ts
  - api-resolve.test.ts
  - api-text-response.test.ts
  - api-update-tags.test.ts
  - api.ts
  - browser.ts
  - cache.ts
  - config.test.ts
  - config.ts
  - dot-path.ts
  - flow-bash-envelope.test.ts
  - flow-debug.test.ts
  - flow-default-onerror.test.ts
  - flow-engine.test.ts
  - flow-engine.ts
  - flow-file-read-schema.test.ts
  - flow-runner.test.ts
  - flow-runner.ts
  - flow-schema.ts
  - flow-types.ts
  - flow-validator.module-refs.test.ts
  - flow-validator.nested-refs.test.ts
  - flow-validator.test.ts
  - flow-validator.ts
  - guide-content.ts
  - home.test.ts
  - home.ts
  - output.test.ts
  - output.ts
  - platform-meta.ts
  - platforms.ts
  - skill-sync.ts
  - table.ts
  - types.ts
  - validate.ts
  - version.test.ts
  - version.ts
- - home.ts
- cli.ts
- index.ts
.gitignore
CLAUDE.md
package-lock.json
package.json
README.md
test-flow-features.ts
tsconfig.json
tsup.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="https://withone.ai">Website</a>
 &nbsp;·&nbsp;
 <a href="https://withone.ai/docs">Docs</a>
 &nbsp;·&nbsp;
 <a href="https://app.withone.ai">Dashboard</a>
 &nbsp;·&nbsp;
 <a href="https://withone.ai/changelog">Changelog</a>
 &nbsp;·&nbsp;
 <a href="https://x.com/withoneai">X</a>
 &nbsp;·&nbsp;
 <a href="https://linkedin.com/company/withoneai">LinkedIn</a>

One gives your AI agent authenticated access to 600+ platforms - Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else - through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.

## Install

```bash
npx @withone/cli@latest init
```

Or install globally:

```bash
npm install -g @withone/cli
one init
```

`one init` walks you through setup: authenticate via browser or enter your [API key](https://app.withone.ai/settings/api-keys), pick your AI agents, and you're done. The MCP server gets installed automatically.

Or authenticate directly:

```bash
one login              # Opens browser for authentication (global or per-directory)
one logout             # Clear credentials (with scope picker and confirmation)
```

Requires Node.js 18+. `one sync` additionally needs Node 20+, because its
local SQLite engine (`better-sqlite3`, an optional dependency) ships prebuilt
binaries only for Node 20 and above. On Node 18 every other command works
normally; `one sync` reports that the engine isn't installed.

## Quick start

```bash
# Connect a platform
one add gmail

# See what you're connected to
one list

# Search for actions you can take
one actions search gmail "send email" -t execute

# Read the docs for an action
one actions knowledge gmail <actionId>

# Execute it
one actions execute gmail <actionId> <connectionKey> \
 -d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'
```

That's it. Five commands to go from zero to sending an email through Gmail's API - fully authenticated, correctly formatted, without touching a single OAuth token.

### Multi-step flows

Chain actions across platforms into reusable workflows:

```bash
# Create a flow that looks up a Stripe customer and sends a Gmail welcome email
one flow create welcome-customer --definition '{
 "key": "welcome-customer",
 "name": "Welcome New Customer",
 "version": "1",
 "inputs": {
 "stripeKey": { "type": "string", "required": true, "connection": { "platform": "stripe" } },
 "gmailKey": { "type": "string", "required": true, "connection": { "platform": "gmail" } },
 "email": { "type": "string", "required": true }
 },
 "steps": [
 { "id": "find", "name": "Find customer", "type": "action",
 "action": { "platform": "stripe", "actionId": "<actionId>", "connectionKey": "$.input.stripeKey",
 "data": { "query": "email:'\''{{$.input.email}}'\''" } } },
 { "id": "send", "name": "Send email", "type": "action",
 "if": "$.steps.find.response.data.length > 0",
 "action": { "platform": "gmail", "actionId": "<actionId>", "connectionKey": "$.input.gmailKey",
 "data": { "to": "{{$.input.email}}", "subject": "Welcome!", "body": "Thanks for joining." } } }
 ]
}'

# Validate it
one flow validate welcome-customer

# Run it - connection keys auto-resolve if you have one connection per platform
one flow execute welcome-customer -i email=jane@example.com
```

Workflows live under `.one/flows/<key>/flow.json` with an optional `lib/` subfolder for `.mjs` code modules — create new flows in this folder layout. Flows can be organized into subdirectory groups: `.one/flows/<group>/<key>/flow.json`. Reference them as `group/key` or just the bare key if unique. (The legacy single-file layout `.one/flows/<key>.flow.json` is deprecated but still loads for backward compatibility.) Flows support conditions, loops, while loops, parallel steps, transforms, sub-flows, pagination, bash steps, and external `.mjs` code modules. Run `one guide flows` for the full reference.

## How it works

```
Your AI Agent
    ↓
  One CLI
    ↓
  One API (api.withone.ai/v1/passthrough)
    ↓
  Gmail / Slack / Shopify / HubSpot / Stripe / ...
```

Every API call routes through One's passthrough proxy. One injects the right credentials, handles rate limiting, and normalizes responses. You never see or manage raw OAuth tokens - your connection key is all you need.

## Commands

### `one init`

Set up your API key and install the MCP server into your AI agents.

```bash
one init
```

Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro.

**Global vs. project scope.** `one init` is interactive and asks where the setup should live:

- **Global** (`~/.one/config.json`) — applies to every folder. Best when you only need one workspace / API key.
- **Project** (`~/.one/projects/<slug>/config.json`) — scoped to the current project, stored under your home directory so secrets never land in git. Use this when different projects need different API keys, connections, or access control.

When you run `one` in a project, it uses the project config if one exists and falls back to the global config otherwise. Use `one config path` to see which config is active and the full resolution order.

In a monorepo, the project root is the nearest ancestor with `.one/`, `.git`, or `package.json` — checked in that order. Run `mkdir .one` in a nested subproject to make it its own project root (so the config is keyed by the nested dir's slug instead of the monorepo's). Your home directory itself is never treated as a project root — `~/.one` is the CLI's own config directory, and a dotfiles `.git` or stray `package.json` in `$HOME` shouldn't turn everything under home into one project. Scope that applies to all of home is the global config.

If you've already set up, `one init` shows your current status for the active scope and lets you update your key, install to more agents, or reconfigure.

**Agent-driven setup (no prompts).** Pass `--auth` and `one init` runs end-to-end without any terminal interaction — handy when an AI agent is onboarding you. It saves the key, auto-installs the One skill, and skips the connect step (`one add` later).

```bash
one init --auth browser            # opens a login window; you authenticate, the window closes — done
one init --auth manual --api-key sk_live_...   # headless / CI, no browser
```

| Flag | What it does |
|------|-------------|
| `-y` | Skip confirmations |
| `-g` | Non-interactive: write the One config globally (`~/.one/config.json`) |
| `-p` | Non-interactive: write the One config for this project (`~/.one/projects/<slug>/config.json`) |
| `--auth <browser\|manual>` | Run setup with **no prompts**. `browser` opens a login window; `manual` uses `--api-key`. Scope from `-g`/`-p` (default global). |
| `--api-key <key>` | API key for `--auth manual` (`sk_live_…` / `sk_test_…`) |
| `--openai-key <key>` | Optional OpenAI key for `one mem` semantic search |

### `one add <platform>`

Connect a new platform via OAuth.

```bash
one add shopify
one add hubspot
one add gmail
one add gmail --tag work        # tag the connection
```

Opens your browser, you authorize, done. The CLI polls until the connection is live. Platform names are lowercase (with dashes for multi-word names) - run `one platforms` to see them all.

| Flag | What it does |
|------|-------------|
| `--tag <name>` | Tag the new connection once it's created. Lets sync/flow profiles target a specific connection via `"connection": { "platform": "gmail", "tag": "work" }` when you have several connections for one platform (e.g. personal vs work Gmail). |

### `one list`

List your active connections with their status, connection keys, and what your access config lets you run on each.

```bash
one list
```

```
  ● gmail       operational   live::gmail::default::abc123
  ● slack       operational   live::slack::default::def456
  ● shopify     operational   live::shopify::default::ghi789
```

You need the connection key (rightmost column) when executing actions.

**Access reporting.** Every connection carries an `access` field describing what the current [access control](#one-config) config permits — so an agent knows its reach up front instead of discovering it as a failure mid-workflow. Three policies:

| Policy | Means | Shown when |
|--------|-------|-----------|
| `{"policy": "full"}` | Every action on the connection | Default (admin, no action allowlist) |
| `{"policy": "methods", "methods": ["GET"]}` | Only actions with those HTTP methods | Permission level is `read` or `write` |
| `{"policy": "actions", "actions": [{"actionId": "...", "title": "...", "method": "..."}]}` | Only these specific actions | An action allowlist is configured |

An action allowlist wins over the permission level (and is then method-filtered by it). When the policy is `actions`, those actions are exactly what may run — no `actions search` needed.

```jsonc
// one --agent list
{
  "total": 2,
  "showing": 2,
  "connections": [
    {
      "platform": "gmail",
      "state": "operational",
      "key": "live::gmail::default::abc123",
      "access": { "policy": "methods", "methods": ["GET"] }
    }
  ],
  "accessHint": "Permission level \"read\": only GET actions will execute."
}
```

`knowledgeOnly: true` appears when knowledge-only mode is on (execution disabled), and `unresolvedActionIds` lists any allowlisted action ids that could not be looked up. In human output, an `Access` column and a summary note appear only when access is actually scoped.

This mirrors the `access` field on the One MCP server's `list_one_integrations` tool, so both surfaces report access the same way.

### `one connection delete <connection-key>`

Remove a connection by its key.

```bash
one connection delete live::gmail::default::abc123
one connection rm live::gmail::default::abc123      # alias
```

Shows the connection details and asks for confirmation before deleting. Use `--force` to skip the confirmation prompt.

| Option | What it does |
|--------|-------------|
| `-f, --force` | Skip confirmation prompt |

### `one platforms`

Browse all 600+ available platforms.

```bash
one platforms              # all platforms
one platforms -c "CRM"     # filter by category
one platforms --json       # machine-readable output
```

### `one actions search <platform> <query>`

Search for API actions on a connected platform using natural language.

```bash
one actions search shopify "list products"
one actions search hubspot "create contact" -t execute
one actions search gmail "send email"
```

Returns the top 5 matching actions with their action IDs, HTTP methods, and paths. Use `-t execute` when you intend to run the action, or `-t knowledge` (default) when you want to learn about it or write code against it.

### `one actions knowledge <platform> <actionId>`

Get the full documentation for an action - parameters, validation rules, request/response structure, examples, and the exact API request format.

```bash
one actions knowledge shopify 67890abcdef
```

Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.

### `one actions execute <platform> <actionId> <connectionKey>`

Execute an API action on a connected platform.

```bash
# Simple GET
one actions execute shopify <actionId> <connectionKey>

# POST with data
one actions execute hubspot <actionId> <connectionKey> \
 -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'

# With path variables
one actions execute shopify <actionId> <connectionKey> \
 --path-vars '{"order_id": "12345"}'

# With query params
one actions execute stripe <actionId> <connectionKey> \
 --query-params '{"limit": "10"}'
```

| Option | What it does |
|--------|-------------|
| `-d, --data <json>` | Request body (POST, PUT, PATCH) |
| `--path-vars <json>` | Replace `{variables}` in the URL path |
| `--query-params <json>` | Query string parameters |
| `--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 |
| `--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 genuine binary downloads — PDFs, images). Text responses (text/plain, HTML, CSV, XML) render inline automatically. |
| `--no-cache` | Bypass the cached action details and re-fetch them; the fresh details still refresh the cache (execution itself is never cached) |

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.

#### Parallel execution

Execute multiple actions concurrently with `--parallel`, separating each action with `--`:

```bash
one --agent actions execute --parallel \
  gmail send-email conn123 -d '{"to":"a@b.com","subject":"Hi","body":"Hello"}' \
  -- slack post-message conn456 -d '{"channel":"#general","text":"Done"}' \
  -- google-sheets append-row conn789 -d '{"values":["x","y"]}'
```

Each segment follows the same format: `<platform> <actionId> <connectionKey> [-d ...] [--path-vars ...] [--query-params ...]`. All segments are validated upfront before any execution starts. Results are collected via `Promise.allSettled` — if one fails, the rest still complete.

| Option | What it does |
|--------|-------------|
| `--parallel` | Enable parallel mode |
| `--max-concurrency <n>` | Max concurrent actions per batch (default: 5) |

Agent-mode output includes `parallel: true`, per-action `status`/`durationMs`/`response`/`_preflight` (`{"cache":"hit"|"miss"}`), plus `totalDurationMs`, `succeeded`, and `failed` counts.

### `one cache`

Manage the local cache for knowledge and search responses. The CLI automatically caches `actions knowledge` and `actions search` results so repeated calls serve instantly from disk. `actions execute` reuses the cached action details (method, path, validation schema) for its preflight lookup, so a knowledge call followed by execute costs a single API round trip.

```bash
one cache list # List all cached entries with age and status
one cache list --expired # Show only expired entries
one cache clear # Clear all cached data
one cache clear <actionId> # Clear a specific entry
one cache update-all # Re-fetch fresh data for all cached entries
```

Knowledge and search commands also support cache flags:

```bash
one actions knowledge gmail <actionId> --no-cache # Skip cache, fetch fresh
one actions knowledge gmail <actionId> --cache-status # Check cache status
one actions search gmail "send email" --no-cache # Skip cache for search
one actions execute gmail <actionId> <key> --no-cache # Fresh action-details lookup
```

Default TTL is 1 hour. Configure via `ONE_CACHE_TTL` environment variable or `cacheTtl` in `~/.one/config.json`.

Note: execution responses are never cached — the action always runs live. Only action metadata (docs, method, path, schema) is cached, and agent-mode execute output reports it via `"_preflight": {"cache": "hit"|"miss"}`.

### `one mem` — unified memory store

One ships a local memory store (a real Postgres process bootstrapped on demand via the bundled `embedded-postgres` plugin, with a `postgres` plugin for remote/self-hosted) that backs both user-authored notes and synced platform data. **Zero-config** — the first `one mem` call on a fresh machine auto-initializes the cluster at `~/.one/pg/cluster/` and writes a daemon PID file so subsequent CLI invocations reuse it.

```bash
# User memories — works immediately on a new install
one mem add note '{"content":"Design review is Thursday"}' --tags work --weight 7
one mem update <id> '{"status":"done"}' # merges into data; refreshes searchable_text
one mem search "design review" # hybrid FTS + semantic (if key set)
one mem list note --limit 20

# Merge keys (`keys[]`) are a first-class column (unique across ACTIVE records;
# archiving frees them). Manage them after creation with `mem key` — NOT `mem update`.
one mem key <id> --add email:x@y.com # also --remove / --set <csv>

# Find every record tied to a person/company, grouped by type. Spans BOTH columns:
# `keys[]` (this record IS the entity — drives merge) and `identity_keys[]` (this
# record INVOLVES the entity — Gmail thread participants, calendar attendees; never merges).
one mem find-by-key email:jane@acme.com              # every record carrying the key
one mem find-by-key email:jane@acme.com --type gmail/gmailThreads
one mem find-by-key email:jane@acme.com email:bob@acme.com   # intersection — records with BOTH

# Backfill searchable_text for rows that landed NULL or with UUID-noise-heavy text
# (drops ids/timestamps, leads with name/title/email). No embedding provider needed.
one mem reindex --searchable --type attio/attioPeople

# Listing synced platform rows — type is positional and namespaced as <platform>/<model>;
# there is NO --platform flag and NO platform column in the schema.
one mem list "gmail/threads"
one mem list "attio/attioPeople" --limit 5

# Enable semantic search (optional)
one init                                             # re-run — prompts for OpenAI key
# OR
one mem config set embedding.apiKey sk-...           # writes top-level openaiApiKey
# OR
export OPENAI_API_KEY=sk-...                         # no persistence

# Status + diagnostics
one mem status                                       # backend, provider, _upgrade hint
one mem doctor                                       # 7-check health report
```

Key surfaces: `add`, `get`, `update`, `archive`, `list`, `search` (`--deep` forces semantic), `context`, `link`/`linked`/`unlink`, `key`, `sources`, `find-by-source`, `find-by-key`, `export`, `import`, `migrate`, `vacuum`, `reindex`. Run `one guide memory` for the full reference.

`find-by-key` is the cross-platform join: keys are matched **case-insensitively** (they are lowercased on write, and the query is lowercased to match), `--type` narrows to one record type, and `--limit` (default 10) caps how many records are *shown per type* while the reported per-type `count` and overall `total` stay full match counts. Above 2000 matches the response flags `truncated` and the counts become floors — re-run with `--type` for an exact answer. Populate `identity_keys[]` from a sync profile's `identityKeys` field (see `one guide sync`), which ships pre-wired for `gmail/gmailThreads`, `google-calendar/events`, and `fathom/meetings`.

### `one sync` (and `one mem sync` alias)

Sync platform data into the unified memory store for instant queries, hybrid FTS + semantic search, scheduled refresh, and change-driven automation. Memory is always written; pass `--no-memory` to skip (rare).

```bash
# Discover → init (seeds from built-in, auto-tests) → declare searchable → preview → run
one sync models stripe
one sync init stripe balanceTransactions

# Optional: declare clean fields for embedding, then preview
one sync init stripe balanceTransactions --config '{
  "memory": {
    "embed": true,
    "searchable": ["description","type","amount","currency"]
  }
}'
one sync test stripe/balanceTransactions --show-searchable

# Run — every row lands in memory (SQLite also written for enrich-phase compat)
one sync run stripe --since 90d
one mem sync run stripe                              # identical (alias)
# Profiles with `enrich` run a second detail pass. It enriches each record ONCE;
# the list pass thereafter merges rather than replaces, so the enriched payload
# survives (reported as `memPreserved`). `--full-refresh` reconciles deletions,
# it does not refresh detail content. To refresh detail:
one sync run gmail --re-enrich                       # re-fetch every detail endpoint
# ...or set `enrich.invalidateOn` in the profile (e.g. "historyId", "updated_at")
# so only records that actually changed upstream are re-enriched, automatically.

# Query + search (reads from memory)
one sync query stripe/balanceTransactions --where "status=available" --limit 20
one sync query stripe/customers --where 'address.city=SF'   # dotted paths supported
one sync search "refund"                             # hybrid, per-type

# Schedule unattended syncs + change hooks
one sync schedule add stripe --every 1h
one sync init stripe balanceTransactions --config '{"onInsert":"one flow execute handle-new-txn"}'

# Deletion detection
one sync run stripe --full-refresh
```

> **Sync uses passthrough actions only.** Profiles referencing a custom/composer action are rejected at runtime. `sync models` already filters to passthrough-only; if a model has no passthrough list endpoint, compose a flow instead of syncing.

> **Connections are late-bound.** Profiles use `"connection": { "platform": "<name>", "tag"?: "..." }` instead of literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. `tag` only needed for multi-account platforms (e.g. two Gmail accounts).

> **`memory.searchable` paths.** Drives what gets embedded + FTS-indexed. Supports numeric indexes (`values.name[0].full_name`) and `[]` wildcards (`messages[].snippet`, `messages[].payload.parts[].body.data`). Without declared paths the default walker concatenates every string — correct but noisy for hierarchical APIs. Always declare when `embed: true`.

| Subcommand | What it does |
|------------|-------------|
| `profiles [platform]` | List built-in pre-validated profiles |
| `doctor` | Verify sync engine health |
| `models <platform>` | Discover available data models |
| `init <platform> <model>` | Create/patch profile (seeds from built-in, auto-tests) |
| `test <platform>/<model>` | Validate profile. `--show-searchable` previews embedded text |
| `run <platform>` | Sync data (`--full-refresh`, `--since`, `--dry-run`, `--no-memory`) |
| `query <platform>/<model>` | Query memory with `--where` (dotted paths), `--after/before` |
| `search <query>` | Hybrid FTS + semantic across all synced data |
| `list [platform]` | Show profiles, record counts, freshness |
| `schedule add/list/status/remove/repair` | Cron-backed scheduled syncs with drift detection |
| `remove <platform>` | Delete synced data (`--dry-run` to preview) |

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` or `one guide memory` 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 # 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).

```bash
one guide                 # full guide (all topics)
one guide overview        # setup, --agent flag, discovery workflow
one guide actions         # search, knowledge, execute workflow
one guide flows           # multi-step API workflows

one --agent guide         # full guide as structured JSON
one --agent guide flows   # single topic as JSON
```

Topics: `overview`, `actions`, `flows`, `relay`, `cache`, `sync`, `all` (default).

In agent mode (`--agent`), the JSON response includes the guide content and an `availableTopics` array so agents can discover what sections exist.

### `one flow create [key]`

Create a workflow from a JSON definition. New workflows are always saved to the folder layout at `.one/flows/<key>/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/<key>.flow.json` single-file layout is deprecated; existing legacy files continue to load and run unchanged for backward compatibility.

```bash
# From a --definition flag
one flow create welcome-customer --definition '{"key":"welcome-customer","name":"Welcome","version":"1","inputs":{},"steps":[]}'

# Create in a subdirectory group
one flow create research/company-research --definition @flow.json

# From stdin
cat flow.json | one flow create

# Custom output path
one flow create my-flow --definition '...' -o ./custom/path.json
```

| Option | What it does |
|--------|-------------|
| `--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 workflow by key or file path. Pass inputs with repeatable `-i` flags.

```bash
# Execute with inputs
one flow execute welcome-customer \
  -i customerEmail=jane@example.com

# Dry run - resolve every step's interpolations and show what they evaluate to,
# without executing any step (catches wiring bugs without burning API credits)
one flow execute welcome-customer --dry-run -i customerEmail=jane@example.com

# Stop after a specific step (isolate where a long flow breaks)
one flow execute welcome-customer --stop-after fetch-user -i customerEmail=jane@example.com

# Combine: run steps up to a point for real, then dry-resolve the suspect step
# against the REAL accumulated output (so $.steps.* references resolve too)
one flow execute welcome-customer --dry-run --stop-after send-email -i customerEmail=jane@example.com

# Verbose - show each step as it runs
one flow execute welcome-customer -v -i customerEmail=jane@example.com
```

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>`.

| Option | What it does |
|--------|-------------|
| `-i, --input <name=value>` | Input parameter (repeatable) |
| `--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). |
| `--mock` | With `--dry-run`: execute transforms/code with realistic mock API responses |
| `--stop-after <stepId>` | Execute steps up to and including `<stepId>`, then stop (later steps are not run). Combined with `--dry-run`, runs earlier steps for real and dry-resolves `<stepId>` against their output without executing it. Inspect what ran with `one flow inspect <runId>`. |
| `--skip-validation` | Skip input validation against action schemas |
| `--allow-bash` | Allow bash step execution (disabled by default for security) |
| `-v, --verbose` | Show full request/response for each step |
| `--output-file <path>` | 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`. |

Step-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.

### `one flow list`

List all workflows saved in `.one/flows/`.

```bash
one flow list
```

### `one flow validate <key>`

Validate a workflow JSON file against the schema.

```bash
one flow validate welcome-customer
```

### `one flow resume <runId>`

Resume a paused or failed workflow run from where it left off.

```bash
one flow resume abc123
one flow resume abc123 --allow-bash    # required if the flow has bash steps
```

`--allow-bash` is gated the same way as on `flow execute` — resuming doesn't
inherit the permission from the original run, so pass it again. `one flow list`
shows which flows need it.

### `one flow runs [flowKey]`

List workflow runs, optionally filtered by workflow key.

```bash
one flow runs                    # all runs
one flow runs welcome-customer   # runs for a specific workflow
```

### `one flow inspect <runId>`

Inspect 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.

```bash
one flow inspect abc123          # truncates large outputs
one flow inspect abc123 --full   # full, pretty-printed outputs
```

Pairs with `--stop-after`: run up to a step, then `one flow inspect <runId>` to see its output.

### `one config`

Configure access control for the MCP server. Optional - full access is the default.

```bash
one config
```

| Setting | Options | Default |
|---------|---------|---------|
| Permission level | `admin` / `write` / `read` | `admin` |
| Connection scope | All or specific connections | All |
| Action scope | All or specific action IDs | All |
| Knowledge-only mode | Enable/disable execution | Off |

Settings propagate automatically to all installed agent configs.

Run [`one list`](#one-list) to see the effect: each connection reports an `access` field describing exactly what these settings let you run on it.

#### `one config skills status` / `one config skills sync`

`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.

| Command | What it does |
|---------|--------------|
| `one config skills status` | Show installed skill version, current CLI version, and path |
| `one config skills sync` | Force a re-copy of packaged skill files (for troubleshooting) |

Auto-sync refuses to resurrect skills if you opted out of skill installation during `one init` — the canonical dir has to already exist.

### `one update`

Updates the CLI to the latest version (`npm install -g @withone/cli@latest`).

The 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.

To disable background auto-updates entirely (e.g. on CI or a shared agent host), set:

```bash
export ONE_NO_AUTO_UPDATE=1
```

Run `one update` manually whenever you want to upgrade.

### Telemetry

The 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).

To opt out, set any of:

```bash
export ONE_NO_TELEMETRY=1     # also accepted: ONE_DISABLE_TELEMETRY=1, or the cross-tool standard DO_NOT_TRACK=1
```

Telemetry is also disabled automatically when `CI=1`. You can persist the choice by adding `"telemetry": "off"` to `~/.one/config.json`.

### Project config (`.onerc`)

Drop 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).

| Key | Purpose |
|-----|---------|
| `ONE_SECRET` | API key (also honored as env var) |
| `ONE_API_BASE` | API base URL (also honored as env var) |
| `ONE_PERMISSIONS` | `admin` / `write` / `read` |
| `ONE_CONNECTION_KEYS` | Comma-separated connection-key allowlist |
| `ONE_ACTION_IDS` | Comma-separated action-ID allowlist |
| `ONE_KNOWLEDGE_AGENT` | `true` / `false` — knowledge-only mode |

Precedence: env var > `.onerc` > `~/.one/config.json`.

```bash
# .onerc
ONE_SECRET=sk_live_xxx
ONE_API_BASE=https://development-api.withone.ai
ONE_PERMISSIONS=read
```

> ⚠️ **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.

### Relocating the CLI's state (`ONE_HOME`)

Everything the CLI stores — `~/.one/config.json`, the knowledge cache, memory
databases, sync schedules, and the installed skill files — is rooted at your
home directory. Set `ONE_HOME` to put it somewhere else:

```bash
export ONE_HOME=/srv/one-state
one whoami          # now reads /srv/one-state/.one/config.json
```

Useful for containers, CI runners, and shared/multi-tenant shells where the
account's home directory isn't the right place for per-workspace state. It
works identically on every platform — unlike `HOME`, which `os.homedir()`
ignores on Windows.

## The workflow

The power of One is in the workflow. Every interaction follows the same pattern:

```
one list                    → What am I connected to?
one actions search          → What can I do?
one actions knowledge       → How do I do it?
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:

```
one actions knowledge       → Learn each action's schema
one flow create             → Define the workflow as JSON
one flow validate           → Check it
one flow execute            → Run it
```

Workflows 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.

## For AI agents

If 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.

If you're an AI agent using the One MCP server, the tools map directly:

| MCP Tool | CLI Command |
|----------|------------|
| `list_one_integrations` | `one list` + `one platforms` |
| `search_one_platform_actions` | `one actions search` |
| `get_one_action_knowledge` | `one actions knowledge` |
| `execute_one_action` | `one actions execute` |

The workflow is the same: list → search → knowledge → execute. Never skip the knowledge step - it contains required parameter info and platform-specific details that are critical for building correct requests.

## MCP server installation

`one init` handles this automatically. Here's where configs go:

| Agent | Global | Project |
|-------|--------|---------|
| Claude Code | `~/.claude.json` | `.mcp.json` |
| Claude Desktop | Platform-specific app support dir | - |
| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | - |
| Codex | `~/.codex/config.toml` | `.codex/config.toml` |
| Kiro | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |

Project configs can be committed to your repo. Each team member runs `one init` with their own API key.

## Development

```bash
npm run dev        # watch mode
npm run build      # production build
npm run typecheck  # type check
```

cli

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

cli

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README