one

One CLI

You have access to the One CLI which lets you interact with 750+ third-party platforms through their APIs. Always include the --agent flag right after one for structured JSON output.

If the user wants a separate API key / connections for a specific project (vs. their default), walk them through running one init from that project folder and picking the "project" scope — see references/scoping.md. For monorepo subprojects (where a parent already has .git/package.json), have them mkdir .one in the subproject first so the config is keyed to that dir, not the monorepo root.

Authentication

one login                    # Browser-based login (opens app.withone.ai)
one logout                   # Clear local credentials

one login opens the browser for OAuth authentication and automatically creates and stores an API key. If already logged in, the user can choose to log in globally or for the current directory. one logout shows current session info and confirms before clearing credentials.

The consent page asks which harness will use the key (Claude Code, Codex, Cursor, …) and records the install location as tags on the key (scope:global / scope:project, path:, host:, user:, harness:, and device: unless telemetry is off). The CLI prints what it will send before opening the browser. one whoami shows the key's name once it is stored.

Onboarding a user with no prompts: run one init --auth browser — it opens a login window (the user authenticates there), saves the key, and auto-installs this skill, all without blocking on stdin. Add -g/-p for scope (default global). For CI/CD or headless environments, use one init --auth manual --api-key sk_live_....

Core Workflow: find -> execute

Always follow this sequence when the user wants to do something on a connected platform:

1. List connections

one --agent connection list

Returns connected platforms with their connection keys (needed for execution), platform names in kebab-case (needed for finding actions), and an access field per connection telling you what you may run there. access is what One enforces for this key (the choices made on the consent page, or later in the dashboard), narrowed by any limits set with one config; access.level names it the way the consent page does: full, read-write, read-only, custom or none. When telling the user their access, use those words (Full access, Read & write, Read only, Custom, No access).

Read access before you plan a workflow — it saves you from discovering a restriction as a 403 halfway through:

`access`	What it means
`{"policy": "full"}`	Every action on this connection is available
`{"policy": "methods", "methods": ["GET"]}`	Only actions with these HTTP methods will execute — don't propose writes
`{"policy": "actions", "actions": [...]}`	Only these exact actions may run. Each has `actionId`, `title`, `method` — use them directly: `actions load <actionId>` reads their docs, no find needed

accessSource is "server" when One reported the key's access, or "local" when it could not (the accessHint says so) — then access reflects only this CLI's settings and One may allow less: tell the user it is unverified rather than calling it full access.

Two more fields appear only when relevant:

"knowledgeOnly": true — actions execute is disabled. actions find returns each action's whole document with how to call it from code; write integration code instead of executing.
"unresolvedActionIds": [...] — allowlisted ids that couldn't be looked up; treat them as unavailable and tell the user.

An empty actions array means the allowlist grants nothing on that connection — say so rather than looking for alternatives.

1b. Delete a connection

one --agent connection delete <connection-key>

Removes a connection. Returns {"deleted": true, "platform": "...", "key": "..."} on success. Use the connection key from one --agent connection list.

2. Find every action the task needs, with its docs (READ them before executing)

one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>"

One call for the whole task: one platform and intent pair per operation, on any platforms (up to 10). One's decision model picks the action for each and returns it with its documentation: exactly what parameters are required, how to structure the request, and where each value goes. Never execute without reading it — without it you'll guess wrong on parameters.

