Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ one login # Opens the browser to sign in and create a key
one logout # Clear local credentials
```

The first `one login` writes the global config; once a key exists it asks whether the new one applies globally or to this directory. For a project key from the start, use `one init -p`. `one logout` asks which config to clear when both a project and a global config exist, and deletes the whole file (API key, OpenAI key, access control and memory settings). The API key itself stays active until you revoke it in the dashboard.
The first `one login` writes the global config; once a key exists it asks whether the new one applies globally or to this directory. For a project key from the start, use `one init -p`. `one logout` asks which config to clear when both a project and a global config exist, and deletes the whole file (API key, OpenAI key, access control and memory settings). With `--agent` there's no prompt: it needs `--force` (without it, it returns `confirmation_required` and the config it would clear), and it clears only the config in effect (the project config if there is one) unless you pass `--scope global` or `--scope both`. The API key itself stays active until you revoke it in the dashboard.

The browser consent page names the key and tags it with where this CLI is installed (scope, project path, machine, OS user, CLI version, chosen harnesses, and the per-install device id unless telemetry is off) so you can find and revoke it from Settings → API keys. The terminal prints exactly what will be sent before the browser opens.

Expand Down Expand Up @@ -422,6 +422,7 @@ One ships a local memory store (a real Postgres process bootstrapped on demand v
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" # FTS; hybrid with an OpenAI key + pgvector
one mem search "design review" --deep # hybrid or an error naming what's missing (no FTS fallback)
one mem list note --limit 20

# Merge keys (`keys[]`) are a first-class column (unique across ACTIVE records;
Expand Down Expand Up @@ -477,7 +478,8 @@ one sync models stripe
one sync init stripe balanceTransactions

# Optional: declare clean fields for embedding, then preview
# (--config merges into the existing profile; without it, init replaces the profile)
# (--config merges into the existing profile. Without it, init refuses when a
# profile already exists; --force replaces it with the built-in)
one sync init stripe balanceTransactions --config '{
"memory": {
"embed": true,
Expand All @@ -487,9 +489,10 @@ one sync init stripe balanceTransactions --config '{
one sync test stripe/balanceTransactions --show-searchable

# Run — every row lands in memory (enriching profiles also keep a project-local
# SQLite mirror). --embed embeds the rows; the profile's memory.embed alone is not
# applied today. --since only applies to profiles with a dateFilter (Stripe has none).
one sync run stripe --embed
# SQLite mirror). Rows are embedded when the profile's memory.embed says so (else
# defaults.embedOnSync); --embed / --no-embed override it for one run.
# --since only applies to profiles with a dateFilter (Stripe has none).
one sync run stripe
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
Expand Down Expand Up @@ -526,7 +529,7 @@ one sync run stripe --full-refresh
| `profiles [platform]` | List built-in pre-validated profiles |
| `doctor` | Verify sync engine health (exits non-zero when not ready) |
| `models <platform>` | Discover available data models |
| `init <platform> <model>` | Create a profile from the built-in or inference (replaces an existing one); `--config` merges into it. Auto-tests |
| `init <platform> <model>` | Create a profile from the built-in or inference. If one exists it refuses unless you pass `--config` (merges into it) or `--force` (replaces it). Auto-tests |
| `test <platform>/<model>` | Validate profile. `--show-searchable` previews embedded text |
| `suggest-searchable <platform>/<model>` | Rank candidate `memory.searchable` paths from a live sample |
| `approve <platform>` | Approve the shell commands (`transform`, hooks) in profiles you didn't create |
Expand Down Expand Up @@ -669,13 +672,13 @@ one flow execute welcome-customer -v -i email=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 (top-level runs only, not sub-flows or resumes).

Ctrl+C does not pause a run. A run that fails can be resumed with `one flow resume <runId>`.
Press Ctrl+C to pause a run: it stops before the next step and prints the `one flow resume <runId>` command (with the `--allow-*`/`--confirm-write` flags it needs). A bash or code step that the Ctrl+C interrupts runs again on resume. Press Ctrl+C again to quit at once; the run is still saved as paused. A run that fails can also be resumed 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 running actions, code, bash or file steps. Transform and condition expressions are evaluated, in the sandbox. `$.input.*`/`$.env.*` resolve up front; `$.steps.*` refs are reported as deferred (they're produced at runtime). Still needs required inputs and `--allow-bash`/`--allow-code`, and records a run. |
| `--mock` | Mock `action`, `paginate` and `bash` steps (an action returns its schema's example response when it has one). Every other step runs for real, `file-write` included. A mocked step's `response` is `{"_mock": true}`; read `.output`. Works with or without `--dry-run` |
| `--mock` | Mock `action`, `paginate`, `bash` and `file-write` steps (an action returns its schema's example response when it has one; `file-write` steps report `{ path, bytesWritten }` without writing anything). Every other step runs for real, `code.module` included. A mocked step's `response` is `{"_mock": true}`; read `.output`. Works with or without `--dry-run` |
| `--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. Use a top-level step or a loop/condition/while child; a `parallel` substep is ignored. 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) |
Expand Down Expand Up @@ -706,7 +709,7 @@ one flow validate welcome-customer

