foldrun 14.3.0 → 14.4.0

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 CHANGED
@@ -116,28 +116,33 @@ const HELP = `foldrun — agents are just folders
116
116
  foldrun check --rules every rule check knows: id, level, what it guards against (--json)
117
117
  foldrun check --to <ws> --online also the network checks, run by the platform: known vulnerabilities for exact runtime pins (OSV) and remote MCP servers' tool text — and what could not be checked
118
118
  foldrun agent run <name> run one agent once on the platform (--task "…", --to, --wait, --test)
119
- foldrun agent link <agent> add to its team, in its frontmatter: --subagent <worker>, --consult <agent> or --can-ask (--description for a worker with none)
119
+ foldrun agent run <name> --no-task run it with no instruction, on its own prompt alone — the dashboard's Run (--to, --wait, --test)
120
+ foldrun agent link <agent> add to its team, in its frontmatter: --subagent <worker> (--isolated: sandbox: own on the worker), --consult <agent> or --can-ask (--description for a worker with none)
120
121
  foldrun agent unlink <agent> take one away: --subagent <name>, --consult <name> or --can-ask
121
122
  foldrun agent network <agent> the sites its sandbox may reach; set the level (open, trusted, none, inherit) and --add / --remove <site> (repeatable)
122
123
  foldrun agent import <workspace>/<agent> copy an agent you already have in another workspace into this one — its agent.md, own skills and scripts, not its memory (--as <name>, --workspace <name>; --to <ws> on the platform)
123
124
  foldrun agent import --list what could be imported into a deployed workspace: every other workspace you can read, and its agents (--to, --json)
124
125
  foldrun flow add <flow> <pattern> one canvas block as a markdown edit: chain, parallel, router, fan-out, loop, approval, ask, wait, rescue, subflow — diff shown, checked, --dry-run
125
126
  foldrun flow rm-step <flow> --step <n|agent> delete one step (its options too); groups renumber, agent file untouched — says what else changes, diff, checked, asks (--yes), --dry-run
127
+ foldrun flow rm-step <flow> --step 2,4 delete several steps in one revision (one write, or one PATCH with --to), as the canvas's multi-select delete
126
128
  foldrun flow dup-step <flow> --step <n|agent> copy one step (marker and options) directly under it, in parallel with it — diff, checked, --dry-run
127
129
  foldrun flow show <flow> the flow as the canvas draws it: trigger, groups, step chips, each agent's team, check problems in place
128
130
  foldrun flow run <flow> start a flow on the platform — the same command as invoke
131
+ foldrun flow inputs <flow> its saved input sets, as "Run with…" lists them (this folder, or --to; --json)
132
+ foldrun flow inputs save <flow> <name> --task "…" save one into evals/<flow>-inputs.md (a set of that name is replaced; --file for the task, --to the deployed copy)
129
133
  foldrun flow hook <flow> the flow's webhook URL as it is now, changing nothing (--json) — the URL is a credential
130
134
  foldrun flow rotate-hook <flow> a new webhook URL for a flow; the old one stops at once — asks first, --yes means it
131
135
  foldrun flow set <flow> --step <n|agent> key=value … the step editor: model, effort, max_output_tokens, retry, timeout, verify, when, case, else, loop, until, each, max, limits, instruction (key= clears) — diff, checked, --dry-run
132
136
  foldrun flow trigger <flow> manual|webhook|schedule the trigger picker (--schedule "<cron>", --timezone <zone>) — diff, checked, --dry-run
133
137
  foldrun flow compute <flow> vcpu <n> memory <GiB> disk <GiB> what one run may hold at once across its steps (its compute:) — any of them, --clear for none
138
+ foldrun flow compute <flow> --clear disk drop just the named figures (vcpu, memory, disk), the rest kept
134
139
  foldrun flow filter <flow> --payload <file|-|json> would this delivery start it? its filter: and the condition that held it back (--to <ws>: the deployed flow); exit 1 when not
135
140
  foldrun flow move-step <flow> --step <n|agent> drag a card: --group <g> runs it beside group g, --after <g> gives it its own group after g (0 = first) — diff, checked, --dry-run
136
141
  foldrun flow copy-step <flow> --step <n|agent>[,<n>…] the steps' markdown on stdout, as the canvas's Copy
137
142
  foldrun flow paste <flow> step markdown from stdin or --file in as new groups (--after <g>, default last) or beside one (--group <g>) — diff, checked, --dry-run
138
143
  foldrun flow draft "<what it should do>" Draft with AI on the platform (--to; --flow <name> redrafts one): shows the files and the check, saves on yes (--yes, --dry-run)
139
- foldrun assistant ["<message>"] the dashboard's assistant (also: foldrun ai): answers from the foldrun docs and the deployed workspace's files, writes agents, flows, tools and skills as diffs with the check, saves on yes (--to, --yes, --dry-run, --json); every reply is kept — --conversation <id> carries one on; no message in a terminal is a conversation (/save, /files, /drop, /new, /quit)
140
- foldrun assistant history your kept conversations, newest first (--q <text> searches them, --workspace, --json); show <id> prints one, rm <id> deletes it
144
+ foldrun assistant ["<message>"] the dashboard's assistant (also: foldrun ai): answers from the foldrun docs and the deployed workspace's files, writes agents, flows, tools and skills as diffs with the check, saves on yes (--to, --yes, --dry-run, --json; --page "<what you are looking at>" as the dashboard sends the page it is on); every reply is kept — --conversation <id> carries one on; no message in a terminal is a conversation (/save, /files, /drop, /new, /quit)
145
+ foldrun assistant history your kept conversations, newest first (--q <text> searches them, --workspace, --limit <n>, --json); show <id> prints one, rm <id> deletes it
141
146
  foldrun tool test <name> exercise one tool alone, no model and no run (key=value args, --to)
142
147
  foldrun hook ls the hooks in this workspace and the account library: on, tool, description — invalid ones with the reason (--json); --to <ws>: the DEPLOYED workspace's, who turns each on, and what they denied, rewrote or failed lately (--runs <n>, --all)
143
148
  foldrun hook add <name> --on <event> a hook folder: hook.md and a run.mjs that allows everything, the contract in its comments (--tool <pattern>, --library, --to)
@@ -148,6 +153,7 @@ const HELP = `foldrun — agents are just folders
148
153
  foldrun eval [name] run one eval, or all of them (--to <workspace>: the deployed evals, run on the platform; --last reads their latest results, --run <id> one run's verdict, running nothing)
149
154
  foldrun eval new <name> a new eval in the deployed workspace, its agent the first one there — edit its cases, then eval <name> --to (--to)
150
155
  foldrun eval compare <eval> --models fast,default --to <ws> the cases under 2–4 models side by side (m:effort, --agent, --repeat, --max-usd; --list, --run <id>)
156
+ foldrun eval compare <eval> --models fast@writer,max:high@writer an item's own @agent compares only that agent's steps in that setting (--agent is the default for items without one)
151
157
  foldrun eval improve <eval> --to <ws> ask the assistant for a proposed fix from the failures, wait for the draft (--no-wait)
152
158
  foldrun proposals --to <ws> proposed fixes (--status ready, --eval) — show|apply|dismiss <id> (apply asks; --yes)
153
159
  foldrun eval grades <eval> --to <ws> a grader's findings (trigger: runs): pass rate over --days (30), each graded run (--status fail, --limit); exit 1 on a failure
@@ -155,10 +161,13 @@ const HELP = `foldrun — agents are just folders
155
161
  foldrun promote <run-id> keep a finished run as a regression case in evals/ (--eval <name>, --expect "contains: …" repeatable, --case <name>); a run that went wrong takes --should "what it should have done"
156
162
  foldrun probe <model> live check: can this model hold a tool loop here?
157
163
  foldrun logs [run-id] recent runs in one workspace, or one run's full event trail (--local: this machine's)
158
- foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>
164
+ foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>
159
165
  foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
166
+ foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs) as a view; a name taken is replaced
167
+ foldrun runs views rm <name> delete a saved view (asks; --yes)
160
168
  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 (--to, --yes, --dry-run, --json)
161
169
  foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
170
+ foldrun runs rm <run-id> <run-id>… delete several: lists them, asks once, then deletes each
162
171
  foldrun report <run-id> one run, whole: header, every step, what it wrote and what is still waiting
163
172
  foldrun report <run-id> get <agent>/<path> download a file the run archived from that agent's outputs/ (--file <path>|-, --force)
164
173
  foldrun report <run-id> --compare [<run-id>] beside the flow's last good run (or the one named): changed files and what differs step by step (--json)
@@ -168,36 +177,44 @@ const HELP = `foldrun — agents are just folders
168
177
  foldrun report <run-id> live the live browser view: which agents have a frame; --agent <name> saves the newest as a JPEG (--file <path>|-)
169
178
  foldrun approvals every gate waiting on a person, with its question (--to <workspace> for one)
170
179
  foldrun insights recurring problems found in the runs, with what they cost and what to do (--days, --to, --json)
171
- foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --all, --kind, --unread, --dismissed)
180
+ foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --started, --mine, --all, --kind, --workspace <ws>, --unread, --dismissed)
172
181
  foldrun inbox read|unread|dismiss|restore <id>… mark items in your own view (dismiss sets aside; it still waits where it lives)
