foldrun 14.2.2 → 14.3.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 +19 -11
- package/docs/api.md +18 -7
- package/docs/cli.md +13 -5
- package/docs/team-and-access.md +12 -1
- package/package.json +2 -2
- package/src/commands.mjs +203 -19
package/bin/foldrun.mjs
CHANGED
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
// foldrun notifications what mail you get, per category — set <category> on|off
|
|
27
27
|
// foldrun flags the feature flags for this account — on or off, and why (read-only)
|
|
28
28
|
// foldrun backups how the account is backed up, its snapshots — request a restore from one, requests lists them
|
|
29
|
-
// foldrun team who is in the account, their roles and workspaces
|
|
29
|
+
// foldrun team who is in the account, their roles and workspaces; invite, role, access, remove
|
|
30
30
|
// foldrun team invites the invites still out; `revoke <id>` takes one back
|
|
31
31
|
// foldrun restore <ws> a workspace's source back to a point in its history (shows the change, asks)
|
|
32
32
|
// foldrun onboarding the account's getting-started steps, the next one first
|
|
@@ -56,6 +56,7 @@
|
|
|
56
56
|
// foldrun login <site> a browser window to sign in to a site by hand; the session
|
|
57
57
|
// (cookies, storage, identity) is stored for an agent to wear
|
|
58
58
|
// foldrun whoami who the platform thinks this terminal is
|
|
59
|
+
// foldrun me the person this machine is signed in as; their name and timezone
|
|
59
60
|
// foldrun doctor what is between this terminal and the platform, checked
|
|
60
61
|
// foldrun accounts every account signed in here; `use <name>` switches
|
|
61
62
|
// foldrun keys <verb> ls / create / revoke — the account's API keys
|
|
@@ -204,7 +205,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
204
205
|
foldrun gallery the platform's built-in tools (web) and whether you keep your own copy — also pull (a copy for offline runs), upgrade <tool>
|
|
205
206
|
foldrun identity what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
|
|
206
207
|
foldrun jobs the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
|
|
207
|
-
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} | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
|
|
208
|
+
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)
|
|
208
209
|
foldrun account export everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
|
|
209
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
|
|
210
211
|
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)
|
|
@@ -255,7 +256,13 @@ Signing in
|
|
|
255
256
|
session: cookies, storage and the browser identity it needs
|
|
256
257
|
foldrun logout forget this machine's key, and revoke it where allowed
|
|
257
258
|
foldrun whoami who you are on the platform: account, role, workspaces
|
|
258
|
-
foldrun
|
|
259
|
+
foldrun me the person this machine is signed in as: name, address, timezone (--json)
|
|
260
|
+
foldrun me name <first> [last] set your name (--clear for none) · foldrun me timezone <zone|auto> the zone you read times in
|
|
261
|
+
foldrun team who is in the account: role, the workspaces each may open, when they joined (--json)
|
|
262
|
+
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
|
|
263
|
+
foldrun team role <email|id> <role> change a member's role (viewer, editor, admin); their keys above it stop
|
|
264
|
+
foldrun team access <email|id> which workspaces they may open: --workspaces a,b, --all or --none; never wider than yours
|
|
265
|
+
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
|
|
259
266
|
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
|
|
260
267
|
foldrun team invites revoke <id> take an invite back: its link stops working at once (an admin's; a key may)
|
|
261
268
|
foldrun onboarding the account's getting-started steps, done or not, the next one first (--json)
|
|
@@ -286,7 +293,7 @@ Options
|
|
|
286
293
|
--test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
|
|
287
294
|
--follow logs: keep tailing a live run (with --url: on the platform)
|
|
288
295
|
--status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
|
|
289
|
-
--since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w
|
|
296
|
+
--since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w, or today (the last 24h)
|
|
290
297
|
--since <span> audit: entries from 24h, 7d, 30d ago, or a date (default 7d); --until <date> ends the window
|
|
291
298
|
--action <a> audit: one action (apikey.created) or a family (apikey, secret, member, support)
|
|
292
299
|
--actor <who> audit: one person or key — an email, key:<label>, support:<email>
|
|
@@ -345,17 +352,17 @@ Options
|
|
|
345
352
|
--stale [days] agent ls: only agents not run in that many days (never run included); bare, those past alerts: stale_days
|
|
346
353
|
--reason "<text>" account pause, workspace pause: why — shown to everyone who opens it
|
|
347
354
|
--stop account pause, workspace pause: also stop every run going now (asks; --yes to mean it)
|
|
348
|
-
--yes approve, stop, rerun (bulk), pause --stop, flow rotate-hook, flow draft, assistant, history restore, restore <ws>, import, billing plan, workspace set name, and every rm/revoke/unshare: skip the confirmation, deliberately (required with no terminal)
|
|
355
|
+
--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)
|
|
349
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}
|
|
350
357
|
--events <a,b> account set notify: failed, awaiting-approval, completed
|
|
351
358
|
--failed webhooks deliveries: only the ones that gave up
|
|
352
359
|
--limit <n> runs, billing, history, changelog: how many rows
|
|
353
360
|
--value "<text>" secrets set: skip the prompt (careful with shell history)
|
|
354
361
|
--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)
|
|
355
|
-
--clear secrets sites: unbind it; flow compute: no cap of its own
|
|
356
|
-
--all secrets workspaces: every workspace may use the account secret again; mcp connections: the disconnected ones too
|
|
357
|
-
--none secrets workspaces, secrets set: no workspace may use the account secret
|
|
358
|
-
--workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account)
|
|
362
|
+
--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
|
|
364
|
+
--none secrets workspaces, secrets set: no workspace may use the account secret; team access: no workspaces
|
|
365
|
+
--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
|
|
359
366
|
--add <site> agent network: add a site to its network: list (repeatable)
|
|
360
367
|
--remove <site> agent network: take a site off its network: list (repeatable)
|
|
361
368
|
--out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
|
|
@@ -380,7 +387,8 @@ Options
|
|
|
380
387
|
--port <n> connect: loopback port for the redirect (default 8642 — register http://localhost:8642/callback on the app)
|
|
381
388
|
--authorize-url / --token-url connect, secrets clients add: the provider's own OAuth addresses
|
|
382
389
|
--authorize-param name=value connect, secrets clients add: an extra authorize-URL parameter the provider documents (repeatable — e.g. access_type=offline)
|
|
383
|
-
--role <r> keys create: viewer, editor (default) or admin
|
|
390
|
+
--role <r> keys create, team invite: viewer, editor (default) or admin
|
|
391
|
+
--no-send team invite: make the link, mail nothing
|
|
384
392
|
--expires <span> keys create: when it stops working — 30d, 90d, 365d or never (default never)
|
|
385
393
|
--grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
|
|
386
394
|
--a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
|
|
@@ -426,7 +434,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
426
434
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
427
435
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
428
436
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
429
|
-
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"]);
|
|
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"]);
|
|
430
438
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
431
439
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
|
|
432
440
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
package/docs/api.md
CHANGED
|
@@ -49,6 +49,17 @@ session and answer a key with `401` (a user's avatar answers a key with
|
|
|
49
49
|
*does* — files, runs, secrets, shares, schedules, hooks, storage, billing —
|
|
50
50
|
takes the key.
|
|
51
51
|
|
|
52
|
+
One key is a person: the one their own `foldrun login` minted (`origin:
|
|
53
|
+
cli-login`). It may also invite (`POST /api/team`), change a member's role or
|
|
54
|
+
workspaces and remove them (`PATCH`/`DELETE /api/team/members/<id>`), and set
|
|
55
|
+
that person's name and timezone (`POST /api/auth/name`, `/api/auth/timezone`).
|
|
56
|
+
It acts at the lower of its role and the person's role now — an owner's is an
|
|
57
|
+
admin, so making, changing or removing an admin stays in the browser — in the
|
|
58
|
+
workspaces both allow, and the audit entry says `via: foldrun login` with the
|
|
59
|
+
key's id. A request carrying a key is decided by the key, never by a cookie
|
|
60
|
+
beside it. Transfer, password, email, two-step sign-in, sessions, avatars and
|
|
61
|
+
closing the account stay a signed-in session's.
|
|
62
|
+
|
|
52
63
|
## Quick start
|
|
53
64
|
|
|
54
65
|
```sh
|
|
@@ -218,7 +229,7 @@ paying for the steps around it.
|
|
|
218
229
|
| `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live |
|
|
219
230
|
| `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record. `404` for no such run, `409` for one already finished |
|
|
220
231
|
| `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start. `404` for no such run, `409` for one not finished, `400` for a `step` that is not a whole number |
|
|
221
|
-
| `/api/workspaces/<ws>/runs/bulk` | POST | one action on many runs at once. `action` is `stop` or `rerun`; the runs are named by any of `runIds`, `status`, `flow`, `since`, `until`, AND-ed together, and a call naming none of them is refused rather than treated as "everything". `from` picks the step a rerun starts at, `dryRun: true` answers with what would be touched and touches nothing. At most 100 runs per call — past that it answers `422` with the count, because a filter matching more than that is almost certainly the wrong filter. Each run is its own outcome: the reply carries `matched`, `succeeded`, `failed` and a `runs` array, so one run that finished a second ago does not abort the other thirty |
|
|
232
|
+
| `/api/workspaces/<ws>/runs/bulk` | POST | one action on many runs at once. `action` is `stop` or `rerun`; the runs are named by any of `runIds`, `status`, `flow`, `since`, `until`, AND-ed together (`status: ["stopped"]` names a run a person stopped, whose record says `failed`; `failed` names it too), and a call naming none of them is refused rather than treated as "everything". `from` picks the step a rerun starts at, `dryRun: true` answers with what would be touched and touches nothing. At most 100 runs per call — past that it answers `422` with the count, because a filter matching more than that is almost certainly the wrong filter. Each run is its own outcome: the reply carries `matched`, `succeeded`, `failed` and a `runs` array, so one run that finished a second ago does not abort the other thirty |
|
|
222
233
|
| `/api/workspaces/<ws>/runs/<id>/approve` | POST | release a run parked on a human: `decision` (`approve` or `reject` — anything else is a 400 that decides nothing; left out only beside `payload`), `note`, `reason`, `step` (one of several waiting, its index from 0). `payload` (a string, or JSON sent as its text, up to 20000 characters) releases a step parked on `wait: event` with that payload, as its event URL would, recorded as released by the caller — 400 with `reject` or when no such step is waiting. `run:start`. Idempotent |
|
|
223
234
|
| `/api/workspaces/<ws>/runs/<id>/answer` | POST | answer a question an agent asked mid-step (`tools: [ask]`): `{question: <id>, answer}`. The agent is waiting in a live sandbox and gets it within a second or two. First answer wins — a second is `409` with the answer that stands; also `409` when the agent stopped waiting (its ask timed out) or its step is no longer running. `404` when the question is not this run's or has expired |
|
|
224
235
|
| `/api/workspaces/<ws>/runs/<id>/message` | POST | say something to a running agent: `{text, step?}` (at most 4 000 characters). It reaches the model after its next tool call, as context — it never changes the step's tools. `step` is the step's index in the run; left out, the only running step. With several running (a parallel group) and no `step`, `400` listing them in `running`, so a sibling never takes a message meant for another. `409` unless the run, and that step, are running. Replies `{ok, step, message}` |
|
|
@@ -353,11 +364,11 @@ Reads return which secrets exist, never their values.
|
|
|
353
364
|
| Route | Methods | |
|
|
354
365
|
|---|---|---|
|
|
355
366
|
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must also say `a2a: { publish: true }`) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
|
|
356
|
-
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation) |
|
|
357
|
-
| `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
367
|
+
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
|
|
368
|
+
| `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
358
369
|
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
|
|
359
370
|
| `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
|
|
360
|
-
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
|
|
371
|
+
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. A session, or the person's own `foldrun login` key (acting as at most admin). Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
|
|
361
372
|
| `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
|
|
362
373
|
| `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
|
|
363
374
|
| `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
|
|
@@ -461,7 +472,7 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
461
472
|
| `/api/auth/sessions` | GET, DELETE | list; revoke one (`id`) or the rest (`others`) |
|
|
462
473
|
| `/api/auth/password` | POST | `current`, `next` — at least 10 characters, not your email, not in a known breach |
|
|
463
474
|
| `/api/auth/email` | POST | `email`, `password` — ask to move your login to a new address. Nothing moves yet: that address is mailed a link, and clicking it makes the move, verifies the address, ends your other sessions and tells the old address. The answer (`pending: true`) is the same whether or not the address already has a login — if it does, the mail there says so instead. 5 a day. An install that can send no mail (no platform mail key and no account `RESEND_API_KEY`/`EMAIL_FROM`) refuses with 409 `{ error, code: "mail_not_configured" }` saying how to set mail up — the login stays where it is |
|
|
464
|
-
| `/api/auth/name` | POST | `firstName`, `lastName` — optional halves, null clears one; shown by email when empty |
|
|
475
|
+
| `/api/auth/name` | POST | `firstName`, `lastName` — optional halves, null clears one; shown by email when empty. A session, or the person's own `foldrun login` key |
|
|
465
476
|
| `/api/auth/forgot` | POST | `email`. Always 200 with the same sentence, whatever the address; a reset link goes to the inbox if there is an account. 3 per address per hour (a 429, the same for any address), 20 per caller per hour when a trusted proxy names the caller; and on the mail itself, a ceiling for the install per hour of which one caller may spend at most 10 — past either, the answer is the same sentence and no mail goes |
|
|
466
477
|
| `/api/auth/reset` | POST | `token` (from the link), `password`. Works once and for 30 minutes; every other session of yours ends; signs you in |
|
|
467
478
|
| `/api/auth/verify?token=` | GET | the link in the confirmation email — marks the address verified and lands on the dashboard. The link an email change mails moves the login here too, once, and not after a password change |
|
|
@@ -470,7 +481,7 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
470
481
|
| `/api/auth/mfa/enable` | POST | `enrol`, `code` from the app. Stores the secret (sealed) and returns eight `backup` codes exactly once, and ends the person's other sessions as a password change does (`otherSessionsEnded`; this browser stays signed in) |
|
|
471
482
|
| `/api/auth/mfa/verify` | POST | the second step of a sign-in: `challenge` (from `/api/auth/login` when it answered `mfa: true`) and `code` — six digits or a backup code. 6 tries per five minutes; after 10 wrong six-digit codes in a row they are paused for up to a day (a backup code still works) and the person is mailed. A 429 carries `Retry-After` |
|
|
472
483
|
| `/api/auth/mfa/disable` | POST | `password` and `code` — a session alone is not enough to remove the second factor |
|
|
473
|
-
| `/api/auth/timezone` | POST | `timezone` — what a cron expression means |
|
|
484
|
+
| `/api/auth/timezone` | POST | `timezone` — what a cron expression means; null goes back to the browser's. A session, or the person's own `foldrun login` key |
|
|
474
485
|
|
|
475
486
|
Login is rate limited per IP, which only works when `FOLDRUN_TRUST_PROXY`
|
|
476
487
|
(`1`, or `cloudflare` with `FOLDRUN_EDGE_SECRET`) tells the platform a real
|
|
@@ -487,7 +498,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
487
498
|
| `/api/cli/login` | POST | `hostname` → `{ id, code, verifyUrl, expiresAt, interval }`. Open: there is no credential yet. Ten-minute lifetime |
|
|
488
499
|
| `/api/cli/login/<id>` | GET | `{ status }` — `pending`, `denied`, `expired`, or `approved` with `token`, `account`, `email`, `role`. The key is returned once; the request is gone after |
|
|
489
500
|
| `/api/cli/authorize` | GET, POST | `?code=` describes the request: machine, expiry, `createdAt`, `requestedFrom` (the asking network as an IPv4 /24 or IPv6 /48, from the trusted proxy — null when not known), `requestedCountry` (behind Cloudflare; else null), `sameNetwork` (whether the browser looking is on that network; null when either is not known) and `approveBy`. POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. A request more than five minutes old can no longer be approved (`410`; it can still be denied) — device-code phishing, RFC 8628 §5.4. Every role may sign its own CLI in; an owner's key is an admin's |
|
|
490
|
-
| `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null) |
|
|
501
|
+
| `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null); `person` — `{ email, firstName, lastName, timezone }` for a signed-in session or a `foldrun login` key, null for any other key |
|
|
491
502
|
| `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
|
|
492
503
|
| `/api/me/inbox` | GET, POST | your inbox — what waits on you across the workspaces you may see. GET `{ person, items: [{ id, kind (approval, question, issue, proposal, run), bucket (mine, started, team), why, workspace, title, detail, at, href, read, dismissed }], counts: { mine, started, team, unread } }`, newest first. `mine` is assigned to you (named in `approvers:`, owner of the flow or agent, or you asked for the proposal); `started` is runs you started — failed or BLOCKED/BAD this week, a gate on one (someone else decides it), a question it asked; `team` is the rest that waits in your workspaces. By default `mine` and `started`; `?bucket=mine\|started\|team\|all`, `?kind=`, `?workspace=`, `?dismissed=1` for what you set aside. `counts.unread` is unread `mine` + `started`. POST `{ ids \| id, action: read\|unread\|dismiss\|restore }` changes your view only — dismissing never decides a gate or resolves an issue; ids name an occurrence, so a thing that happens again is new. A key acts for the person who minted it, inside the key's own scope; one no person minted is a `400` |
|
|
493
504
|
| `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per workspace), `low-balance`, `product-updates`. PATCH `{ category, enabled, workspace? }` or `{ preferences: [ … ] }`; answers the same as GET. Turning a required category off is a `409` with the reason; `workspace` on an account-wide category is a `400`; `enabled: true` account-wide clears that category's per-workspace offs. A key acts for the person who minted it |
|
package/docs/cli.md
CHANGED
|
@@ -110,7 +110,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
110
110
|
| `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
|
|
111
111
|
| `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `rm` of an oauth2 secret also revokes its grant at the provider when it has a revocation URL, and says if that failed. `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
|
|
112
112
|
| `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
|
|
113
|
-
| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted, `--token-auth basic` for a provider that takes the secret only as HTTP Basic), `token-exchange` (RFC 8693: `--token-url`, `--client-id`, `--subject-secret <NAME>` whose token is traded, and `--audience`, `--scopes`, `--requested-token-type` to narrow it). On the platform, or this machine's vault with `--local` |
|
|
113
|
+
| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `--site <host>` as it is stored, or later with `secrets sites`). `--site` binds any kind as it is stored, `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted, `--token-auth basic` for a provider that takes the secret only as HTTP Basic), `token-exchange` (RFC 8693: `--token-url`, `--client-id`, `--subject-secret <NAME>` whose token is traded, and `--audience`, `--scopes`, `--requested-token-type` to narrow it). On the platform, or this machine's vault with `--local` |
|
|
114
114
|
| `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --authorize-url … --token-url … --client-id … --scopes …` saves one (secret prompted), with `--authorize-param name=value` for anything else the provider's authorize URL takes and `--token-auth basic` for a provider that takes the secret only as HTTP Basic, `clients rm <name>` removes it |
|
|
115
115
|
| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--authorize-url` and `--token-url` from the provider's OAuth docs, `--authorize-param name=value` for its extras; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; `--token-auth basic` sends the secret as HTTP Basic, for providers that refuse it in the form body; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
|
|
116
116
|
| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
|
|
@@ -135,7 +135,14 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
135
135
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
136
136
|
| `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
|
|
137
137
|
| `foldrun whoami` | who you are on the platform: account, role, which workspaces |
|
|
138
|
-
| `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json
|
|
138
|
+
| `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json` |
|
|
139
|
+
| `foldrun team invite [email]` | invite someone (`POST /api/team`): `--role viewer\|editor\|admin` (default editor), `--workspaces a,b` or `--all` (omitted: every workspace, unless you are scoped — then name them), `--no-send` to mail nothing. Without an address the link works for whoever has it. Prints the link once: it works one time, for seven days, and is shown only to you. `--json`. Like every `team` write, it is a person's: it works from your own `foldrun login` on this machine, never from a key made by hand, and it acts at the lower of that sign-in's role and yours now — an owner's sign-in here is an admin, so inviting, changing or removing an admin stays in Settings → Team |
|
|
140
|
+
| `foldrun team role <email\|id> <role>` | change a member's role to viewer, editor or admin (`PATCH /api/team/members/<id>`); the member by address (any case) or id. Their keys above the new role stop. Nobody changes their own role, and owner is transferred, not set |
|
|
141
|
+
| `foldrun team access <email\|id>` | which workspaces a member may open (`PATCH /api/team/members/<id>`): `--workspaces a,b`, `--all` or `--none`; never wider than yours. Their keys that reach beyond it stop |
|
|
142
|
+
| `foldrun team remove <email\|id>` | remove a member (`DELETE /api/team/members/<id>`). Asks first; with no terminal it needs `--yes`. Their keys and the invites they made stop with them. Transferring the account stays in Settings → Team (signed in, with your password) |
|
|
143
|
+
| `foldrun me` | the person this machine is signed in as (`GET /api/me`'s `person`): name, address, account, role, timezone. `--json`. A key made by hand is nobody: it says so and exits 1 |
|
|
144
|
+
| `foldrun me name <first> [last]` | set your name (`POST /api/auth/name`); `--clear` for none, so you are shown by your address |
|
|
145
|
+
| `foldrun me timezone <zone\|auto>` | the zone you read times in (`POST /api/auth/timezone`), e.g. `Australia/Sydney`; `auto` goes back to the browser's. Password, email, two-step sign-in and sessions stay in Settings → Profile |
|
|
139
146
|
| `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role, workspaces, who made it, when it expires, and its id. `--all` adds accepted, revoked and expired ones; `--json`. Never the link: an invite works once and its link is shown only to the person who made it. An admin's (`team:manage`), a key included; a scoped key sees the invites inside its scope |
|
|
140
147
|
| `foldrun team invites revoke <id>` | take an invite back (`DELETE /api/team/invites/<id>`): its link stops working at once. One already revoked or expired says so and changes nothing; one already accepted is refused (remove the member in Settings → Team instead). An admin invite is the owner's to revoke |
|
|
141
148
|
| `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), workspace, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). The dashboard card is hidden per person from the dashboard |
|
|
@@ -160,7 +167,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
160
167
|
| `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
|
|
161
168
|
| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
|
|
162
169
|
| `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
|
|
163
|
-
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` runs every step on foldrun's models — the platform's keys, billed in credits at foldrun's price list, hosted only; a provider the platform cannot serve now is refused — and `model use own` goes back to the account's own key, which is kept. `model prices` (`--provider <p>`, `--json`) lists foldrun's price list as the account pays it, USD per million tokens. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
|
|
170
|
+
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name; the headers already set are kept, as the dashboard's card keeps them, and `--header name=` drops one), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` runs every step on foldrun's models — the platform's keys, billed in credits at foldrun's price list, hosted only; a provider the platform cannot serve now is refused — and `model use own` goes back to the account's own key, which is kept. `model prices` (`--provider <p>`, `--json`) lists foldrun's price list as the account pays it, USD per million tokens. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
|
|
164
171
|
| `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set compute vcpu 2 memory 4 disk 20` (this workspace's own pool, inside the account's; any of them), `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
|
|
165
172
|
| `foldrun workspace vocabulary` | what the dashboard's editor completes as you type in a workspace (`--to`): agents, flows, skills, tools, secrets (names only), scripts, document types and linkable documents (`GET …/vocabulary`; `--json`) |
|
|
166
173
|
| `foldrun notify test` | send one test notification to whatever the workspace's `notify:` resolves to, and print what happened — the provider's own words when it failed ("domain not verified"). Exits 1 when it did not go. `--to <workspace>` |
|
|
@@ -201,7 +208,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
201
208
|
| `--test` | `run`, `invoke`, `agent run`: a test run — every step runs, nothing outward happens, `state/` and `storage/` are left alone, and the run page lists what would have happened. See [Test runs](runs#test-runs) |
|
|
202
209
|
| `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
|
|
203
210
|
| `--status <s>` | `runs`, and a bulk `stop` or `rerun`: only these statuses, comma-separated — `failed`, `completed`, `awaiting-approval`, `running`, `queued` |
|
|
204
|
-
| `--since <span>` | `runs`, and a bulk `stop` or `rerun`: only runs started within `24h`, `7d`, `90m`, `2w
|
|
211
|
+
| `--since <span>` | `runs`, and a bulk `stop` or `rerun`: only runs started within `24h`, `7d`, `90m`, `2w`, or `today` (the dashboard's "Today": the last 24 hours). `--status stopped` names a run a person stopped (its record says failed; `--status failed` names it too). `observe` and `triggers` take a number of days instead (sent as `?days=`). `--until <span\|date>` on a bulk `stop` or `rerun`: only runs started before then |
|
|
205
212
|
| `--since <span>` (audit) | `audit`: entries from `24h`, `7d` (default), `30d` ago or a date; `--until <date>` ends the window |
|
|
206
213
|
| `--action <a>` | `audit`: one action (`apikey.created`) or a family (`apikey`, `secret`, `member`, `support`) |
|
|
207
214
|
| `--actor <who>` | `audit`: one person or key — an email, `key:<label>`, `support:<email>` |
|
|
@@ -259,7 +266,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
259
266
|
| `--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; use it through a site binding |
|
|
260
267
|
| `--device`, `--device-url <url>` | `connect`: connect with a code you type on any device (RFC 8628) instead of a redirect — no browser and no loopback port here. With `--client <saved app>` the platform runs it; otherwise the device endpoint comes from `--issuer` or `--device-url` |
|
|
261
268
|
| `--generate-key` | with `--token-auth jwt`: foldrun makes the key (EC P-256) and prints the public JWK to register with the provider; `connect` waits for Enter before it opens the consent |
|
|
262
|
-
| `--role <r>` | `keys create`: `viewer`, `editor` (default) or `admin` |
|
|
269
|
+
| `--role <r>` | `keys create`, `team invite`: `viewer`, `editor` (default) or `admin` |
|
|
270
|
+
| `--no-send` | `team invite`: make the link and mail nothing |
|
|
263
271
|
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
|
|
264
272
|
| `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
|
|
265
273
|
| `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
|
package/docs/team-and-access.md
CHANGED
|
@@ -96,8 +96,19 @@ A key is minted with a role (`editor` unless you say otherwise) and acts as
|
|
|
96
96
|
the account with that role. It can never be wider than the person who made
|
|
97
97
|
it: not a higher role, and not a workspace they cannot open — a key minted
|
|
98
98
|
by someone scoped to two workspaces is scoped to those two. Two things a key cannot do: act against a named
|
|
99
|
-
member — inviting, re-roling, removing, transferring need a
|
|
99
|
+
member — inviting, re-roling, removing, transferring need a person,
|
|
100
100
|
because a key names an account and never a who — and exceed its role.
|
|
101
|
+
|
|
102
|
+
One key is a person: the one your own `foldrun login` minted on your
|
|
103
|
+
machine. From it you can manage the team — `foldrun team invite`, `team
|
|
104
|
+
role`, `team access`, `team remove` — and set your own name and timezone
|
|
105
|
+
(`foldrun me name`, `foldrun me timezone`). It acts at the lower of its role
|
|
106
|
+
and yours now, in the workspaces both allow; a key is never an owner, so an
|
|
107
|
+
owner's sign-in here is an admin, and inviting, changing or removing an admin
|
|
108
|
+
stays in Settings → Team. The audit log marks each such act `via: foldrun
|
|
109
|
+
login`. Transferring the account, your password, email, two-step sign-in and
|
|
110
|
+
sessions stay in the browser. Any other key — one made in Settings → API
|
|
111
|
+
keys, a CI key — is refused all of these.
|
|
101
112
|
A scoped admin sees and revokes only keys inside its own scope; a key wider
|
|
102
113
|
than that, the owner's included, is not in its list.
|
|
103
114
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "14.
|
|
3
|
+
"version": "14.3.0",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
24
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
25
|
-
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts",
|
|
25
|
+
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-switches.test.ts",
|
|
26
26
|
"release": "node scripts/release.mjs",
|
|
27
27
|
"typecheck": "tsc -p tsconfig.json",
|
|
28
28
|
"docs:sync": "node scripts/sync-docs.mjs",
|
package/src/commands.mjs
CHANGED
|
@@ -3462,12 +3462,17 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3462
3462
|
// login, API headers, a service account's key, a client-credentials app.
|
|
3463
3463
|
if (typeof flags.kind === "string") {
|
|
3464
3464
|
const { body, local } = await secretOfKind(flags.kind, flags);
|
|
3465
|
-
|
|
3465
|
+
// --site binds it as it is stored, as the plain value does (and as the
|
|
3466
|
+
// Connections form does for a client certificate). It used to be
|
|
3467
|
+
// dropped here without a word.
|
|
3468
|
+
const sites = siteFlags(flags);
|
|
3469
|
+
if (url) await remoteCall(url, flags, "/api/secrets", { method: "PUT", body: JSON.stringify({ name, ...body, workspace: scope, ...(sites.length ? { sites } : {}), ...withLimit }) });
|
|
3466
3470
|
else {
|
|
3467
3471
|
const { k, limit } = await localLimit();
|
|
3468
3472
|
local(k, name, body, scope, limit);
|
|
3473
|
+
if (sites.length) await localSetSites(name, sites, scope);
|
|
3469
3474
|
}
|
|
3470
|
-
console.log(`\n ${c.green("✓")} ${name} stored as ${flags.kind}${url ? "" : " on this machine"} — declare it in agent.md under \`secrets:\` to use it\n`);
|
|
3475
|
+
console.log(`\n ${c.green("✓")} ${name} stored as ${flags.kind}${url ? "" : " on this machine"}${sites.length ? ` and sent only to ${sites.join(", ")}` : ""} — declare it in agent.md under \`secrets:\` to use it\n`);
|
|
3471
3476
|
return 0;
|
|
3472
3477
|
}
|
|
3473
3478
|
// --oauth2: store a refresh recipe instead of a static value. The
|
|
@@ -6216,14 +6221,29 @@ async function telemetryCmd(url, args, flags) {
|
|
|
6216
6221
|
}
|
|
6217
6222
|
if (sub !== "set") throw new Error(`unknown telemetry verb "${sub}" — set <url> [--header name=\${SECRET}], clear, test (bare: show it)`);
|
|
6218
6223
|
if (!endpoint) throw new Error("`foldrun account telemetry set https://<collector>/v1/traces --header authorization=${OTEL_TOKEN}`");
|
|
6219
|
-
|
|
6224
|
+
// The platform replaces the whole telemetry block, so the headers already
|
|
6225
|
+
// there are sent back with it, as the dashboard's card does: `--header
|
|
6226
|
+
// name=value` adds or changes one, `--header name=` drops one, and the rest
|
|
6227
|
+
// are kept. Sending only the new ones used to drop every other header.
|
|
6228
|
+
const given = {};
|
|
6220
6229
|
for (const h of [flags.header].flat().filter((x) => typeof x === "string")) {
|
|
6221
6230
|
const i = h.indexOf("=");
|
|
6222
|
-
if (i < 1) throw new Error(`--header is name=value, e.g. --header authorization='\${OTEL_TOKEN}' — not "${h}"`);
|
|
6223
|
-
|
|
6224
|
-
}
|
|
6231
|
+
if (i < 1) throw new Error(`--header is name=value (name= drops it), e.g. --header authorization='\${OTEL_TOKEN}' — not "${h}"`);
|
|
6232
|
+
given[h.slice(0, i).trim().toLowerCase()] = h.slice(i + 1).trim();
|
|
6233
|
+
}
|
|
6234
|
+
const { defaults } = await remoteCall(url, flags, "/api/account");
|
|
6235
|
+
const current = defaults?.telemetry;
|
|
6236
|
+
if (current?.hidden) throw new Error("the account's telemetry is hidden from this key (it needs access to every workspace) — set it from a key or login that has them all");
|
|
6237
|
+
const headers = { ...(current?.headers ?? {}) };
|
|
6238
|
+
for (const [k, v] of Object.entries(given)) {
|
|
6239
|
+
if (v) headers[k] = v;
|
|
6240
|
+
else delete headers[k];
|
|
6241
|
+
}
|
|
6242
|
+
const kept = Object.keys(headers).filter((k) => !(k in given));
|
|
6225
6243
|
const r = await remoteCall(url, flags, "/api/account", { method: "PATCH", body: JSON.stringify({ telemetry: { otlp: endpoint, ...(Object.keys(headers).length ? { headers } : {}) } }) });
|
|
6226
|
-
console.log(`\n ${c.green("✓")} every run that finishes is sent to ${r.defaults?.telemetry?.endpoint ?? endpoint} — \`foldrun account telemetry test\` proves it arrives
|
|
6244
|
+
console.log(`\n ${c.green("✓")} every run that finishes is sent to ${r.defaults?.telemetry?.endpoint ?? endpoint} — \`foldrun account telemetry test\` proves it arrives`);
|
|
6245
|
+
if (kept.length) console.log(` ${c.dim(`kept the header${kept.length === 1 ? "" : "s"} already set: ${kept.join(", ")} (--header name= drops one)`)}`);
|
|
6246
|
+
console.log();
|
|
6227
6247
|
return 0;
|
|
6228
6248
|
}
|
|
6229
6249
|
|
|
@@ -6569,10 +6589,12 @@ function when(iso) {
|
|
|
6569
6589
|
return `${pad(d.getDate())} ${month} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
|
6570
6590
|
}
|
|
6571
6591
|
|
|
6572
|
-
/** `--since 24h`, `7d`, `90m`, `2w` — a window, in milliseconds.
|
|
6592
|
+
/** `--since 24h`, `7d`, `90m`, `2w` — a window, in milliseconds. `today`
|
|
6593
|
+
* is the dashboard's "When: Today": the last 24 hours. */
|
|
6573
6594
|
function parseSince(spec) {
|
|
6595
|
+
if (String(spec).trim().toLowerCase() === "today") return 864e5;
|
|
6574
6596
|
const m = /^(\d+(?:\.\d+)?)\s*([smhdw])$/i.exec(String(spec).trim());
|
|
6575
|
-
if (!m) throw new Error(`--since wants a span like 24h, 7d or
|
|
6597
|
+
if (!m) throw new Error(`--since wants a span like 24h, 7d, 90m or today — not "${spec}"`);
|
|
6576
6598
|
return Number(m[1]) * { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2].toLowerCase()];
|
|
6577
6599
|
}
|
|
6578
6600
|
|
|
@@ -7479,7 +7501,7 @@ async function runsCmd(flags, layout) {
|
|
|
7479
7501
|
.slice(0, limit);
|
|
7480
7502
|
|
|
7481
7503
|
if (!rows.length) {
|
|
7482
|
-
const how = [wanted ? `status ${[...wanted].join(", ")}` : null, verdicts ? `verdict ${[...verdicts].join(", ")}` : null, outcomes ? `outcome ${[...outcomes].join(", ")}` : null, flags.since ? `the last ${flags.since}` : null]
|
|
7504
|
+
const how = [wanted ? `status ${[...wanted].join(", ")}` : null, verdicts ? `verdict ${[...verdicts].join(", ")}` : null, outcomes ? `outcome ${[...outcomes].join(", ")}` : null, flags.since ? (String(flags.since).trim().toLowerCase() === "today" ? "today" : `the last ${flags.since}`) : null]
|
|
7483
7505
|
.filter(Boolean)
|
|
7484
7506
|
.join(" in ");
|
|
7485
7507
|
console.log(`\n ${c.dim(`no runs${how ? ` matching ${how}` : ""}${flags.to ? ` in ${flags.to}` : ""}`)}\n`);
|
|
@@ -12104,7 +12126,7 @@ async function secretOfKind(kind, flags) {
|
|
|
12104
12126
|
}
|
|
12105
12127
|
case "client-cert": {
|
|
12106
12128
|
// A client certificate for mutual TLS. Bind it to the exact hosts it is
|
|
12107
|
-
// for with `foldrun secrets sites NAME host
|
|
12129
|
+
// for with --site host (or later `foldrun secrets sites NAME host`); the egress proxy presents
|
|
12108
12130
|
// it there. --export also puts it in the sandbox as files.
|
|
12109
12131
|
const cert = read(flags["cert-file"], "--cert-file <cert.pem> — the certificate, chain included");
|
|
12110
12132
|
const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
|
|
@@ -12469,17 +12491,25 @@ async function evalNewCmd(name, flags, layout) {
|
|
|
12469
12491
|
|
|
12470
12492
|
/**
|
|
12471
12493
|
* `foldrun team` — who is in the account, their role and which workspaces
|
|
12472
|
-
* they may open (GET /api/team).
|
|
12473
|
-
* access
|
|
12474
|
-
*
|
|
12475
|
-
*
|
|
12476
|
-
*
|
|
12477
|
-
*
|
|
12494
|
+
* they may open (GET /api/team). The writes are a person's: `invite`,
|
|
12495
|
+
* `role`, `access` and `remove` are taken from this machine's own `foldrun
|
|
12496
|
+
* login` key (owner decision, 4 Nov 2026), which acts at the lower of its
|
|
12497
|
+
* role and the person's — an owner's key is an admin, so making, changing or
|
|
12498
|
+
* removing an admin stays in Settings → Team. A key made by hand is refused
|
|
12499
|
+
* by the platform. Transferring the account is the browser's alone.
|
|
12500
|
+
* `foldrun team invites` lists the links still out, `revoke <id>` ends one.
|
|
12478
12501
|
*/
|
|
12479
12502
|
async function teamCmd(positional, flags) {
|
|
12480
12503
|
if (positional[0] === "invites") return teamInvitesCmd(positional.slice(1), flags);
|
|
12504
|
+
if (positional[0] === "invite") return teamInviteCmd(positional.slice(1), flags);
|
|
12505
|
+
if (positional[0] === "role") return teamRoleCmd(positional.slice(1), flags);
|
|
12506
|
+
if (positional[0] === "access") return teamAccessCmd(positional.slice(1), flags);
|
|
12507
|
+
if (positional[0] === "remove" || positional[0] === "rm") return teamRemoveCmd(positional.slice(1), flags);
|
|
12508
|
+
if (positional[0] === "transfer") {
|
|
12509
|
+
throw new Error("transferring the account is the owner's, signed in, with their password: Settings → Team in the browser");
|
|
12510
|
+
}
|
|
12481
12511
|
if (positional[0]) {
|
|
12482
|
-
throw new Error(
|
|
12512
|
+
throw new Error(`\`foldrun team\` lists the members; \`team invite\`, \`team role\`, \`team access\`, \`team remove\` and \`team invites\` change them — not "${positional[0]}"`);
|
|
12483
12513
|
}
|
|
12484
12514
|
const url = platformFor(flags, "team");
|
|
12485
12515
|
const { members = [] } = await remoteCall(url, flags, "/api/team");
|
|
@@ -12497,7 +12527,159 @@ async function teamCmd(positional, flags) {
|
|
|
12497
12527
|
const scope = m.workspaces === null || m.workspaces === undefined ? "every workspace" : m.workspaces.length ? m.workspaces.join(", ") : "no workspaces";
|
|
12498
12528
|
console.log(` ${c.bold(pad(m.email, w))} ${pad(m.owner ? "owner" : m.role, 7)} ${c.dim(scope)} ${c.dim(m.createdAt ? `joined ${String(m.createdAt).slice(0, 10)}` : "")}`);
|
|
12499
12529
|
}
|
|
12500
|
-
console.log(`\n ${c.dim(`${members.length} member${members.length === 1 ? "" : "s"} ·
|
|
12530
|
+
console.log(`\n ${c.dim(`${members.length} member${members.length === 1 ? "" : "s"} · foldrun team invite | role | access | remove (your own \`foldrun login\`, never a key made by hand)`)}\n`);
|
|
12531
|
+
return 0;
|
|
12532
|
+
}
|
|
12533
|
+
|
|
12534
|
+
/** `--workspaces a,b` → the names, `--all` → null (every one), `--none` →
|
|
12535
|
+
* [] (none); undefined when neither was given. */
|
|
12536
|
+
function memberScopeFlag(flags) {
|
|
12537
|
+
const given = [flags.workspaces !== undefined, flags.all === true, flags.none === true].filter(Boolean).length;
|
|
12538
|
+
if (given > 1) throw new Error("one of --workspaces <names>, --all or --none");
|
|
12539
|
+
if (flags.all === true) return null;
|
|
12540
|
+
if (flags.none === true) return [];
|
|
12541
|
+
if (flags.workspaces === undefined) return undefined;
|
|
12542
|
+
if (typeof flags.workspaces !== "string") throw new Error("--workspaces takes the names: --workspaces sales,ops");
|
|
12543
|
+
return flags.workspaces.split(",").map((w) => w.trim()).filter(Boolean);
|
|
12544
|
+
}
|
|
12545
|
+
|
|
12546
|
+
/** One member, by address (any case) or id, from GET /api/team. */
|
|
12547
|
+
async function memberNamed(url, flags, who, verb) {
|
|
12548
|
+
if (!who) throw new Error(`whom? \`foldrun team ${verb} <email|id>\` — \`foldrun team\` lists them`);
|
|
12549
|
+
const { members = [] } = await remoteCall(url, flags, "/api/team");
|
|
12550
|
+
const m = members.find((x) => x.id === who || String(x.email).toLowerCase() === String(who).toLowerCase());
|
|
12551
|
+
if (!m) throw new Error(`no member "${who}" — \`foldrun team\` lists them`);
|
|
12552
|
+
return m;
|
|
12553
|
+
}
|
|
12554
|
+
|
|
12555
|
+
const SCOPE_TEXT = (w) => (w === null || w === undefined ? "every workspace" : w.length ? w.join(", ") : "no workspaces");
|
|
12556
|
+
|
|
12557
|
+
/**
|
|
12558
|
+
* `foldrun team invite [email] [--role viewer|editor|admin] [--workspaces
|
|
12559
|
+
* a,b | --all] [--no-send]` — POST /api/team. With an address only that
|
|
12560
|
+
* person can accept it, and it is mailed unless --no-send; without one the
|
|
12561
|
+
* link works for whoever has it. Either way the link is printed here, once:
|
|
12562
|
+
* it is shown to its maker alone and works one time, for seven days.
|
|
12563
|
+
*/
|
|
12564
|
+
async function teamInviteCmd(positional, flags) {
|
|
12565
|
+
const url = platformFor(flags, "team invite");
|
|
12566
|
+
const email = positional[0];
|
|
12567
|
+
const role = typeof flags.role === "string" ? flags.role : "editor";
|
|
12568
|
+
if (!["viewer", "editor", "admin"].includes(role)) throw new Error("--role is viewer, editor or admin (owner is transferred, in the browser)");
|
|
12569
|
+
if (flags.none === true) throw new Error("an invite opens some workspaces: --workspaces <names>, or --all for every one");
|
|
12570
|
+
const workspaces = memberScopeFlag(flags);
|
|
12571
|
+
const body = { role, ...(workspaces !== undefined ? { workspaces } : {}), ...(email ? { email } : {}), ...(flags["no-send"] === true ? { send: false } : {}) };
|
|
12572
|
+
const r = await remoteCall(url, flags, "/api/team", { method: "POST", body: JSON.stringify(body) });
|
|
12573
|
+
if (flags.json === true) {
|
|
12574
|
+
console.log(JSON.stringify({ ...r, link: r.path ? new URL(r.path, url).toString() : null }, null, 2));
|
|
12575
|
+
return 0;
|
|
12576
|
+
}
|
|
12577
|
+
const link = new URL(r.path, url).toString();
|
|
12578
|
+
console.log(`\n ${c.green("invited")} ${c.bold(r.email ?? "anyone with the link")} as ${r.role} · ${SCOPE_TEXT(r.workspaces)} ${c.dim(`(${r.id}, until ${String(r.expires).slice(0, 10)})`)}`);
|
|
12579
|
+
if (r.sent === true) console.log(` ${c.dim("mailed to")} ${r.email}`);
|
|
12580
|
+
else if (r.sent === false) console.log(` ${c.yellow("not mailed")} ${c.dim(r.sendError ?? "")}`);
|
|
12581
|
+
console.log(`\n ${link}`);
|
|
12582
|
+
console.log(` ${c.dim("works once, for seven days, and is shown only now · foldrun team invites revoke " + r.id + " takes it back")}\n`);
|
|
12583
|
+
return 0;
|
|
12584
|
+
}
|
|
12585
|
+
|
|
12586
|
+
/** `foldrun team role <email|id> <viewer|editor|admin>` — PATCH
|
|
12587
|
+
* /api/team/members/<id> { role }. Their keys above the new role stop. */
|
|
12588
|
+
async function teamRoleCmd(positional, flags) {
|
|
12589
|
+
const url = platformFor(flags, "team role");
|
|
12590
|
+
const [who, role] = positional;
|
|
12591
|
+
if (!role) throw new Error("`foldrun team role <email|id> <viewer|editor|admin>`");
|
|
12592
|
+
if (role === "owner") throw new Error("owner is not a role you set — the owner transfers the account, in Settings → Team");
|
|
12593
|
+
if (!["viewer", "editor", "admin"].includes(role)) throw new Error(`not a role: "${role}" — viewer, editor or admin`);
|
|
12594
|
+
const m = await memberNamed(url, flags, who, "role");
|
|
12595
|
+
const r = await remoteCall(url, flags, `/api/team/members/${enc(m.id)}`, { method: "PATCH", body: JSON.stringify({ role }) });
|
|
12596
|
+
if (flags.json === true) {
|
|
12597
|
+
console.log(JSON.stringify(r, null, 2));
|
|
12598
|
+
return 0;
|
|
12599
|
+
}
|
|
12600
|
+
console.log(`\n ${c.green("changed")} ${c.bold(m.email)} ${c.dim(m.owner ? "owner" : m.role)} → ${r.role ?? role} ${c.dim("· any key of theirs above it has stopped")}\n`);
|
|
12601
|
+
return 0;
|
|
12602
|
+
}
|
|
12603
|
+
|
|
12604
|
+
/** `foldrun team access <email|id> --workspaces a,b | --all | --none` —
|
|
12605
|
+
* PATCH /api/team/members/<id> { workspaces }. Never wider than yours. */
|
|
12606
|
+
async function teamAccessCmd(positional, flags) {
|
|
12607
|
+
const url = platformFor(flags, "team access");
|
|
12608
|
+
const workspaces = memberScopeFlag(flags);
|
|
12609
|
+
if (workspaces === undefined) throw new Error("which workspaces? `foldrun team access <email|id> --workspaces a,b` (or --all, or --none)");
|
|
12610
|
+
const m = await memberNamed(url, flags, positional[0], "access");
|
|
12611
|
+
const r = await remoteCall(url, flags, `/api/team/members/${enc(m.id)}`, { method: "PATCH", body: JSON.stringify({ workspaces }) });
|
|
12612
|
+
if (flags.json === true) {
|
|
12613
|
+
console.log(JSON.stringify(r, null, 2));
|
|
12614
|
+
return 0;
|
|
12615
|
+
}
|
|
12616
|
+
console.log(`\n ${c.green("changed")} ${c.bold(m.email)}: ${SCOPE_TEXT(m.workspaces)} → ${SCOPE_TEXT(r.workspaces)} ${c.dim("· any key of theirs beyond it has stopped")}\n`);
|
|
12617
|
+
return 0;
|
|
12618
|
+
}
|
|
12619
|
+
|
|
12620
|
+
/** `foldrun team remove <email|id> [--yes]` — DELETE
|
|
12621
|
+
* /api/team/members/<id>. Asks first; with no terminal it needs --yes.
|
|
12622
|
+
* Their keys and the invites they made stop with them. */
|
|
12623
|
+
async function teamRemoveCmd(positional, flags) {
|
|
12624
|
+
const url = platformFor(flags, "team remove");
|
|
12625
|
+
const m = await memberNamed(url, flags, positional[0], "remove");
|
|
12626
|
+
if (!(await confirmed(flags, "team remove", `remove ${m.email} (${m.owner ? "owner" : m.role}) from the account — their keys and pending invites stop too. Remove? [y/N] `))) {
|
|
12627
|
+
console.log(`\n ${c.dim("nobody removed")}\n`);
|
|
12628
|
+
return 0;
|
|
12629
|
+
}
|
|
12630
|
+
const r = await remoteCall(url, flags, `/api/team/members/${enc(m.id)}`, { method: "DELETE" });
|
|
12631
|
+
if (flags.json === true) {
|
|
12632
|
+
console.log(JSON.stringify(r, null, 2));
|
|
12633
|
+
return 0;
|
|
12634
|
+
}
|
|
12635
|
+
console.log(`\n ${c.green("removed")} ${c.bold(m.email)} ${c.dim("· their keys and pending invites have stopped")}\n`);
|
|
12636
|
+
return 0;
|
|
12637
|
+
}
|
|
12638
|
+
|
|
12639
|
+
/**
|
|
12640
|
+
* `foldrun me` — the person this machine is signed in as (GET /api/me's
|
|
12641
|
+
* `person`): address, name, timezone. `foldrun me name <first> [last]`
|
|
12642
|
+
* (`--clear`) sets the name (POST /api/auth/name), `foldrun me timezone
|
|
12643
|
+
* <zone|auto>` the zone timestamps and crons are read in (POST
|
|
12644
|
+
* /api/auth/timezone). Only a `foldrun login` key is a person; a key made by
|
|
12645
|
+
* hand is refused. Password, email, two-step sign-in and sessions stay in
|
|
12646
|
+
* Settings → Profile.
|
|
12647
|
+
*/
|
|
12648
|
+
async function meCmd(positional, flags) {
|
|
12649
|
+
const url = remoteUrl(flags);
|
|
12650
|
+
if (!url) throw new Error(NOT_SIGNED_IN);
|
|
12651
|
+
const [sub, ...rest] = positional;
|
|
12652
|
+
if (sub === "name") {
|
|
12653
|
+
if (flags.clear !== true && !rest.length) throw new Error("`foldrun me name <first> [last]`, or `foldrun me name --clear`");
|
|
12654
|
+
const body = flags.clear === true ? { firstName: null, lastName: null } : { firstName: rest[0], lastName: rest.slice(1).join(" ") || null };
|
|
12655
|
+
await remoteCall(url, flags, "/api/auth/name", { method: "POST", body: JSON.stringify(body) });
|
|
12656
|
+
console.log(`\n ${c.green("saved")} ${flags.clear === true ? "no name — you are shown by your address" : `name ${c.bold([body.firstName, body.lastName].filter(Boolean).join(" "))}`}\n`);
|
|
12657
|
+
return 0;
|
|
12658
|
+
}
|
|
12659
|
+
if (sub === "timezone") {
|
|
12660
|
+
const zone = rest[0];
|
|
12661
|
+
if (!zone) throw new Error("`foldrun me timezone <zone>` (e.g. Australia/Sydney), or `foldrun me timezone auto` for the browser's");
|
|
12662
|
+
const r = await remoteCall(url, flags, "/api/auth/timezone", { method: "POST", body: JSON.stringify({ timezone: zone === "auto" ? null : zone }) });
|
|
12663
|
+
console.log(`\n ${c.green("saved")} timezone ${c.bold(r.timezone ?? "automatic (the browser's)")}\n`);
|
|
12664
|
+
return 0;
|
|
12665
|
+
}
|
|
12666
|
+
if (sub) throw new Error(`\`foldrun me\` shows you; \`foldrun me name\` and \`foldrun me timezone\` change you — not "${sub}"`);
|
|
12667
|
+
const me = await remoteCall(url, flags, "/api/me");
|
|
12668
|
+
if (flags.json === true) {
|
|
12669
|
+
console.log(JSON.stringify(me.person ?? null, null, 2));
|
|
12670
|
+
return 0;
|
|
12671
|
+
}
|
|
12672
|
+
if (!me.person) {
|
|
12673
|
+
console.log(`\n ${c.dim("this credential is a key made by hand — it is nobody. `foldrun login` signs this machine in as you")}\n`);
|
|
12674
|
+
return 1;
|
|
12675
|
+
}
|
|
12676
|
+
const p = me.person;
|
|
12677
|
+
const name = [p.firstName, p.lastName].filter(Boolean).join(" ");
|
|
12678
|
+
console.log(`\n ${c.bold(name || p.email)}${name ? ` ${c.dim(p.email)}` : ""}`);
|
|
12679
|
+
console.log(` account ${me.account}`);
|
|
12680
|
+
console.log(` role ${me.role}${me.actor?.kind === "key" ? c.dim(" (this machine's sign-in)") : ""}`);
|
|
12681
|
+
console.log(` timezone ${p.timezone ?? c.dim("automatic (the browser's)")}`);
|
|
12682
|
+
console.log(`\n ${c.dim("foldrun me name <first> [last] · foldrun me timezone <zone|auto> · password, email, two-step sign-in: Settings → Profile")}\n`);
|
|
12501
12683
|
return 0;
|
|
12502
12684
|
}
|
|
12503
12685
|
|
|
@@ -13216,6 +13398,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
13216
13398
|
return backupsCmd(positional, flags);
|
|
13217
13399
|
case "team":
|
|
13218
13400
|
return teamCmd(positional, flags);
|
|
13401
|
+
case "me":
|
|
13402
|
+
return meCmd(positional, flags);
|
|
13219
13403
|
case "onboarding":
|
|
13220
13404
|
return onboardingCmd(flags);
|
|
13221
13405
|
case "probe":
|