### `one flow resume <runId>`

Resume a failed workflow run. It skips the top-level steps that completed and re-runs the failed step from its start (a failed loop, parallel, while or sub-flow step re-runs all its inner steps, so writes there can repeat). It uses the current flow file.
Resume a failed or paused workflow run. It skips the top-level steps that completed and re-runs the failed step from its start (a failed loop, parallel, while or sub-flow step re-runs all its inner steps, so writes there can repeat). It uses the current flow file.

```bash
one flow resume abc123
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@withone/cli",
"version": "2.15.2",
"version": "2.16.0",
"description": "CLI for managing One",
"type": "module",
"files": [
Expand Down
14 changes: 8 additions & 6 deletions skills/one/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ 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. It is not available with `--agent`; use `one --agent init --auth browser [-p]` instead. `one logout` shows current session info and confirms before clearing credentials, but **with `--agent` there is no confirmation**: it deletes both this directory's project config and the global config. Never run it unless the user asked to log out.
`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. It is not available with `--agent`; use `one --agent init --auth browser [-p]` instead. `one logout` shows current session info and confirms before clearing credentials, With `--agent` there's no prompt: without `--force` it returns `confirmation_required` and the config it would clear. With `--force` it clears only the config in effect (the project config if there is one, else the global one); `--scope global|both` picks another. Never run it unless the user asked to log out.

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.

Expand Down Expand Up @@ -227,6 +227,7 @@ Underneath, the store has no `platform` column — `type` is the only platform-s
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 with key + pgvector, else FTS
one --agent mem search "deadline" --deep # hybrid, or an error listing what's missing (no FTS fallback)
one --agent mem list note --limit 20
one --agent mem link <from-id> <to-id> relates_to --bi

Expand Down Expand Up @@ -298,8 +299,8 @@ export OPENAI_API_KEY=sk-...
# Check built-in profiles (pre-validated configs for common platforms)
one --agent sync profiles

# Setup — seeds from the built-in. Without --config it REPLACES an existing profile;
# with --config it merges into the existing one.
# Setup — seeds from the built-in. If a profile already exists, init refuses
# (status: "exists"); --config merges into it, --force replaces it.
one --agent sync init stripe balanceTransactions
# If _complete: true and _test.ok: true → ready to run

Expand Down Expand Up @@ -327,8 +328,9 @@ one --agent sync test attio/attioPeople --show-searchable
# Iterate until the numbers match intent.

# Run — memory is always written; pass --no-memory to skip (rare).
# Add --embed to embed: the profile's memory.embed alone isn't applied today.
one --agent sync run stripe --embed
# Embeds when the profile's memory.embed says so (else defaults.embedOnSync);
# --embed / --no-embed override it for one run.
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" # this project's synced models (mem search works anywhere)
Expand Down Expand Up @@ -356,7 +358,7 @@ Without declared paths, the default walker concatenates every string in the reco

**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. Shell commands in a profile you didn't create with `sync init --config` (e.g. one from a cloned repo) are refused until approved: `one --agent sync approve <platform>` returns the commands; show them to the user and re-run with `--yes` only if they agree. 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). **Don't fix it with a bare `one sync init <platform> <model>`**: without `--config` that replaces the profile and loses the user's `connection.tag`, `memory`, hooks and other edits. Copy just the missing fields from `one --agent sync profiles <platform>` and pass them with `one sync init <platform> <model> --config '{...}'`, which merges.
**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). **Don't fix it with `one sync init <platform> <model> --force`** (the hint's suggestion): that replaces the profile and loses the user's `connection.tag`, `memory`, hooks and other edits. A bare `sync init` refuses because the profile exists. Copy just the missing fields from `one --agent sync profiles <platform>` and pass them with `one sync init <platform> <model> --config '{...}'`, which merges.

**Old project sync data is never imported automatically.** `sync run` ignores `.one/sync/data/*.db` and `.one/sync/state/` (a cloned repo can ship them) and prints a hint. Show the user `one --agent mem migrate --dry-run` before running `mem migrate`.

Expand Down
8 changes: 4 additions & 4 deletions skills/one/references/flows.md
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ Strategies: `fail` (default), `continue`, `retry`, `fallback`.