182
+ foldrun inbox read --all mark all read: every unread item (--team, --started, --mine for one tab; --kind, --workspace)
173
183
  foldrun mcp this account as MCP tools for an AI app, over stdio, with this machine's sign-in: \`claude mcp add foldrun -- foldrun mcp\` (--read-only: only the tools that read)
174
184
  foldrun mcp connections the AI apps connected over OAuth (claude.ai and the like): which app, whose, what access, last used — everyone's for an admin, else yours (--all adds the disconnected, --json)
175
185
  foldrun mcp disconnect <id> end one: every token it holds stops working (asks; --yes)
186
+ foldrun mcp clients add <name> a machine client for /api/mcp, signing in with client credentials (no person approves its tokens): --role viewer|editor|admin, --workspaces a,b, --write (else read only), --token-auth basic|post|jwt (jwt with --jwks-file <path>); prints the client id and secret, the secret once
176
187
  foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
177
- foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d or --times 5, --note "…"
188
+ foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d, --until <ISO time> or --times 5, --note "…"
178
189
  foldrun issues doctor <id> the run doctor on the issue's newest run, in its workspace: why, and the fix as diffs, saved on yes (--yes, --dry-run, --json)
179
190
  foldrun approve <run-id> release a waiting gate — asks first, --yes means it, --note "…" steers the step; --payload releases a wait: event step
