foldrun 26.3.3 → 26.3.5

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
@@ -106,14 +106,14 @@ if (command === "--version" || command === "-v") {
106
106
  const HELP = `foldrun — agents are just folders
107
107
 
108
108
  foldrun init [dir] create an account folder: AGENTS.md, library/ and workspaces/<name>
109
- foldrun new <name> another workspace in this account — blank (--starter for the example researcher, writer and flow)
110
- foldrun agent new <name> one more agent in this workspace (--to <workspace> in an account)
111
- foldrun agent new <name> --platform make it in the DEPLOYED workspace, as the dashboard's New agent does (--to, --description, --model)
109
+ foldrun new <name> another project in this account — blank (--starter for the example researcher, writer and flow)
110
+ foldrun agent new <name> one more agent in this project (--to <workspace> in an account)
111
+ foldrun agent new <name> --platform make it in the DEPLOYED project, as the dashboard's New agent does (--to, --description, --model)
112
112
  foldrun flow new <name> one more flow — its first step names an agent you already have
113
- foldrun flow new <name> --platform make it in the deployed workspace from a shape (--pattern pipeline|review-loop|fan-out|debate|router, --to)
114
- foldrun tool new <name> one more tool: a folder with its program beside it (--transport, --language; --platform in the deployed workspace, --template <gallery entry>)
115
- foldrun agent ls the agents deployed in a workspace: model, last run, owner, description (--to, --json, --stale [days]) — flow ls the flows and how each fires
116
- foldrun check [dir] validate every workspace here, and the shared library
113
+ foldrun flow new <name> --platform make it in the deployed project from a shape (--pattern pipeline|review-loop|fan-out|debate|router, --to)
114
+ foldrun tool new <name> one more tool: a folder with its program beside it (--transport, --language; --platform in the deployed project, --template <gallery entry>)
115
+ foldrun agent ls the agents deployed in a project: model, last run, owner, description (--to, --json, --stale [days]) — flow ls the flows and how each fires
116
+ foldrun check [dir] validate every project here, and the shared library
117
117
  foldrun check --to <ws> validate the DEPLOYED copy instead — fetched from the platform, checked here
118
118
  foldrun check --security only the security rules: hard-coded secrets, hidden text, agents that can leak, unpinned code — fails on a warning
119
119
  foldrun check --rules every rule check knows: id, level, what it guards against (--json)
@@ -123,8 +123,8 @@ const HELP = `foldrun — agents are just folders
123
123
  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)
124
124
  foldrun agent unlink <agent> take one away: --subagent <name>, --consult <name> or --can-ask
125
125
  foldrun agent network <agent> the sites its sandbox may reach; set the level (open, trusted, none, inherit) and --add / --remove <site> (repeatable)
126
- 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)
127
- foldrun agent import --list what could be imported into a deployed workspace: every other workspace you can read, and its agents (--to, --json)
126
+ foldrun agent import <workspace>/<agent> copy an agent you already have in another project into this one — its agent.md, own skills and scripts, not its memory (--as <name>, --workspace <name>; --to <ws> on the platform)
127
+ foldrun agent import --list what could be imported into a deployed project: every other project you can read, and its agents (--to, --json)
128
128
  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
129
129
  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
130
130
  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
@@ -144,17 +144,17 @@ const HELP = `foldrun — agents are just folders
144
144
  foldrun flow copy-step <flow> --step <n|agent>[,<n>…] the steps' markdown on stdout, as the canvas's Copy
145
145
  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
146
146
  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)
147
- 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)
147
+ foldrun assistant ["<message>"] the dashboard's assistant (also: foldrun ai): answers from the foldrun docs and the deployed project'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)
148
148
  foldrun assistant history your kept conversations, newest first (--q <text> searches them, --workspace, --limit <n>, --json); show <id> prints one, rm <id> deletes it
149
149
  foldrun tool test <name> exercise one tool alone, no model and no run (key=value args, --to)
150
- 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)
150
+ foldrun hook ls the hooks in this project and the account library: on, tool, description — invalid ones with the reason (--json); --to <ws>: the DEPLOYED project's, who turns each on, and what they denied, rewrote or failed lately (--runs <n>, --all)
151
151
  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)
152
152
  foldrun hook test <name> run one hook here on a sample event, as a step would: its answer and how long it took (--event '<json>'|@file; --to <workspace>: the deployed one, on the platform)
153
153
  foldrun hook rm <name> delete a hook folder — says which agents still turn it on, asks (--yes, --library)
154
154
  foldrun extract [dir] move single-file script tools into folders (tool.md + run.*)
155
155
  foldrun run <target> run an agent or flow HERE (target: name, or flow:name) — on the platform: flow run / invoke a flow, agent run one agent
156
156
  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)
157
- 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)
157
+ foldrun eval new <name> a new eval in the deployed project, its agent the first one there — edit its cases, then eval <name> --to (--to)
158
158
  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>)
159
159
  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)
160
160
  foldrun eval improve <eval> --to <ws> ask the assistant for a proposed fix from the failures, wait for the draft (--no-wait)
@@ -164,7 +164,7 @@ const HELP = `foldrun — agents are just folders
164
164
  foldrun eval trends --to <ws> evals by change, as the Observe page: each eval now against its last run on a different commit, biggest drop first (--json); exit 1 when a change made one worse
