foldrun 26.3.4 → 26.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +2 -2
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/cli.md
CHANGED
|
@@ -32,22 +32,22 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
32
32
|
|
|
33
33
|
| | |
|
|
34
34
|
|---|---|
|
|
35
|
-
| `foldrun init [dir]` | create an account folder with one
|
|
36
|
-
| `foldrun new <name>` | another
|
|
37
|
-
| `foldrun agent new <name>` | one more agent inside a
|
|
38
|
-
| `foldrun agent new <name> --platform` | the dashboard's **New agent** on the DEPLOYED
|
|
39
|
-
| `foldrun agent ls` | the agents deployed in a
|
|
35
|
+
| `foldrun init [dir]` | create an account folder with one project in it — `--workspace <name>` names it, `--flat` makes the older single-folder shape |
|
|
36
|
+
| `foldrun new <name>` | another project in this account — blank: an `AGENTS.md` and empty `agents/` and `flows/`. `--starter` adds the example researcher, writer and `publish` flow; `--from <template>` copies a template |
|
|
37
|
+
| `foldrun agent new <name>` | one more agent inside a project, with the frontmatter the format requires — and every key explained beside it. Also `foldrun flow new <name>`, whose first step names an agent this project already has, and `foldrun tool new <name>`, which writes a `transport: script` folder with its program in a file beside the definition (`--transport script\|http\|mcp`, `--language javascript\|python\|bash`). In an account with more than one project, `--to <name>` says which; inside one, it is already known. The templates are the same ones the dashboard's New button writes, so what is scaffolded is what `foldrun check` accepts |
|
|
38
|
+
| `foldrun agent new <name> --platform` | the dashboard's **New agent** on the DEPLOYED project (`POST …/agents { name, description, model }`): the platform writes its own template as a revision, and nothing is written in this folder. `--to <workspace>` (or the folder you stand in), `--description "…"`, `--model fast\|default\|max`. Without `--platform`, `--to` keeps naming a project of this account folder. Also `flow new <name> --platform` (`POST …/flows { name, pattern }`, `--pattern pipeline\|review-loop\|fan-out\|debate\|router`, default `pipeline`) and `tool new <name> --platform` (`POST …/assets { kind: "tools" }` — a `script` tool as here unless `--transport`/`--template` says otherwise; `--template` also takes a gallery entry, `--language`). `foldrun pull` brings them down |
|
|
39
|
+
| `foldrun agent ls` | the agents deployed in a project — name, model, last run, owner (its own `owner:`, else the project's, else the account's), description (`GET …/agents`); `flow ls` the flows and how each fires (`GET …/flows`). `--stale <days>` keeps the agents not run in that many days (never run included), bare `--stale` those past `alerts: stale_days`. `--to <workspace>`, `--json` for the list as the platform returns it |
|
|
40
40
|
| `foldrun guide` | the coding-agent rules, copied from what Next.js does: a short managed block in the account's `AGENTS.md`, between `<!-- BEGIN:foldrun-agent-rules -->` markers, telling a coding agent (Claude Code, Cursor, Codex) to read `foldrun docs` before it writes an agent, flow or tool, and a `CLAUDE.md` that imports it with `@AGENTS.md`. `foldrun init` writes them, `foldrun pull` refreshes them, and `foldrun check` re-adds them when a coding agent runs it and they are missing or old — as `next dev` does. Only the block is rewritten, in place; text around it is kept. The runtime strips the block, so the agents that run in the account never see it; the rest of `AGENTS.md` stays their shared context. `--check` exits 1 when the block is missing or old (for CI), `--print` writes it to stdout |
|
|
41
41
|
| `foldrun docs [page]` | these docs, from the copy that ships inside the CLI — the way Next.js ships `node_modules/next/dist/docs` — so a coding agent reads the version it is driving, offline. No page lists them; `foldrun docs flows` prints one; `--path` prints the folder. Design records and the platform operator's routes are left out |
|
|
42
|
-
| `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every
|
|
42
|
+
| `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every project, then the shared library. Includes each agent's colleagues: an `agents:` or `subagents:` name that is not an agent, a sub-agent with no `description:`, a sub-agent that would hold none of its tools inside its parent's. Signed in, it also asks the platform's open `/api/version` which Chrome its runner image has, and warns when a pinned `web.browse.user_agent:` claims another major ([why](tools#how-this-agents-browser-presents-itself)); it warns about the old `web.browse.session:` key too (now `vendor_session:`). Hooks: a `hooks/<name>/` folder that is not a valid hook (`on:`, `run.mjs` beside `hook.md`, `tool:` only on tool events, `timeout:` 1 to 120), and a `hooks:` name in an agent or an AGENTS.md that is in neither `hooks/` nor the library, are errors; a `tool.call` hook on an agent whose `web.search:` (or `web.fetch:`) the model provider runs on its own servers is a warning — those calls never reach the hook. It is also the security scanner: a credential written into any file, invisible Unicode, override phrases in knowledge and skills, an agent that reads the web while holding a secret and an open way out, `curl \| sh`, an MCP server at no fixed version, a typo of a frontmatter field. Every finding names its rule (`secret/hardcoded`, `agent/config`, …); see [Checks](checks) |
|
|
43
43
|
| `foldrun check --security` | only the security rules (secret, security, content, supply-chain), exiting 1 on a warning. Also `--rule <id or category>` (repeatable), `--fail-on error\|warn\|info\|never`, `--format text\|json\|sarif` (`--json`; `--out <file>`), `--changed` (only files changed against git HEAD; `--base <ref>`), `--write-baseline` (accept today's findings into `.foldrun/check-baseline.json`; `--no-baseline`), `--rules` (list every rule). A `foldrun-ignore <rule>: <reason>` comment on the line before a finding silences it; the reason is required. [Checks](checks) |
|
|
44
44
|
| `foldrun extract [dir]` | move each single-file script tool — a `tools/<name>.md` with its program in a fenced block — into a folder: `tools/<name>/tool.md` with `run:` pointing at `run.js`, `run.py` or `run.sh` beside it. Frontmatter is edited as text, never re-serialised, so the diff is only what moved. A tool that already has a folder is left for you; `--dry-run` lists what it would do |
|
|
45
|
-
| `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a
|
|
45
|
+
| `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a project edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the project and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked (an editor's key or above; the platform keeps the answer 10 minutes while the files are unchanged). Either way it ends with when the platform's [daily rescan](checks#online-checks-and-the-daily-rescan) last ran, as the Checks page does — a platform that does not say leaves the line out |
|
|
46
46
|
| `foldrun agent run <name>` | run one agent once on a platform, with no flow file: a flow of one step. `--task "…"` is the instruction and is required. Prints the run id and how to follow it; `--wait` holds on (in 25-second pieces, as `invoke` does) and then prints the same report `foldrun report` would; `--test` makes it a [test run](runs#test-runs) |
|
|
47
47
|
| `foldrun agent run <name> --no-task` | run it with no instruction, as the dashboard's **Run** on an agent row does (`POST …/agents/<agent>/run` with `{}`): the agent works from its own prompt alone. Explicit, so a mistyped `--task` never starts a run with nothing to do; `--task` and `--no-task` together are refused. `--wait`, `--test` and `--to` as for `agent run` |
|
|
48
48
|
| `foldrun agent link <agent>` | add to an agent's team, in its own frontmatter — `--subagent <worker>` (`subagents:`, a worker it delegates to), `--consult <agent>` (`agents:`, a colleague it asks) or `--can-ask` (`ask` in `tools:`, so it may ask you mid-step). The edit is core's, the one the canvas's docks make: only the lines of that one list change, flow style stays flow style, comments and the prose stay byte for byte. A sub-agent without a `description:` needs one, because the model picks a sub-agent by it — asked for at a terminal, `--description "…"` otherwise, and written into the worker's file first. `--isolated` also writes `sandbox: own` on the worker: each job it is handed runs in its own sandbox, with its own tools, secrets and network, not cut to the delegating agent's; its reply comes back with the files it wrote (`foldrun docs agents`). Says which flows use the agent ("used by 3 flows"), since the change reaches all of them. Prints the diff, and refuses an edit `foldrun check` would call an error; `--dry-run` writes nothing. In this folder by default (`--workspace <name>` in an account with several); `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>`. In this folder it re-reads each file just before writing — after the description prompt, after `check` — and refuses, writing nothing to either file, when one changed since it was read |
|
|
49
|
-
| `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another
|
|
50
|
-
| `foldrun agent import --list` | what could be imported into a deployed workspace: every other
|
|
49
|
+
| `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another project into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the project you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the project lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
|
|
50
|
+
| `foldrun agent import --list` | what could be imported into a deployed workspace: every other project this key may read, and each one's agents with their descriptions (`GET …/agents/import`). Imports nothing. `--to <workspace>`, `--json` |
|
|
51
51
|
| `foldrun agent unlink <agent>` | take one away: `--subagent <name>`, `--consult <name>` or `--can-ask`. An emptied list is written `key: []`, not deleted. In this folder, refused the same way, nothing written, when the file changed since it was read |
|
|
52
52
|
| `foldrun agent network <agent> [open\|trusted\|none\|inherit]` | which sites the agent's sandbox may reach ([Network](network)). Alone, prints what a run resolves — the level, where it came from, the sites added — and, for an agent that searches, how a step walled to that list searches (through the egress proxy's search door, or not at all under a list narrow on purpose whose `web:` names no actions). With a level and/or `--add <site>` / `--remove <site>` (repeatable), rewrites the one `network:` line of its `agent.md` — the edit the dashboard's Network card makes — prints the diff and the new resolution; `inherit` drops the agent's own level, and a line with nothing left to say is removed. `--dry-run` writes nothing; `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>` |
|
|
53
53
|
| `foldrun flow add <flow> <pattern>` | one palette block from the [flow canvas](flows#editing-on-the-canvas), as the same markdown edit the canvas writes (core's `flow-patterns`): `chain` (alias `step`: `--agent <name>`, `--instruction "…"`, `--after <n>` or `--before <n>`, default last), `parallel` (`--agent`, `--group <n>`), `router` (`--agent <triage>`, `--cases BUG=bugs,DOCS=docs`, `--else <agent>`, `--after`), `fan-out` (`--step`, `--each lines\|items\|"rows of <path>"`, `--max <n>`), `loop` (alias `evaluator`: `--step`, `--loop <n>` default 3, `--until <MARKER>` default APPROVED, `--judge "<claim>"` adds `verify: judge:`), `approval` (`--step`; the `!` marker, `approve: true` on a `?` step), `ask` (`--step`, `--question "…"`), `wait` (`--step`, `--wait 30m\|event`), `rescue` (`--step`, `--on-fail <agent>`), `subflow` (`--flow <other>`, `--after`). `--step` is the step's place in the file (1 = the first step line) or the agent it runs; `--off` takes a step pattern back off. Prints the diff, runs the rules `check` runs over the result and refuses — writing nothing — an edit that would add an error; one that was there before does not block it. `--dry-run` shows the diff and writes nothing. In this folder by default; `--to <workspace>` edits the deployed copy through the canvas's own route (`PATCH …/flows/<flow>` with `{ edit }`), and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
|
|
@@ -69,34 +69,34 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
69
69
|
| `foldrun flow copy-step <flow> --step <n\|agent>[,<n>…]` | the canvas's Copy: the steps' markdown — line, marker and every option (core's `stepSource`) — on stdout. Reads only |
|
|
70
70
|
| `foldrun flow paste <flow>` | the canvas's Paste: step markdown from stdin or `--file <path>` goes in as new groups after `--after <g>` (default last), or beside group `--group <g>`, renumbered to fit (core's `pasteSteps`) — `foldrun flow copy-step a --step 2 \| foldrun flow paste b`. Diff, checked, `--dry-run`; `--to` sends `PATCH { edit: { op: "paste" } }` |
|
|
71
71
|
| `foldrun flow draft "<what it should do>"` | **Draft with AI**, on the platform (`--to <workspace>`; `--flow <name>` redrafts an existing flow): `POST …/flows/draft` has a model write the flow and any agent files it needs, checks and repairs once, and the CLI prints the notes, every file as a diff and what the check still finds. Nothing is saved until you say yes — `--yes` on a pipe, `--dry-run` never; on a pipe without `--yes` it saves nothing and exits 1, though the draft call was made and charged; each file goes through `PUT …/source` with `ifMatch`, so one that changed meanwhile is refused. One model call, charged like a step |
|
|
72
|
-
| `foldrun assistant ["<message>"]` | the dashboard's **assistant**, from a terminal (also `foldrun ai`; `--to <workspace>`): `POST …/assistant` answers from the foldrun docs and the deployed
|
|
73
|
-
| `foldrun assistant history` | your kept assistant conversations, newest first (`GET /api/assistant/conversations`): id,
|
|
74
|
-
| `foldrun tool test <name>` | exercise one tool, alone — no model, no run, no flow. The real thing runs: the HTTP request against the declared `base:`, the script with the
|
|
75
|
-
| `foldrun hook ls` | the hooks in this
|
|
76
|
-
| `foldrun hook add <name> --on <event>` | a hook folder: `hook.md` (`on:` one of `tool.call`, `tool.result`, `step.start`, `step.end`; `tool:` from `--tool <pattern>` — `Bash`, `Write\|Edit`, `mcp__*` — on the tool events only) and a self-contained `run.mjs` that allows everything, with the whole contract in its comments: the event on stdin, one JSON answer on stdout, exit 2 to deny with stderr as the reason. `--library` writes it in the account library for every
|
|
72
|
+
| `foldrun assistant ["<message>"]` | the dashboard's **assistant**, from a terminal (also `foldrun ai`; `--to <workspace>`): `POST …/assistant` answers from the foldrun docs and the deployed project's files only, and writes agents, flows, tools and skills as proposals — the CLI prints the reply, the doc sections it read, every proposed file as a diff and what the check finds. Nothing is saved until you say yes — `--yes` on a pipe, `--dry-run` never; on a pipe without `--yes` it saves nothing and exits 1 (a plain question with no files exits 0); each file goes through `PUT …/source` with `ifMatch`, so one that changed meanwhile is refused. It prints the tokens the reply used and what it was charged. A proposed new project is created blank on yes (`--yes` on a pipe; never over one that exists); in a conversation the CLI then moves into it and carries on. Every reply is kept; `--conversation <id>` carries one on (its messages and unsaved files come back, and its project unless `--to` says another). With no message, in a terminal, it is a conversation: `/save`, `/files`, `/drop <path>`, `/new`, `/quit`. `--page "<text>"` says what you are looking at, as the dashboard sends the page it is on (`page`, e.g. `flows — daily.md`). `--json` prints the platform's answer. Each reply is one model call, charged like a step. See [Assistant](assistant) |
|
|
73
|
+
| `foldrun assistant history` | your kept assistant conversations, newest first (`GET /api/assistant/conversations`): id, project, when, how many messages and unsaved files, and the first question. `--q <text>` searches them, `--workspace <name>` narrows to one, `--limit <n>` caps how many, `--json` prints the answer. `foldrun assistant show <id>` prints one whole; `foldrun assistant rm <id>` deletes it (asks; `--yes`) |
|
|
74
|
+
| `foldrun tool test <name>` | exercise one tool, alone — no model, no run, no flow. The real thing runs: the HTTP request against the declared `base:`, the script with the project's secrets in its environment, the MCP handshake. Prints the transport, whether it exited cleanly, how long it took, everything the tool printed, and any secret it needed by NAME and never by value. Its arguments are `key=value` pairs, one per argument the tool declares, and `--path` is an http tool's probe path. It waits five minutes by default, because a tool that crawls takes as long as it takes — `--timeout <seconds>` waits longer, and a test given up on says so rather than claiming the tool failed |
|
|
75
|
+
| `foldrun hook ls` | the hooks in this project (`hooks/<name>/`) and the account library (`library/hooks/<name>/`): each one's `on:`, `tool:` and description, read the way a run reads them — a folder that is not a valid hook is listed with the reason and the command exits 1. A project hook shadows a library one of the same name. `--json` for a script. `--to <workspace>` lists the DEPLOYED project's hooks instead (`GET /api/workspaces/<ws>/hooks`, the dashboard's Hooks panel): who turns each on, and the denies, rewrites and failures they wrote into recent runs — `--runs <n>` reads further back (default 50, up to 500), `--all` shows every decision |
|
|
76
|
+
| `foldrun hook add <name> --on <event>` | a hook folder: `hook.md` (`on:` one of `tool.call`, `tool.result`, `step.start`, `step.end`; `tool:` from `--tool <pattern>` — `Bash`, `Write\|Edit`, `mcp__*` — on the tool events only) and a self-contained `run.mjs` that allows everything, with the whole contract in its comments: the event on stdin, one JSON answer on stdout, exit 2 to deny with stderr as the reason. `--library` writes it in the account library for every project; `--to <workspace>` picks one in an account. An agent turns it on with `hooks: [name]`; `hooks:` in a project's or the account's AGENTS.md turns it on for every agent under it |
|
|
77
77
|
| `foldrun hook test <name>` | run one hook HERE on one event, exactly as a step runs it (the event on stdin, a stripped environment, its `timeout:`), and print its answer — decision, reason, a rewritten input, context, reply or note — and how long it took. `--event '<json>'` or `--event @file`; without it, a sample event for the hook's `on:`. A deny is an answer (exit 0); a hook that crashes, times out or answers in the wrong shape is a failure (exit 1) — which, on a gate, refuses the call. `--to <workspace>` runs the DEPLOYED hook on the platform instead (`POST …/hooks/<name>/test { event }`) |
|
|
78
78
|
| `foldrun hook rm <name>` | delete a hook folder (`--library` for the account's). Says which agents and AGENTS.md files still turn it on — their steps are refused until it goes from their `hooks:` — and asks; `--yes` on a pipe |
|
|
79
79
|
| `foldrun run <target>` | run an agent or a flow HERE, on this machine (`name`, or `flow:name`) — `--test` for a [test run](runs#test-runs). On a platform: `flow run`/`invoke` for a flow, `agent run` for one agent |
|
|
80
|
-
| `foldrun eval [name]` | one eval, or all of them — a grader (`trigger: runs`) is listed and skipped, since it has no cases. `--to <workspace>` runs the DEPLOYED
|
|
80
|
+
| `foldrun eval [name]` | one eval, or all of them — a grader (`trigger: runs`) is listed and skipped, since it has no cases. `--to <workspace>` runs the DEPLOYED project's evals on the platform (`POST …/evals/<name>/run` with `async: true`, then polling `GET …/run?run=<id>` — an eval longer than a proxy's timeout still gets its own verdict), waiting for each (`--timeout <s>`, default 900; past it, the run id to read it with). `--run <id>` prints that run's verdict and runs nothing — a run that was lost or is unknown exits 1; `--last` prints each eval's latest result and runs nothing, and prints the same lines; exits 1 when a case fails |
|
|
81
81
|
| `foldrun eval compare <eval> --models <m[:effort],…> --to <workspace>` | an eval's cases under two to four models, side by side (`POST …/evals/<eval>/compare`, then polled) — the Evals page's **Compare models**. `--models fast,default,max` or `fast:low,max:high`; `--effort` for the items that name none; `--agent <name>` compares only that agent's steps of a flow eval; `--repeat` 1–5; `--max-usd` the spend limit (default 5). Every run is a test run. Waits (`--timeout <s>`, default 3600; past it, the id to read it with) and prints each setting's passing, cost, cost and time per run, then the cases where they differ. `--list` the kept comparisons; `--run <id>` one of them; `--json` |
|
|
82
82
|
| `foldrun eval compare <eval> --models fast@writer,max:high@editor` | a different agent per setting, as the Compare panel's **Steps** per row: an item's own `@agent` compares only that agent's steps in that setting (`configs[i].agent`); `--agent` is the default for items without one. `model[:effort][@agent]`, either order of the last two; an `@` followed by a digit (a Vertex-style `model@20240620`) stays part of the model id |
|
|
83
83
|
| `foldrun eval improve <eval> --to <workspace>` | ask for a proposed fix now (`POST …/evals/<eval>/improve`) — from a grader's failed grades no proposal covers, or an eval's last failed cases — and wait for the draft (`--timeout`, default 300), then print it like `proposals show`. `--no-wait` returns with the id. Exits 1 unless the draft is ready |
|
|
84
|
-
| `foldrun proposals --to <workspace>` | the proposed fixes in a
|
|
84
|
+
| `foldrun proposals --to <workspace>` | the proposed fixes in a project, newest first: status, the eval, the failures it covers, the files it changes. `--status ready` for the ones waiting on you, `--eval <name>`, `--json`. The Evals page's Proposed fixes |
|
|
85
85
|
| `foldrun proposals show\|apply\|dismiss <id> --to <workspace>` | `show`: the assistant's reasoning, the failures, the change per file as `-`/`+` lines. `apply`: prints the change and asks before writing it (`--yes` without a terminal); each file is a revision by you; refused when a file changed since. `dismiss`: set it aside |
|
|
86
86
|
| `foldrun eval grades <eval> --to <workspace>` | what a grader (an eval with `trigger: runs`) found in the real runs it graded: the pass rate over `--days` (default 30), then each graded run, newest first, with the check that failed — `--status fail` for the failures alone, `--limit`, `--json`. `GET …/evals/<eval>/grades`, the Evals page's grader card. Exits 1 when a graded run in the window failed |
|
|
87
87
|
| `foldrun eval grade <eval> --run <id> --to <workspace>` | grade one finished run now, sampled or not (`POST …/evals/<eval>/grade`) — **Grade a run** on the card. Prints each check; exits 1 unless it passed |
|
|
88
|
-
| `foldrun eval trends --to <workspace>` | evals by change, the
|
|
89
|
-
| `foldrun eval new <name>` | the Evals page's New, on the deployed
|
|
88
|
+
| `foldrun eval trends --to <workspace>` | evals by change, the project Observe page's table (`GET …/evals/trends`): each eval's latest score and the commit it ran on, against its most recent run on a different commit, and the change — biggest drop first. Exits 1 when a change made an eval worse; `--json` for the document. An eval called `trends` is still read with `--last` or `--run <id>` |
|
|
89
|
+
| `foldrun eval new <name>` | the Evals page's New, on the deployed project (`POST …/evals { name }`): an eval whose `agent:` is the project's first agent and whose case is a placeholder — edit it (`source cat`/`put`), then `foldrun eval <name> --to <workspace>` runs it. `--to <workspace>` |
|
|
90
90
|
| `foldrun promote <run-id>` | keep a finished run as a regression case: its task and what the next run must still say go into `evals/<target>-regressions.md` (or `--eval <name>`), appended when the file exists. `--expect "contains: $34"` — repeatable, eval syntax — replaces the default judge line that holds the next run to the recorded conclusion; `--case <name>` names the case. A run that went wrong (failed, BLOCKED, BAD) takes `--should "what it should have done"` — the judge's claim — or `--expect` |
|
|
91
91
|
| `foldrun probe <model>` | can this model hold a tool loop here? A live check |
|
|
92
|
-
| `foldrun logs [run-id]` | recent runs in one
|
|
93
|
-
| `foldrun runs` | what has run lately across the whole account: when,
|
|
94
|
-
| `foldrun runs outputs <run-id>` | which files the run archived from its agents' `outputs/` — the run page's **Out** column: each agent's files with their sizes, and the `foldrun report <run-id> get <agent>/<path>` that downloads one. `--to <workspace>` names the run's
|
|
92
|
+
| `foldrun logs [run-id]` | recent runs in one project, or one run's whole event trail. `--follow` tails a live run: on a platform it reads the run's server-sent events (`GET …/runs/<id>/stream`, what the dashboard's run page reads — `invoke --watch` and `agent run --wait` too), reconnecting up to three times if the stream goes quiet; a run on this machine is read from its file. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
|
|
93
|
+
| `foldrun runs` | what has run lately across the whole account: when, project, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary — or, for a failed run, why it failed: `✗ agent: ` and the sentence every surface gives ([why it failed](runs#why-it-failed)). A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, `--context <id>` (one [conversation](runs#conversations)'s runs), or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, project, status, verdict, summary and failure), `--limit <n>` (20 by default) is one page: when more match it prints the next page's cursor — `--before <cursor>` shows that page (a time or a run id works too), `--page <n>` the nth page of `--limit`, `--all` every run that matches; `--json` prints `{ runs, next }`. `--local` prints exactly what `logs --local` prints — this machine's runs, one project |
|
|
94
|
+
| `foldrun runs outputs <run-id>` | which files the run archived from its agents' `outputs/` — the run page's **Out** column: each agent's files with their sizes, and the `foldrun report <run-id> get <agent>/<path>` that downloads one. `--to <workspace>` names the run's project (else it is found); `--json` prints `{ runId, files: [{ agent, path, bytes, href }], totalBytes }`. `GET /api/workspaces/<ws>/runs/<id>/files` |
|
|
95
95
|
| `foldrun customers` | your own users, by the id on their runs ([end customers](runs#end-customers)): the limits each is held to and who is blocked; `block <id> [--reason "…"]`, `unblock <id>` (asks; `--yes`), `usage [--days 7]` (model spend per customer), `limits --starts-per-minute N` (also `--max-open-runs`, `--gateway-rpm`, `--gateway-concurrency`, `--daily-model-usd`; `default` — or `none` for the spend — puts one back); `--json`. `GET`/`PATCH /api/customers`, `GET /api/customers/usage`, `PUT`/`DELETE /api/customers/<id>/block` |
|
|
96
96
|
| `foldrun runs views save <name>` · `foldrun runs views rm <name>` | the runs page's **save view**: `save` keeps the filters given (`--status`, `--flow`, `--to`, `--since`, `--q`, `--tool`, `--tool-error`, `--agent`, `--model`, `--min-tokens`, `--min-secs`, `--context`, `--customer`; `--since 24h` is kept as the dashboard's `today`) under that name, replacing a view of the same name; `rm` deletes one (asks; `--yes`). `PATCH /api/me/preferences` `{ runViews }` — the whole list, at most 20. `--json` prints the list after |
|
|
97
97
|
| `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
|
|
98
|
-
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal. Several ids (`runs rm <id> <id>…`) are the runs list's **Delete** on a selection, through the same route (`POST …/runs/bulk` `{ action: "delete" }`, one call per
|
|
99
|
-
| `foldrun runs rm --until <30d\|date>` | delete every **finished** run that started before then — its record, captured calls and archived outputs — in every
|
|
98
|
+
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal. Several ids (`runs rm <id> <id>…`) are the runs list's **Delete** on a selection, through the same route (`POST …/runs/bulk` `{ action: "delete" }`, one call per project): it lists them, asks once, then deletes them — each run its own outcome, so one refused does not stop the rest, and it exits 1 |
|
|
99
|
+
| `foldrun runs rm --until <30d\|date>` | delete every **finished** run that started before then — its record, captured calls and archived outputs — in every project, or one with `--to` ([how long a run is kept](runs#how-long-a-run-is-kept)). Counts what would go, asks once (`--yes` with no terminal; `--dry-run` only counts), then deletes 100 at a time until none match (`POST …/runs/bulk { action: "delete", until }`). Runs still going are left alone; the ledger lines stay. Needs an admin (`workspace:manage`) |
|
|
100
100
|
| `foldrun report <run-id>` | one run, whole, without opening the dashboard: the header — and for a failed run why it failed and what to do (`✗ agent: The step ran out of memory. Memory limit: 4 GiB; …` and `fix: …`, [why it failed](runs#why-it-failed)) — then every step with its group, agent, attempts, the runner image it ran on (`slim · browser pod` when it browsed through the account's pod from slim), cost, how much of its input the prompt cache served (`90% cached`; nothing for a step recorded before 18 Oct 2026) and, under a step that wrote a fifth or more of its input to the cache, why (`prompt cache: 75% of input written to the cache — memory changed since step 1`), how many model turns it took, duration, what happened to the browser pod under it (reconnects, `browser pod lost; re-ran on full` with its tries — `slim · lost` then `full` — or why it was not re-run), whether its `verify:` held and the first line of what it said — and for a failed step, the error and the last events before it. Then what it wrote, what it published and what is still waiting on a person. `--json` prints the run record instead |
|
|
101
101
|
| `foldrun report <run-id> --compare [<run-id>]` | this run beside the flow's [last good run](runs#compare-with-the-last-good-run), or the one named: whether they ran the same files and which changed, then what differs step by step (status, new errors, instruction, model, tools, time, tokens). `--json` |
|
|
102
102
|
| `foldrun report <run-id> --tree` | the run as [one tree](runs#the-trace-tree): each step, each model call (model, tokens, why it stopped) and each tool call under the call that asked for it, with how long each took and `← what went wrong` on the first failure. `--json` gives the tree and the failure path |
|
|
@@ -104,119 +104,119 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
104
104
|
| `foldrun report <run-id> get <agent>/<path>` | download one file the run archived — whatever that agent left in `outputs/`, copied under the run when it ended. Writes it beside you under its own name; `--file <path>` names somewhere else (`-` for stdout), `--force` overwrites |
|
|
105
105
|
| `foldrun report <run-id> live` | the run page's live browser view: which agents' browsers have posted a frame, and when; `--agent <name>` saves the newest frame as a JPEG (`--file <path>`, `-` for stdout) and prints the page's address, the engine and whether the browser has closed (`GET …/runs/<id>/live`) |
|
|
106
106
|
| `foldrun insights` | recurring [problems](runs#insights) found in the last week of runs — a prompt mostly uncached, a big tool result sent again, a retry loop, steps near their timeout — each with why, what to do, about what it cost and the runs it was seen in. `--days <1-30>`, `--to <workspace>`, `--json` |
|
|
107
|
-
| `foldrun inbox` | what waits on you across your
|
|
107
|
+
| `foldrun inbox` | what waits on you across your projects ([your inbox](runs#your-inbox)): gates, questions agents ask, open issues, proposed fixes, your runs that went wrong this week — assigned to you and started by you by default; `--team`, `--started`, `--mine`, `--all`, `--dismissed`, `--kind approval\|question\|issue\|proposal\|run`, `--workspace <ws>`, `--unread`, `--json`. Each item shows its id; exits 1 when something assigned to you is unread |
|
|
108
108
|
| `foldrun inbox read\|unread\|dismiss\|restore <id>…` | mark items in your own view: `dismiss` sets one aside (it still waits where it lives), `restore` puts it back. `inbox read --all` is **Mark all read**: every unread item — of one tab with `--team`, `--started` or `--mine`, narrowed by `--kind` and `--workspace` — in calls of 200 |
|
|
109
109
|
| `foldrun mcp` | this account as an [MCP server](mcp) on stdin/stdout, for an AI app to start: `claude mcp add foldrun -- foldrun mcp`, `codex mcp add foldrun -- foldrun mcp`. Each line is one JSON-RPC message, forwarded to the platform's `POST /api/mcp` with this machine's sign-in (`--profile`, `--url`, `--token` as for any platform command); stdout carries nothing but protocol. `--read-only` offers only the tools that read. Typed into a terminal it prints how to connect and exits 2 |
|
|
110
|
-
| `foldrun mcp connections` | the AI apps connected to the account over OAuth (claude.ai and the like): the app, where its answers go, whose approval, read only or read and act, which
|
|
110
|
+
| `foldrun mcp connections` | the AI apps connected to the account over OAuth (claude.ai and the like): the app, where its answers go, whose approval, read only or read and act, which projects, connected and last used. Everyone's for an admin (`keys:manage`), else your own; `--all` adds the disconnected, `--json` the raw list |
|
|
111
111
|
| `foldrun mcp clients add <name>` | register a machine client that signs in to `/api/mcp` with client credentials (no person approves its tokens): `--role viewer\|editor\|admin`, `--workspaces a,b`, `--write` (else read only), `--token-auth basic\|post\|jwt` with `--jwks-file <path>` for jwt. Prints the client id and secret, the secret once. Listed and ended like any connection |
|
|
112
112
|
| `foldrun mcp disconnect <id>` | end one connection: every token it holds stops at once. Your own, or anyone's as an admin. Asks first; `--yes` when there is no terminal |
|
|
113
113
|
| `foldrun issues` | the account's [issues](runs#issues): what went wrong, grouped, open until someone resolves it — kind, desk and flow (or the platform cause and every desk it hit), how many times since when, the newest reason and what to do. `--to <workspace>` narrows it, `--all` adds resolved ones (`--status open\|acknowledged\|snoozed\|resolved\|all`), `--json` |
|
|
114
114
|
| `foldrun issues show\|ack\|snooze\|resolve\|reopen <id>` | one issue: `show` adds its runs and history; `ack` says you have seen it, `snooze --for 30m\|4h\|1d\|1w` (or `--until <ISO>`, or `--times <n>`: until it happens n more times) hides it for a while, `resolve` closes it until it happens again, `reopen` undoes that. `--note "…"` is kept in its history |
|
|
115
|
-
| `foldrun issues doctor <id>` | the run doctor on an issue's newest run, in that run's
|
|
116
|
-
| `foldrun approvals` | every gate waiting on a person, anywhere in the account: which
|
|
115
|
+
| `foldrun issues doctor <id>` | the run doctor on an issue's newest run, in that run's project — the issue card's **Doctor** button: why (platform, check, work or outside), and the fix as diffs, saved on yes (`--yes`, `--dry-run`, `--json`). A missed schedule has no run and is refused |
|
|
116
|
+
| `foldrun approvals` | every gate waiting on a person, anywhere in the account: which project, flow and run, which step and agent, the question, how long it has been waiting and which files under `storage/` the gate previews — and, first, every question an agent is asking mid-step, with its choices. `--to <workspace>` narrows it |
|
|
117
117
|
| `foldrun approve <run-id>` | release a waiting gate. Approving is outward — the step behind it publishes, sends or posts — so it prints what it is about to release and asks you to type the run id back, unless `--yes`. `--note "…"` is read by the agent as guidance, `--step <n>` decides one gate of several. `--payload <json\|text\|@file>` releases a step parked on `wait: event` with that body instead, as its event URL would — the trace names you, not "an external event" |
|
|
118
118
|
| `foldrun reject <run-id>` | refuse one, failing the step and the run with it. `--note` is the reason, and it goes on the trace. `--event-wait` rejects a step parked on `wait: event` instead — the event box's **Reject**: it stops waiting, the step fails and the run ends (`POST …/approve` `{ decision: "reject", step }`, one call per step) |
|
|
119
|
-
| `foldrun stop <run-id>` | kill a run in flight: the queued job is dropped and the sandbox the current step is spending in is destroyed. It prints which step is running and what has been spent, then asks you to type the run id back unless `--yes`. Finished steps keep their results, and costs already incurred stay on the bill. A run that has already finished is said so, not stopped. With no run id and a filter — `--status running,queued`, `--since 2h`, `--until 1h` (started before then: a span ago, or a date), `--flow <name>` — it stops every run that matches (`POST …/runs/bulk`), in `--to <workspace>` or across the account: it lists what matches first, asks, and then stops exactly the runs it listed, so one that starts in between is not swept up. `--dry-run` lists and touches nothing. The route refuses more than 100 at once. Several run ids (`stop <id> <id>…`) are the runs list's selection: each id's
|
|
119
|
+
| `foldrun stop <run-id>` | kill a run in flight: the queued job is dropped and the sandbox the current step is spending in is destroyed. It prints which step is running and what has been spent, then asks you to type the run id back unless `--yes`. Finished steps keep their results, and costs already incurred stay on the bill. A run that has already finished is said so, not stopped. With no run id and a filter — `--status running,queued`, `--since 2h`, `--until 1h` (started before then: a span ago, or a date), `--flow <name>` — it stops every run that matches (`POST …/runs/bulk`), in `--to <workspace>` or across the account: it lists what matches first, asks, and then stops exactly the runs it listed, so one that starts in between is not swept up. `--dry-run` lists and touches nothing. The route refuses more than 100 at once. Several run ids (`stop <id> <id>…`) are the runs list's selection: each id's project is found as for one, then it lists them, asks once and stops them through the same route (`{ runIds }`, 100 a call) |
|
|
120
120
|
| `foldrun answer <run-id> "…"` | answer the question an agent is asking mid-step (`tools: [ask]`). `--option <n>` picks one of the choices it offered; `--question <id>` one of several. The agent is waiting in its sandbox and carries on at once. `foldrun approvals` lists what is being asked |
|
|
121
121
|
| `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
|
|
122
|
-
| `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `rm` of an oauth2 secret also revokes its grant at the provider when it has a revocation URL, and says if that failed. `--site <domain>` (repeatable, or `a,b`) binds it as it is stored. `--account --workspaces a,b` stores an account secret limited to those
|
|
123
|
-
| `foldrun secrets ls` | the secrets in scope — where each is set, shadowed or not, its sites and the
|
|
122
|
+
| `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `rm` of an oauth2 secret also revokes its grant at the provider when it has a revocation URL, and says if that failed. `--site <domain>` (repeatable, or `a,b`) binds it as it is stored. `--account --workspaces a,b` stores an account secret limited to those projects in the same write, so it is never open in between; `--account --none` to no project yet (`secrets workspaces` changes it later). The account's `RESEND_API_KEY` and `EMAIL_FROM` (the sender of everyone's reset mail) are refused from the CLI: the owner sets them signed in, in Settings → Secrets |
|
|
123
|
+
| `foldrun secrets ls` | the secrets in scope — where each is set, shadowed or not, its sites and the projects an account secret is limited to — and, on the platform, whether the far end still takes it: accepted by its host on a date, refused (with the status, how many times running and when it last worked), the host's own failure ("its end, not the key"), or not used yet, as Settings → Secrets → Connections shows it. `--json` prints the document (`GET /api/secrets`) |
|
|
124
124
|
| `foldrun secrets rm NAME` | delete one (asks; `--yes` on a pipe). An oauth2 secret's grant is revoked at the provider. When an account secret leaves the OAuth client saved under its name unused, the CLI says so with the command that removes it (`secrets clients rm <name>`) — the dashboard deletes it with the secret; `--with-client` does that here too, after asking. A client another connection still uses is never touched |
|
|
125
125
|
| `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
|
|
126
|
-
| `foldrun secrets workspaces NAME [workspace…]` | limit an account secret to those workspaces: every other one finds it not set (`PATCH /api/secrets { name, workspaces }`). `--all` opens it to every
|
|
126
|
+
| `foldrun secrets workspaces NAME [workspace…]` | limit an account secret to those workspaces: every other one finds it not set (`PATCH /api/secrets { name, workspaces }`). `--all` opens it to every project again, `--none` to no project; no names prints which may use it. An admin over every project; it applies to runs that start after it |
|
|
127
127
|
| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `--site <host>` as it is stored, or later with `secrets sites`). `--site` binds any kind as it is stored, `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted, `--token-auth basic` for a provider that takes the secret only as HTTP Basic), `token-exchange` (RFC 8693: `--token-url`, `--client-id`, `--subject-secret <NAME>` whose token is traded, and `--audience`, `--scopes`, `--requested-token-type` to narrow it). On the platform, or this machine's vault with `--local` |
|
|
128
128
|
| `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --authorize-url … --token-url … --client-id … --scopes …` saves one (secret prompted), with `--authorize-param name=value` for anything else the provider's authorize URL takes and `--token-auth basic` for a provider that takes the secret only as HTTP Basic, `clients rm <name>` removes it |
|
|
129
129
|
| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--authorize-url` and `--token-url` from the provider's OAuth docs, `--authorize-param name=value` for its extras; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; `--token-auth basic` sends the secret as HTTP Basic, for providers that refuse it in the form body; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
|
|
130
|
-
| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a
|
|
131
|
-
| `foldrun deploy [dir]` | push this account into an installation — every
|
|
130
|
+
| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a project's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
|
|
131
|
+
| `foldrun deploy [dir]` | push this account into an installation — every project and the shared library. `foldrun deploy <workspace>` pushes one. Never removes a project the platform has and the folder does not. It first prints where it is going and as whom (`deploying to <url> as <profile> (<email>)`); a deploy that would delete files the folder no longer has lists them and asks — what runs wrote (`storage/`, `state/`, the trigger log) is never deleted, so never listed. The confirmed list goes with the deploy; if the platform would now remove anything else it refuses and the CLI asks again. With no terminal (a script, a CI job, a coding agent) it refuses unless `--yes`. A deploy that only adds or changes files asks nothing |
|
|
132
132
|
| `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
|
|
133
133
|
| `foldrun pull [workspace]` | bring the platform's account down into this folder — refuses to overwrite a locally edited file, and names every one it would have taken (`--force` takes them) |
|
|
134
|
-
| `foldrun export [workspace]` | a deployed
|
|
135
|
-
| `foldrun import <file.zip>` | take a package in: first shows what it adds, what is identical, what it would replace and what it still needs (secrets, tools, skills, scripts, agents, flows), then asks. Never deletes; replacing a file needs `--overwrite`. `--to <workspace>` (a name that does not exist makes it, from a
|
|
134
|
+
| `foldrun export [workspace]` | a deployed project as a `.zip` — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state, storage or a secret's value. `--flow <name>` exports that flow with every flow and agent it runs and the tools, skills and scripts they grant; `--agent <name>` that agent and what it grants. Written under the name the platform gives it (`<ws>.zip`, `<ws>-flow-<name>.zip`); `--file <path>` (`-` for stdout), `--force` to replace (`GET …/export`) |
|
|
135
|
+
| `foldrun import <file.zip>` | take a package in: first shows what it adds, what is identical, what it would replace and what it still needs (secrets, tools, skills, scripts, agents, flows), then asks. Never deletes; replacing a file needs `--overwrite`. `--to <workspace>` (a name that does not exist makes it, from a project package), `--dry-run` previews only (`--json` for the plan), `--yes` with no terminal (`POST …/import`) |
|
|
136
136
|
| `foldrun snapshot push [dir]` | send a folder for an agent on foldrun to work on (a snapshot). What goes is what git would commit — tracked files and untracked ones `.gitignore` does not exclude, as they are on disk; links and submodules are left out and named. A secret in any file stops it before anything leaves the machine (remove it, or leave the file out with `.gitignore`); the platform checks again. Answers the snapshot id, kept 7 days from the last send and while a run uses it. `--to <workspace>`, `--dry-run` packs and checks only, `--out <file.tar.gz>` keeps the archive (`--force` over a file that is there), `--json` (`POST …/snapshots`) |
|
|
137
137
|
| `foldrun status [workspace]` | per workspace: what is added, changed and only-on-the-platform, plus which files moved there since your last deploy from here. Reads only |
|
|
138
138
|
| `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1, saying *status unavailable — the platform may be down*, when it does not answer. Plain `foldrun status` opens with the same one-line verdict |
|
|
139
139
|
| `foldrun status --platform --history` | what the status page draws as bars: each component's uptime over the window and a mark per day — up, degraded or maintenance, an outage, or no samples — then the incidents and maintenance in it, from the open `GET /api/status/history?days=<n>`. `--days 1-90` (default 90), `--json` |
|
|
140
140
|
| `foldrun workspaces` | what exists here, what exists on the platform, which are both — also `new <name>`, and `rm <name>` (locally; `--platform --yes` deletes it there). `--json`: `{ platform, workspaces: [{ name, here, platform }], error? }`, exit 1 when the platform could not be read |
|
|
141
|
-
| `foldrun workspaces show <name>` | what is deployed in one
|
|
142
|
-
| `foldrun workspaces new <name> --platform` | the dashboard's **Create
|
|
143
|
-
| `foldrun workspaces demo` | **Try the demo pipeline**: makes the `demo-pipeline`
|
|
141
|
+
| `foldrun workspaces show <name>` | what is deployed in one project (`GET /api/workspaces/<name>`): its agents with model and description, its flows and how each fires, and its files counted by top-level folder. `--json` for the document |
|
|
142
|
+
| `foldrun workspaces new <name> --platform` | the dashboard's **Create project**: blank — an `AGENTS.md` and nothing to delete (`POST /api/workspaces { name, template: true }`) — or `--starter` for the example researcher, writer and publish flow (`{ name, starter: true }`). The plan's project count applies. Without `--platform` it makes the folder here, as `foldrun new` does |
|
|
143
|
+
| `foldrun workspaces demo` | **Try the demo pipeline**: makes the `demo-pipeline` project on the platform — a four-step flow with a parallel pair, an approval gate and a pretend CRM tool (`POST /api/workspaces { demo: true }`) |
|
|
144
144
|
| `foldrun library` | the account's shared library on the platform, as the Library page shows it: `ls [skills\|tools\|hooks\|scripts\|knowledge\|memory]`, `cat <kind>/<path>`, `put <kind>/<path>` (from `--file`, else stdin), `new <kind>/<name>` (the Library page's New, `POST /api/library/<kind> { name, template, language }`: the platform's template — `--template` a transport or a gallery entry, `--language` for a script tool), `rm <kind>/<path>` (asks). `deploy` still pushes the whole of it |
|
|
145
|
-
| `foldrun find <words>` | the dashboard's ⌘K search:
|
|
145
|
+
| `foldrun find <words>` | the dashboard's ⌘K search: projects, agents, flows, tools, skills, knowledge, memory and runs across the account, ranked the same way (`GET /api/search`; `--json`) |
|
|
146
146
|
| `foldrun invoke <flow>` | start a flow on a running platform — `--watch` follows its trace here; `--test` makes it a [test run](runs#test-runs) `--once <key>` sends the key as the run's idempotency key, so a CI step that retries after a dropped response is answered with the run it already started instead of paying for a second. `--tag <t>`, repeatable, labels the run (the API's `tags`). `--inputs <name>` sends a saved input set as the task — a case of `evals/<flow>-inputs.md` or of an eval that runs the flow, as the platform has it (see [Run with saved inputs](flows#run-with-saved-inputs)). `foldrun flow run <flow>` is the same command |
|
|
147
|
-
| `foldrun source <verb>` | one
|
|
147
|
+
| `foldrun source <verb>` | one project file on a platform: `ls [dir]`, `cat <path>`, `put <path>` (from `--file`, else stdin; `--message` goes on the revision), `new <kind> <name>`, `mv <from> <to>`, `rm <path>` — the editor's own door, so every write is a revision. `new` is the dashboard's New button for any document (`POST …/assets { kind, name, agent?, template?, language? }`): `tools`, `knowledge`, `memory`, `skills`, `scripts` (and `agents`, `flows`, `evals`), the template written by the platform; `--agent <name>` puts a knowledge, memory, skill or script document inside that agent. For a whole tree, `deploy` |
|
|
148
148
|
| `foldrun source put <path> --check` | the dashboard editor's checked save (`PUT …/source { check: true }`): a file a deploy would refuse is refused — HTTP 422, the issues printed with their rule ids, exit 1, nothing written; a save that passes prints its warnings. Without `--check` a save is written as before (the editor's **Save anyway**). `--empty` writes an empty file on purpose, as the file tree's **+ Add file** does; an empty input without it is refused, since that is nearly always a pipe that broke |
|
|
149
|
-
| `foldrun source share <path>` | the dashboard's **Move to shared** (`POST /api/workspaces/<ws>/source/share`): a skill, tool, script, knowledge or memory file into the account library and out of the
|
|
150
|
-
| `foldrun open [page]` | the dashboard for this
|
|
149
|
+
| `foldrun source share <path>` | the dashboard's **Move to shared** (`POST /api/workspaces/<ws>/source/share`): a skill, tool, script, knowledge or memory file into the account library and out of the project, moved by the platform in one call. A skill or folder tool (`skills/x/SKILL.md`, `tools/x/tool.md`, or the folder) moves whole, subfolders in place. It lists what would move first (the platform's dry run), asks (`--yes` with no terminal), then moves. A folder holding a file the library cannot hold (an image, a binary) is refused and nothing moves; a library file of the same path is refused unless `--overwrite`; `--dry-run` stops after the list; `--json` prints the answer. A hook is refused — `hook add --library` makes a shared one. `--to <workspace>`; the library is every project's, so it needs an account-wide sign-in |
|
|
150
|
+
| `foldrun open [page]` | the dashboard for this project, in the browser (`runs`, `agents`, `graph`, `repo`…) |
|
|
151
151
|
| `foldrun login` | sign this machine in from the browser — no key to copy. Type the code it shows on the page and approve within five minutes |
|
|
152
152
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
153
153
|
| `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
|
|
154
|
-
| `foldrun whoami` | who you are on the platform: account, role, which
|
|
154
|
+
| `foldrun whoami` | who you are on the platform: account, role, which projects |
|
|
155
155
|
| `foldrun signup status` | can a stranger sign up on the platform, and how: **free** sign-up (an account without paying) open or closed, **paid** sign-up (choosing a plan — foldrun's hosted platform only, in effect only while payments are ready) open or closed, and while paid is open the plans it sells. Reads the open `GET /api/signup` — what foldrun.io's sign-up buttons read — and never sends a key, whatever `--url` names; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1 when the platform does not answer or answers another shape. What each switch is SET to, and why paid is not in effect, is the operator console's |
|
|
156
|
-
| `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the
|
|
157
|
-
| `foldrun team invite [email]` | invite someone (`POST /api/team`): `--role viewer\|editor\|admin` (default editor), `--workspaces a,b` or `--all` (omitted: every
|
|
156
|
+
| `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the projects they may open — a scoped key sees only the ones it shares — and when they joined. `--json` |
|
|
157
|
+
| `foldrun team invite [email]` | invite someone (`POST /api/team`): `--role viewer\|editor\|admin` (default editor), `--workspaces a,b` or `--all` (omitted: every project, unless you are scoped — then name them), `--no-send` to mail nothing. Without an address the link works for whoever has it. Prints the link once: it works one time, for seven days, and is shown only to you. `--json`. Like every `team` write, it is a person's: it works from your own `foldrun login` on this machine, never from a key made by hand, and it acts at the lower of that sign-in's role and yours now — an owner's sign-in here is an admin, so inviting, changing or removing an admin stays in Settings → Team |
|
|
158
158
|
| `foldrun team role <email\|id> <role>` | change a member's role to viewer, editor or admin (`PATCH /api/team/members/<id>`); the member by address (any case) or id. Their keys above the new role stop. Nobody changes their own role, and owner is transferred, not set |
|
|
159
|
-
| `foldrun team access <email\|id>` | which
|
|
159
|
+
| `foldrun team access <email\|id>` | which projects a member may open (`PATCH /api/team/members/<id>`): `--workspaces a,b`, `--all` or `--none`; never wider than yours. Their keys that reach beyond it stop |
|
|
160
160
|
| `foldrun team remove <email\|id>` | remove a member (`DELETE /api/team/members/<id>`). Asks first; with no terminal it needs `--yes`. Their keys and the invites they made stop with them. Transferring the account stays in Settings → Team (signed in, with your password) |
|
|
161
161
|
| `foldrun me` | the person this machine is signed in as (`GET /api/me`'s `person`): name, address, account, role, timezone. `--json`. A key made by hand is nobody: it says so and exits 1 |
|
|
162
162
|
| `foldrun me name <first> [last]` | set your name (`POST /api/auth/name`); `--clear` for none, so you are shown by your address |
|
|
163
163
|
| `foldrun me timezone <zone\|auto>` | the zone you read times in (`POST /api/auth/timezone`), e.g. `Australia/Sydney`; `auto` goes back to the browser's. Password, email, two-step sign-in and sessions stay in Profile |
|
|
164
|
-
| `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role,
|
|
164
|
+
| `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role, projects, who made it, when it expires, and its id. `--all` adds accepted, revoked and expired ones; `--json`. Never the link: an invite works once and its link is shown only to the person who made it. An admin's (`team:manage`), a key included; a scoped key sees the invites inside its scope |
|
|
165
165
|
| `foldrun team invites revoke <id>` | take an invite back (`DELETE /api/team/invites/<id>`): its link stops working at once. One already revoked or expired says so and changes nothing; one already accepted is refused (remove the member in Settings → Team instead). An admin invite is the owner's to revoke |
|
|
166
|
-
| `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own),
|
|
166
|
+
| `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), project, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). `--to <workspace>` adds that project's checklist: a flow that ran to the end, a schedule or webhook, an owner, an eval, `notify:` — each with where it is done (`GET /api/me/onboarding?workspace=`). Hiding the card, a step or a checklist item is per person, from the dashboard |
|
|
167
167
|
| `foldrun preferences` | your own settings on the platform — today the theme (`system`, `light`, `dark`), kept with you on every browser; `preferences set theme dark` changes it (`/api/me/preferences`; a key acts for whoever minted it) |
|
|
168
168
|
| `foldrun api spec` | the platform's OpenAPI 3.1 document, from `GET /api/openapi.json` (no key needed) — to stdout, or `--out <file>`. Every other command sends `Foldrun-Version` (the API version this CLI was built for), an `Idempotency-Key` on each write (reused on its own retry), and waits out one `429` for `Retry-After` before saying so. See [Using the API](api-usage) |
|
|
169
169
|
| `foldrun api version` | Settings → API keys → API: the API version this account's requests get when they send no `Foldrun-Version`, whether it is pinned, every version still served, the rate limits, and the last 30 days: requests by version, and any deprecated route the account still calls — by which key or person, and when it stops answering. `api version pin <YYYY-MM-DD>` pins it, `unpin` goes back to current (`PATCH /api/account/api`; an admin's) |
|
|
170
170
|
| `foldrun changelog` | What's new: first the API — its current version, the breaking changes each dated version brought, and the routes deprecated with their sunset dates — then the platform's release notes, newest first — features, fixes, docs — and which release this install runs (`GET /api/changelog`; `--limit <n>` up to 50, `--json`) |
|
|
171
171
|
| `foldrun version` | this CLI's version, its `@foldrun/core`'s, and — when a platform is known (`--url`, `--profile`, `FOLDRUN_URL` or where you signed in) — that platform's: version, release time, API version, each component's commit and the browsers its runner image has (with versions where known: `chrome 154.0.8037.58`), from `GET /api/version` (sent with your key; signed out, a platform names only its version and API date). Warns when the platform was released with a newer CLI than this one. An unreachable platform is a dim line, not a failure. `--json` prints `{ cli, core, platform }`. `foldrun --version` (or `-v`) prints only the CLI's version, offline. See [Versions and releases](versions) |
|
|
172
172
|
| `foldrun doctor` | check the road to the platform, one line each: Node (22 or newer), the CLI and core versions, which of `FOLDRUN_URL`, `FOLDRUN_TOKEN`, `FOLDRUN_TIMEOUT`, `HTTPS_PROXY` are set (never their values), which model credential a local run would use (by its variable, never its value), the account it would act as, DNS for the platform's host, and a timed `GET /api/healthz`. The first thing to run when a command cannot reach the platform |
|
|
173
|
-
| `foldrun storage <verb>` | what a
|
|
174
|
-
| `foldrun storage text <path>` | a file already in a
|
|
173
|
+
| `foldrun storage <verb>` | what a project PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token|id>` revokes one — the link answers 404 from then on and the token is never reused. Only an admin, or the person who made a link, sees its token; anyone else sees the link with its token masked and an id (`sh_…`) to unshare it by. `--to <workspace>` from anywhere; inside a project folder it is already known. `ls --all` lists every project's storage, as the account's Storage page: a block per project with its files, size and quota, the busiest first, then the empty ones by name (`[prefix]` narrows each; `--json` is `{ workspaces: [...] }`, one storage document per project; a project that could not be read is a non-zero exit) |
|
|
174
|
+
| `foldrun storage text <path>` | a file already in a project's storage, as text: `POST /api/workspaces/<ws>/storage/extract` with `{ path, lang, ocr, engine, wait, write }`. Prints the text, and the platform writes it beside the file as `<path>.txt` (`wrote <path>.txt` on stderr) unless `--no-write`. The same `--lang`, `--ocr`, `--engine`, `--wait` and `--json` as `foldrun text`, and the same polling when it answers 202. `--to <workspace>` or `--workspace <name>` from anywhere; inside a project folder it is already known |
|
|
175
175
|
| `foldrun text <file>` | a file on this machine as text, read by the platform ([Files to text](extract)): it uploads the bytes to `POST /api/extract` and prints what the platform read — a photo, scan or PDF (OCR in Persian and English), a Word, sheet or slide file, or a recording (speech to text). `--lang fa\|en\|auto` (default auto), `--ocr auto\|always\|never` (auto reads page images only where a page has no text layer), `--engine docling` picks the parser, `--wait <s>` is how long the platform may hold the request before answering with a job (`30`, `30s`, `2m`). A long job answers 202 and is polled at `GET /api/extract/<id>` every 2 s (or as Retry-After says) with one progress line on stderr until it is done or failed. The text goes to stdout; `--out <path>` (or `-o <path>`) writes it to a file instead (refused when the file exists; `--force` overwrites); `--json` prints the whole result — `sha256`, `kind`, `format`, `text`, `pages`, `ocrPages`, `seconds`, `language`, `engine`, `truncated`, `warnings`, `cached`, `ms`. Files over 10 MB go into storage first (`foldrun storage put`, then `foldrun storage text`). Warnings go to stderr; a refused or failed job prints the platform's reason and exits 1 |
|
|
176
|
-
| `foldrun runtimes` | the environments a deployed
|
|
177
|
-
| `foldrun schedule` | every flow in the account whose `trigger:` is a clock:
|
|
176
|
+
| `foldrun runtimes` | the environments a deployed project's agents need — each distinct `runtime:` (an agent's own merged with its tools'), the packages in it, which agents use it, and whether the platform has built it: ready, building, or failed with the installer's own error. `foldrun deploy` prints the same thing after a deploy and waits up to two minutes for builds in progress (`--no-runtimes` skips the wait); this asks again later, and `--wait` holds on while any is building. Exits 1 when one has failed. `--to <workspace>` from anywhere |
|
|
177
|
+
| `foldrun schedule` | every flow in the account whose `trigger:` is a clock: project, flow, the cron line, its timezone, how many steps, whether the scheduler can parse it, and the next three times it fires. The times are the point — `0 5 1-7 * 5` reads as "the first Friday" and fires eight times in twenty-eight days, because day-of-month and day-of-week are OR'd. Exits 1 if any line is unparseable, since an invalid schedule errors nowhere and simply never runs. `--to <workspace>` narrows it |
|
|
178
178
|
| `foldrun schedule tick` | Settings' **Run scheduler now**: fire whatever is due this minute and print which flows went (`POST /api/schedule`). They were due anyway; this only makes them go now |
|
|
179
179
|
| `foldrun rerun <run-id>` | the same flow again, from a step: `--from <n>` as the flow file numbers them, or `--agent <name>` for the first step that agent runs. `--instruction "…"` tells that step something else this once, without changing the flow file. Earlier steps are recorded as skipped. This is the debug loop from the terminal: fix the file, `deploy`, `rerun --from` the step that failed. `--wait` follows the new run like `invoke --wait`; `--to <workspace>` from anywhere. With no run id and a filter (`--status failed`, `--since 24h`, `--until 2h`, `--flow <name>`) it reruns every match from `--from <n>` (default 1), listing and asking first as a bulk `stop` does; `--dry-run` lists only. Several run ids (`rerun <id> <id>…`) rerun those, from `--from <n>` (default 1) — `--agent` and `--instruction` are for one run |
|
|
180
180
|
| `foldrun triggers` | why nothing ran. One row per flow that fired in the window: its trigger, how many fires became runs, when it last ran, and every reason for the difference with a count — a duplicate delivery, a throttled or debounced burst, a fire the platform slept through, an `overlap: skip`, a flow switched off by `disable_after:`. Below it, as the Triggers page: every decision, newest first (when, flow, the outcome in words with the key that decided it, the detail), and the deliveries at the hook and inbox URLs — whether a request arrived and was authentic before any flow rule had a say, with how many were refused, so a bad token shows even when nothing fired. `--limit <n>` of each (default 10). A switched-off flow is a non-zero exit; one successful run clears it. `--since <days>` (default 7), `--to <workspace>`, `--json` for the whole document (`flows`, `events`, `deliveries`) |
|
|
181
|
-
| `foldrun observe` | where the account fails, retries and spends: one row per
|
|
182
|
-
| `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per
|
|
181
|
+
| `foldrun observe` | where the account fails, retries and spends: one row per project — runs, failed and what share, steps, cost, and its completion rate against the window before — then the account Observe page's analysis (`GET /api/observe`): the completion rate and what was charged against the window of the same length before, **why runs went wrong** (the platform's causes first, each with its desks and what the newest said), the **agents to watch** (those that failed or retried) and the **tools to watch** (those that errored), then the recent failures in their own words. 7 days unasked, as the page (until 5 Nov 2026 it was 30). `--to <workspace>` prints that project in full, as its Observe page does, over 30 days unasked: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share, when it began and when it was done, p50/p95; `services` says **in parallel** where the search and browser pods booted beside the step pod, and `go` how long it was **held** for them. `--since <days>` (or `--days`) picks any window; `--json` for the document — `{ days, account, workspaces }` account-wide (`account` the analysis, `null` from a platform without it), one project's report with `--to` |
|
|
182
|
+
| `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per project — and what it was charged over `--days <n>` (default 56) from the ledger, per project with the change against the period before. `--json` for both documents |
|
|
183
183
|
| `foldrun usage --limit <n>` | the Usage page's **by flow** and **by agent** tables in the text output: what each flow and each agent was charged over the window, its runs and the change against the period before, most charged first — the first `n` of each (default 10; `0` hides them). `--json` has them all, in `history.byFlow` and `history.byAgent` |
|
|
184
|
-
| `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each
|
|
185
|
-
| `foldrun usage meters` | what the period used, meter by meter (the Usage page's **Compute** and **Tokens** tabs; `GET /api/usage?from=&to=`): the two credit pots, plan credits and bought credits; vCPU, RAM, step disk, storage and network, each with its quantity, rate and credits (storage against the GB your plan includes); search pods, browser pods and warm builds, each with its pod-hours, sessions and the GB it moved; the plan fee as its own line; each step size with the credits an hour it costs; and tokens by provider and model, where a model on your own key shows `0 credits` because your provider bills you. `--since <day>` and `--until <day>` (UTC, `YYYY-MM-DD`) choose the period, default the month so far and at most a year; `--json` prints `period`, `credits`, `tokens`, `compute` and `billed`. A key limited to some
|
|
184
|
+
| `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each project with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn. It also prints how many of the account's **runs wait for their turn** against its limit: while that many wait, a new run is refused at once (409, `waiting_cap`) rather than lined up, and the CLI says so where you started it. `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
|
|
185
|
+
| `foldrun usage meters` | what the period used, meter by meter (the Usage page's **Compute** and **Tokens** tabs; `GET /api/usage?from=&to=`): the two credit pots, plan credits and bought credits; vCPU, RAM, step disk, storage and network, each with its quantity, rate and credits (storage against the GB your plan includes); search pods, browser pods and warm builds, each with its pod-hours, sessions and the GB it moved; the plan fee as its own line; each step size with the credits an hour it costs; and tokens by provider and model, where a model on your own key shows `0 credits` because your provider bills you. `--since <day>` and `--until <day>` (UTC, `YYYY-MM-DD`) choose the period, default the month so far and at most a year; `--json` prints `period`, `credits`, `tokens`, `compute` and `billed`. A key limited to some projects sees those projects' usage and no credits, plan fee or ledger total |
|
|
186
186
|
| `foldrun usage rates` | what each meter costs this account now — vCPU per hour, RAM per GiB-hour, step disk, storage over the plan's allowance, network per GB — in dollars and credits, the account's plan, the plans on offer with their credits, storage and compute at once, what a default step costs an hour, and the price list for foldrun's models with the margin (the **Rates** tab; `GET /api/usage/rates`; `--json` prints it whole). Says so when nothing is billed |
|
|
187
|
-
| `foldrun usage budget` | the Spend limits page: the account's `budget:` and each
|
|
188
|
-
| `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its
|
|
189
|
-
| `foldrun billing invoices` | the Invoices tab: the plan's tax invoices from Stripe — number, date, amount and currency, status, what it was for, and Stripe's link to it — and every credit purchase with its receipt link, newest first (`GET /api/billing/invoices`). `--json` for the document. Any member or key with every
|
|
187
|
+
| `foldrun usage budget` | the Spend limits page: the account's `budget:` and each project's, what is spent in its window (today, this week or this month, in the account's calendar) and how far into the cap that is — marked past the 80% warning, and at the cap with when new runs start again (`GET /api/usage/budget`). Most spent first; a project with no cap shows its month's spend. `--to <workspace>` for one, `--json` for the document. A key scoped to some projects sees those, not the account's figure. Set a cap with `foldrun account set budget …` or `foldrun workspace set budget 60/day --to <ws>` |
|
|
188
|
+
| `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its project, flow and run id; an adjustment carries its own note. `--limit <n>` shows more. `statement [YYYY-MM]` is a month of the ledger (this month by default) — `--csv` for the file an accountant wants, to stdout or `--file <path>`. `wallet` is the burn, the runway and auto top-up; `wallet set auto-top-up --threshold <usd> --amount <usd>` turns it on (a refill of 5–500), `set auto-top-up off` turns it off, `set email <address>` is where receipts go. `details` is who invoices are made out to; `details set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …` changes it, merged with what is there. `portal` prints a link to Stripe's billing portal. Changing the wallet, the details, and the portal are the account owner's; anyone else is told so |
|
|
189
|
+
| `foldrun billing invoices` | the Invoices tab: the plan's tax invoices from Stripe — number, date, amount and currency, status, what it was for, and Stripe's link to it — and every credit purchase with its receipt link, newest first (`GET /api/billing/invoices`). `--json` for the document. Any member or key with every project; one scoped to some is refused, as the statement is. An install without billing says it has none |
|
|
190
190
|
| `foldrun billing wallet clear email` | no address for receipts and low-balance warnings (`PUT /api/billing/wallet { email: null }`, as the wallet page's emptied field). `wallet set auto-top-up off` keeps the threshold and the refill for the next time it is turned on, as the page's switch does; `wallet` shows them beside off |
|
|
191
191
|
| `foldrun billing details set --clear-address` | drops the address from who invoices are made out to, the rest kept; `--clear-email` and `--clear-abn` the same for the email and the ABN (each refused beside its own `--address`/`--email`/`--abn`) |
|
|
192
|
-
| `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, storage, compute at once and
|
|
192
|
+
| `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, storage, compute at once and projects, which one the account is on and this cycle's credits left (`GET /api/billing/plans`). `billing plan <id>` chooses one — a first plan answers with Stripe's checkout page, a change on a live plan is prorated at Stripe at once (asks first; `--yes`); `plan cancel` stops it at the end of the cycle, `plan resume` undoes that until then (`POST`/`DELETE /api/billing/subscribe`) |
|
|
193
193
|
| `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
|
|
194
194
|
| `foldrun browser` | a real Google Chrome on this computer for an AI app, driven by the gallery's own browser program ([browser](browser.md)): `setup` (checks Chrome, fetches the program, installs Playwright once at the version it names), `open [url]` (the window, to sign in to sites yourself — sign-ins stay in its own profile, `~/.foldrun/browser/chrome`), `close`, `reset` (removes the profile; asks, `--yes`), `doctor` (what is installed, where the profile is, whether the window is open), `mcp` (the MCP server an app starts: `claude mcp add --scope user foldrun-browser -- foldrun browser mcp`) |
|
|
195
195
|
| `foldrun gallery` | the tools (`web`, `docs`, `video`) and skills (`modern-website`, `motion-video`) the platform ships to every account, by shelf, and for each whether this account keeps its own copy and whether that copy still matches; `--json` for a script. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <name>` replaces the account's copy of a tool or skill with the current gallery version, the old one a revision back. `foldrun check` knows the gallery's names, so a signed-out check warns rather than calling them missing |
|
|
196
|
-
| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the
|
|
197
|
-
| `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the
|
|
198
|
-
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every
|
|
196
|
+
| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the project in, `--json` |
|
|
197
|
+
| `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the project's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
|
|
198
|
+
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every project under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every project refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any project while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name; the headers already set are kept, as the dashboard's card keeps them, and `--header name=` drops one), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin, and in a terminal it (or no `--key`) asks for it hidden — a pasted key works, `--use` also runs on it from now on in the same request (as `model use own`, which the dashboard's Save does) — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` runs every step on foldrun's models — the platform's keys, billed in credits at foldrun's price list, hosted only; a provider the platform cannot serve now is refused — and `model use own` goes back to the account's own key, which is kept. `model prices` (`--provider <p>`, `--json`) lists foldrun's price list as the account pays it, USD per million tokens. `export` downloads everything the platform holds about the account — projects, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). `beta` shows whether the account gets beta features first, and the beta flags as they stand for it; `beta on` joins the beta, `beta off` leaves it (an admin of every project; `--json`). Singular — `accounts` below is the list of logins on this machine |
|
|
199
199
|
| `foldrun account clear compute <vcpu\|memory\|disk>…` | drops just those figures of the account's own pool and keeps the rest (`{ compute: { diskGiB: null } }`, as the Governance card's emptied field); bare `clear compute` drops all three. `clear notify email` or `clear notify url` drops one channel and keeps the other and the events; the last channel goes with `clear notify`, which turns notify off |
|
|
200
|
-
| `foldrun workspace` | one deployed
|
|
201
|
-
| `foldrun workspace clear compute <vcpu\|memory\|disk>…` | the same for one
|
|
202
|
-
| `foldrun workspace vocabulary` | what the dashboard's editor completes as you type in a
|
|
203
|
-
| `foldrun notify test` | send one test notification to whatever the
|
|
204
|
-
| `foldrun webhooks deliveries` | the `notify:` webhooks a
|
|
200
|
+
| `foldrun workspace` | one deployed project's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set compute vcpu 2 memory 4 disk 20` (this project's own pool, inside the account's; any of them), `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this project's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
|
|
201
|
+
| `foldrun workspace clear compute <vcpu\|memory\|disk>…` | the same for one project (`--to`): just those figures of its own pool, and `clear notify email\|url` for one channel of its own `notify:`, the other and the events kept |
|
|
202
|
+
| `foldrun workspace vocabulary` | what the dashboard's editor completes as you type in a project (`--to`): agents, flows, skills, tools, secrets (names only), scripts, document types and linkable documents (`GET …/vocabulary`; `--json`) |
|
|
203
|
+
| `foldrun notify test` | send one test notification to whatever the project's `notify:` resolves to, and print what happened — the provider's own words when it failed ("domain not verified"). Exits 1 when it did not go. `--to <workspace>` |
|
|
204
|
+
| `foldrun webhooks deliveries` | the `notify:` webhooks a project sent, newest first: event, status (`delivered`, `retrying`, `failed`, `skipped`), attempts, the last answer and the delivery id — and a switched-off endpoint first, with the way back. `--failed` for the ones that gave up, `--status <s>`, `--event <e>`, `--limit`, `--offset`, `--json`. `--to <workspace>` |
|
|
205
205
|
| `foldrun webhooks redeliver <id>` | send one delivery again now, with the same `X-Foldrun-Delivery` id; prints the attempt and exits 1 when it was refused. `--to <workspace>` |
|
|
206
|
-
| `foldrun notifications` | what mail you get, category by category: `always` for the required ones (security, invites, billing, account), `on`/`off` for the rest, and the
|
|
207
|
-
| `foldrun notifications set <category> on\|off` | turn one category off, or back on — account-wide, or for one
|
|
206
|
+
| `foldrun notifications` | what mail you get, category by category: `always` for the required ones (security, invites, billing, account), `on`/`off` for the rest, and the projects where run alerts or approvals differ. `--json` |
|
|
207
|
+
| `foldrun notifications set <category> on\|off` | turn one category off, or back on — account-wide, or for one project with `--to <workspace>` (`run-alerts`, `approvals`). A required category is refused with the reason |
|
|
208
208
|
| `foldrun flags` | the feature flags for this account: each one `on` or `off` and why — `account` (set for this account), `global` (set for every account), `rollout` (a share of accounts, with its percentage) or `default` — and what it does. Read-only: only the platform's operator changes a flag (on foldrun's hosted platform; a self-hosted install runs every flag at its default). `--json` for the API's answer as it came. See [Feature flags](feature-flags.md) |
|
|
209
|
-
| `foldrun history [path]` | every change to a deployed
|
|
209
|
+
| `foldrun history [path]` | every change to a deployed project, newest first: revision id, when, who, the message and the files. A path narrows it to one file; `--id <revision>` prints that revision as diffs; `--limit <n>`; `--to <workspace>` |
|
|
210
210
|
| `foldrun history restore <path> --id <revision>` | the History drawer's **Restore this version**: the file is rewritten with that revision's text as a new revision, `restored <rev> from history`, so the restore is itself undone the same way. Shows the diff against the file now and asks (`--yes`, `--dry-run`); sent with `ifMatch`, so a file that changed since is refused. A version that does not pass today's checks is still restored, and the errors are printed (`--to`) |
|
|
211
|
-
| `foldrun restore <workspace> --to <revision\|time\|age>` | put a
|
|
212
|
-
| `foldrun backups` | how the account is backed up: the schedule, how many are kept, the last snapshot (verified? copied off the server? encrypted?), the snapshots that hold the account, each marked encrypted or not, each
|
|
211
|
+
| `foldrun restore <workspace> --to <revision\|time\|age>` | put a project's source back as it was then — `--to` is a revision id (`r-…`, from `foldrun history`), the commit a deploy named, a date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`). Always shows the change first (`--dry-run`: the full diff and nothing else); the restore asks for the project's name typed back (`--yes` with no terminal) and sends the removals it showed, so a file added in between refuses it. A new revision, so it prints the `foldrun restore … --to <from>` that undoes it. Runs, `state/`, storage and secrets are not touched. See [Backups and restore](backups-and-restore.md) |
|
|
212
|
+
| `foldrun backups` | how the account is backed up: the schedule, how many are kept, the last snapshot (verified? copied off the server? encrypted?), the snapshots that hold the account, each marked encrypted or not, each project's last change, and earlier restore requests (`--limit`, `--json`). `backups request --what runs\|state\|storage\|everything --at "<when>" [--to <workspace>] [--backup <id>] [--note "…"]` asks the platform team for a restore from a snapshot — recorded and emailed; nothing is restored until they do it. `backups requests` lists every request this account has made, and where each stands (`GET /api/account/backups/requests`, `--json`) |
|
|
213
213
|
| `foldrun accounts` | every account signed in on this machine whose sign-in still works, and which one a bare command acts as. Each is asked once (`GET /api/me`, in parallel); one whose key is refused (revoked, expired, an account that is gone) or whose platform does not answer is left out and counted in one line — the active one is always shown, marked when it fails. `--all` lists every one with what it answered; `accounts prune` forgets the refused ones on this machine (asks first; `--yes` on a pipe; `--unreachable` also those that did not answer). `foldrun profiles` is the same command |
|
|
214
214
|
| `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
|
|
215
215
|
| `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
|
|
216
|
-
| `foldrun keys rotate <id>` | a new key with the old one's label, role,
|
|
216
|
+
| `foldrun keys rotate <id>` | a new key with the old one's label, role, projects and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
|
|
217
217
|
| `foldrun keys set <id> --customer required\|optional` | whether every run the key starts must name an end customer ([end customers](runs#end-customers)); make one that requires it from the start with `foldrun keys create <label> --require-customer`. `PATCH /api/keys/<id>` |
|
|
218
218
|
| `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each published with `a2a:` (a flow not published when the key is minted is refused: publish first) — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
|
|
219
|
-
| `foldrun a2a ls --to <ws>` | what a
|
|
219
|
+
| `foldrun a2a ls --to <ws>` | what a project serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the project's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`; then, under **Secret and code**, every agent that holds a secret and can run code, accepted or not, with the `--accept-risk` line that accepts it. `--json` prints the answer as it came |
|
|
220
220
|
| `foldrun a2a publish <flow>` | sets `a2a: { publish: true }` in the flow, keeping the rest of its block: `--name`, `--description`, `--example "…"` (repeatable — the card's examples), `--public-card` (the card is readable without a key; calling never is) or `--private-card`. Checked with core's `a2a:` rules before anything is written; shows the diff, `--dry-run` writes nothing. Without `--to` it edits this folder (`deploy` ships it); `--to <workspace>` sends the flow page's `PATCH …/flows/<flow> { a2a, expect }` — an admin's, the platform refuses an editor — and prints the card URL. A caller also needs an A2A key that names the flow |
|
|
221
221
|
| `foldrun a2a unpublish <flow>` | `a2a: publish: false` — no outside agent may call it, whatever keys name it; the rest of `a2a:` stays for the next publish. `--to`, `--dry-run` as for `publish` |
|
|
222
222
|
| `foldrun a2a publish <flow> --accept-risk <agent,…>` | `a2a: accept_risk` — the flow's agents an admin accepts holding a secret while they can run code: their answer goes back to the caller, so without it such a flow is not published (`400`, `a2a_secret_code`) and takes no new task ([A2A](a2a.md#secret-and-code-accept_risk)). Name every agent accepted — the list replaces the flow's; `--clear-accept-risk` takes it out. With `--to`, an admin's |
|
|
@@ -224,17 +224,17 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
224
224
|
| `foldrun a2a card <flow> --to <ws>` | the flow's card URL and JSON-RPC endpoint, then the card itself. A private card is read with an A2A key from `$FOLDRUN_A2A_KEY` (or `--key-env NAME`); without one the URLs are printed and the card is not |
|
|
225
225
|
| `foldrun a2a call <card-url> "<text>"` | a small A2A 1.0 client (core's `a2a-client`), to try a published flow or any A2A agent: reads the card (its JSON-RPC interface must be at the card's own origin; redirects are never followed), sends `SendMessage` with the text and `--data <json\|@file>` as a data part (`--context <id>` continues a conversation), prints the task id, then polls `GetTask` until the task ends or `--max-wait <s>` (default 300) runs out — `--no-wait` (or `--return-immediately`, A2A's name for it) returns at once. Prints the state and the answer (`--json` the task). The key is an A2A key from `$FOLDRUN_A2A_KEY` or `--key-env NAME`, never this CLI's API key and never a command-line value. Exit 0 when completed or still open, 1 when failed, canceled or rejected |
|
|
226
226
|
| `foldrun a2a status <task-id> --card <url>` | `GetTask`: the task as it stands, and its answer once it has one (`--json`). `foldrun a2a cancel <task-id> --card <url>` sends `CancelTask` (asks first; `--yes` on a pipe) — on a foldrun flow that stops its run; exit 0 when it reads canceled. The exit code is the same with or without `--json`: `status` exits 1 for a failed, rejected or canceled task. An agent's text and ids are printed with terminal control characters removed |
|
|
227
|
-
| `foldrun audit` | the account's audit log, newest first — sign-ins and refusals, sessions, MFA, keys minted, rotated and revoked, invites and role changes, secrets set and deleted (by name), deploys,
|
|
227
|
+
| `foldrun audit` | the account's audit log, newest first — sign-ins and refusals, sessions, MFA, keys minted, rotated and revoked, invites and role changes, secrets set and deleted (by name), deploys, project deletes, plan and billing changes, and every time support viewed the account, with the reason. `--since 7d` (default) or a date, `--until`, `--action apikey` (a family or one action), `--actor <email\|key:label\|support:email>`, `--to <workspace>`, `--limit`, `--all` to follow every page, `--json`, `--csv [--file audit.csv]`. The owner's and unscoped admins'. There is no `audit` for support's view-as: that is a person's act in the browser, never a key's |
|
|
228
228
|
|
|
229
229
|
## Options
|
|
230
230
|
|
|
231
231
|
| | |
|
|
232
232
|
|---|---|
|
|
233
|
-
| `--workspace <dir>` | the
|
|
233
|
+
| `--workspace <dir>` | the project folder (default `.`). On `init` it names the first project instead |
|
|
234
234
|
| `--flat` | `init`: the single-folder shape — `agents/` and `flows/` at the root, no account around them |
|
|
235
235
|
| `--from <template>` | `init`: start from a shipped template, e.g. `templates/hello` |
|
|
236
|
-
| `--starter` | `new`, `workspaces new`: include the example researcher, writer and `publish` flow — a new
|
|
237
|
-
| `--as <name>` | `agent import`: the name the copy gets in this
|
|
236
|
+
| `--starter` | `new`, `workspaces new`: include the example researcher, writer and `publish` flow — a new project is otherwise blank |
|
|
237
|
+
| `--as <name>` | `agent import`: the name the copy gets in this project (rewrites its `name:`); `storage put`: the path one uploaded file lands at |
|
|
238
238
|
| `--transport <k>` | `tool new`: `script` (the default — a folder with its program beside it), `http` or `mcp` |
|
|
239
239
|
| `--language <l>` | `tool new`, `source new`, `library new`: the script's language — `javascript`, `python` or `bash` |
|
|
240
240
|
| `--task "<text>"` | the instruction for a manual run |
|
|
@@ -254,7 +254,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
254
254
|
| `--flow <name>` | `runs`, and a bulk `stop` or `rerun`: only that flow's runs. `flow add … subflow`: the other flow to run as a step |
|
|
255
255
|
| `--agent`, `--instruction`, `--after`/`--before`, `--group`, `--step`, `--cases`/`--else`, `--each`/`--max`, `--loop`/`--until`/`--judge`, `--question`, `--wait`, `--on-fail`, `--off` | `flow add`: see the patterns above. `--agent` on `rerun` is the first step that agent runs; `--question` on `answer` picks one of several questions; `--wait` alone stays the switch `invoke` and `agent run` read |
|
|
256
256
|
| `--schedule "<cron>"`, `--timezone <zone>` | `flow trigger schedule`: the cron line (5 fields, or `@daily`) and the zone it is read in |
|
|
257
|
-
| `--team`, `--started`, `--mine`, `--all` | `inbox`: which bucket — the rest of what waits in your
|
|
257
|
+
| `--team`, `--started`, `--mine`, `--all` | `inbox`: which bucket — the rest of what waits in your projects, runs you started, what is assigned to you, or every one (default: assigned and started). `--workspace <ws>`: only that project's items. `inbox read --all` marks every unread item read |
|
|
258
258
|
| `--dismissed`, `--unread` | `inbox`: what you set aside; only what you have not read |
|
|
259
259
|
| `--models <m[:effort],…>` | `eval compare`: the settings to compare — two to four tiers or model ids, each with an optional `:effort` |
|
|
260
260
|
| `--if-version <n>` | `account model use`: change the choice only while it is still that `choiceVersion` (`account model --json` shows it; 0: never chosen) — refused (409) when someone chose since, as Settings does |
|
|
@@ -270,7 +270,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
270
270
|
| `--preview` | `storage cat`: the platform reads the file and prints what is in it |
|
|
271
271
|
| `--ttl <days>`, `--forever` | `storage share`: how long the link works (default 7 days), or never expires. `--forever` on `keys create`: the key never expires |
|
|
272
272
|
| `--into <folder/>` | `storage put`: upload under that folder of `storage/` |
|
|
273
|
-
| `--all` (storage) | `storage ls`: every
|
|
273
|
+
| `--all` (storage) | `storage ls`: every project's storage; `storage shares`: expired and revoked links too |
|
|
274
274
|
| `--backup <id>` | `backups request`: the snapshot to restore from, by its id (optional; `--at` names the point either way) |
|
|
275
275
|
| `--csv` | `billing statement`: the CSV instead of the table |
|
|
276
276
|
| `--csv` (audit) | `audit`: the log as CSV, for an auditor — `--file <path>` saves it |
|
|
@@ -283,7 +283,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
283
283
|
| `--id <revision>` | `history`: one revision, as diffs |
|
|
284
284
|
| `--engine <e>` | `login <site>`: the browser to sign in with — `chrome` (default; it signs in with Chromium, so `chromium` is the same), `firefox` or `safari` (`webkit`). Not `lightpanda` or `obscura`, which keep no profile to sign in with — the full list is [Engines](tools#engines) |
|
|
285
285
|
| `--new-client` | `connect`: enter a new OAuth client even when one is saved for the secret |
|
|
286
|
-
| `--limit <n>` | `runs`, `billing`, `history`: how many rows, newest first (`runs` default 20, `billing` 15); `triggers`: how many decisions and deliveries (default 10). Each
|
|
286
|
+
| `--limit <n>` | `runs`, `billing`, `history`: how many rows, newest first (`runs` default 20, `billing` 15); `triggers`: how many decisions and deliveries (default 10). Each project is asked for its own newest `n` before the merge, so one busy desk cannot crowd out a quiet one |
|
|
287
287
|
| `--limit <n>` (usage) | `usage`: rows of by flow and by agent, the most charged first (default 10; `0` hides them) |
|
|
288
288
|
| `--step <n>` | `approve`, `reject`: decide one gate, numbered as `report` prints it. Without it, every step of that run which is waiting |
|
|
289
289
|
| `--payload <json\|text\|@file>` | `approve`: release a step waiting on `wait: event` with this body (`POST …/approve` `{ payload }`). JSON is sent as JSON, anything else as text; `@file` reads a file |
|
|
@@ -297,12 +297,12 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
297
297
|
| `--print` | `open`: print the URL, do not open it |
|
|
298
298
|
| `--value "<text>"` | `secrets set`: skip the prompt — careful with shell history |
|
|
299
299
|
| `--oauth2` | `secrets set`: store an auto-refreshing OAuth credential instead of a value — the token URL, client id, client secret and refresh token are prompted; `--token-auth` says how the app proves itself |
|
|
300
|
-
| `--workspaces <a,b>`, `--none` | `secrets set --account`: limit the account secret to those
|
|
300
|
+
| `--workspaces <a,b>`, `--none` | `secrets set --account`: limit the account secret to those projects, or to none, in the same write. `secrets workspaces`: `--all` or `--none` instead of names |
|
|
301
301
|
| `--with-client` | `secrets rm`: also delete the account secret's saved OAuth client when no connection uses it any more (asks) |
|
|
302
302
|
| `--use` | `account model set`: run on the key from now on, in the same request |
|
|
303
303
|
| `--site <domain>`, `--clear` | `secrets set`, `secrets sites`: a site the secret is bound to (repeatable); `--clear` unbinds |
|
|
304
304
|
| `--add <site>`, `--remove <site>` | `agent network`: a site to add to, or take off, the agent's `network:` list (repeatable) |
|
|
305
|
-
| `--account` | `secrets`: account scope rather than this
|
|
305
|
+
| `--account` | `secrets`: account scope rather than this project's — the project is the folder's name (`--workspace`), local or on the platform alike |
|
|
306
306
|
| `--wait` | `invoke`, `agent run`: hold on and print the result. Asked in 25-second pieces, so a flow that runs for many minutes is never cut by whatever sits in front of the platform; a run parked on a person prints its page and exits 2 |
|
|
307
307
|
| `--from <n>` | `invoke`, `flow run`, `rerun`: start at step n; earlier steps are recorded as skipped. A bulk `rerun` defaults to 1. (One flag, two meanings: a template on `init`, a step everywhere else) |
|
|
308
308
|
| `--no-browser` | `login`, `connect`: print the address instead of opening it |
|
|
@@ -327,14 +327,14 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
327
327
|
| `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
|
|
328
328
|
| `--card <url>` | `a2a status`, `a2a cancel`: the agent card of the agent that holds the task |
|
|
329
329
|
| `--force` | `deploy`: deploy while runs are in flight. `pull`, `storage get`: overwrite local files |
|
|
330
|
-
| `--no-runtimes` | `deploy`: do not wait for the
|
|
330
|
+
| `--no-runtimes` | `deploy`: do not wait for the project's environments to be built, or print them |
|
|
331
331
|
| `--platform` / `--yes` | `workspaces rm`: delete it on the platform, said twice because it cannot be undone |
|
|
332
332
|
| `--platform` | `workspaces new`, `agent new`, `flow new`, `tool new`: make it on the platform, not in this folder. `status`: the platform's own health (`--history` for the daily record) |
|
|
333
333
|
| `--description`, `--model`, `--pattern`, `--template` | `agent new --platform`: its description and model tier. `flow new --platform`: the shape to start from. `tool new --platform`, `source new`, `library new`: a transport or gallery entry to start from |
|
|
334
334
|
| `--list` | `agent import`: what could be imported, importing nothing |
|
|
335
335
|
| `--on <event>` | `hook add`: what the hook listens for — `tool.call`, `tool.result`, `step.start` or `step.end` |
|
|
336
336
|
| `--tool <pattern>` | `hook add`: which tools a `tool.call` or `tool.result` hook sees — `Bash`, `Write\|Edit`, `mcp__*`; all of them when unset |
|
|
337
|
-
| `--library` | `hook add`, `hook rm`: the account library's `library/hooks/`, not this
|
|
337
|
+
| `--library` | `hook add`, `hook rm`: the account library's `library/hooks/`, not this project's |
|
|
338
338
|
| `--event <json\|@file>` | `hook test`: the event the hook reads on stdin (default: a sample for its `on:`) |
|
|
339
339
|
| `--path <p>` | `tool test`: the path an http tool should probe, appended to its `base:` — a path that escapes the base is refused, the same confinement the agent gets |
|
|
340
340
|
| `--timeout <s>` | how many seconds one request to the platform may take — or `FOLDRUN_TIMEOUT`. Default 30, and 300 for `tool test`, where the tool itself is the thing being waited on |
|
|
@@ -361,14 +361,14 @@ my-account/
|
|
|
361
361
|
```
|
|
362
362
|
|
|
363
363
|
Every command works from anywhere inside it. At the account root they act on
|
|
364
|
-
the whole account; inside a
|
|
364
|
+
the whole account; inside a project, on that project.
|
|
365
365
|
|
|
366
366
|
The older shape — a single folder with `agents/` and `flows/` at its root — is
|
|
367
367
|
still read by every command, unchanged, and `foldrun init --flat` still makes
|
|
368
368
|
one. A folder shape is a file format: it does not break because a better one
|
|
369
369
|
arrived.
|
|
370
370
|
|
|
371
|
-
Inside an account folder, the workspace-scoped commands take the
|
|
371
|
+
Inside an account folder, the workspace-scoped commands take the project as a
|
|
372
372
|
positional, or need nothing when there is exactly one:
|
|
373
373
|
|
|
374
374
|
```sh
|
|
@@ -378,9 +378,9 @@ foldrun deploy blog-desk
|
|
|
378
378
|
```
|
|
379
379
|
|
|
380
380
|
**The account's own AGENTS.md** — the shared context every agent in every
|
|
381
|
-
|
|
381
|
+
project reads — goes up with the account: `deploy` at an account root sends
|
|
382
382
|
it when it differs (`PUT /api/account/agents-md`, checked as a deploy checks
|
|
383
|
-
it; an admin of every
|
|
383
|
+
it; an admin of every project may send it — anyone else is told and the
|
|
384
384
|
rest of the deploy goes on), and `pull` fetches it (refusing to overwrite a
|
|
385
385
|
local edit without `--force`, as for every file). The coding-agent block the
|
|
386
386
|
CLI keeps in that file is never compared or read by a running agent. It is
|
|
@@ -405,7 +405,7 @@ admin's: a key is never an owner.
|
|
|
405
405
|
|
|
406
406
|
That key lasts 90 days, and renews itself: when a command finds fewer than
|
|
407
407
|
14 days left, the CLI rotates the key from itself (same label, role and
|
|
408
|
-
|
|
408
|
+
projects) and stores the new one, saying so on one dim line. A machine in
|
|
409
409
|
use never sees its sign-in end; one left unused for 90 days is signed out,
|
|
410
410
|
and the next command says to run `foldrun login` again. A key handed in with
|
|
411
411
|
`--token` or `FOLDRUN_TOKEN` is never renewed — its end is its owner's.
|
|
@@ -426,7 +426,7 @@ made it, revokes it.
|
|
|
426
426
|
**In CI, set `FOLDRUN_TOKEN`** rather than logging in: the environment beats
|
|
427
427
|
the file, so a job with a key in its variables never reads one from disk.
|
|
428
428
|
`foldrun keys create ci --workspaces leads` makes a key that opens that one
|
|
429
|
-
|
|
429
|
+
project and nothing else on the account.
|
|
430
430
|
|
|
431
431
|
## Signing in to a site, for an agent
|
|
432
432
|
|
|
@@ -471,7 +471,7 @@ web:
|
|
|
471
471
|
It also says which cookie looks like the login and **when it dies**, so the
|
|
472
472
|
answer to "why did it stop working" exists before it stops working.
|
|
473
473
|
|
|
474
|
-
`--account` stores against the account rather than this
|
|
474
|
+
`--account` stores against the account rather than this project, `--to
|
|
475
475
|
<workspace>` picks another, `--local` keeps it in this machine's store, and
|
|
476
476
|
`--print` shows everything without storing a thing. `--engine firefox` or
|
|
477
477
|
`webkit` signs in through those instead.
|
|
@@ -522,7 +522,7 @@ CI job with a key in its environment never reads the file.
|
|
|
522
522
|
### Getting a credential for someone else's account
|
|
523
523
|
|
|
524
524
|
**A key is its account.** The platform reads the account off the key, so
|
|
525
|
-
your own key cannot be pointed at somebody else's
|
|
525
|
+
your own key cannot be pointed at somebody else's projects however the
|
|
526
526
|
command is written — which is the property that makes keys safe to hand
|
|
527
527
|
out, and the reason a second account needs a second credential.
|
|
528
528
|
|
|
@@ -559,7 +559,7 @@ path for a lost password, not a way in — and the person will be signed out
|
|
|
559
559
|
without knowing why unless you tell them.
|
|
560
560
|
|
|
561
561
|
Joining a team is a different thing again: a member of ONE account, with a
|
|
562
|
-
role and a
|
|
562
|
+
role and a project scope. See [Team and access](team-and-access).
|
|
563
563
|
|
|
564
564
|
## Talking to a platform
|
|
565
565
|
|
|
@@ -571,20 +571,20 @@ installation:
|
|
|
571
571
|
| `--url <url>` | the platform, or `FOLDRUN_URL`, or where you last signed in |
|
|
572
572
|
| `--token <key>` | an API key, or `FOLDRUN_TOKEN`, or the one `foldrun login` stored |
|
|
573
573
|
| `--profile <name>` | act as one stored account for this command alone |
|
|
574
|
-
| `--to <workspace>` | which
|
|
574
|
+
| `--to <workspace>` | which project there (deploy defaults to the folder name) |
|
|
575
575
|
| `--tenant <name>` | account to deploy into (local installations only) |
|
|
576
576
|
| `--data <dir>` | the installation's data directory |
|
|
577
577
|
| `--commit <sha>` | record which commit a deploy is |
|
|
578
578
|
| `--dry-run` | check and report, change nothing |
|
|
579
579
|
| `--force` | deploy even while runs are in flight |
|
|
580
580
|
|
|
581
|
-
`check`, `run`, `eval` and `probe` are local — they read the
|
|
581
|
+
`check`, `run`, `eval` and `probe` are local — they read the project on disk
|
|
582
582
|
and the runs beside it — until `check --to` or `eval --to` names a deployed
|
|
583
|
-
|
|
583
|
+
project. `flow add`, `flow show` and `agent link`/`unlink` edit and read this
|
|
584
584
|
folder, and the deployed copy only when `--to`, `--url`, `--profile` or
|
|
585
585
|
`--token` is given: being signed in is not enough to send an edit there. `logs` and `deploy` are local too, until a platform is
|
|
586
586
|
named — by `--url`, by `FOLDRUN_URL`, or by having signed in (`--local` puts a
|
|
587
|
-
deploy back on this machine): then it lists that
|
|
587
|
+
deploy back on this machine): then it lists that project's runs there, prints one run's
|
|
588
588
|
trail, and `--follow` tails a live one. `open` always needs a platform.
|
|
589
589
|
|
|
590
590
|
## The loop, in order
|
|
@@ -603,5 +603,5 @@ foldrun open runs # the same, in the browser
|
|
|
603
603
|
```
|
|
604
604
|
|
|
605
605
|
Previews of a branch come back with the GitHub and GitLab app; until then a
|
|
606
|
-
second
|
|
606
|
+
second project (`foldrun deploy --to leads-try`) is the place to try a
|
|
607
607
|
change.
|