180
- foldrun reject <run-id> refuse one, with --note as the reason
191
+ foldrun reject <run-id> refuse one, with --note as the reason; --event-wait rejects a step waiting on wait: event (the step fails, the run ends)
181
192
  foldrun stop <run-id> kill a run in flight — asks first, --yes means it
182
193
  foldrun stop --status running [--since 2h] [--until 1h] [--flow f] every run a filter matches (runs/bulk): lists them, asks, stops only those (--dry-run, --to)
194
+ foldrun stop <run-id> <run-id>… stop several (runs/bulk): lists them, asks once (--dry-run, --yes)
183
195
  foldrun answer <run-id> "…" answer the question an agent is asking mid-step (--option <n> picks a choice)
184
196
  foldrun message <run-id> "…" say something to a running agent — it hears it after its next tool call
185
197
  foldrun rerun <run-id> run it again from a step (--from <n>) or from an agent's step (--agent <name>); --instruction "…" tells that step something else this once; --wait
186
198
  foldrun rerun --status failed [--since 24h] [--until 2h] [--flow f] rerun every run a filter matches, from --from <n> (default 1) — lists, asks (--dry-run, --to)
199
+ foldrun rerun <run-id> <run-id>… rerun several (runs/bulk), from --from <n> (default 1) — lists, asks once (--dry-run, --yes)
187
200
  foldrun observe where the account fails, retries and spends, per workspace (--to <workspace> in full, --since <days>, --json)
188
201
  foldrun usage what the account consumed, and what it was charged week by week (--days <n>, --json)
202
+ foldrun usage --limit <n> how many rows of by flow and by agent (the most charged; default 10, 0 hides them)
189
203
  foldrun usage compute cores, GiB and disk its running steps may hold — the account, each workspace, each live run — what they hold now, and the steps waiting for room (--json)
190
204
  foldrun schedule every flow that fires on a clock, its cron line and the next times (--to <workspace>)
191
205
  foldrun schedule tick fire whatever is due now — Settings' "Run scheduler now"
192
206
  foldrun guide write the coding-agent rules: a block in AGENTS.md and CLAUDE.md importing it (--check, --print)
193
207
  foldrun docs [page] foldrun's docs, from the copy this CLI ships — what a coding agent should read (--path)
194
- foldrun triggers why nothing ran: per flow, fired vs started and every reason (--since <days>, --to <workspace>)
195
- foldrun storage <verb> what a workspace produced: ls [prefix], cat <path> (--preview: a PDF, sheet, deck or zip as text), get <path>, put <file|folder>... (--into <folder/>, --as <path> for one file), rm <path> — and share <path> (--ttl <days>, --forever), shares (--all), unshare <token>
208
+ foldrun triggers why nothing ran: per flow, fired vs started and every reason, then the newest decisions and the deliveries at the hook and inbox URLs (--since <days>, --limit <n> of each, default 10, --to <workspace>, --json)
209
+ foldrun storage <verb> what a workspace produced: ls [prefix], cat <path> (--preview: a PDF, sheet, deck or zip as text), get <path>, put <file|folder>... (--into <folder/>, --as <path> for one file), rm <path> — and share <path> (--ttl <days>, --forever), shares (--all), unshare <token|id>
210
+ foldrun storage ls --all every workspace's storage, as the account's Storage page: a block per workspace, busiest first ([prefix], --json)
196
211
  foldrun runtimes the environments a deployed workspace's agents need (python, pip and npm packages) and whether each is built — failed ones with the installer's error (--wait holds on while any is building)
197
212
  foldrun billing the account's balance and its recent ledger entries (--limit <n>)
198
213
  foldrun billing statement [YYYY-MM] a month of the ledger (--csv for the file, --file <path> to save it)
199
214
  foldrun billing wallet burn, runway, auto top-up — also set auto-top-up --threshold <usd> --amount <usd> | off, set email <address>
215
+ foldrun billing wallet clear email no receipt or low-balance email (set auto-top-up off keeps the threshold and refill for next time)
200
216
  foldrun billing details who invoices are made out to — also set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …
217
+ foldrun billing details set --clear-address | --clear-email | --clear-abn drop one from the invoice details, the rest kept
201
218
  foldrun billing portal a link to Stripe's billing portal (owner only)