165
165
  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"
166
166
  foldrun probe <model> live check: can this model hold a tool loop here?
167
- foldrun logs [run-id] recent runs in one workspace, or one run's full event trail (--local: this machine's)
167
+ foldrun logs [run-id] recent runs in one project, or one run's full event trail (--local: this machine's)
168
168
  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, --context <id>, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
169
169
  foldrun runs outputs <run-id> which files the run archived from its agents' outputs/, with their sizes (--to, --json); report <run-id> get downloads one
170
170
  foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
@@ -172,7 +172,7 @@ const HELP = `foldrun — agents are just folders
172
172
  foldrun runs views rm <name> delete a saved view (asks; --yes)
173
173
  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)
174
174
  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
175
- foldrun runs rm <run-id> <run-id>… delete several: lists them, asks once, then deletes them in one runs/bulk call per workspace, as the dashboard does
175
+ foldrun runs rm <run-id> <run-id>… delete several: lists them, asks once, then deletes them in one runs/bulk call per project, as the dashboard does
176
176
  foldrun runs rm --until <30d|date> delete every finished run that started before then — records, captured calls, archived outputs (an admin; --to <workspace>, --dry-run, --yes); live runs are left alone
177
177
  foldrun report <run-id> one run, whole: header, every step, what it wrote and what is still waiting
178
178
  foldrun report <run-id> get <agent>/<path> download a file the run archived from that agent's outputs/ (--file <path>|-, --force)
@@ -192,7 +192,7 @@ const HELP = `foldrun — agents are just folders
192
192
  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
193
193
  foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
194
194
  foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d, --until <ISO time> or --times 5, --note "…"
195
- 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)
195
+ foldrun issues doctor <id> the run doctor on the issue's newest run, in its project: why, and the fix as diffs, saved on yes (--yes, --dry-run, --json)
196
196
  foldrun approve <run-id> release a waiting gate — asks first, --yes means it, --note "…" steers the step; --payload releases a wait: event step
197
197
  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)
198
198
  foldrun stop <run-id> kill a run in flight — asks first, --yes means it