intent names the operation alone, in a few words: "send a message to a channel", not "post 'deploy done' in #eng". IDs, names, and message text in the intent make the search miss.
--task (optional) is the whole job in one line, in general terms: "email a weather report to a contact", without names, addresses, IDs, or message text. It helps choose between similar actions.
-t knowledge searches the catalog for writing code and building flows and relays (it includes the platform's own passthrough endpoints); the default, -t execute, is the catalog for running actions now.
--ai-model (optional): the model you are running as (e.g. claude-sonnet-5), used to tune documentation per model.
--no-knowledge (optional): list the chosen actions without their documentation, when you only need the actionIds. Load the documentation with actions load before executing.
Platform names are lowercase; multi-word names use dashes: gmail, hubspot, ship-station, google-calendar.

Each entry of answers[] carries:

selected[] — the action(s) to use, each with actionId, title, method, path, and knowledge (its docs). More than one means the intent needs them together (look up, then update).
alsoSelected[] — also needed, listed rather than documented to keep the answer small: actions load them.
runnerUp — only when the model was unsure: a substitute for the pick. Use one or the other, never both.
alternatives[] — other candidates, undocumented.
status — why: a confidence; no action fits (rephrase the intent by outcome, or check the platform); the decision model was unavailable (the top search result — check it fits); not allowed by this CLI (the next allowed candidate stood in); or allow none of them (the access settings block the operation — tell the user, rephrasing won't help).

guide (once, at the end) says how to execute any of them.

Large docs come back as a digest (truncated: true): the request-building sections (method/URL, headers, description, rules, required + optional parameters, sample request, gotchas, error handling), then a notice naming what it left out with the exact command to load it. Sections named (appendix) are appended reference chunks or companion endpoints, not the action doc itself.

3. Load more of a document (only when you need it)

one --agent actions load <actionId> --section "Response Fields"   # by heading
one --agent actions load <actionId> --section response,optional    # by alias, several at once
one --agent actions load <actionId> --full                         # whole document
one --agent actions load <actionId> --toc                          # every heading, no text
one --agent actions load <actionId>                                # an alternative's digest

Served from the local cache once a doc is cached. Aliases: response, fields, optional, required, examples, errors, success, body, query, path, notes, behavior, gotchas. An unknown name returns the list of available sections — retry with one of those ids. Up to 10 action ids per call.

4. Execute

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
--mock — Return example response without making an API call (useful for building UI)
--skip-validation — Skip input validation against the action schema
--output <path> — Save response to a file (for binary downloads like PDFs, images, documents). Text responses (text/plain, HTML, CSV, XML) render inline automatically; --output is only needed for genuinely binary payloads.
--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 before executing. Missing params return a structured error with the flag name, parameter name, and description. Pass --skip-validation to bypass.

Examples:

# Simple GET
one --agent actions execute shopify <actionId> <connectionKey>

# POST with body data
one --agent actions execute hubspot <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"]}'

Parallel execution

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

one --agent actions execute --parallel \
  gmail send-email conn123 -d '{"to":"a@b.com"}' \
  -- slack post-message conn456 -d '{"text":"done"}'

All segments are validated before any execution. Failed actions don't block others. Use --max-concurrency <n> (default 5) to control batching. Agent-mode output: {"parallel":true,"results":[...],"succeeded":N,"failed":N,"totalDurationMs":N}. Each result carries "_preflight":{"cache":"hit"|"miss"} showing whether that action's details were served from cache.

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 lowercase; multi-word names use dashes (hubspot not HubSpot, google-calendar not googleCalendar)
Always use the exact action ID from a find answer — never guess or construct them
Always read the action's docs (from actions find) before executing — they have 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

Caching

Action documentation is cached locally (~/.one/cache/). actions find and actions load read it through the cache, and actions execute reuses the cached action details for its preflight lookup, so after a find (or a prior execute of the same action) it makes a single API call — the action itself. Find's picks are not cached: the decision model answers every call.

Cache is automatic — no setup required
Default TTL: 1 hour (configurable via ONE_CACHE_TTL env var)
In --agent mode, execute responses include "_preflight": {"cache": "hit"|"miss"}
Use --no-cache to force a fresh fetch: works on find, load, and execute (refreshes execute's action-details lookup)
Use actions load <actionId> --cache-status to check cache state without fetching
load --section <name> and --full read from the cached document — no extra API call once the doc is cached
Manage cache: one cache list, one cache clear, one cache update-all
Execution responses are NEVER cached — the action always runs live; only action metadata (docs, method, path, schema) is cached

Unified Memory

One ships a local memory store (a real Postgres process bootstrapped on demand via the bundled embedded-postgres plugin, with a postgres plugin available for remote/self-hosted Postgres) that backs both user-authored notes and synced platform data. one mem <cmd> is the primary surface; one sync is a namespaced alias (one mem sync ...) that writes synced rows into the same store.

Zero-config. The first one mem call on a new machine auto-initializes — no separate mem init step required. The embedded-postgres plugin downloads its Postgres binaries on first run (~52MB) and writes a daemon PID/port file at ~/.one/pg/.pgserve.json so subsequent CLI invocations reuse the running cluster. The daemon listens on 5434, or the next free port if another program holds it; pin one with one --agent mem config set embedded-postgres.port <n> (a conflict on a pinned port is an error, not a silent move). If an OpenAI key is already resolvable (env, .onerc, or config.openaiApiKey), embeddings enable automatically and search becomes hybrid FTS + semantic. Otherwise you get FTS-only with a structured _upgrade hint on every response telling the user how to upgrade.

Listing synced rows. mem list <type> takes a positional namespaced type — there is no --platform flag. Synced rows live under <platform>/<model> types:

one --agent mem list "gmail/threads"
one --agent mem list "attio/attioPeople" --limit 5
one --agent mem list "google-calendar/events"

Underneath, the store has no platform column — type is the only platform-scoping mechanism. If you need raw SQL via mem sql, filter with WHERE type LIKE 'platform/%' (not WHERE platform = ...).

# User memories
one --agent mem add note '{"content":"..."}' --tags work --weight 7
one --agent mem update <id> '{"status":"done"}'         # merges into data; refreshes searchable_text
one --agent mem search "deadline"                       # hybrid if key set, else FTS
one --agent mem list note --limit 20
one --agent mem link <from-id> <to-id> relates_to --bi

# Merge keys — the `keys[]` column (first-class, NOT data). Unique across ACTIVE
# records; archiving a record frees its keys. `mem update '{"keys":[...]}'` is rejected.
one --agent mem key <id> --add email:x@y.com            # add/--remove/--set — EDITS keys[]
one --agent mem find-by-source attio/attioPeople:abc-1  # ONE record (prefers the active owner)

# Identity keys — cross-platform lookup. READ-ONLY query, does not edit anything.
# Spans BOTH `keys[]` (record IS the entity) and `identity_keys[]` (record INVOLVES
# the entity: Gmail thread From/To/Cc, calendar attendees — never merges).
one --agent mem find-by-key email:jane@acme.com                # every record involving this person
one --agent mem find-by-key email:jane@acme.com --type gmail/gmailThreads
one --agent mem find-by-key email:a@x.com email:b@y.com        # intersection — records with BOTH

# Backfill searchable_text (no embedding provider needed) — fixes NULL/noisy text
one --agent mem reindex --searchable --type attio/attioPeople

# Status + diagnostics
one --agent mem status                                  # backend, provider, _upgrade hint
one --agent mem doctor                                  # full health report

Don't confuse mem key with mem find-by-key. mem key WRITES the merge column (keys[]) on one record — adding a key another active record already owns is an error, and --set replaces the whole array. mem find-by-key only READS, across both key columns. If you want "show me everything about this person", you always want find-by-key.

find-by-key agent output is grouped by record type:

{
  "keys": ["email:jane@acme.com"],
  "total": 13,
  "truncated": false,
  "fetchCap": 2000,
  "perTypeLimit": 10,
  "byType": {
    "attio/attioPeople": { "count": 1,  "items": [ {"id": "...", "type": "...", "data": {}, "keys": ["attio/attioPeople:J1", "email:jane@acme.com"], "updated_at": "..."} ] },
    "gmail/gmailThreads": { "count": 12, "items": [] }
  }
}

items are whole mem records. keys and identity_keys are OMITTED, not [], when the record has none — the contact above matched on keys[] and so carries no identity_keys field at all. Always read them as (item.identity_keys ?? []).

Read it in this order:

truncated — if true, more than fetchCap (2000) records matched. total and every count are then floors, and because rows come back ordered by type, whole types sorting after the cut are MISSING from byType entirely. Re-run with --type <type> to get an accurate answer; do not report the counts as-is.
total / count — ungrouped and per-type match counts (accurate when truncated is false).
items — whole mem records, same fields as mem get, capped at perTypeLimit (--limit, default 10). count > items.length just means display truncation — raise --limit.
keys — the key form that actually matched. Lookups are lowercased/trimmed first (matching how sync writes them), with a one-shot verbatim retry for hand-written mixed-case keys, so email:Jane@Acme.com finds email:jane@acme.com.

Adding OpenAI for semantic search

Stored at the top level of ~/.one/config.json as openaiApiKey, same precedence as ONE_SECRET (env > .onerc OPENAI_API_KEY=... > project > global). Three equivalent ways to set:

# Via re-run of one init (interactive prompt)
one init

# Via config set (writes to top-level, not the memory block)
one --agent mem config set embedding.apiKey sk-...

# Via env var (no persistence)
export OPENAI_API_KEY=sk-...

Syncing platforms into memory

# Check built-in profiles (pre-validated configs for common platforms)
one --agent sync profiles

# Setup — seeds from the built-in, merges your --config overrides
one --agent sync init stripe balanceTransactions
# If _complete: true and _test.ok: true → ready to run

# Preview what gets embedded BEFORE paying embedding cost (agent declares paths)
one --agent sync init attio attioPeople --config '{
  "memory": {
    "embed": true,
    "searchable": [
      "values.name[0].full_name",
      "values.job_title[0].value",
      "values.description[0].value",
      "values.email_addresses[0].email_address"
    ]
  }
}'
# Skip the "pick paths by reading the docs" step — let the CLI rank them from a live sample
one --agent sync suggest-searchable attio/attioPeople
# → { suggestions: [{path, score, hitRate, avgLength, noiseFraction, sampleValue}], configPatch: {...paste-ready...} }

one --agent sync test attio/attioPeople --show-searchable
# → Previews across 5 samples. Each path has { hits, total, sample }:
#     5/5 = path resolves on every record (clean)
#     1/5 = field is real but sparse on this page
#     0/5 = typo, or field never populated in sampled records
# Iterate until the numbers match intent.

# Run — memory is always written; pass --no-memory to skip (rare)
one --agent sync run stripe
one --agent sync schema stripe/customers         # inspect field paths/types before querying
one --agent sync query stripe/balanceTransactions --where "status=available" --limit 20
one --agent sync search "refund"                 # hybrid across all synced platforms
one --agent sync list stripe                     # progress + freshness

# Schedule unattended syncs
one sync schedule add stripe --every 1h

memory.searchable paths

Declared on the profile, drives what gets embedded + FTS-indexed. Supports numeric indexes AND [] wildcards for array fan-out:

values.name[0].full_name              # numeric index (first element)
messages[].snippet                    # wildcard — every element's .snippet
messages[].payload.parts[].body.data  # nested wildcards

Without declared paths, the default walker concatenates every string in the record — correct but often noisy for hierarchical APIs (Attio, HubSpot). Always declare paths for any profile with embed: true.

Sync rejects custom actions — profiles must use passthrough. sync init only surfaces passthrough models; sync run aborts if the list or enrich action is tagged custom. If no passthrough exists, compose a flow instead.

Connections are late-bound — profiles use "connection": { "platform": "<name>" }, not literal connectionKey strings. The key is resolved at sync time, so one add <platform> (re-auth) doesn't break the profile. For multi-account platforms, add "tag": "<connection-tag>" to disambiguate, and create the tagged connection with one add <platform> --tag <name>. Don't hardcode connection keys in profiles.

Extracting a flat field? Use derive, not transform. derive computes top-level fields from paths already in the record ("derive": { "from_email": { "path": "messages[0].payload.headers[name=From].value", "extract": "email" } }), using the same path syntax as identityKeys. transform spawns sh -c, so it needs jq on PATH and silently does nothing on Windows — never put one in a profile you intend to share. A path that resolves to nothing omits the field rather than writing null.

Installed profiles do not auto-update. sync run reads only .one/sync/profiles/<platform>_<model>.json and never merges the shipped built-in, so a profile created before a capability shipped silently lacks it — a pre-#167 gmail profile writes zero identity keys, forever, with no change in record counts. sync run warns when the built-in declares identityKeys / identityKey / enrich / dateFilter / memory that your copy lacks (agent mode: a profileDrift array). Fix with one sync init <platform> <model>, which patches rather than overwrites.

Cross-platform identity on a profile. Two separate fields, and picking the wrong one silently mangles data:

"identityKey": "properties.email" — singular. "This record IS this entity." One dot-path; the value lands in keys[] and MERGES records for the same entity across platforms (HubSpot + Attio for one person collapse into a single record).
"identityKeys": [{"prefix": "email", "path": "attendees[].email"}] — plural. "This record INVOLVES these people." Paths support [] wildcards and a [name=From] equality filter (Gmail headers). Values land in the separate identity_keys[] column, which does NOT merge — a 20-attendee event stays one event, not 20 contacts. Use this for anything with N participants.

Both are queryable with one --agent mem find-by-key <prefix>:<value>.

Enriching profiles (gmail/gmailThreads, fathom/meetings) sync in two phases: a list pass, then a detail pass that fetches full bodies/transcripts. Two things follow. Enrichment happens once per record by default — phase 2 only visits rows it has never enriched, and --full-refresh does not reset that (it reconciles deletions, it is not a detail refresh). To refresh detail content, either set enrich.invalidateOn in the profile to a list field that moves when the detail changes (historyId, updated_at) so only genuinely-changed records re-enrich automatically, or run one sync run <platform> --re-enrich to re-fetch every detail endpoint. And the list pass never overwrites an enriched record: data merges rather than replaces, and searchable_text / identity_keys[] are left alone. sync run reports these as memPreserved. So on an enriching profile without invalidateOn, a record whose upstream detail changed will look stale until you re-enrich — that is expected, not a sync failure.

Advanced features (enrich, transform, exclude, hooks, --full-refresh, alternative backends, embedding tuning): run one guide memory or one guide sync for the full reference.

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. To debug: flow execute <key> --dry-run (resolve interpolations without running), --stop-after <stepId> (run up to a step then stop), and flow inspect <runId> (a past run's per-step outputs).

Adding One Connect to an App

When the user is building an app whose own users should connect their tools (Gmail, Stripe, Slack...) to it, that is One Connect, not this CLI's connections. Install its skill inside the app, then follow it:

one --agent skills add connect      # from the @withone/connect version the app installed; latest from npm otherwise

It lands in .agents/skills/one-connect (and .claude/skills/one-connect). The result's next array says what to do; the skill covers the button, the two routes, key mode vs token mode, and calling One with the grant. Never ask the user to paste the client secret or connect key into chat.

Adding New Connections

If the user needs a platform that isn't connected yet, tell them to run:

one add <platform>
one add <platform> --tag <name>   # tag it (for multiple connections per platform)

This is interactive and opens the browser for OAuth. After connecting, the platform will appear in one --agent connection list. Use --tag when the user has (or will have) more than one connection for the same platform so sync/flow profiles can target a specific one via "connection": { "platform": "<name>", "tag": "<name>" }.

Removing Connections

To delete a connection that is no longer needed:

one --agent connection delete <connection-key>

The connection key comes from one --agent connection list. Returns {"deleted": true, "platform": "...", "key": "..."} on success.