202
219
  foldrun billing plans the plans, which one the account is on and this cycle's credits — also plan <id>, plan cancel, plan resume (asks first)
203
220
  foldrun billing top-up <usd> Stripe's checkout page for adding credit (owner only; --no-browser prints it)
@@ -206,9 +223,11 @@ const HELP = `foldrun — agents are just folders
206
223
  foldrun identity what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
207
224
  foldrun jobs the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
208
225
  foldrun account the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, compute vcpu <n> memory <GiB> disk <GiB>, deploy_block none|secrets|security, network_enforce on|off, owner, alerts <threshold> <value>, judge model|effort <value>; or <job>.<field>, e.g. governance.owner), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} (others kept; name= drops one) | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
226
+ foldrun account clear compute <vcpu|memory|disk>… drop just those figures of the account's pool · clear notify <email|url>: drop one channel, the other and the events kept
209
227
  foldrun account export everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
210
- foldrun account model what steps run on — your own key: set <provider> --key <api key> (--key - reads stdin; custom --base-url --format), remove; or foldrun's models (billed in credits): use foldrun --provider <p>, use own, prices
228
+ foldrun account model what steps run on — your own key: set <provider> --key <api key> (--key - reads stdin; custom --base-url --format; --use runs on it at once, as use own), remove; or foldrun's models (billed in credits): use foldrun --provider <p>, use own, prices
211
229
  foldrun workspace one deployed workspace's settings (--to) — also set <name|description|timezone|budget|compute|notify|network_enforce|owner|alerts|judge> <value> (compute vcpu <n> memory <GiB> disk <GiB>: this workspace's pool) (or <job>.<field>), clear <key>, pause [--reason] [--stop] / resume (the kill switch)
230
+ foldrun workspace clear compute <vcpu|memory|disk>… drop just those figures of its pool · clear notify <email|url>: one channel, the rest kept (--to)
212
231
  foldrun workspace vocabulary the names the dashboard's editor completes in a workspace: agents, flows, skills, tools, secrets, scripts, types, documents (--to, --json)
213
232
  foldrun notify test send one test notification from a workspace and say what happened (--to <workspace>)
214
233
  foldrun webhooks deliveries the notify: webhooks a workspace sent, newest first — status, attempts, last answer (--failed, --status <s>, --event <e>, --limit, --offset, --to)
@@ -219,11 +238,14 @@ const HELP = `foldrun — agents are just folders
219
238
  foldrun history [path] every change to a deployed workspace, newest first (--id <revision> for its diff, --limit, --to)
220
239
  foldrun history restore <path> --id <revision> put one file back as that revision left it, as a new revision — diff, asks (--yes, --dry-run, --to)
221
240
  foldrun restore <ws> --to <revision|time|age> put a workspace's source back as it was then — shows the change, asks for the name typed back (--dry-run: the diff only, --yes)
222
- foldrun backups how the account is backed up (encrypted?), when it last was, the snapshots it is in — also request --what runs|state|storage|everything --at "<when>" [--to <ws>] [--note]
241
+ foldrun backups how the account is backed up (encrypted?), when it last was, the snapshots it is in — also request --what runs|state|storage|everything --at "<when>" [--to <ws>] [--backup <id>] [--note]
223
242
  foldrun backups requests every restore asked of the platform team, and where each stands (--json)
224
- foldrun secrets set NAME store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes; --site <domain> (repeatable) binds it as it is stored
243
+ foldrun secrets set NAME store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m|client-cert|identity|token-exchange for the other shapes; --oauth2 for a refresh token; --site <domain> (repeatable) binds it as it is stored; --account --workspaces a,b or --none limits it as it is stored
244
+ foldrun secrets ls the secrets in scope: where each is set, its sites and workspaces — and on the platform whether the far end last accepted it, refused it (since when) or nothing has used it yet (--json)
245
+ foldrun secrets rm NAME delete one (asks; --yes) — an oauth2 secret's grant is revoked at the provider; an account secret's saved OAuth client left unused is named, and --with-client deletes it too (asks)
225
246
  foldrun secrets sites NAME [site…] bind a secret to sites: the egress proxy fills it for those alone and it never enters a sandbox; no sites lists them, --clear unbinds
226
247
  foldrun secrets workspaces NAME [workspace…] limit an account secret to those workspaces — every other one finds it not set; --all opens it to every workspace again, --none to no workspace, no names shows which may use it (an admin over every workspace; applies to runs that start after it)
248
+ foldrun secrets workspaces NAME … --if-workspaces <a,b|all|none> only if the list is still the one you read — refused otherwise, as Settings does
227
249
  foldrun secrets clients the OAuth clients saved on the platform — also add <name> (--authorize-url/--token-url, --client-id, --scopes, --authorize-param name=value), rm <name>
228
250
  foldrun connect NAME OAuth sign-in from the terminal, stored as an auto-refreshing secret — --client <saved> runs it from a saved client through the platform
229
251
  foldrun deploy [dir] push the whole account, or deploy <workspace> for one of them