@@ -203,22 +203,22 @@ const HELP = `foldrun — agents are just folders
203
203
  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
204
204
  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)
205
205
  foldrun rerun <run-id> <run-id>… rerun several (runs/bulk), from --from <n> (default 1) — lists, asks once (--dry-run, --yes)
206
- foldrun observe where the account fails, retries and spends, per workspace, then the window against the one before, why runs went wrong, the agents and tools to watch (--to <workspace> in full, --since <days>, --json)
206
+ foldrun observe where the account fails, retries and spends, per project, then the window against the one before, why runs went wrong, the agents and tools to watch (--to <workspace> in full, --since <days>, --json)
207
207
  foldrun usage what the account consumed, and what it was charged week by week (--days <n>, --json)
208
208
  foldrun usage --limit <n> how many rows of by flow and by agent (the most charged; default 10, 0 hides them)
209
- 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)
209
+ foldrun usage compute cores, GiB and disk its running steps may hold — the account, each project, each live run — what they hold now, and the steps waiting for room (--json)
210
210
  foldrun usage meters what the period used, meter by meter: vCPU, RAM, step disk, storage, network with quantity, rate and credits, the plan fee, each step size, the two credit pots, and tokens by provider and model — your own key at 0 credits (--since <day>, --until <day>, --json)
211
211
  foldrun usage rates what each meter costs this account, its plan and the plans on offer, and the price list for foldrun's models (--json)
212
- foldrun usage budget spend against each cap — the account's and each workspace's budget:, what is spent in its window (today, this week, this month) and how close it is (--to <workspace> for one, --json)
212
+ foldrun usage budget spend against each cap — the account's and each project's budget:, what is spent in its window (today, this week, this month) and how close it is (--to <workspace> for one, --json)
213
213
  foldrun schedule every flow that fires on a clock, its cron line and the next times (--to <workspace>)
214
214
  foldrun schedule tick fire whatever is due now — Settings' "Run scheduler now"
215
215
  foldrun guide write the coding-agent rules: a block in AGENTS.md and CLAUDE.md importing it (--check, --print)
216
216
  foldrun docs [page] foldrun's docs, from the copy this CLI ships — what a coding agent should read (--path)
217
217
  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)
218
- 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>
219
- foldrun storage text <path> a file in a workspace's storage as text, read by the platform (PDF, scan, document, sheet, recording) — printed, and written beside it as <path>.txt unless --no-write (--lang, --ocr, --engine, --wait, --json; --to or --workspace <ws>)
220
- foldrun storage ls --all every workspace's storage, as the account's Storage page: a block per workspace, busiest first ([prefix], --json)
221
- 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)
218
+ foldrun storage <verb> what a project 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>
219
+ foldrun storage text <path> a file in a project's storage as text, read by the platform (PDF, scan, document, sheet, recording) — printed, and written beside it as <path>.txt unless --no-write (--lang, --ocr, --engine, --wait, --json; --to or --workspace <ws>)
220
+ foldrun storage ls --all every project's storage, as the account's Storage page: a block per project, busiest first ([prefix], --json)
221
+ foldrun runtimes the environments a deployed project'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)
222
222
  foldrun billing the account's balance and its recent ledger entries (--limit <n>)
223
223
  foldrun billing statement [YYYY-MM] a month of the ledger (--csv for the file, --file <path> to save it)
224
224
  foldrun billing invoices the plan's tax invoices from Stripe (number, date, amount, status, link) and every credit purchase with its receipt (--json)
@@ -238,49 +238,49 @@ const HELP = `foldrun — agents are just folders
238
238
  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
239
239
  foldrun account export everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
240
240
  foldrun account model what steps run on — your own key: set <provider> --key <api key> (--key - reads stdin, or asks for it hidden in a terminal; 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
241
- 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)
241
+ foldrun workspace one deployed project'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 project's pool) (or <job>.<field>), clear <key>, pause [--reason] [--stop] / resume (the kill switch)
242
242
  foldrun workspace clear compute <vcpu|memory|disk>… drop just those figures of its pool · clear notify <email|url>: one channel, the rest kept (--to)
243
- foldrun workspace vocabulary the names the dashboard's editor completes in a workspace: agents, flows, skills, tools, secrets, scripts, types, documents (--to, --json)
244
- foldrun notify test send one test notification from a workspace and say what happened (--to <workspace>)
245
- foldrun webhooks deliveries the notify: webhooks a workspace sent, newest first — status, attempts, last answer (--failed, --status <s>, --event <e>, --limit, --offset, --to)
243
+ foldrun workspace vocabulary the names the dashboard's editor completes in a project: agents, flows, skills, tools, secrets, scripts, types, documents (--to, --json)
244
+ foldrun notify test send one test notification from a project and say what happened (--to <workspace>)
245
+ foldrun webhooks deliveries the notify: webhooks a project sent, newest first — status, attempts, last answer (--failed, --status <s>, --event <e>, --limit, --offset, --to)
246
246
  foldrun webhooks redeliver <id> send one delivery again now, same X-Foldrun-Delivery id; exits 1 when refused (--to)
247
247
  foldrun notifications what mail you get, category by category, and which are always sent (--json)
248
248
  foldrun notifications set <category> on|off turn one off or back on — account-wide, or --to <workspace> for run-alerts and approvals
249
249
  foldrun flags the feature flags for this account: each on or off, and why — set for this account, for every account, a staged rollout, or the default (--json). Read-only: the platform's operator changes them
250
- foldrun history [path] every change to a deployed workspace, newest first (--id <revision> for its diff, --limit, --to)
250
+ foldrun history [path] every change to a deployed project, newest first (--id <revision> for its diff, --limit, --to)
251
251
  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)
252
- 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)
252
+ foldrun restore <ws> --to <revision|time|age> put a project's source back as it was then — shows the change, asks for the name typed back (--dry-run: the diff only, --yes)
253
253
  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]
254
254
  foldrun backups requests every restore asked of the platform team, and where each stands (--json)
255
255
  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
256
- 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)
256
+ foldrun secrets ls the secrets in scope: where each is set, its sites and projects — and on the platform whether the far end last accepted it, refused it (since when) or nothing has used it yet (--json)
257
257
  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)
