@forumulate/cli 0.5.0 → 0.9.0

package/README.md

@@ -34,11 +34,107 @@ The SDK (`ForumulateClient.fromEnv()`) and the MCP server ([`@forumulate/mcp`](h
 ## Quickstart
 
 ```sh
-forumulate orgs                      # id  slug  name
-forumulate spaces acme               # an org id or its slug
-forumulate items acme <spaceId>      # what is in a space, and where its content lives
+forumulate config set org acme       # the default for every --org
+forumulate orgs list                 # id  slug  name
+forumulate spaces list               # the spaces in acme
+forumulate items list --space docs   # what is in a space, and where its content lives
+forumulate api list --search webhook # every API operation, by summary
 ```
 
+## Resource commands
+
+Every group takes the same verbs (`list`, `get`, `create`, `update`, `delete`, and `publish` where a thing has a draft), the same scope flags (`--org`, `--space`, `--library`, each an id or a slug), and `--json` for the API's answer untouched. `forumulate <group> --help` lists a group's verbs and the operation each one calls.
+
+| Group | Verbs |
+| --- | --- |
+| `orgs list\|get\|create\|update\|delete`, `orgs deepl status\|set\|clear`, `orgs strings list\|set\|remove` | Your organizations, their DeepL key, and their own wording for interface strings. |
+| `members list\|update\|remove\|sign-out\|reassign` | People in an org. |
+| `invites list\|create\|bulk\|revoke\|pending\|accept\|redeem\|join`, `invites links list\|create\|revoke` | Invitations you send (one, many, or a shareable link) and the ones waiting for you. |
+| `groups …`, `roles …`, `service-accounts` / `bots` `… tokens list\|create\|revoke` | Groups and join requests, custom roles, and non-human members with their tokens. |
+| `tokens` / `pats` `list\|scopes\|create\|rotate\|rename\|revoke` | Your personal access tokens, by id or by name. |
+| `webhooks list\|events\|create\|update\|delete\|test\|rotate-secret\|deliveries\|replay` | Endpoints, their deliveries, and replays. |
+| `extensions …`, `audit list\|actions\|export` | Installed extensions and the marketplace; the audit log (export as CSV). |
+| `spaces list\|overview\|get\|create\|update\|delete\|restore\|purge\|duplicate\|move\|rename\|access\|preview`, `spaces slugs list\|forget` | Spaces in an org: slugs, moves, copies and the trash. |
+| `snapshots list\|create\|restore\|delete`, `shape get\|set\|patch\|preset\|kinds …` | Space snapshots, and a space's shape override. |
+| `items` / `pages` `list\|get\|content\|create\|update\|write\|section\|fields\|chunks\|verify\|publish\|delete` | Any piece in a space. `--file page.md` fills the body; front matter sets `title` and `slug`. |
+| `docs list\|get\|save\|publish\|unpublish\|history\|diff\|rollback\|move\|duplicate\|…`, `docs schedule get\|set\|cancel`, `docs checkpoints …`, `docs trash …`, `docs import zip\|docx\|url\|files`, `docs locales …`, `docs search` | A docs space's pages: drafts, revisions, scheduled publishing, rollback, the trash, imports and languages. |
+| `collections …`, `versions list\|create\|update\|default\|delete\|settings\|configure` | Collections and their page order; docs versions. |
+| `change-requests` / `crs` `list\|open\|review\|approve\|merge\|close\|rebase\|comment\|…`, `crs reviewers …`, `crs rules get\|set` | Proposed docs changes, review and merge rules. |
+| `openapi list\|register\|resync\|lint\|import\|generate\|…`, `openapi sdk languages\|get\|download` | OpenAPI specs behind reference pages, and the SDKs generated from them. |
+| `sdks packages\|register\|publish\|publishes`, `sdks registries list\|set\|test\|remove` | Publishing those SDKs to package registries. |
+| `blog`, `forum`, `changelog` `list\|get\|create\|update\|publish\|delete\|…` | Articles, topics and releases; scheduling, pinning, settings, flags, polls, replies. `create --file post.md --publish`. |
+| `blog` / `forum` / `changelog` / `status` `translations list\|get\|put\|remove\|auto` | One piece's translations at its own door. `translations` (below) is the whole-space workflow. |
+| `roadmap board\|get\|submit\|update\|status\|vote\|comment\|merge\|proxy-votes …` | A roadmap space. |
+| `status board`, `status incidents …`, `status components …`, `status channels …`, `status groups get\|set` | A status space: incidents, components, where they are announced. |
+| `events …`, `course outline\|enrol\|complete`, `careers …`, `forms …` | Events and RSVPs, course progress, job applications, forms and submissions (CSV export). |
+| `libraries list\|get\|create\|update\|delete`, `libraries members\|locales\|model\|keys …` | Headless CMS libraries: grants, languages, the model, delivery keys. |
+| `entries list\|types\|get\|create\|update\|fields\|patch\|publish\|bulk\|trash\|restore\|lock …\|locale get\|set` | A library's entries. |
+| `media …`, `releases list\|create\|add\|schedule\|publish\|rollback\|…`, `environments` / `envs list\|fork\|compare\|promote` | Library media, content releases, and sandbox environments. |
+| `domains list\|add\|setup\|verify\|activate\|www\|allow-ips\|redirect\|remove\|…`, `assets list\|all\|upload\|download\|delete` | Custom domains on a space (by id or hostname), and its uploaded files. |
+| `theme get\|set\|patch\|export\|import`, `theme draft get\|set\|patch\|apply\|discard\|publish` | A space's theme: kept in git with `export`/`import`, staged as a draft, then published. |
+| `sites …`, `sites domains …`, `sites theme export\|import`, `sites draft …` | Sites: several spaces under one domain and theme. |
+| `github status\|connect\|import\|export\|pull-request` | Sync a docs space with a repository. |
+| `reader page\|markdown\|pdf\|version`, `reader blog index\|article\|rss\|json-feed\|…` | What a reader is served, as the public API answers it (`--out` for a PDF or feed). |
+| `space-types list\|get\|presets\|slots` | What each kind of space is. |
+| `search <query…>`, `search semantic\|recent\|tags\|tag\|gaps\|reindex` | Unified search across docs, forum and blog, and the searches that found nothing. |
+
+Flags are derived from the API itself: every query parameter of the operation (`--limit`, `--state`) and every top-level body field (`--name`, `--visibility`) is a flag, and `--data`/`--field` work as they do under `forumulate api`. A Markdown file with front matter fills an item, post, topic or release: `title` and `slug` come from the front matter unless you pass them.
+
+```sh
+forumulate spaces create Guides --slug guides --type DOCS --visibility PUBLIC
+forumulate items create --space guides --file getting-started.md --publish
+forumulate webhooks create https://hooks.example.com/f --events page.published,post.created
+forumulate webhooks deliveries <webhookId> && forumulate webhooks replay <webhookId> <deliveryId>
+forumulate tokens rotate ci-deploy --graceMinutes 60
+forumulate status incidents create "API latency" --space status --severity minor
+```
+
+`delete`, `remove` and `revoke` ask first; `--yes` skips the question, and with no terminal (CI) `--yes` is required. `--dry-run` prints the request instead of sending it. A command whose answer is a file (an SDK archive, a PDF, a CSV export) writes it to `--out <file>`, and one that uploads (`assets upload`, `media upload`, `docs import zip`) takes the local path as its argument.
+
+```sh
+forumulate docs schedule set <pageId> 2026-11-01T09:00:00Z --space guides
+forumulate docs rollback <pageId> <revisionId> --mode draft --space guides
+forumulate crs open "Rate limits rewrite" --space guides && forumulate crs merge <crId> --space guides
+forumulate openapi resync <specId> --space reference --background true
+forumulate releases create "Spring launch" && forumulate releases schedule <releaseId> 2026-03-01T08:00:00Z
+forumulate theme export --space docs --json > theme.json && forumulate theme import --space docs --data @theme.json
+forumulate blog translations auto <postId> es --space blog
+forumulate audit export --from 2026-10-01 --out audit.csv
+```
+
+## `forumulate api`: every operation
+
+The resource commands cover the daily work. `forumulate api` covers the rest — every operation in the API, from a copy of the OpenAPI document bundled with the CLI.
+
+```sh
+forumulate api list --tag Webhook                 # operationId, method, path, summary
+forumulate api describe Space_create              # parameters as flags, the body as fields
+forumulate api Space_list acme --limit 20         # path params positionally…
+forumulate api Space_get --orgId acme --spaceId <id>   # …or by name (--org-id works too)
+forumulate api GET /orgs/{orgId}/members --paginate --json
+forumulate api POST /orgs/acme/spaces --data @space.json
+cat body.json | forumulate api Item_putContent acme <spaceId> <itemId> --data -
+forumulate api Space_update acme <spaceId> --field settings.overview="Start here"
+```
+
+- **Parameters**: `--<name> value` for path, query and header parameters; a repeated flag is joined with commas (how every array parameter here is spelled). Path parameters may be positional, in path order; `orgId` defaults to `--org`, `FORUMULATE_ORG`, then `forumulate config`. `-p name=value` sets one whose name collides with a CLI flag.
+- **Body**: `--data '{…}'`, `--data @file.json` or `--data -` (stdin), then `--field a.b=value` (typed by the body schema; `a:=<json>` for raw JSON), then any `--<field>` the body declares. Multipart operations take `--form name=value` and `--form file=@path`.
+- **Output**: a list prints as a table with a footer saying whether there is more (`--cursor <next>`), a single resource as `key  value` lines; `--json` prints the body as received; `--paginate` follows `page.nextCursor` to the end and prints one merged list; `--columns a,b` picks table columns; `-i` adds the status and headers.
+- **Transport**: `Forumulate-Version: 2026-12-01` on every request (`--api-version` or `forumulate config set api-version` to pin another), an `Idempotency-Key` on every write that declares one (the same key on a retry), and retries for a 429 (honouring `Retry-After`) and for a 502/503/504 on a request that is safe to repeat.
+- **Exit status** is 0 on a 2xx and 1 on anything else, including a usage error, so it works in a pipeline.
+
+A route newer than your copy of the CLI still works as `forumulate api <METHOD> <path>`; it is sent as written.
+
+## Configuration and completion
+
+```sh
+forumulate config set org acme            # also: space, library, api-version
+forumulate config list                    # value and where it came from
+eval "$(forumulate completion zsh)"       # or bash; fish: forumulate completion fish > ~/.config/fish/completions/forumulate.fish
+```
+
+A flag beats the environment (`FORUMULATE_ORG`, `FORUMULATE_SPACE`, `FORUMULATE_LIBRARY`, `FORUMULATE_API_VERSION`), and the environment beats `~/.config/forumulate/config.json`. Completion covers commands, verbs, operationIds and each operation's flags.
+
 ## Common tasks
 
 **1. Publish a folder of Markdown (docs-as-code).** One folder per collection, nested folders as parent pages, front matter for title, slug, description, icon, tags, order and any other page field, images uploaded, links rewritten. Blog and changelog folders become posts. Re-runs change only what changed; `--prune` removes what the folder no longer has; the space is read back afterwards. An optional `forumulate.yaml` sets the space's settings and theme, the site, an OpenAPI reference and status monitors. See [Publish a folder of Markdown from git](https://forumulate.com/guides/publish-from-git) and `examples/publish-docs.yml` for GitHub Actions.
@@ -49,6 +145,14 @@ forumulate publish ./docs --org acme --space docs --prune
 forumulate publish . --only getting-started,theme             # just these
 ```
 
+**1b. Sync a folder (content as code).** `forumulate sync <folder>` is the same engine as a plan by default: `--apply` writes it, `--diff` shows what changes inside each post or page, `--prune` removes what has no file. A `forumulate.yml` maps folders to spaces: blog posts, docs pages, FAQ questions (with `short-answer:` and `related:` slots), changelog releases and blog categories (`tags:` in the manifest or `_tags.yml`: label, colour, cover, icon, parent). Matched by slug, images uploaded once by content hash, `README`/`LICENSE`/`_drafts/`/dotfiles skipped — and a second run writes nothing. See [Content as code](https://forumulate.com/guides/content-as-code).
+
+```sh
+forumulate sync .                   # the plan
+forumulate sync . --diff            # the plan, with paragraph and field diffs
+forumulate sync . --apply --prune   # do it, read it back
+```
+
 **2. Publish one page by id.**
 
 ```sh
@@ -58,7 +162,7 @@ forumulate publish acme <spaceId> <pageId>
 **3. Search docs, forum and blog together.**
 
 ```sh
-forumulate search acme rate limits
+forumulate search rate limits --org acme   # or, older form: forumulate search acme rate limits
 ```
 
 **4. Snapshot a space before a big change.**
@@ -74,7 +178,19 @@ forumulate domains acme <spaceId>                         # each domain and its
 forumulate domains verify acme <spaceId> docs.acme.dev   # re-check, and print the DNS still missing
 ```
 
-Add `--json` to any command for raw JSON, `--version` for the version, and `forumulate help` for the full list. Every command exits non-zero on failure, so it works in a pipeline.
+**6. Manage translations.** Use `forumulate translations`, or its alias `forumulate i18n`. It covers every translation capability: a space's or library's languages, coverage, a file round trip, machine translation with your own key, chrome labels, interface overrides, names and the switcher. See [Translations everywhere](https://forumulate.com/guides/translations-everywhere).
+
+```sh
+forumulate translations locales set es=Español fr --space docs     # declare exactly these
+forumulate translations status --space docs --fail-on missing,outdated   # CI gate (exit 1)
+forumulate translations pull --space docs --include-missing        # translations/<locale>/<slug>.md
+forumulate translations push --space docs --dry-run                # the diff; drop --dry-run to apply
+forumulate translations auto --space docs --locale es              # your DeepL key; missing + outdated
+forumulate translations labels pull --space docs --format xliff    # for your TMS
+forumulate translations overrides push overrides.json --prune
+```
+
+Add `--json` to any command for raw JSON, `--version` for the version, and `forumulate help` for the full list. Every command exits non-zero on failure, so it works in a pipeline. The older positional forms — `spaces <orgId>`, `items <orgId> <spaceId>`, `search <orgId> <query…>`, `domains [verify] <orgId> <spaceId>` — still work and print exactly what they did.
 
 ### In CI
 
@@ -83,6 +199,9 @@ Add `--json` to any command for raw JSON, `--version` for the version, and `foru
 - run: npx -y @forumulate/cli publish acme ${{ vars.DOCS_SPACE_ID }} ./docs
   env:
     FORUMULATE_TOKEN: ${{ secrets.FORUMULATE_TOKEN }}
+- run: npx -y @forumulate/cli translations status --org acme --space docs --fail-on missing,outdated
+  env:
+    FORUMULATE_TOKEN: ${{ secrets.FORUMULATE_TOKEN }}
 ```
 
 ## `forumulate conformance`

package/dist/api/args.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Argument parsing for `forumulate api` and the resource commands.
+ *
+ * The older commands parse against a fixed list of value flags. These cannot:
+ * `forumulate api` takes a flag per API parameter, and there are a thousand of
+ * them. So the rule is inverted — every `--flag` takes the next token as its
+ * value unless it is a known switch, the next token is itself a flag, or the
+ * flag is written `--flag=value`. `--no-x` is `x=false`.
+ */
+export interface Parsed {
+    positionals: string[];
+    /** Every value given for a flag, in order (a flag may repeat). */
+    flags: Map<string, string[]>;
+}
+/** Flags that never take a value. */
+export declare const SWITCHES: Set<string>;
+export declare function parseArgs(argv: string[], switches?: Set<string>): Parsed;
+export declare const flag: (p: Parsed, name: string) => string | undefined;
+export declare const has: (p: Parsed, name: string) => boolean;
+export declare const all: (p: Parsed, name: string) => string[];
+//# sourceMappingURL=args.d.ts.map

package/dist/api/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/api/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kEAAkE;IAClE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9B;AAED,qCAAqC;AACrC,eAAO,MAAM,QAAQ,aAanB,CAAC;AAYH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAY,GAAG,MAAM,CAsClF;AAED,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAAsC,CAAC;AAC/F,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,EAAE,MAAM,MAAM,KAAG,OAG7C,CAAC;AACF,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,EAA6B,CAAC"}

package/dist/api/args.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.all = exports.has = exports.flag = exports.SWITCHES = void 0;
+exports.parseArgs = parseArgs;
+/** Flags that never take a value. */
+exports.SWITCHES = new Set([
+    'json',
+    'paginate',
+    'yes',
+    'y',
+    'help',
+    'h',
+    'dry-run',
+    'verbose',
+    'include-headers',
+    'publish',
+    'all',
+    'force',
+]);
+const SHORT = {
+    f: 'field',
+    H: 'header',
+    d: 'data',
+    p: 'param',
+    y: 'yes',
+    h: 'help',
+    i: 'include-headers',
+};
+function parseArgs(argv, switches = exports.SWITCHES) {
+    const positionals = [];
+    const flags = new Map();
+    const add = (k, v) => flags.set(k, [...(flags.get(k) ?? []), v]);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        let name;
+        if (a.startsWith('--') && a.length > 2)
+            name = a.slice(2);
+        else if (/^-[a-zA-Z]$/.test(a))
+            name = SHORT[a.slice(1)] ?? a.slice(1);
+        if (name === undefined) {
+            positionals.push(a);
+            continue;
+        }
+        const eq = name.indexOf('=');
+        if (eq > 0) {
+            add(name.slice(0, eq), name.slice(eq + 1));
+            continue;
+        }
+        if (switches.has(name)) {
+            add(name, 'true');
+            continue;
+        }
+        if (name.startsWith('no-')) {
+            add(name.slice(3), 'false');
+            continue;
+        }
+        const next = argv[i + 1];
+        // `--data -` is stdin, so a lone dash is a value, not a flag.
+        if (next !== undefined && (next === '-' || !next.startsWith('-') || /^-\d/.test(next))) {
+            add(name, next);
+            i++;
+        }
+        else
+            add(name, 'true');
+    }
+    return { positionals, flags };
+}
+const flag = (p, name) => p.flags.get(name)?.at(-1);
+exports.flag = flag;
+const has = (p, name) => {
+    const v = (0, exports.flag)(p, name);
+    return v !== undefined && v !== 'false';
+};
+exports.has = has;
+const all = (p, name) => p.flags.get(name) ?? [];
+exports.all = all;
+//# sourceMappingURL=args.js.map

package/dist/api/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/api/args.ts"],"names":[],"mappings":"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"}

package/dist/api/command.d.ts

@@ -0,0 +1,17 @@
+import type { CommandDeps } from '../commands/context';
+/**
+ * `forumulate api` — every operation in the API, from the bundled spec.
+ *
+ *   forumulate api list [--tag Space] [--search webhook]
+ *   forumulate api describe Space_create
+ *   forumulate api Space_list acme --limit 20
+ *   forumulate api GET /orgs/{orgId}/spaces acme --paginate
+ *   forumulate api POST /orgs/acme/spaces --data @space.json
+ *
+ * The resource commands (`spaces`, `webhooks`, …) cover what people do daily;
+ * this covers everything else, so a route that ships today is callable today
+ * with no CLI release — `operations.test.ts` walks the spec to keep it so.
+ */
+export declare const API_HELP = "forumulate api \u2014 call any operation in the Forumulate API\n\nUsage:\n  forumulate api list [--tag <tag>] [--search <words>] [--method GET]\n  forumulate api describe <operationId | METHOD path> [--json]\n  forumulate api <operationId> [path params\u2026] [flags]\n  forumulate api <METHOD> <path> [path params\u2026] [flags]\n\nParameters:\n  --<name> <value>        a path, query or header parameter (--orgId, --org-id)\n  -p, --param name=value  the same, for a name that collides with a flag below\n  path params may also be given positionally, in path order; orgId defaults\n  to --org / FORUMULATE_ORG / `forumulate config set org \u2026`\n\nBody:\n  -d, --data '{\u2026}' | @file.json | -   JSON body (- reads stdin)\n  -f, --field a.b=value   one field, typed by the body schema (a:=<json> raw)\n  --<field> <value>       a top-level body field the operation declares\n  --form name=value | name=@file      multipart operations (uploads)\n\nOutput and transport:\n  --json                  the response body, untouched\n  --paginate              follow page.nextCursor to the end (one merged list)\n  --max-pages <n>         stop after n pages (default 1000)\n  --columns a,b,c         table columns for a list answer\n  -i, --include-headers   print the status line and response headers\n  -H, --header 'Name: v'  an extra request header\n  --api-version <date>    Forumulate-Version to send (default 2026-12-01)\n  --idempotency-key <k>   instead of the generated one\n  --dry-run               print the request, send nothing\n\nExit status is 0 on a 2xx and 1 otherwise (usage errors included).";
+export declare function runApi(argv: string[], deps: CommandDeps): Promise<number>;
+//# sourceMappingURL=command.d.ts.map

package/dist/api/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/api/command.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,+kDA+B8C,CAAC;AAIpE,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC/E"}

package/dist/api/command.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_HELP = void 0;
+exports.runApi = runApi;
+const args_1 = require("./args");
+const describe_1 = require("./describe");
+const output_1 = require("./output");
+const send_1 = require("./send");
+const spec_1 = require("./spec");
+const request_1 = require("./request");
+/**
+ * `forumulate api` — every operation in the API, from the bundled spec.
+ *
+ *   forumulate api list [--tag Space] [--search webhook]
+ *   forumulate api describe Space_create
+ *   forumulate api Space_list acme --limit 20
+ *   forumulate api GET /orgs/{orgId}/spaces acme --paginate
+ *   forumulate api POST /orgs/acme/spaces --data @space.json
+ *
+ * The resource commands (`spaces`, `webhooks`, …) cover what people do daily;
+ * this covers everything else, so a route that ships today is callable today
+ * with no CLI release — `operations.test.ts` walks the spec to keep it so.
+ */
+exports.API_HELP = `forumulate api — call any operation in the Forumulate API
+
+Usage:
+  forumulate api list [--tag <tag>] [--search <words>] [--method GET]
+  forumulate api describe <operationId | METHOD path> [--json]
+  forumulate api <operationId> [path params…] [flags]
+  forumulate api <METHOD> <path> [path params…] [flags]
+
+Parameters:
+  --<name> <value>        a path, query or header parameter (--orgId, --org-id)
+  -p, --param name=value  the same, for a name that collides with a flag below
+  path params may also be given positionally, in path order; orgId defaults
+  to --org / FORUMULATE_ORG / \`forumulate config set org …\`
+
+Body:
+  -d, --data '{…}' | @file.json | -   JSON body (- reads stdin)
+  -f, --field a.b=value   one field, typed by the body schema (a:=<json> raw)
+  --<field> <value>       a top-level body field the operation declares
+  --form name=value | name=@file      multipart operations (uploads)
+
+Output and transport:
+  --json                  the response body, untouched
+  --paginate              follow page.nextCursor to the end (one merged list)
+  --max-pages <n>         stop after n pages (default 1000)
+  --columns a,b,c         table columns for a list answer
+  -i, --include-headers   print the status line and response headers
+  -H, --header 'Name: v'  an extra request header
+  --api-version <date>    Forumulate-Version to send (default 2026-12-01)
+  --idempotency-key <k>   instead of the generated one
+  --dry-run               print the request, send nothing
+
+Exit status is 0 on a 2xx and 1 otherwise (usage errors included).`;
+const API_SWITCHES = new Set(['json', 'paginate', 'include-headers', 'dry-run', 'help', 'verbose']);
+async function runApi(argv, deps) {
+    const parsed = (0, args_1.parseArgs)(argv, API_SWITCHES);
+    const [first, ...rest] = parsed.positionals;
+    const json = (0, args_1.has)(parsed, 'json');
+    if (!first || first === 'help' || ((0, args_1.has)(parsed, 'help') && first !== 'describe')) {
+        deps.out(exports.API_HELP);
+        return first || (0, args_1.has)(parsed, 'help') ? 0 : 1;
+    }
+    try {
+        if (first === 'list' || first === 'ls')
+            return list(parsed, rest, deps, json);
+        if (first === 'describe') {
+            const target = resolveOp(rest);
+            if (!target)
+                return usage(deps, 'api describe <operationId | METHOD path>', rest.join(' '));
+            if (json)
+                deps.out(JSON.stringify({ ...target.op, b: undefined, body: target.op.b ? (0, describe_1.expand)(target.op.b) : undefined }, null, 2));
+            else
+                for (const l of (0, describe_1.describe)(target.op))
+                    deps.out(l);
+            return 0;
+        }
+        return await invoke(parsed, deps, json);
+    }
+    catch (e) {
+        if (e instanceof request_1.UsageError) {
+            deps.err(`Usage: ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function usage(deps, form, got) {
+    if (got)
+        deps.err(`No operation matches "${got}". Try: forumulate api list --search <words>`);
+    deps.err(`Usage: forumulate ${form}`);
+    return 1;
+}
+/** `Space_list` or `GET /orgs/{orgId}/spaces` or `GET /orgs/acme/spaces`. */
+function resolveOp(words) {
+    const [a, b] = words;
+    if (!a)
+        return undefined;
+    if ((0, spec_1.isMethod)(a) && b?.startsWith('/')) {
+        const hit = (0, spec_1.findByPath)(a, b);
+        return hit && { ...hit, used: 2 };
+    }
+    const op = (0, spec_1.findById)(a);
+    return op && { op, values: {}, used: 1 };
+}
+function list(parsed, rest, deps, json) {
+    const ops = (0, spec_1.filterOps)({
+        tag: (0, args_1.flag)(parsed, 'tag'),
+        search: [(0, args_1.flag)(parsed, 'search'), ...rest].filter(Boolean).join(' ') || undefined,
+        method: (0, args_1.flag)(parsed, 'method'),
+    });
+    if (json) {
+        deps.out(JSON.stringify(ops.map((o) => ({ operationId: o.id, method: o.m, path: o.p, summary: o.s, tags: o.t })), null, 2));
+        return 0;
+    }
+    if (ops.length === 0) {
+        deps.err('No operations match.');
+        return 1;
+    }
+    for (const l of (0, output_1.table)(ops.map((o) => ({ operationId: o.id, method: o.m, path: o.p, summary: o.s ?? '' })), ['operationId', 'method', 'path', 'summary']))
+        deps.out(l);
+    deps.out(`-- ${ops.length} of ${(0, spec_1.loadIndex)().ops.length} operations`);
+    return 0;
+}
+async function invoke(parsed, deps, json) {
+    const words = parsed.positionals;
+    const target = resolveOp(words);
+    const src = {
+        readFile: deps.readFile,
+        readStdin: deps.readStdin,
+        defaultOrg: (0, args_1.flag)(parsed, 'org') ?? deps.defaultOrg,
+    };
+    let request;
+    let op;
+    if (target) {
+        op = target.op;
+        ({ request } = await (0, request_1.planRequest)(op, parsed, words.slice(target.used), src, target.values));
+    }
+    else if ((0, spec_1.isMethod)(words[0]) && words[1]?.startsWith('/')) {
+        // A path the bundled spec does not know (a route newer than this CLI):
+        // send it as written, unknown flags as query parameters.
+        const query = {};
+        for (const [k, v] of parsed.flags)
+            if (!request_1.API_FLAGS.has(k))
+                query[k] = v.join(',');
+        const fake = {
+            id: `${words[0].toUpperCase()} ${words[1]}`,
+            m: words[0].toUpperCase(),
+            p: words[1].split('?')[0],
+            b: {},
+        };
+        const withQuery = {
+            ...parsed,
+            flags: new Map([...parsed.flags].filter(([k]) => request_1.API_FLAGS.has(k))),
+        };
+        ({ request } = await (0, request_1.planRequest)(fake, withQuery, words.slice(2), src));
+        request.query = {
+            ...Object.fromEntries(new URLSearchParams(words[1].split('?')[1] ?? '')),
+            ...query,
+        };
+        deps.err(`note: ${request.method} ${fake.p} is not in this CLI's bundled spec; sending it as written.`);
+    }
+    else {
+        return usage(deps, 'api <operationId | METHOD path> [flags]', words.join(' '));
+    }
+    const http = deps.http;
+    if ((0, args_1.has)(parsed, 'dry-run') && !op?.q?.some((p) => p.n === 'dryRun')) {
+        (0, send_1.printRequest)(http, request, deps);
+        return 0;
+    }
+    await (0, send_1.sendAndPrint)(http, request, {
+        json,
+        paginate: (0, args_1.has)(parsed, 'paginate'),
+        maxPages: Number((0, args_1.flag)(parsed, 'max-pages') ?? 1000),
+        columns: columns(parsed),
+        includeHeaders: (0, args_1.has)(parsed, 'include-headers'),
+    }, deps);
+    return 0;
+}
+const columns = (p) => (0, args_1.flag)(p, 'columns')?.split(',').filter(Boolean);
+//# sourceMappingURL=command.js.map

package/dist/api/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/api/command.ts"],"names":[],"mappings":"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"}

package/dist/api/describe.d.ts

@@ -0,0 +1,5 @@
+import { type Operation, type SchemaNode } from './spec';
+export declare function describe(op: Operation): string[];
+/** The body schema as JSON, refs expanded a few levels — `describe --json`. */
+export declare function expand(node: SchemaNode | undefined, depth?: number): unknown;
+//# sourceMappingURL=describe.d.ts.map

package/dist/api/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/api/describe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAyD5F,wBAAgB,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,EAAE,CA0BhD;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,OAAO,CAmBvE"}

package/dist/api/describe.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describe = describe;
+exports.expand = expand;
+const spec_1 = require("./spec");
+/**
+ * `forumulate api describe <operationId>`: what to pass, in the CLI's own terms.
+ *
+ * Each parameter is printed as the flag that sets it, and the body as an
+ * indented field list with types, required marks and enums — enough to write
+ * `--field` flags or a `--data` file without opening the reference.
+ */
+/** An enum of 40 event names is a paragraph, not a type: show a few and say how many. */
+function enumText(values) {
+    const shown = values
+        .slice(0, 8)
+        .map((v) => JSON.stringify(v))
+        .join('|');
+    return values.length > 8
+        ? `${shown}|… (${values.length} values; describe --json lists all)`
+        : shown;
+}
+function typeOf(node, depth = 0) {
+    const n = (0, spec_1.resolveRef)(node);
+    if (!n)
+        return 'any';
+    if (n.c !== undefined)
+        return JSON.stringify(n.c);
+    if (n.e)
+        return enumText(n.e);
+    if (n.any)
+        return [...new Set(n.any.map((v) => typeOf(v, depth + 1)))].join(' | ');
+    if (n.t === 'array')
+        return `${typeOf(n.i, depth + 1)}[]`;
+    return (n.t ?? (n.p ? 'object' : 'any')) + (n.n ? '?' : '');
+}
+function fields(node, indent, depth, out) {
+    const n = (0, spec_1.resolveRef)(node);
+    if (!n || depth > 3)
+        return;
+    if (n.any) {
+        const objects = n.any.map((v) => (0, spec_1.resolveRef)(v)).filter((v) => v?.p);
+        if (objects.length > 1) {
+            objects.forEach((v, i) => {
+                out.push(`${indent}one of (${i + 1}/${objects.length})${v.d ? ` — ${v.d}` : ''}`);
+                fields(v, `${indent}  `, depth + 1, out);
+            });
+            return;
+        }
+        if (objects.length === 1)
+            return fields(objects[0], indent, depth, out);
+    }
+    for (const part of n.all ?? [])
+        fields(part, indent, depth + 1, out);
+    const required = new Set(n.r ?? []);
+    for (const [k, v] of Object.entries(n.p ?? {})) {
+        const child = (0, spec_1.resolveRef)(v);
+        out.push(`${indent}${k}${required.has(k) ? '*' : ''}  ${typeOf(v)}${child?.d ? `  — ${child.d}` : ''}`);
+        const inner = child?.t === 'array' ? (0, spec_1.resolveRef)(child.i) : child;
+        if (inner?.p && depth < 2)
+            fields(inner, `${indent}  `, depth + 1, out);
+    }
+}
+function describe(op) {
+    const out = [`${op.id}  ${op.m} ${op.p}${op.dep ? '  (deprecated)' : ''}`];
+    if (op.s)
+        out.push(`  ${op.s}`);
+    if (op.t?.length)
+        out.push(`  tags: ${op.t.join(', ')}`);
+    const params = op.q ?? [];
+    const path = (0, spec_1.pathParams)(op);
+    out.push('', 'Usage:', `  forumulate api ${op.id}${path.map((p) => ` <${p}>`).join('')} [flags]`);
+    if (params.length) {
+        out.push('', 'Parameters:');
+        for (const p of params) {
+            const t = p.e ? enumText(p.e) : (p.t ?? 'string');
+            out.push(`  --${p.n}${p.r ? '*' : ''}  ${p.in} ${t}${p.d ? `  — ${p.d}` : ''}`);
+        }
+    }
+    if (op.b) {
+        out.push('', `Body (${op.mp ? 'multipart/form-data: --form name=value | name=@file' : 'JSON: --data, --field, or --<field>'})${op.br ? ', required' : ''}:`);
+        fields(op.b, '  ', 0, out);
+    }
+    if (op.ik)
+        out.push('', 'Sends an Idempotency-Key (override with --idempotency-key).');
+    if (params.some((p) => p.n === 'cursor'))
+        out.push('Paged: --paginate follows page.nextCursor to the end.');
+    out.push('', '* required');
+    return out;
+}
+/** The body schema as JSON, refs expanded a few levels — `describe --json`. */
+function expand(node, depth = 0) {
+    const n = (0, spec_1.resolveRef)(node, (0, spec_1.loadIndex)());
+    if (!n)
+        return {};
+    if (depth > 6)
+        return { type: n.t ?? 'object' };
+    const out = {};
+    if (n.t)
+        out.type = n.t;
+    if (n.d)
+        out.description = n.d;
+    if (n.e)
+        out.enum = n.e;
+    if (n.c !== undefined)
+        out.const = n.c;
+    if (n.n)
+        out.nullable = true;
+    if (n.r)
+        out.required = n.r;
+    if (n.p)
+        out.properties = Object.fromEntries(Object.entries(n.p).map(([k, v]) => [k, expand(v, depth + 1)]));
+    if (n.i)
+        out.items = expand(n.i, depth + 1);
+    if (n.any)
+        out.anyOf = n.any.map((v) => expand(v, depth + 1));
+    if (n.all)
+        out.allOf = n.all.map((v) => expand(v, depth + 1));
+    return out;
+}
+//# sourceMappingURL=describe.js.map