@@ -243,6 +265,8 @@ const HELP = `foldrun — agents are just folders
243
265
  foldrun invoke <flow> start a flow on a running platform (--to <workspace>; --once <key> so a retry never starts a second run; --tag <t> repeatable)
244
266
  foldrun source <verb> the files on a platform, one at a time: ls, cat <path>, put <path>, mv, rm (--to <workspace>)
245
267
  foldrun source new <kind> <name> the dashboard's New for any document — tools, knowledge, memory, skills, scripts (agents, flows, evals too): the platform writes the template (--agent <a> inside one agent, --template, --language, --to)
268
+ foldrun source put <path> --check the editor's checked save: refused with the issues (exit 1, nothing saved) when the file would not check out; --empty writes an empty file
269
+ foldrun source share <path> the dashboard's Move to shared: a skill, tool, script, knowledge or memory file (a skill or folder tool whole) into the account library, then out of the workspace — asks (--yes), --dry-run, --overwrite (--to)
246
270
  foldrun open [page] the dashboard for this workspace, in the browser
247
271
  foldrun api spec the platform's OpenAPI 3.1 document (GET /api/openapi.json) — stdout, or --out <file>
248
272
  foldrun api version the API version this account's requests get, the versions served, the rate limits, your last 30 days by version and any deprecated route you still call — also pin <YYYY-MM-DD>, unpin (admin; --json)
@@ -270,13 +294,14 @@ Signing in
270
294
  foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
271
295
  foldrun accounts every account signed in on this machine, and which one is active
272
296
  foldrun use <name> act as one of them from here on
273
- foldrun keys ls the account's API keys: created, last used, expires, scope — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
297
+ foldrun keys ls the account's API keys: created, last used, expires, scope, and which are a machine's CLI sign-in (they renew themselves) — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
274
298
  foldrun keys create <label> --a2a --to <ws> --flows a,b a key for an OUTSIDE agent: it opens /a2a for those published flows and no /api route (--max-tasks N open at once, default 10; --expires); shown once
275
299
  foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
276
300
  foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
301
+ foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
277
302
  foldrun a2a unpublish <flow> a2a: publish: false — no outside agent may call it; the rest of a2a: is kept (--to <ws>, --dry-run)
278
303
  foldrun a2a card <flow> --to <ws> the flow's agent card URL and endpoint, then the card (a private card needs an A2A key in $FOLDRUN_A2A_KEY or --key-env)
279
- foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
304
+ foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait or --return-immediately, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
280
305
  foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
281
306
  foldrun audit the account's audit log, newest first: sign-ins, keys, invites, secrets by name, deploys, support views (--since 7d, --action, --actor, --to, --all, --csv)
282
307
  foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
@@ -290,6 +315,8 @@ Options
290
315
  --transport <k> tool new: script (default), http or mcp
291
316
  --language <l> tool new, source new, library new: the script's language — javascript, python, bash
292
317
  --task "<text>" the instruction for a manual run
318
+ --no-task agent run: start it with no instruction — the agent works from its own prompt alone
319
+ --task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
293
320
  --test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
294
321
  --follow logs: keep tailing a live run (with --url: on the platform)
295
322
  --status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
@@ -300,7 +327,8 @@ Options
300
327
  --since <days> observe, triggers: the window in days (observe default 30, triggers 7)
301
328
  --until <span|date> stop, rerun (bulk): only runs started before then — 2h ago, or a date
302
329
  --verdict <v> runs: only completed runs whose summary leads with it — good, bad, quiet, blocked (comma-separated)
303
- --flow <name> export: that flow and everything it runs; stop, rerun: only that flow's runs; flow add: the other flow a subflow step runs; flow draft: the existing flow to redraft
330
+ --q <words> runs: the runs page's text search — every word, any order, across id, flow, workspace, status, verdict, summary and failure; assistant history: search the conversations
331
+ --flow <name> export: that flow and everything it runs; runs, stop, rerun: only that flow's runs; flow add: the other flow a subflow step runs; flow draft: the existing flow to redraft
304
332
  --agent <name> export: that agent and what it grants; flow add: the agent a chain, parallel or router step runs; rerun: from the first step that agent runs; report live: whose browser frame; source new: the agent the document belongs to
305
333
  --instruction "<text>" flow add: what a new step (chain, parallel, router) is told to do
306
334
  --after <n> flow add, flow move-step, flow paste: put the new group after the nth (0 = first); --before <n> before it (flow add); default last
@@ -314,17 +342,26 @@ Options
314
342
  --on-fail <agent> flow add: who takes the step over when it fails
315
343
  --off flow add: take the pattern off the step instead (fan-out, loop, approval, ask, wait, rescue)
316
344
  --schedule "<cron>" flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
317
- --team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you)
345
+ --team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you); --workspace <ws> only that workspace's items; inbox read --all marks every unread one read
318
346
  --dismissed, --unread inbox: what you set aside; only what you have not read
319
347
  --read-only mcp: offer the AI app only the tools that read — no run, approve, answer, message or stop
320
348
  --models <m[:effort],…> eval compare: two to four tiers or model ids to compare, each with an optional :effort
321
349
  --max-usd <n> eval compare: the spend limit — no run starts once the runs and judges have spent it (default 5)
322
350
  --payload <file|-|json> flow filter: the delivery to test — a file, - for stdin, or JSON inline
323
- --kind <k> secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file 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>), client-cert (--cert-file, --key-file, --passphrase, --export to put it in the sandbox as files too), identity (--audience: keyless cloud access, no credential stored), m2m (--token-url, --client-id, --scopes; secret prompted)
351
+ --kind <k> secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file 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>), client-cert (--cert-file, --key-file, --passphrase, --export to put it in the sandbox as files too), identity (--audience: keyless cloud access, no credential stored), m2m (--token-url, --client-id, --scopes; secret prompted), token-exchange (RFC 8693: --token-url, --client-id, --subject-secret <NAME> whose token is traded, --audience, --scopes, --requested-token-type <urn> to narrow it)
352
+ --oauth2 secrets set: store an auto-refreshing OAuth credential — token URL, client id, client secret and refresh token are prompted (--token-auth picks how the app proves itself)
353
+ --token-auth <how> connect, secrets clients add, secrets set --kind m2m|token-exchange, secrets set --oauth2: how the app proves itself at the token URL — post (the form body, the default), basic (HTTP Basic), none (a public app), jwt (private_key_jwt: --key-file or --generate-key), mtls (a client certificate: --cert-file, --key-file); mcp clients add: basic (default), post or jwt (with --jwks-file)
354
+ --revoke-url <url> connect, secrets clients add: the provider's https revocation endpoint (RFC 7009), when its metadata does not give one; deleting or reconnecting the secret revokes its grant there
355
+ --dpop connect, secrets clients add, secrets set --kind m2m: DPoP-bound tokens (RFC 9449) — the connection gets its own key and its requests carry proofs
356
+ --device connect: sign in with a code typed on any device (RFC 8628), no browser or loopback port here; --device-url <url> when --issuer does not give the endpoint
357
+ --with-client secrets rm: also delete the account secret's saved OAuth client when no connection uses it any more (asks)
358
+ --use account model set: run on the key at once, as account model use own, in the same request
324
359
  --client <name> connect: run the consent from that OAuth client saved on the platform (secrets clients lists them)
325
360
  --subagent <name> agent link, agent unlink: a worker it delegates to (subagents:)
326
361
  --consult <name> agent link, agent unlink: a colleague it asks (agents:)
327
362
  --can-ask agent link, agent unlink: ask in its tools — it may ask you mid-step
363
+ --isolated agent link: with --subagent, sandbox: own on the worker — each job runs in its own sandbox with its own tools, secrets and network
364
+ --backup <id> backups request: the snapshot to restore from, as foldrun backups lists it (optional — --at names the point either way)
328
365
  --description "<text>" agent link: what a --subagent is for, when its file has no description:; agent new --platform: its one line
329
366
  --model <tier> agent new --platform: fast, default or max
330
367
  --pattern <p> flow new --platform: pipeline (default), review-loop, fan-out, debate or router
@@ -337,37 +374,48 @@ Options
337
374
  --tag <t> invoke, flow run: a label on the run — repeatable, sent as tags
338
375
  --inputs <set> invoke, flow run: the task is a saved input set (evals/<flow>-inputs.md, or an eval case for the flow)
339
376
  --preview storage cat: the platform reads the file and prints what is in it
377
+ --ttl <days> storage share: how long the link works (default 7); --forever: it never expires
378
+ --into <folder/> storage put: upload under that folder of storage/
379
+ --as <path> storage put: the path one uploaded file lands at; agent import: the name the copy gets
340
380
  --csv billing statement: the CSV file instead of the table
341
381
  --csv audit: the log as CSV, for an auditor (--file <path> to save it)
342
382
  --threshold / --amount billing wallet set: auto top-up refills --amount (5-500 USD) when the balance falls below --threshold
343
383
  --name / --abn / --address / --email billing details set: the invoice's legal name, ABN, "line1, city, state, postcode, AU", receipt email
384
+ --clear-address / --clear-email / --clear-abn billing details set: drop that one from the invoice details, the rest kept
385
+ --clear-name / --clear-description / --clear-examples a2a publish, a2a unpublish: drop that one from the card, the rest of a2a: kept
344
386
  --days <n> usage: the window the charges cover (default 56); status --platform --history: 1-90 (default 90)
345
387
  --id <revision> history: one revision in full, as diffs
346
388
  --engine <e> login: (with a site) the browser to sign in with — chrome (default: real Google Chrome, Chromium when it is not installed), chromium, firefox or safari
347
389
  --new-client connect: enter a new OAuth client even when one is saved for the secret
348
390
  --step <n> approve, reject: decide only that step; default is every step that is waiting
349
391
  --payload <json|text|@f> approve: release a step waiting on wait: event with this body, recorded as you
392
+ --event-wait reject: refuse a step waiting on wait: event instead of a person's gate — it stops waiting, the step fails and the run ends
350
393
  --note "<text>" approve, reject: guidance the agent reads — or the reason for a refusal; billing credit: the ledger line's note
351
394
  --run <id> eval --to: that eval run's verdict, by the id the run printed; runs nothing
352
395
  --stale [days] agent ls: only agents not run in that many days (never run included); bare, those past alerts: stale_days
353
396
  --reason "<text>" account pause, workspace pause: why — shown to everyone who opens it
354
397
  --stop account pause, workspace pause: also stop every run going now (asks; --yes to mean it)
355
398
  --yes approve, stop, rerun (bulk), pause --stop, flow rotate-hook, flow draft, assistant, history restore, restore <ws>, import, billing plan, workspace set name, team remove, and every rm/revoke/unshare: skip the confirmation, deliberately (required with no terminal)
356
- --json report: the raw run record instead of the report; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, workspaces, workspaces show, agent ls, flow ls, agent import --list, backups requests, team, hook ls: the raw document; version: {cli, core, platform}
399
+ --json report: the raw run record instead of the report; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, workspaces, workspaces show, agent ls, flow ls, agent import --list, backups requests, team, hook ls, secrets ls, triggers, storage ls --all: the raw document; version: {cli, core, platform}
357
400
  --events <a,b> account set notify: failed, awaiting-approval, completed
358
401
  --failed webhooks deliveries: only the ones that gave up
359
- --limit <n> runs, billing, history, changelog: how many rows
402
+ --limit <n> runs, billing, history, changelog: how many rows; triggers: how many decisions and deliveries (default 10)
403
+ --limit <n> usage: rows of by flow and by agent, the most charged first (default 10; 0 hides them)
360
404
  --value "<text>" secrets set: skip the prompt (careful with shell history)
361
405
  --site <domain> secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
362
406
  --clear secrets sites: unbind it; flow compute: no cap of its own; me name: no name
363
- --all secrets workspaces: every workspace may use the account secret again; mcp connections: the disconnected ones too; team invite, team access: every workspace
407
+ --all secrets workspaces: every workspace may use the account secret again; storage ls: every workspace's storage; storage shares: expired and revoked links too; mcp connections: the disconnected ones too; team invite, team access: every workspace
364
408
  --none secrets workspaces, secrets set: no workspace may use the account secret; team access: no workspaces
409
+ --if-workspaces <a,b|all|none> secrets workspaces: change it only while the list is still this one (refused, 409, when someone changed it since)
410
+ --if-version <n> account model use: change it only while the choice is still that choiceVersion (account model --json; 0: never chosen)
365
411
  --workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account); team invite, team access: the workspaces they may open
366
412
  --add <site> agent network: add a site to its network: list (repeatable)
367
413
  --remove <site> agent network: take a site off its network: list (repeatable)
368
414
  --out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
369
415
  --file <path> source put, library put, flow paste: the local file to send (default: stdin); secrets set --kind file|service-account: the file it holds; storage get, report get, report live, account export, export, billing statement: where to write it (- for stdout)
370
416
  --message "<why>" source put: recorded on the file's revision
417
+ --check source put: refuse the save when the file would not check out (422: the issues printed, nothing written)
418
+ --empty source put: write an empty file on purpose (empty input is refused otherwise)
371
419
  --account secrets: account scope instead of the workspace's
372
420
  --wait invoke, agent run: hold on and print the result
373
421
  --path <p> tool test: the path an http tool should probe, appended to its base:
@@ -408,6 +456,8 @@ Platform options (deploy, invoke, secrets, logs, keys)
408
456
  --local deploy: into the installation on this machine, even when signed in
409
457
  --commit <sha> deploy: record which commit this is
410
458
  --overwrite import: replace files the workspace already has with different text (refused otherwise)
459
+ --overwrite source share: replace a library file of the same path (refused otherwise)
460
+ --dry-run source share: list what would move, move nothing
411
461
  --dry-run deploy: check and report, change nothing; flow add, flow set, flow trigger, flow compute, flow move-step, flow paste, flow draft, assistant, history restore, agent link, agent unlink: show the diff, write nothing; restore <ws>: the diff only, restore nothing; import: the preview only, write nothing; stop, rerun (bulk): list what matches, touch nothing
412
462
  --no-runtimes deploy: do not wait for the workspace's environments to be built
413
463
  --force deploy: deploy even while runs are in flight; pull, storage get: overwrite local files
@@ -434,7 +484,7 @@ if (!command || command === "--help" || command === "-h") {
434
484
  // `--value` as the account's argument and stored an empty secret; `--force