258
258
  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
259
- 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)
259
+ foldrun secrets workspaces NAME [workspace…] limit an account secret to those projects — every other one finds it not set; --all opens it to every project again, --none to no project, no names shows which may use it (an admin over every project; applies to runs that start after it)
260
260
  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
261
261
  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>
262
262
  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
263
263
  foldrun deploy [dir] push the whole account, or deploy <workspace> for one of them
264
264
  foldrun pull [workspace] bring the platform's account down here (refuses to clobber; --force overrides)
265
- foldrun export [workspace] a deployed workspace as a .zip — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state or secret values (--flow <name> or --agent <name> for one, with what it needs; --file <path>|-, --force)
266
- foldrun import <file.zip> take a package in: shows what it adds, would replace and still needs, then asks (--to <workspace>; a new name makes a workspace; --dry-run, --overwrite, --yes, --json)
265
+ foldrun export [workspace] a deployed project as a .zip — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state or secret values (--flow <name> or --agent <name> for one, with what it needs; --file <path>|-, --force)
266
+ foldrun import <file.zip> take a package in: shows what it adds, would replace and still needs, then asks (--to <workspace>; a new name makes a project; --dry-run, --overwrite, --yes, --json)
267
267
  foldrun snapshot push [dir] send a git folder for an agent on foldrun to work on: what git would commit, checked for secrets here and on the platform, answers the snapshot id (--to <workspace>; --dry-run, --out <file.tar.gz> (--force over one that is there), --json)
268
- foldrun status [workspace] per workspace: what is added, changed or gone since the last deploy
268
+ foldrun status [workspace] per project: what is added, changed or gone since the last deploy
269
269
  foldrun status --platform is the platform up: each component, and any incident or maintenance posted (--json)
270
270
  foldrun status --platform --history uptime per component per day and the incidents in the window, as the status page's bars (--days 1-90, default 90; --json)
271
271
  foldrun workspaces what exists here and on the platform (--json for a script) — also rm <name> (--platform --yes)
272
272
  foldrun workspaces show <name> what is deployed in one: its agents, flows and how each fires, its files by folder (--json)
273
273
  foldrun workspaces new <name> --platform make it on the platform: blank (an AGENTS.md), or --starter for the example researcher, writer and flow
274
- foldrun workspaces demo make the demo pipeline workspace on the platform — "Try the demo pipeline"
274
+ foldrun workspaces demo make the demo pipeline project on the platform — "Try the demo pipeline"
275
275
  foldrun library the account's shared library on the platform: ls [skills|tools|hooks|scripts|knowledge|memory], cat <kind>/<path>, put <kind>/<path> (--file, else stdin), rm <kind>/<path> (asks)
276
276
  foldrun library new <kind>/<name> a new one from the platform's template, as the Library page's New (--template <transport or gallery entry>, --language)
277
- foldrun find <words> search the account as the dashboard's ⌘K does: workspaces, agents, flows, tools, skills, knowledge, memory, runs (--json)
277
+ foldrun find <words> search the account as the dashboard's ⌘K does: projects, agents, flows, tools, skills, knowledge, memory, runs (--json)
278
278
  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)
279
279
  foldrun source <verb> the files on a platform, one at a time: ls, cat <path>, put <path>, mv, rm (--to <workspace>)
280
280
  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)
281
281
  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
282
- 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)
283
- foldrun open [page] the dashboard for this workspace, in the browser
282
+ 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 project — asks (--yes), --dry-run, --overwrite (--to)
283
+ foldrun open [page] the dashboard for this project, in the browser
284
284
  foldrun api spec the platform's OpenAPI 3.1 document (GET /api/openapi.json) — stdout, or --out <file>
285
285
  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)
286
286
  foldrun changelog the platform's release notes, newest first: features, fixes, docs — and the API's versions, breaking changes and deprecations (--limit <n>, --json)
@@ -292,18 +292,18 @@ Signing in
292
292
  open a browser, sign in to that site by hand, and store the
293
293
  session: cookies, storage and the browser identity it needs
294
294
  foldrun logout forget this machine's key, and revoke it where allowed
295
- foldrun whoami who you are on the platform: account, role, workspaces
295
+ foldrun whoami who you are on the platform: account, role, projects
296
296
  foldrun signup status can a stranger sign up on the platform: free sign-up, paid sign-up, and the plans sold while paid is in effect — the open /api/signup, no key sent (--url, --json; exits 1 when it does not answer)
297
297
  foldrun me the person this machine is signed in as: name, address, timezone (--json)
