foldrun 19.0.2 → 19.1.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 +1 -1
- package/bin/foldrun.mjs +1 -1
- package/docs/api.md +1 -1
- package/docs/cli.md +1 -1
- package/docs/getting-started.md +35 -16
- package/package.json +1 -1
- package/src/commands.mjs +22 -4
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 |
|
package/bin/foldrun.mjs
CHANGED
|
@@ -295,7 +295,7 @@ Signing in
|
|
|
295
295
|
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
296
|
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
297
|
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)
|
|
298
|
+
foldrun onboarding the account's getting-started steps, done or not, the next one first; --to <workspace> adds that workspace's checklist (--json)
|
|
299
299
|
foldrun preferences your own settings on the platform — the theme; set theme system|light|dark (a key acts for whoever minted it)
|
|
300
300
|
foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
|
|
301
301
|
foldrun accounts every account signed in on this machine, and which one is active
|
package/docs/api.md
CHANGED
|
@@ -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
|
@@ -160,7 +160,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
160
160
|
| `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
161
|
| `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
162
|
| `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`).
|
|
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`). `--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
164
|
| `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
165
|
| `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
166
|
| `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) |
|
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/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -12023,23 +12023,41 @@ async function historyCmd(positional, flags, layout) {
|
|
|
12023
12023
|
|
|
12024
12024
|
/**
|
|
12025
12025
|
* `foldrun onboarding` — the account's getting-started steps, each worked
|
|
12026
|
-
* out from what is really there, the next one first.
|
|
12027
|
-
*
|
|
12026
|
+
* out from what is really there, the next one first. `--to <workspace>`
|
|
12027
|
+
* adds that workspace's checklist (a flow that ran to the end, a trigger,
|
|
12028
|
+
* an owner, an eval, notify:). Hiding the dashboard card, a step or a
|
|
12029
|
+
* checklist item is a person's own setting, so it is done there, not with
|
|
12030
|
+
* a key.
|
|
12028
12031
|
*/
|
|
12029
12032
|
async function onboardingCmd(flags) {
|
|
12030
12033
|
const url = platformFor(flags, "onboarding");
|
|
12031
|
-
const
|
|
12034
|
+
const ws = typeof flags.to === "string" && flags.to ? flags.to : null;
|
|
12035
|
+
if (flags.to !== undefined && !ws) throw new Error("`foldrun onboarding --to <workspace>` — name the workspace whose checklist you want");
|
|
12036
|
+
const o = await remoteCall(url, flags, `/api/me/onboarding${ws ? `?workspace=${encodeURIComponent(ws)}` : ""}`);
|
|
12032
12037
|
if (flags.json === true) {
|
|
12033
12038
|
console.log(JSON.stringify(o, null, 2));
|
|
12034
12039
|
return 0;
|
|
12035
12040
|
}
|
|
12041
|
+
const base = String(url).replace(/\/$/, "");
|
|
12036
12042
|
console.log(`\n ${c.bold("Getting started")} ${c.dim(`${o.done} of ${o.total}${o.complete ? " — all done" : ""}`)}\n`);
|
|
12037
12043
|
for (const s of o.steps ?? []) {
|
|
12038
12044
|
const mark = s.done ? c.green("✓") : s.id === o.next?.id ? c.yellow("→") : c.dim("○");
|
|
12039
12045
|
console.log(` ${mark} ${s.done ? c.dim(s.title) : c.bold(s.title)}`);
|
|
12040
12046
|
if (!s.done) {
|
|
12041
12047
|
console.log(` ${c.dim(s.why)}`);
|
|
12042
|
-
console.log(` ${c.dim(`${
|
|
12048
|
+
console.log(` ${c.dim(`${base}${s.href}${s.cli ? ` · ${s.cli}` : ""}`)}`);
|
|
12049
|
+
}
|
|
12050
|
+
}
|
|
12051
|
+
if (!o.complete) console.log(`\n ${c.dim(`step by step in the browser: ${base}/dashboard/welcome`)}`);
|
|
12052
|
+
const cl = o.checklist;
|
|
12053
|
+
if (cl) {
|
|
12054
|
+
console.log(`\n ${c.bold(`${cl.workspace} checklist`)} ${c.dim(`${cl.done} of ${cl.total}${cl.complete ? " — all done" : ""}`)}\n`);
|
|
12055
|
+
for (const i of cl.items ?? []) {
|
|
12056
|
+
console.log(` ${i.done ? c.green("✓") : c.dim("○")} ${i.done ? c.dim(i.title) : c.bold(i.title)}`);
|
|
12057
|
+
if (!i.done) {
|
|
12058
|
+
console.log(` ${c.dim(i.why)}`);
|
|
12059
|
+
console.log(` ${c.dim(`${base}${i.href}`)}`);
|
|
12060
|
+
}
|
|
12043
12061
|
}
|
|
12044
12062
|
}
|
|
12045
12063
|
console.log();
|