- `continue` records the step as failed (`status`, `error`, `errorCode`) and moves on.
- `retry` retries; if it still fails (or `failFastOn` matches, or `retryOn` doesn't), the step fails the flow.
- `fallback` with `fallbackStepId` records the failure and moves on, exactly like `continue`: the engine does **not** run the named step. Without `fallbackStepId` it behaves like `fail`. To run a recovery step, gate it with `"if": "$.steps.<id>.status === 'failed'"`.
- `fallback` with `fallbackStepId` runs the named step when this one fails. The fallback step must be in the same steps list; it is skipped in normal order and runs only as a fallback. The failed step stays recorded (`status: "failed"`, `fallback: "<id>"`), and the fallback's result is at `$.steps.<fallbackId>`. If the fallback fails too, the flow fails. A fallback can't have a fallback of its own, and `fallback` isn't allowed in `defaultOnError`. The validator requires `fallbackStepId`.

**Flow-level default (cli#93).** Set `defaultOnError` at the top of the flow and every step without its own `onError` inherits it — handy when most steps should `continue` (e.g. rendering/formatting pipelines) and you don't want to repeat it N times. A step opts out by declaring its own `onError`:

Expand Down Expand Up @@ -759,11 +759,11 @@ Three tools that turn "re-run the whole 40-step flow to debug step 30" into near

- **`--dry-run`** — resolves every step's interpolations and shows what they evaluate to, *without executing any step*. `$.input.*` / `$.env.*` resolve immediately; `$.steps.*` references are reported as `deferred` (they're produced at runtime). Transform/condition/while steps show their *evaluated* result; if a transform can't evaluate yet because it reads a step that hasn't run, it's marked `deferred` (depends on a later step) rather than shown as an error — genuine problems (syntax errors, missing inputs, a missing field on a step that *did* run) still surface as errors. Catches wiring bugs (typo'd input names, wrong field paths) with zero API spend. In `--agent` mode this is the `flow:dry-run` event whose `steps[]` carry a `references` table (`{selector, value, status}` where status is `resolved` | `deferred` | `missing`), an evaluated `resolved` value, and a `deferred` / `error` flag for expression steps.
- **`--stop-after <stepId>`** — executes steps up to and including `<stepId>`, then stops; later steps don't run. Isolates where a long flow breaks. Emits a `flow:stopped` event; the run's partial state is saved. Target a top-level step or a loop/condition/while child: a `parallel` substep is accepted but ignored (every step then runs for real, even with `--dry-run`), and a target inside a loop stops after the loop's first iteration.
- **`--mock`** — runs the flow with `action`, `paginate` and `bash` steps mocked: an action's `output` is its example response when it has one, otherwise the resolved config; paginate and bash echo their config. A mocked step's `response` is `{"_mock": true}`, so read mocked data from `.output`. **Every other step runs for real, including `file-write`.** Works with or without `--dry-run`.
- **`--mock`** — runs the flow with `action`, `paginate`, `bash` and `file-write` steps mocked: an action's `output` is its example response when it has one, otherwise the resolved config; paginate and bash echo their config; `file-write` steps report `{ path, bytesWritten }` without writing anything. A mocked step's `response` is `{"_mock": true}`, so read mocked data from `.output`. **Every other step runs for real, including `code.module`.** Works with or without `--dry-run`.
- **`--dry-run --stop-after <stepId>`** — runs the steps *before* `<stepId>` for real, then dry-resolves `<stepId>` against that **real** accumulated context (so its `$.steps.*` references resolve to actual upstream output) and stops without executing it. The honest way to preview "what will step N actually receive". Emits a `step:dry-resolve` event for the target.
- **`flow inspect <runId>`** — prints a past run's per-step status, durations, errors, and outputs from its persisted state file (post-mortem, no re-run). Use after `--stop-after`, or on any failed run, to see exactly what each step produced. `--full` disables output truncation.

Ctrl+C does not pause a run; let it finish or fail, then use `flow resume` on a failed run.
Press Ctrl+C to pause a run: it stops before the next step and prints the `one flow resume <runId>` command (with the `--allow-*`/`--confirm-write` flags it needs). A bash or code step that the Ctrl+C interrupts runs again on resume. Press Ctrl+C again to quit at once; the run is still saved as paused. With `--agent` a paused run returns `{"status": "paused", "pausedBefore", "resume"}` and exits 130.

## Important Notes

Expand All @@ -775,6 +775,6 @@ Ctrl+C does not pause a run; let it finish or fail, then use `flow resume` on a
- In agent mode, flows with write steps require `--confirm-write`
- `code.module` steps require `--allow-code` flag (they run with full Node access)
- Action steps validate required params before executing — pass `--skip-validation` to bypass
- `--mock` mocks only action, paginate and bash steps (actions return their schema's example output when it has one); other steps, file writes included, run for real
- `--mock` mocks action, paginate, bash and file-write steps (actions return their schema's example output when it has one; file writes touch nothing); other steps, `code.module` included, run for real
- State is persisted after every step; resume skips completed top-level steps and re-runs the failed one from its start
- For bash+Claude steps, always set timeout to 180000+ and run sequentially (not in parallel)
Loading
Loading