298
298
  foldrun me name <first> [last] set your name (--clear for none) · foldrun me timezone <zone|auto> the zone you read times in
299
- foldrun team who is in the account: role, the workspaces each may open, when they joined (--json)
299
+ foldrun team who is in the account: role, the projects each may open, when they joined (--json)
300
300
  foldrun team invite [email] invite someone (--role viewer|editor|admin, default editor; --workspaces a,b or --all; --no-send): prints the link, once. Your own foldrun login, never a key made by hand; an owner's sign-in here acts as admin, so an admin invite is the browser's
301
301
  foldrun team role <email|id> <role> change a member's role (viewer, editor, admin); their keys above it stop
302
- foldrun team access <email|id> which workspaces they may open: --workspaces a,b, --all or --none; never wider than yours
302
+ foldrun team access <email|id> which projects they may open: --workspaces a,b, --all or --none; never wider than yours
303
303
  foldrun team remove <email|id> remove a member — asks first (--yes with no terminal); their keys and pending invites stop. Transfer stays in Settings → Team
304
- foldrun team invites the account's pending invites — address or "anyone with the link", role, workspaces, who made it, when it expires, its id (--all for accepted, revoked and expired too; --json). Never the link: each works once, shown only to its maker
304
+ foldrun team invites the account's pending invites — address or "anyone with the link", role, projects, who made it, when it expires, its id (--all for accepted, revoked and expired too; --json). Never the link: each works once, shown only to its maker
305
305
  foldrun team invites revoke <id> take an invite back: its link stops working at once (an admin's; a key may)
306
- foldrun onboarding the account's getting-started steps, done or not, the next one first; --to <workspace> adds that workspace's checklist (--json)
306
+ foldrun onboarding the account's getting-started steps, done or not, the next one first; --to <workspace> adds that project's checklist (--json)
307
307
  foldrun preferences your own settings on the platform — the theme; set theme system|light|dark (a key acts for whoever minted it)
308
308
  foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
309
309
  foldrun accounts every account signed in on this machine, and which one is active
@@ -313,12 +313,12 @@ Signing in
313
313
  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
314
314
  foldrun keys set <id> --sonnet openai/gpt-6 which model a gateway key runs each Claude Code tier on (--opus, --haiku; - clears one, --clear all)
315
315
  foldrun keys set <id> --customer required|optional whether every run (API key) or gateway call (gateway key) with it must name an end customer — create one that requires it with keys create … --require-customer
316
- foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every workspace; shown once
316
+ foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every project; shown once
317
317
  foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings, and its status line shows the key's spend
318
318
  foldrun gateway status-line one line for Claude Code's status line: what the gateway key in ANTHROPIC_AUTH_TOKEN has spent, of its limits (asks the gateway; kept 10 s, --cache <s>)
319
319
  foldrun text <file> a local file as text: uploads it to the platform, which reads it — a PDF or scan (OCR in Persian or English), a Word, sheet or slide file, a recording — and prints the text (--lang fa|en|auto, --ocr auto|always|never, --engine docling, --out <path> or -o <path>, --json, --wait <s>); a long job is polled until it ends
320
320
  foldrun talk speak a prompt: records the microphone until you stop talking, foldrun's own Whisper turns it into text (Persian with the Persian model), prints the words — Claude Code's /talk runs it (--lang auto|fa|en…, --max <s> up to 120, --silence <s>, --file <audio or video> instead of the mic, --mic <name>, --plain, --json; the gateway key from ANTHROPIC_AUTH_TOKEN or --url/--key)
321
- 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)
321
+ foldrun a2a ls --to <ws> what a project serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
322
322
  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
323
323
  foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
324
324
  foldrun a2a publish <flow> --accept-risk <agent,…> accept that these agents hold a secret while they can run code (a2a: accept_risk, every one named; their answer goes to the caller) — without it such a flow is not published; --clear-accept-risk takes it out
@@ -332,10 +332,10 @@ Signing in
332
332
  foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
333
333
 
334
334
  Options
335
- --workspace <dir> the workspace folder (default: .) — on init, the first workspace's name
335
+ --workspace <dir> the project folder (default: .) — on init, the first project's name
336
336
  --flat init: the old single-folder shape, no account around it
337
337
  --from <template> init: start from a shipped template, e.g. templates/hello (new takes it too)
338
- --starter new, workspaces new: include the example researcher, writer and publish flow (a new workspace is blank)
338
+ --starter new, workspaces new: include the example researcher, writer and publish flow (a new project is blank)
339
339
  --transport <k> tool new: script (default), http or mcp