435
485
  // ./dir` swallowed the directory. A flag followed by another flag is also
436
486
  // boolean, so an unlisted switch at least does not eat its neighbour.
437
- const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send"]);
487
+ const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
438
488
  // Flags said more than once collect into a list: `--tag a --tag b`.
439
489
  const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
440
490
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
package/docs/api.md CHANGED
@@ -351,7 +351,7 @@ its header and requires a URL it can GET for itself.
351
351
 
352
352
  | Route | Methods | |
353
353
  |---|---|---|
354
- | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect — the owner in person: their signed-in session or the key their own `foldrun login` minted, never another key they minted. An oauth2 recipe from a caller scoped to some workspaces links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PATCH also takes `workspaces` (with or instead of `sites`): `{ name, workspaces: ["sales", "ops"] }` limits an **account** secret to those workspaces — every other one finds it not set, in runs, tool tests, `notify:` (its email too), the egress proxy and MCP, for runs that start after it ([limited to some workspaces](secrets#limited-to-some-workspaces)); `null` opens it to every workspace, `[]` to none; the answer carries `workspaces` (sorted, or `null`). `ifWorkspaces` — the list you loaded, `null` for every workspace — makes it conditional: 409 when the list changed since, nothing written. PUT takes the same `workspaces` and saves it with the value in one write (the answer carries it too); it is never ignored. Account store only (400 with `workspace`), an admin over every workspace (403 for a scoped caller), names of workspaces that exist, checked under the vault's lock (400 otherwise), 404 for a secret that is not there; audited as `secret.workspaces` (PATCH) and in `secret.set` (PUT). GET of the account store lists each limited secret's `workspaces`, and `?workspace=` leaves out an account secret that workspace may not use. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set`. PUT also takes `token_exchange: { token_url, client_id, client_secret?, token_auth?, subject_secret, subject_token_type?, requested_token_type?, audience?, resource?, scope? }`: a secret whose value is another secret's token traded at a token endpoint (RFC 8693); its `kind` is `token-exchange`. Deleting an `oauth2` secret, or replacing one with a PUT, revokes the old grant at the provider (RFC 7009) when its recipe has a `revocation_url`. The secret is written or deleted first, then the old grant is revoked, and the answer carries `revoked: { skipped?, revoked: [refresh_token, access_token], error? }`. `skipped` is `no-revocation-url`, `shared-grant` (another secret holds the same refresh token, or a grant from the same app; providers such as Google revoke per app, so it is kept), `same-app` (the replacement is from the same app, so revoking would end it too) or `unreadable`. A refusal is reported in `error` and never undoes the write. The recipe's `token_auth` (`client_secret_post`, `client_secret_basic`, `none`, `private_key_jwt` with `client_assertion_key`) and `revocation_url` are kept with it. `oauth2.generate_key: true` with `private_key_jwt` makes the key, and the answer carries `public_jwk` |
354
+ | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect — the owner signed in, in the browser: no key, not even their own `foldrun login` one. An oauth2 recipe from a caller scoped to some workspaces links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PATCH also takes `workspaces` (with or instead of `sites`): `{ name, workspaces: ["sales", "ops"] }` limits an **account** secret to those workspaces — every other one finds it not set, in runs, tool tests, `notify:` (its email too), the egress proxy and MCP, for runs that start after it ([limited to some workspaces](secrets#limited-to-some-workspaces)); `null` opens it to every workspace, `[]` to none; the answer carries `workspaces` (sorted, or `null`). `ifWorkspaces` — the list you loaded, `null` for every workspace — makes it conditional: 409 when the list changed since, nothing written. PUT takes the same `workspaces` and saves it with the value in one write (the answer carries it too); it is never ignored. Account store only (400 with `workspace`), an admin over every workspace (403 for a scoped caller), names of workspaces that exist, checked under the vault's lock (400 otherwise), 404 for a secret that is not there; audited as `secret.workspaces` (PATCH) and in `secret.set` (PUT). GET of the account store lists each limited secret's `workspaces`, and `?workspace=` leaves out an account secret that workspace may not use. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set`. PUT also takes `token_exchange: { token_url, client_id, client_secret?, token_auth?, subject_secret, subject_token_type?, requested_token_type?, audience?, resource?, scope? }`: a secret whose value is another secret's token traded at a token endpoint (RFC 8693); its `kind` is `token-exchange`. Deleting an `oauth2` secret, or replacing one with a PUT, revokes the old grant at the provider (RFC 7009) when its recipe has a `revocation_url`. The secret is written or deleted first, then the old grant is revoked, and the answer carries `revoked: { skipped?, revoked: [refresh_token, access_token], error? }`. `skipped` is `no-revocation-url`, `shared-grant` (another secret holds the same refresh token, or a grant from the same app; providers such as Google revoke per app, so it is kept), `same-app` (the replacement is from the same app, so revoking would end it too) or `unreadable`. A refusal is reported in `error` and never undoes the write. The recipe's `token_auth` (`client_secret_post`, `client_secret_basic`, `none`, `private_key_jwt` with `client_assertion_key`) and `revocation_url` are kept with it. `oauth2.generate_key: true` with `private_key_jwt` makes the key, and the answer carries `public_jwk` |
355
355
 
356
356
  `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
357
357
  a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;