foldrun 19.0.2 → 19.2.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/README.md +3 -2
- package/bin/foldrun.mjs +2 -1
- package/docs/api.md +3 -3
- package/docs/cli.md +7 -6
- package/docs/getting-started.md +35 -16
- package/docs/self-hosting.md +5 -1
- package/package.json +1 -1
- package/src/commands.mjs +80 -5
package/README.md
CHANGED
|
@@ -139,7 +139,7 @@ declared the same way.
|
|
|
139
139
|
| `foldrun schedule tick` | fire whatever is due now — Settings' "Run scheduler now" |
|
|
140
140
|
| `foldrun backups` | how the account is backed up and the snapshots it is in; `backups request --what runs --at "<when>" [--to <ws>]` asks the platform team for a restore, `backups requests` lists them |
|
|
141
141
|
| `foldrun restore <ws> --to <commit\|time\|3d>` | a workspace's source back as it was then — shows the change, asks for the name typed back (`--dry-run`, `--yes`) |
|
|
142
|
-
| `foldrun onboarding` | the account's getting-started steps, done or not, the next one first |
|
|
142
|
+
| `foldrun onboarding` | the account's getting-started steps, done or not, the next one first; `--to <workspace>` adds that workspace's checklist |
|
|
143
143
|
| `foldrun triggers` | why nothing ran: per flow, how often its trigger fired, how often that became a run, and every reason for the difference (`--since <days>`, `--to`) |
|
|
144
144
|
| `foldrun webhooks deliveries` | the `notify:` webhooks a workspace sent: status, attempts, the last answer (`--failed`, `--to`) — and `redeliver <id>` to send one again |
|
|
145
145
|
| `foldrun notifications` | what mail you get, per category; `set <category> on\|off` (`--to <workspace>` for run alerts and approvals) — security, invites, billing and account mail are always sent |
|
|
@@ -227,7 +227,8 @@ foldrun deploy
|
|
|
227
227
|
foldrun invoke publish --wait
|
|
228
228
|
```
|
|
229
229
|
|
|
230
|
-
`foldrun login
|
|
230
|
+
`foldrun login` signs in to the hosted platform, https://dash.foldrun.io;
|
|
231
|
+
`foldrun login --url https://your-platform` (or `FOLDRUN_URL`) to your own installation.
|
|
231
232
|
In CI, set `FOLDRUN_URL` and `FOLDRUN_TOKEN` instead — the environment always
|
|
232
233
|
wins over the credentials file, so a job never reads one from disk.
|
|
233
234
|
|
package/bin/foldrun.mjs
CHANGED
|
@@ -286,6 +286,7 @@ Signing in
|
|
|
286
286
|
session: cookies, storage and the browser identity it needs
|
|
287
287
|
foldrun logout forget this machine's key, and revoke it where allowed
|
|
288
288
|
foldrun whoami who you are on the platform: account, role, workspaces
|
|
289
|
+
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)
|
|
289
290
|
foldrun me the person this machine is signed in as: name, address, timezone (--json)
|
|
290
291
|
foldrun me name <first> [last] set your name (--clear for none) · foldrun me timezone <zone|auto> the zone you read times in
|
|
291
292
|
foldrun team who is in the account: role, the workspaces each may open, when they joined (--json)
|
|
@@ -295,7 +296,7 @@ Signing in
|
|
|
295
296
|
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
|
|
296
297
|
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
|
|
297
298
|
foldrun team invites revoke <id> take an invite back: its link stops working at once (an admin's; a key may)
|
|
298
|
-
foldrun onboarding the account's getting-started steps, done or not, the next one first (--json)
|
|
299
|
+
foldrun onboarding the account's getting-started steps, done or not, the next one first; --to <workspace> adds that workspace's checklist (--json)
|
|
299
300
|
foldrun preferences your own settings on the platform — the theme; set theme system|light|dark (a key acts for whoever minted it)
|
|
300
301
|
foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
|
|
301
302
|
foldrun accounts every account signed in on this machine, and which one is active
|
package/docs/api.md
CHANGED
|
@@ -18,7 +18,7 @@ proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
|
|
|
18
18
|
`/api/billing/partner/…` (a storefront's signature),
|
|
19
19
|
`/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
|
|
20
20
|
`login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
|
|
21
|
-
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
21
|
+
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/signup`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
22
22
|
|
|
23
23
|
```
|
|
24
24
|
Authorization: Bearer <api-key> # machines. Settings → API keys
|
|
@@ -471,7 +471,7 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
471
471
|
|
|
472
472
|
| Route | Methods | |
|
|
473
473
|
|---|---|---|
|
|
474
|
-
| `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
|
|
474
|
+
| `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Without an invite, a new account comes in by the first-account exception or free sign-up (`signup.open`) — decided again inside the write, so two first sign-ups at once make one owner; an invite needs no switch. A body with `plan` is refused (400): paid sign-up is not offered by this route yet. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
|
|
475
475
|
| `/api/auth/login` | POST | `email`, `password`. Wrong passwords are limited per account: 8 a quarter hour from one caller when a trusted proxy names the caller (`FOLDRUN_TRUST_PROXY`), so a stranger failing as someone locks out only themselves, and 40 from every caller together, reaching which mails the person; with no caller address, 8 per account from anyone. A 429 carries `Retry-After` |
|
|
476
476
|
| `/api/auth/logout` | POST | ends the session |
|
|
477
477
|
| `/api/auth/session` | GET | who am I |
|
|
@@ -505,7 +505,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
505
505
|
| `/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 |
|
|
506
506
|
| `/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 |
|
|
507
507
|
| `/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 |
|
|
508
|
-
| `/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
|
|
508
|
+
| `/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, hidden }], done, total, complete, next, upNext, hidden, dismissed, dismissedAt, welcomedAt }`. 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). `next` is the first step not done; `upNext` the first neither done nor hidden by this person; `hidden` the step ids they hid; `welcomedAt` when they first opened the welcome flow (`/dashboard/welcome`; the home page sends a person there once, the first time they open an account with no workspace). `?workspace=<name>` adds `checklist: { workspace, items: [{ id, title, why, href, done, hidden }], done, total, complete, dismissed, show }` — that workspace's checklist: `run` (a flow that ran to the end), `trigger` (a schedule or webhook), `owner` (`owner:` by the cascade), `eval`, `notify` (`notify:` with an address or URL, the workspace's or the account's); a workspace outside the caller's scope, or none, is a `404`. A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH, for the signed-in person (kept in their prefs), any of: `{ dismissed: true or false }` hides or brings back the dashboard card; `welcomed: true` records the welcome flow as seen; `hide: [step ids]`, `show: [step ids]` hide or bring back single steps; `checklist: { workspace, dismissed?, hide?: [item ids], show?: [item ids] }` the same for a workspace's checklist. An unknown id is a `400`. A key reads nothing hidden and `dismissed: false`, and cannot PATCH |
|
|
509
509
|
| `/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` |
|
|
510
510
|
| `/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 |
|
|
511
511
|
| `/api/me/preferences` | GET, PATCH | your own display preferences: `{ theme, runViews }` — `theme` is `system` (the default: follow the computer's light or dark setting), `light` or `dark`; `runViews` your saved run searches, `[{ name, query }]` (see [Runs](runs#searching-runs)). PATCH `{ theme }` and/or `{ runViews }` (the whole list, at most 20, each query of the runs filters) answers the same; anything else is a `400`. Kept in your prefs, so it follows you to every browser; the dashboard applies it on the server, before the first paint. A key acts for the person who minted it; a key minted by nobody is a `400` |
|
package/docs/cli.md
CHANGED
|
@@ -133,7 +133,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
133
133
|
| `foldrun export [workspace]` | a deployed workspace as a `.zip` — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state, storage or a secret's value. `--flow <name>` exports that flow with every flow and agent it runs and the tools, skills and scripts they grant; `--agent <name>` that agent and what it grants. Written under the name the platform gives it (`<ws>.zip`, `<ws>-flow-<name>.zip`); `--file <path>` (`-` for stdout), `--force` to replace (`GET …/export`) |
|
|
134
134
|
| `foldrun import <file.zip>` | take a package in: first shows what it adds, what is identical, what it would replace and what it still needs (secrets, tools, skills, scripts, agents, flows), then asks. Never deletes; replacing a file needs `--overwrite`. `--to <workspace>` (a name that does not exist makes it, from a workspace package), `--dry-run` previews only (`--json` for the plan), `--yes` with no terminal (`POST …/import`) |
|
|
135
135
|
| `foldrun status [workspace]` | per workspace: what is added, changed and only-on-the-platform, plus which files moved there since your last deploy from here. Reads only |
|
|
136
|
-
| `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url`, or
|
|
136
|
+
| `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1, saying *status unavailable — the platform may be down*, when it does not answer. Plain `foldrun status` opens with the same one-line verdict |
|
|
137
137
|
| `foldrun status --platform --history` | what the status page draws as bars: each component's uptime over the window and a mark per day — up, degraded or maintenance, an outage, or no samples — then the incidents and maintenance in it, from the open `GET /api/status/history?days=<n>`. `--days 1-90` (default 90), `--json` |
|
|
138
138
|
| `foldrun workspaces` | what exists here, what exists on the platform, which are both — also `new <name>`, and `rm <name>` (locally; `--platform --yes` deletes it there). `--json`: `{ platform, workspaces: [{ name, here, platform }], error? }`, exit 1 when the platform could not be read |
|
|
139
139
|
| `foldrun workspaces show <name>` | what is deployed in one workspace (`GET /api/workspaces/<name>`): its agents with model and description, its flows and how each fires, and its files counted by top-level folder. `--json` for the document |
|
|
@@ -150,6 +150,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
150
150
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
151
151
|
| `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
|
|
152
152
|
| `foldrun whoami` | who you are on the platform: account, role, which workspaces |
|
|
153
|
+
| `foldrun signup status` | can a stranger sign up on the platform, and how: **free** sign-up (an account without paying) open or closed, **paid** sign-up (choosing a plan — foldrun's hosted platform only, in effect only while payments are ready) open or closed, and while paid is open the plans it sells. Reads the open `GET /api/signup` — what foldrun.io's sign-up buttons read — and never sends a key, whatever `--url` names; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1 when the platform does not answer or answers another shape. What each switch is SET to, and why paid is not in effect, is the operator console's |
|
|
153
154
|
| `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` |
|
|
154
155
|
| `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 |
|
|
155
156
|
| `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 |
|
|
@@ -160,7 +161,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
160
161
|
| `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 |
|
|
161
162
|
| `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 |
|
|
162
163
|
| `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 |
|
|
163
|
-
| `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`).
|
|
164
|
+
| `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`). `--to <workspace>` adds that workspace's checklist: a flow that ran to the end, a schedule or webhook, an owner, an eval, `notify:` — each with where it is done (`GET /api/me/onboarding?workspace=`). Hiding the card, a step or a checklist item is per person, from the dashboard |
|
|
164
165
|
| `foldrun preferences` | your own settings on the platform — today the theme (`system`, `light`, `dark`), kept with you on every browser; `preferences set theme dark` changes it (`/api/me/preferences`; a key acts for whoever minted it) |
|
|
165
166
|
| `foldrun api spec` | the platform's OpenAPI 3.1 document, from `GET /api/openapi.json` (no key needed) — to stdout, or `--out <file>`. Every other command sends `Foldrun-Version` (the API version this CLI was built for), an `Idempotency-Key` on each write (reused on its own retry), and waits out one `429` for `Retry-After` before saying so. See [Using the API](api-usage) |
|
|
166
167
|
| `foldrun api version` | Settings → API: the API version this account's requests get when they send no `Foldrun-Version`, whether it is pinned, every version still served, the rate limits, and the last 30 days: requests by version, and any deprecated route the account still calls — by which key or person, and when it stops answering. `api version pin <YYYY-MM-DD>` pins it, `unpin` goes back to current (`PATCH /api/account/api`; an admin's) |
|
|
@@ -279,7 +280,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
279
280
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
280
281
|
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
281
282
|
| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
|
|
282
|
-
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
283
|
+
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
283
284
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
|
284
285
|
| `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
|
|
285
286
|
| `--print` | `open`: print the URL, do not open it |
|
|
@@ -490,8 +491,8 @@ the same platform** — an agency looking after four customers keeps four,
|
|
|
490
491
|
and switches between them without pasting a key:
|
|
491
492
|
|
|
492
493
|
```sh
|
|
493
|
-
foldrun login --url https://
|
|
494
|
-
foldrun login --url https://
|
|
494
|
+
foldrun login --url https://dash.foldrun.io # as acme
|
|
495
|
+
foldrun login --url https://dash.foldrun.io # as beta, in a second browser
|
|
495
496
|
foldrun accounts # both, ● on the active one
|
|
496
497
|
foldrun use acme # from here on, acme
|
|
497
498
|
foldrun logs --profile beta --to leads # just this once, beta
|
|
@@ -525,7 +526,7 @@ foldrun keys create "alex's laptop" --role admin
|
|
|
525
526
|
The key is printed once. They send it to you; you store it as a profile:
|
|
526
527
|
|
|
527
528
|
```sh
|
|
528
|
-
foldrun login --url https://
|
|
529
|
+
foldrun login --url https://dash.foldrun.io --token <the key> --profile acme
|
|
529
530
|
```
|
|
530
531
|
|
|
531
532
|
The key carries the role it was minted with, so an `editor` key cannot
|
package/docs/getting-started.md
CHANGED
|
@@ -118,27 +118,46 @@ written into the workspace, so a workspace is always safe to commit.
|
|
|
118
118
|
|
|
119
119
|
## The checklist on the dashboard
|
|
120
120
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
the
|
|
121
|
+
The first time you open an account that has no workspace, the dashboard
|
|
122
|
+
starts you in the **welcome flow** (`/dashboard/welcome`): add your model key
|
|
123
|
+
(on a hosted platform, where the account brings its own — every run is
|
|
124
|
+
refused until it has one), choose what to start with — the demo pipeline, a
|
|
125
|
+
blank workspace, an imported .zip, the CLI, or connecting your AI app over
|
|
126
|
+
MCP — then run it once and watch each step live, ending on the run's page or,
|
|
127
|
+
if it stops, the reason and the Doctor. Every screen can be skipped, and the
|
|
128
|
+
flow picks up wherever the account really is, however you did the work.
|
|
129
|
+
|
|
130
|
+
After that the home page shows a **Getting started** card: add your model
|
|
131
|
+
key, create a workspace, write or deploy an agent, run a flow, get a run to
|
|
132
|
+
finish, add a secret, schedule a flow or give it a webhook, invite a
|
|
133
|
+
teammate, set up billing (where the plan asks for it) and install the CLI —
|
|
134
|
+
"4 of 8", with the next step opened up and a link to where to do it, and
|
|
135
|
+
**Resume setup** back into the welcome flow. Each step is worked out from the
|
|
136
|
+
account as it is (a run on record, a secret in the vault, a key minted for
|
|
137
|
+
the CLI), so it ticks itself whichever way you did the thing; there is
|
|
138
|
+
nothing to mark. While an account has no model key every dashboard page also
|
|
139
|
+
carries a banner saying so, with a link to Settings → Model provider
|
|
140
|
+
(`foldrun account model set anthropic --key …`, or on foldrun's own platform
|
|
141
|
+
`foldrun account model use foldrun --provider anthropic` to run on foldrun's
|
|
142
|
+
models, billed in credits). A step's **…** menu hides that step for you; the
|
|
143
|
+
card's hides the whole card, and the line at the foot of the page brings it
|
|
144
|
+
back. It goes away by itself once every step is done.
|
|
145
|
+
|
|
146
|
+
Each workspace's overview has a **Workspace checklist** of what a desk needs
|
|
147
|
+
before it can be left to run on its own: a flow that ran to the end, a
|
|
148
|
+
schedule or webhook, an owner, an eval, and `notify:` so someone is told
|
|
149
|
+
when a run fails — each ticked from the workspace itself (the owner and
|
|
150
|
+
`notify:` count when the account's AGENTS.md sets them), each a link to
|
|
151
|
+
where it is done. Hide an item, or the card, for yourself.
|
|
135
152
|
|
|
136
153
|
```sh
|
|
137
154
|
foldrun onboarding # the same steps, in the terminal
|
|
155
|
+
foldrun onboarding --to my-desk # and that workspace's checklist
|
|
138
156
|
```
|
|
139
157
|
|
|
140
|
-
The API is `GET /api/me/onboarding
|
|
141
|
-
setting, so it is done from the dashboard, not with
|
|
158
|
+
The API is `GET /api/me/onboarding` (`?workspace=` for the checklist);
|
|
159
|
+
hiding is a person's own setting, so it is done from the dashboard, not with
|
|
160
|
+
a key.
|
|
142
161
|
|
|
143
162
|
## Where to go next
|
|
144
163
|
|
package/docs/self-hosting.md
CHANGED
|
@@ -77,7 +77,11 @@ whoever ran it (the token is `FOLDRUN_SETUP_TOKEN` in `~/foldrun/.env`, and
|
|
|
77
77
|
does nothing once the owner exists). With `FOLDRUN_BIND` set to one address
|
|
78
78
|
the link uses that address; from another machine, open it through the
|
|
79
79
|
tunnel the installer prints (`ssh -o ExitOnForwardFailure=yes -L …`), never
|
|
80
|
-
over plain http.
|
|
80
|
+
over plain http. After the owner, the install takes new accounts only on an
|
|
81
|
+
invite (Settings → Team) unless you open sign-up to strangers with
|
|
82
|
+
`FOLDRUN_OPEN_SIGNUP=1`; with it off, `/signup` says registration is closed
|
|
83
|
+
and `GET /api/signup` answers `{ "free": false, "paid": false, "plans": [] }`.
|
|
84
|
+
Then sign the CLI in and deploy:
|
|
81
85
|
|
|
82
86
|
```sh
|
|
83
87
|
npm install -g foldrun
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -4422,7 +4422,9 @@ async function connect(positional, flags) {
|
|
|
4422
4422
|
|
|
4423
4423
|
// ---------------------------------------------------------------- login
|
|
4424
4424
|
|
|
4425
|
-
|
|
4425
|
+
// The hosted platform, when nothing names one (--url, FOLDRUN_URL, the
|
|
4426
|
+
// profile `foldrun login` last signed in to). Written once, here.
|
|
4427
|
+
const DEFAULT_PLATFORM = "https://dash.foldrun.io";
|
|
4426
4428
|
|
|
4427
4429
|
function openInBrowser(target) {
|
|
4428
4430
|
// A server-supplied address: only a web page, never a file, an app or a
|
|
@@ -5487,6 +5489,59 @@ async function platformStatusCmd(flags) {
|
|
|
5487
5489
|
return 0;
|
|
5488
5490
|
}
|
|
5489
5491
|
|
|
5492
|
+
/**
|
|
5493
|
+
* `foldrun signup status` — can a stranger sign up on this platform, and
|
|
5494
|
+
* how: free sign-up, paid sign-up, and the plans it sells while paid is in
|
|
5495
|
+
* effect. The open GET /api/signup the public site's buttons read; no key is
|
|
5496
|
+
* ever sent with it, whatever platform --url names. For an operator checking
|
|
5497
|
+
* what foldrun.io now sees after flipping a switch (the console shows each
|
|
5498
|
+
* switch as set and as in effect), or a self-hoster checking theirs.
|
|
5499
|
+
* Exits 1 when the platform does not answer or answers something else.
|
|
5500
|
+
*/
|
|
5501
|
+
async function signupCmd(positional, flags) {
|
|
5502
|
+
const verb = positional[0] ?? "status";
|
|
5503
|
+
if (verb !== "status") throw new Error(`signup: unknown verb "${verb}" — status`);
|
|
5504
|
+
const url = remoteUrl(flags) ?? DEFAULT_PLATFORM;
|
|
5505
|
+
let res;
|
|
5506
|
+
try {
|
|
5507
|
+
res = await remoteFetch(url, "/api/signup", {}, { seconds: timeoutSeconds(flags) });
|
|
5508
|
+
} catch (err) {
|
|
5509
|
+
const error = err instanceof Error ? err.message : String(err);
|
|
5510
|
+
if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
|
|
5511
|
+
else console.log(`\n ${c.red("✗")} ${url} did not answer (${error})\n`);
|
|
5512
|
+
return 1;
|
|
5513
|
+
}
|
|
5514
|
+
/** @type {any} */
|
|
5515
|
+
const body = await res.json().catch(() => null);
|
|
5516
|
+
const shaped = body && typeof body === "object" && typeof body.free === "boolean" && typeof body.paid === "boolean" && Array.isArray(body.plans);
|
|
5517
|
+
if (!res.ok || !shaped) {
|
|
5518
|
+
const error = !res.ok ? `/api/signup → HTTP ${res.status}` : "/api/signup answered something that is not { free, paid, plans }";
|
|
5519
|
+
if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
|
|
5520
|
+
else console.log(`\n ${c.red("✗")} ${error} — ${url}\n`);
|
|
5521
|
+
return 1;
|
|
5522
|
+
}
|
|
5523
|
+
if (flags.json === true) {
|
|
5524
|
+
console.log(JSON.stringify(body, null, 2));
|
|
5525
|
+
return 0;
|
|
5526
|
+
}
|
|
5527
|
+
const door = (open) => (open ? c.green("open") : c.dim("closed"));
|
|
5528
|
+
console.log(`\n ${c.bold("sign-up")} ${c.dim(url)}\n`);
|
|
5529
|
+
console.log(` free ${door(body.free)}`);
|
|
5530
|
+
console.log(` paid ${door(body.paid)}`);
|
|
5531
|
+
if (!body.free && !body.paid) console.log(`\n ${c.dim("new account registration is closed — invites still work")}`);
|
|
5532
|
+
if (body.plans.length) {
|
|
5533
|
+
console.log(`\n ${c.dim("plans")}`);
|
|
5534
|
+
for (const p of body.plans) {
|
|
5535
|
+
const price = p.price && typeof p.price.amount === "number" ? `${(p.price.amount / 100).toFixed(p.price.amount % 100 ? 2 : 0)} ${String(p.price.currency ?? "").toUpperCase()}/${p.price.interval ?? "month"}` : "—";
|
|
5536
|
+
console.log(` ${String(p.name ?? p.id).padEnd(10)} ${price.padEnd(14)} ${c.dim(`${p.credits ?? "?"} credits · ${p.vcpu ?? "?"} vCPU · ${p.memoryGiB ?? "?"} GiB${p.priority ? " · high-priority lane" : ""}`)}`);
|
|
5537
|
+
}
|
|
5538
|
+
} else if (body.paid) {
|
|
5539
|
+
console.log(`\n ${c.dim("no plans listed")}`);
|
|
5540
|
+
}
|
|
5541
|
+
console.log();
|
|
5542
|
+
return 0;
|
|
5543
|
+
}
|
|
5544
|
+
|
|
5490
5545
|
/**
|
|
5491
5546
|
* `foldrun status --platform --history [--days n]` — what the status page
|
|
5492
5547
|
* draws as bars: each component's uptime per day over the window (1–90,
|
|
@@ -12023,23 +12078,41 @@ async function historyCmd(positional, flags, layout) {
|
|
|
12023
12078
|
|
|
12024
12079
|
/**
|
|
12025
12080
|
* `foldrun onboarding` — the account's getting-started steps, each worked
|
|
12026
|
-
* out from what is really there, the next one first.
|
|
12027
|
-
*
|
|
12081
|
+
* out from what is really there, the next one first. `--to <workspace>`
|
|
12082
|
+
* adds that workspace's checklist (a flow that ran to the end, a trigger,
|
|
12083
|
+
* an owner, an eval, notify:). Hiding the dashboard card, a step or a
|
|
12084
|
+
* checklist item is a person's own setting, so it is done there, not with
|
|
12085
|
+
* a key.
|
|
12028
12086
|
*/
|
|
12029
12087
|
async function onboardingCmd(flags) {
|
|
12030
12088
|
const url = platformFor(flags, "onboarding");
|
|
12031
|
-
const
|
|
12089
|
+
const ws = typeof flags.to === "string" && flags.to ? flags.to : null;
|
|
12090
|
+
if (flags.to !== undefined && !ws) throw new Error("`foldrun onboarding --to <workspace>` — name the workspace whose checklist you want");
|
|
12091
|
+
const o = await remoteCall(url, flags, `/api/me/onboarding${ws ? `?workspace=${encodeURIComponent(ws)}` : ""}`);
|
|
12032
12092
|
if (flags.json === true) {
|
|
12033
12093
|
console.log(JSON.stringify(o, null, 2));
|
|
12034
12094
|
return 0;
|
|
12035
12095
|
}
|
|
12096
|
+
const base = String(url).replace(/\/$/, "");
|
|
12036
12097
|
console.log(`\n ${c.bold("Getting started")} ${c.dim(`${o.done} of ${o.total}${o.complete ? " — all done" : ""}`)}\n`);
|
|
12037
12098
|
for (const s of o.steps ?? []) {
|
|
12038
12099
|
const mark = s.done ? c.green("✓") : s.id === o.next?.id ? c.yellow("→") : c.dim("○");
|
|
12039
12100
|
console.log(` ${mark} ${s.done ? c.dim(s.title) : c.bold(s.title)}`);
|
|
12040
12101
|
if (!s.done) {
|
|
12041
12102
|
console.log(` ${c.dim(s.why)}`);
|
|
12042
|
-
console.log(` ${c.dim(`${
|
|
12103
|
+
console.log(` ${c.dim(`${base}${s.href}${s.cli ? ` · ${s.cli}` : ""}`)}`);
|
|
12104
|
+
}
|
|
12105
|
+
}
|
|
12106
|
+
if (!o.complete) console.log(`\n ${c.dim(`step by step in the browser: ${base}/dashboard/welcome`)}`);
|
|
12107
|
+
const cl = o.checklist;
|
|
12108
|
+
if (cl) {
|
|
12109
|
+
console.log(`\n ${c.bold(`${cl.workspace} checklist`)} ${c.dim(`${cl.done} of ${cl.total}${cl.complete ? " — all done" : ""}`)}\n`);
|
|
12110
|
+
for (const i of cl.items ?? []) {
|
|
12111
|
+
console.log(` ${i.done ? c.green("✓") : c.dim("○")} ${i.done ? c.dim(i.title) : c.bold(i.title)}`);
|
|
12112
|
+
if (!i.done) {
|
|
12113
|
+
console.log(` ${c.dim(i.why)}`);
|
|
12114
|
+
console.log(` ${c.dim(`${base}${i.href}`)}`);
|
|
12115
|
+
}
|
|
12043
12116
|
}
|
|
12044
12117
|
}
|
|
12045
12118
|
console.log();
|
|
@@ -14550,6 +14623,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14550
14623
|
return logout(flags);
|
|
14551
14624
|
case "whoami":
|
|
14552
14625
|
return whoami(flags);
|
|
14626
|
+
case "signup":
|
|
14627
|
+
return signupCmd(positional, flags);
|
|
14553
14628
|
case "doctor":
|
|
14554
14629
|
return doctor(flags);
|
|
14555
14630
|
case "version":
|