340
340
  --language <l> tool new, source new, library new: the script's language — javascript, python, bash
341
341
  --task "<text>" the instruction for a manual run
@@ -354,10 +354,10 @@ Options
354
354
  --since <span> audit: entries from 24h, 7d, 30d ago, or a date (default 7d); --until <date> ends the window
355
355
  --action <a> audit: one action (apikey.created) or a family (apikey, secret, member, support)
356
356
  --actor <who> audit: one person or key — an email, key:<label>, support:<email>
357
- --since <days> observe, triggers: the window in days (observe default 7 as the account Observe page, observe --to 30 as a workspace's; triggers 7); observe takes --days too
357
+ --since <days> observe, triggers: the window in days (observe default 7 as the account Observe page, observe --to 30 as a project's; triggers 7); observe takes --days too
358
358
  --until <span|date> stop, rerun (bulk): only runs started before then — 2h ago, or a date; usage meters: the period's last UTC day (YYYY-MM-DD)
359
359
  --verdict <v> runs: only completed runs whose summary leads with it — good, bad, quiet, blocked (comma-separated)
360
- --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
360
+ --q <words> runs: the runs page's text search — every word, any order, across id, flow, project, status, verdict, summary and failure; assistant history: search the conversations
361
361
  --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
362
362
  --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
363
363
  --instruction "<text>" flow add: what a new step (chain, parallel, router) is told to do
@@ -372,7 +372,7 @@ Options
372
372
  --on-fail <agent> flow add: who takes the step over when it fails
373
373
  --off flow add: take the pattern off the step instead (fan-out, loop, approval, ask, wait, rescue)
374
374
  --schedule "<cron>" flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
375
- --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
375
+ --team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you); --workspace <ws> only that project's items; inbox read --all marks every unread one read
376
376
  --dismissed, --unread inbox: what you set aside; only what you have not read
377
377
  --read-only mcp: offer the AI app only the tools that read — no run, approve, answer, message or stop
378
378
  --models <m[:effort],…> eval compare: two to four tiers or model ids to compare, each with an optional :effort
@@ -430,10 +430,10 @@ Options
430
430
  --note "<text>" approve, reject: guidance the agent reads — or the reason for a refusal; billing credit: the ledger line's note
431
431
  --run <id> eval --to: that eval run's verdict, by the id the run printed; runs nothing
432
432
  --stale [days] agent ls: only agents not run in that many days (never run included); bare, those past alerts: stale_days
433
- --reason "<text>" account pause, workspace pause: why — shown to everyone who opens it
434
- --stop account pause, workspace pause: also stop every run going now (asks; --yes to mean it)
433
+ --reason "<text>" account pause, project pause: why — shown to everyone who opens it
434
+ --stop account pause, project pause: also stop every run going now (asks; --yes to mean it)
435
435
  --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)
436
- --json report: the raw run record instead of the report; runs: { runs, next }; runs outputs: { runId, files, totalBytes }; 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}
436
+ --json report: the raw run record instead of the report; runs: { runs, next }; runs outputs: { runId, files, totalBytes }; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, projects, 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}
437
437
  --events <a,b> account set notify: failed, awaiting-approval, completed
438
438
  --failed webhooks deliveries: only the ones that gave up
439
439
  --limit <n> runs, billing, history, changelog: how many rows; triggers: how many decisions and deliveries (default 10)
@@ -443,11 +443,11 @@ Options
443
443
  --value "<text>" secrets set: skip the prompt (careful with shell history)
444
444
  --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)
445
445
  --clear secrets sites: unbind it; flow compute: no cap of its own; me name: no name
446
- --all runs: every run that matches, every page; 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
447
- --none secrets workspaces, secrets set: no workspace may use the account secret; team access: no workspaces
446
+ --all runs: every run that matches, every page; secrets workspaces: every project may use the account secret again; storage ls: every project's storage; storage shares: expired and revoked links too; mcp connections: the disconnected ones too; team invite, team access: every project
447
+ --none secrets workspaces, secrets set: no project may use the account secret; team access: no projects
448
448
  --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)
449
449
  --if-version <n> account model use: change it only while the choice is still that choiceVersion (account model --json; 0: never chosen)
450
- --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
450
+ --workspaces <a,b> secrets set: store an account secret limited to those projects, in the same write (with --account); team invite, team access: the projects they may open
451
451
  --add <site> agent network: add a site to its network: list (repeatable)
452
452
  --remove <site> agent network: take a site off its network: list (repeatable)
453
453
  --out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report; text: where to write the text (-o <file> too; refused when it exists, --force overwrites)
@@ -455,12 +455,12 @@ Options
455
455
  --message "<why>" source put: recorded on the file's revision
456
456
  --check source put: refuse the save when the file would not check out (422: the issues printed, nothing written)
457
457
  --empty source put: write an empty file on purpose (empty input is refused otherwise)
458
- --account secrets: account scope instead of the workspace's
458
+ --account secrets: account scope instead of the project's
459
459
  --wait invoke, agent run: hold on and print the result
460
460
  --path <p> tool test: the path an http tool should probe, appended to its base:
461
461
  --on <event> hook add: what it listens for — tool.call, tool.result, step.start or step.end
462
462
  --tool <pattern> hook add: which tools a tool.call or tool.result hook sees — Bash, Write|Edit, mcp__* (default all)
463
- --library hook add, hook rm: in the account library (every workspace), not this workspace
463
+ --library hook add, hook rm: in the account library (every project), not this project
464
464
  --event <json|@file> hook test: the event the hook reads on stdin (default: a sample for its on:)
465
465
  --watch invoke: follow the run's trace here as it happens
466
466
  --print open: print the URL only
@@ -488,7 +488,7 @@ Options
488
488
  --card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
489
489
 
490
490
  Platform options (deploy, invoke, secrets, logs, keys)
491
- --to <workspace> workspace on the platform (deploy default: folder name); flow add/show, agent link: edit or show the deployed copy instead of this folder; hook test: run the deployed hook on the platform; hook ls: list the deployed workspace's hooks and what they did lately; restore <ws>: the commit, date or age to put it back to (3d, 2026-09-28T14:00)
491
+ --to <workspace> project on the platform (deploy default: folder name); flow add/show, agent link: edit or show the deployed copy instead of this folder; hook test: run the deployed hook on the platform; hook ls: list the deployed project's hooks and what they did lately; restore <ws>: the commit, date or age to put it back to (3d, 2026-09-28T14:00)
492
492
  --tenant <name> account to deploy into (default: default, local only)
493
493
  --data <dir> the installation's data directory
494
494
  --url <url> a running platform (or FOLDRUN_URL, or where you last signed in)
@@ -499,11 +499,11 @@ Platform options (deploy, invoke, secrets, logs, keys)
499
499
  --quiet leave out the dim "acting as …" line a platform command prints on stderr
500
500
  --local deploy: into the installation on this machine, even when signed in
501
501
  --commit <sha> deploy: record which commit this is
502
- --overwrite import: replace files the workspace already has with different text (refused otherwise)
502
+ --overwrite import: replace files the project already has with different text (refused otherwise)
503
503
  --overwrite source share: replace a library file of the same path (refused otherwise)
504
504
  --dry-run source share: list what would move, move nothing
505
505
  --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
506
- --no-runtimes deploy: do not wait for the workspace's environments to be built
506
+ --no-runtimes deploy: do not wait for the project's environments to be built
507
507
  --force deploy: deploy even while runs are in flight; pull, storage get, text: overwrite local files
508
508
  --yes deploy: allow deleting files this folder no longer has (asked otherwise; required with no terminal)
509
509
  --platform --yes workspaces rm: delete it on the platform, deliberately
package/docs/a2a.md CHANGED
@@ -49,7 +49,7 @@ a2a:
49
49
  | `accept_risk` | a list of this flow's agents that an admin accepts **holding a secret while they can run code** ([below](#secret-and-code-accept_risk)). Up to 50 names |
50
50
 
51
51
  A block `foldrun check` cannot read publishes nothing — a typo never opens a
52
- flow nobody meant to open. Whether a flow is published is the workspace's
52
+ flow nobody meant to open. Whether a flow is published is the project's
53
53
  policy, so changing `a2a:` needs the **admin** role (`workspace:manage`) by
54
54
  every door: the editor, a deploy, `PATCH /flows/<f>`, `PUT /source`. An
55
55
  editor's change that leaves `a2a:` as it was goes through.
@@ -67,9 +67,9 @@ foldrun a2a ls --to sales # what the workspace serves, and it
67
67
  foldrun a2a unpublish lead-finder --to sales
68
68
  ```
69
69
 
70
- The workspace's **Triggers** page, section **Outside agents (A2A)** (and
70
+ The project's **Triggers** page, section **Outside agents (A2A)** (and
71
71
  `GET /api/workspaces/<ws>/a2a`), lists every
72
- flow that says `a2a:`, its card and endpoint URLs, the workspace's A2A keys and
72
+ flow that says `a2a:`, its card and endpoint URLs, the project's A2A keys and
73
73
  the newest tasks with the key that asked.
74
74
 
75
75
  `foldrun check` warns on a published flow that is risky to open
@@ -134,9 +134,9 @@ or delete, a deploy, an import, a restore, a proposed fix:
134
134
  - a new tool (a `{Bash: ask}` turned into a plain grant counts), secret, API,
135
135
  MCP server, outside agent (`remotes:`), script or sub-agent; a changed API,
136
136
  MCP or remote spec;
137
- - a wider network — the agent's, or the workspace's `network:` in AGENTS.md
137
+ - a wider network — the agent's, or the project's `network:` in AGENTS.md
138
138
  (a higher level, or a new site);
139
- - a hook gone (the agent's own, or the workspace's `hooks:`),
139
+ - a hook gone (the agent's own, or the project's `hooks:`),
140
140
  `permissionMode: plan` dropped, `sandbox: own` added;
141
141
  - a new agent behind the flow — a step, rescuer, delegate, sub-agent or
142
142
  subflow that was not there.
@@ -158,13 +158,13 @@ secret-and-code agent it creates.
158
158
  ## A2A keys
159
159
 
160
160
  A caller needs an **A2A key**: a key of its own kind, minted by an admin of
161
- the workspace, for one workspace and the flows it names.
161
+ the project, for one project and the flows it names.
162
162
 
163
163
  ```sh
164
164
  foldrun keys create "Partner CRM" --a2a --to sales --flows lead-finder,quote --max-tasks 5
165
165
  ```
166
166
 
167
- or **Settings → API keys**, kind **A2A key**: the workspace, the published
167
+ or **Settings → API keys**, kind **A2A key**: the project, the published
168
168
  flows it may call, and how many tasks it may have open at once. The key is
169
169
  shown once.
170
170
 
@@ -326,7 +326,7 @@ request foldrun cannot take **now** is `-32000` with a foldrun reason:
326
326
  | reason | |
327
327
  |---|---|
328
328
  | `BUSY` | the flow is `overlap: skip` and a run is live — send the same message later |
329
- | `PAUSED` | the workspace or account is paused |
329
+ | `PAUSED` | the project or account is paused |
330
330
  | `UNAVAILABLE` | out of budget or funds, or otherwise not taking work |
331
331
  | `RATE_LIMITED` | the key's rate limit (`429` from the proxy carries `Retry-After`) |
332
332
  | `TOO_MANY_TASKS` | the key has `maxTasks` open |
@@ -335,7 +335,7 @@ request foldrun cannot take **now** is `-32000` with a foldrun reason:
335
335
  | `PERMISSION_DENIED` | a key that is not an A2A key (HTTP `403`) |
336
336
  | `AGENT_NOT_FOUND` | the flow is not published, not named by the key, or not there — all alike (HTTP `404`) |
337
337
 
338
- A task of another key, flow or workspace is `TaskNotFoundError` (`-32001`),
338
+ A task of another key, flow or project is `TaskNotFoundError` (`-32001`),
339
339
  never "not yours".
340
340
 
341
341
  A run started over A2A goes through the same admission as one started from
@@ -412,14 +412,14 @@ Ended tasks are kept 90 days.
412
412
  [`security/published-flow-secret-code`](checks#security-published-flow-secret-code)
413
413
  — one that holds a secret and can run code (info once accepted); and
414
414
  [`security/published-flow-ungated`](checks#security-published-flow-ungated)
415
- — a step that acts outside the workspace with no approval or `ask:` before
415
+ — a step that acts outside the project with no approval or `ask:` before
416
416
  it, which any key holder starts. Put a gate (`2!.`) on it, or take a leg
417
417
  away.
418
418
  - **Left as they are** (FOL-112 N7, N8): one key can hold up to its
419
419
  `maxTasks` runs waiting in the approvals queue — `maxTasks` bounds it; give
420
- a partner's key a small one. A card URL carries the account and workspace
420
+ a partner's key a small one. A card URL carries the account and project
421
421
  names (`/a2a/<account>/<ws>/…`) — treat them as disclosed to every key
422
- holder, and to everyone when `public_card: true`; name a workspace you
422
+ holder, and to everyone when `public_card: true`; name a project you
423
423
  publish from accordingly.
424
424
  - **A public card is metadata only**: the name, description and examples you
425
425
  wrote, the endpoint and the auth scheme — never steps, agents or files.