@thinger-io/cli-core 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog
 
+## [0.5.0] - 2026-10-21
+
+One grammar for every command, noun first:
+`<cli> <noun> [<noun>…] <verb> [<parent ids>…] [<id>] [options]`. Nouns
+nest under their parent (`device property`, `product profile api`), verbs
+come from a closed set, ids are positional and named after their noun,
+and the options keep one meaning everywhere. Some commands of 0.4 change
+form (see the table below); the old forms are gone, not aliased.
+
+The MCP serves eight tools, `resource_describe|list|get|create|update|
+delete|clone|call`, instead of 25: what had a tool of its own (bucket data,
+storage files, device resources, the guides, the profiles, dashboard apps,
+plugin and product API calls) is a type or an action of them, and every
+record is addressed with `ids`, one key per level named as the server's
+REST path names it. The old tool names and the `parent`/`id` arguments are
+gone, not aliased (see the second table below).
+
+### Added
+
+- MCP: eight tools for everything. Each takes a `type` and `ids`
+  (`{"device": "d1", "bucket": "b1"}`); the keys are the server's REST
+  placeholders (`type` for an asset type, `group` for an asset group,
+  `rule` and `instance` for alarms, `resource` for every product profile
+  category), so a body's id field and its `ids` key share a name and
+  `create` and `clone` need no mapping. Records answered by `list`, `get`
+  and `create` carry their `ids`, ready to pass back. A call with an
+  unknown argument is refused listing the ones the tool takes, and points
+  a misplaced key to `ids`, `filter` or `body` (an id in an action's body
+  too: `{"device": …}` goes in `ids`). An action that refuses its input
+  shows one of its examples.
+
+
+- The core's types and actions, served by the same tools: `bucket_data`
+  (list reads, create writes), `storage_file` (`ids.file` is the path;
+  `body.local` uploads files and folders of this machine), `device_resource`
+  (list, and its `call` action), `doc` (the guides), `profile`; actions
+  `device.send`, `device.overview`, `product_profile_api.call`,
+  `plugin.call` and `dashboard.init|dev|publish`. A CLI adds its own the
+  same way (`resourceTypes`, `resourceActions`).
+- `resource_describe`: without a type, the catalog with each type's ids and
+  ready-to-send examples; with one, its ids, actions, the permission each
+  verb needs, its schemas and examples (the tests check every example
+  against the tools). A `describe` resource hook adds to it, and hooks
+  get `ids` and `merge` (an update that patches) in their context.
+- Actions that change a lot at once answer a plan and run with
+  `confirm: true`: `replace_all` of the product profile categories (a diff
+  of what it adds, changes and removes), a host's `update_settings` (a diff
+  of the settings) and `restart`, `plugin.remove|kill`, alarm rules'
+  `test_notification`, and `dashboard.publish` with `prune`. MCP clients
+  that support elicitation are asked instead. The CLI asks unless `-y`.
+- `mcp --read-only` (or `<PREFIX>_MCP_READ_ONLY=1`): only describe, list,
+  get and the read-only actions are served.
+- Tool annotations (read-only, destructive, idempotent) on the eight tools.
+- `doc list` and `doc get <doc>`: the guides from the command line.
+- `api <path>`: any request to the profile's server, as `gh api` does for
+  GitHub. `{user}` stands for the account (`--user` for another), `-X`
+  picks the method (GET, or POST with a body), `--from <file|->` and
+  `-s key=value` (dots nest) build the body, `-q key=value` the query, and
+  `-o <file>` saves the answer (binary answers are only written to a file
+  or a pipe). Only paths of the profile's server: a full URL is refused.
+- Commands for every resource type, generated from the MCP catalog:
+  `list|get|create|update|delete|clone|describe` and the type's actions,
+  for its 47 types. A child type nests under its parent's command and takes
+  its ids first (`device bucket tag get <device> <bucket> <tag>`); the
+  product profile categories go under `product profile` (`api`, `bucket`,
+  `property`, `autoprovision`, `flow`, `code`), alarms under `alarm`
+  (`alarm rule`, `alarm instance`) and assets under `asset` (`asset type`,
+  `asset group`); server types go under
+  `admin` (`admin host restart <host>`). They run the handlers of the
+  `resource_*` tools, hooks included (generated device credentials, token
+  expiries such as "30d"). Bodies come from `--from <file|->` and
+  `-s key=value` (JSON values, dots nest); create, update and clone take
+  `-n/--name` and `-d/--description` on the types that have them, `update
+  --merge` patches, `--projects` sets the projects; `list` takes
+  `--search`, `--filter`, `--count` and `--index` and returns every record
+  unless `--count`; `get` takes `-f <dot.path>` (one field) and
+  `-o <file>`; actions take `-f`, `-o` and `-q`; `delete`,
+  `replace-all`, `plugin uninstall` and `admin host restart` ask unless
+  `-y`. With `-j` they print `{ ok, data }`. What they print speaks of
+  commands, not tools: types by their command (`device property`, not
+  `device_property`), `--index` for the next page, and `describe` lists
+  the type's commands and actions where the MCP lists the tools that run
+  them, its ids as the command takes them, the create, update and clone
+  bodies as tables of fields (nested ones by their dot path, one table per
+  alternative) with their examples pretty-printed, and the permission each
+  verb needs (`-j` keeps the MCP's text).
+- `set <parents…> <property> <value>` on every property type (device,
+  product, plugin, asset type, asset group, project and account
+  properties): the value, parsed as JSON, created when missing.
+- Commands over the MCP tools that are not CRUD: `bucket write` (a JSON
+  sample, an array or NDJSON), `bucket export` (create the export, wait for
+  it, download it, delete it from the server unless `--keep`), `storage
+  file list|upload|download|delete` (folders and binary files), `device
+  send` (data of an HTTP device), `device overview`, `device resource
+  list|call`, `product profile api call` (a product API resource for the
+  whole product), `product apply --from <file|->` (create or update a
+  product from the JSON of `product export`: record, each profile
+  category, services and product properties) and `plugin call`.
+- `device list`, `product list` and `bucket list` take the list options
+  too, keeping their tables; `device create` and `product create` take
+  `--from`, `-s` and `--projects`, and their id may come from the body
+  (when the record is created but its projects cannot be set, the error
+  says so).
+- `buildProgram(opts)`: the command tree `runCli` runs, for tests; and
+  `checkGrammar(program, { exceptions })` (`commands/grammar`), which checks
+  a tree against the grammar (names, verbs, positionals, options, help
+  groups, the catalog's commands) for the tests of every CLI.
+- `runCli({ argumentHelp })`: help of the positional arguments of the CLI's
+  own commands. Every positional argument has a description in the help.
+- The help groups commands the same way at every level: Resources,
+  Administration, Configuration, Integration and Operations at the root;
+  Records, Data, Actions and Subresources inside a noun.
+- MCP tool results carry their structured data for these commands (under
+  a symbol: MCP clients see the same text as before).
+
+### Changed (breaking)
+
+| 0.4                                          | 0.5                                                          |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| `device list <pattern>`                      | `device list --search <text>` (or `--filter name=<regex>`)   |
+| `device info <device>`                       | `device get <device>`                                        |
+| `device property <device>`                   | `device property list <device>`                              |
+| `device property <device> <property> [-f p]` | `device property get <device> <property> [-f p]`             |
+| `device property-set <device> <prop> <json>` | `device property set <device> <property> <json>`             |
+| `device resource <device>`                   | `device resource list <device>`                              |
+| `device resource <device> <res> -i k=v`      | `device resource call <device> <resource> -s k=v` (`--from`) |
+| `product info <product>`                     | `product get <product>`                                      |
+| `product property-list <product>`            | `product property list <product>`                            |
+| `product property-get <product> <prop>`      | `product property get <product> <property>`                  |
+| `product property-set <product> <prop> <v>`  | `product property set <product> <property> <value>`          |
+| `product property-delete <product> <prop>`   | `product property delete <product> <property> -y`            |
+
+- The outputs change with the commands: `device get` and `product get`
+  print the record as JSON (as `info` did); `device property get` and
+  `product property get` print the property record, with its value under
+  `value`, so `-f` paths start there (`-f value.setpoint` where 0.4 took
+  `-f setpoint`); `device property list` and
+  `product property list` print the property records (with `-j`, the
+  records instead of `{ product, properties: [names] }`); `product property
+  delete` asks unless `-y`. `device resource call` has no `-i/--input`: its
+  input comes from `--from` and `-s`, like every command that sends data.
+- `register(program, groups)`'s groups are Resources at the root (they were
+  Operations), and `registerToolCommands(program)` is now
+  `registerDataCommands(program)` (`commands/data`) and no longer takes
+  them.
+- The MCP tools (the CLI commands keep their forms and `-j` outputs; only
+  the help of some positionals is renamed: `asset type get <type>`,
+  `asset group get <group>`, `alarm rule get <rule>`, `alarm instance get
+  <instance>`, `product profile <category> get <product> <resource>`):
+
+| 0.4 tool                                 | 0.5 call                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------ |
+| `resource_* parent "d1" id "b1"`          | `resource_* ids {"device": "d1", "bucket": "b1"}`                              |
+| `bucket_data_read bucket`                | `resource_list type "bucket_data" ids {bucket}` (`filter` for the query)       |
+| `bucket_data_write bucket data`          | `resource_create type "bucket_data" ids {bucket} body <sample or samples>`     |
+| `storage_file_list storage path`         | `resource_list type "storage_file" ids {storage} filter {path}`                |
+| `storage_file_read storage path`         | `resource_get type "storage_file" ids {storage, file}`                         |
+| `storage_file_write storage path …`      | `resource_create type "storage_file" ids {storage, file} body {content\|local}` |
+| `storage_file_delete storage path`       | `resource_delete type "storage_file" ids {storage, file}`                      |
+| `device_resource_list device`            | `resource_list type "device_resource" ids {device}`                            |
+| `device_resource_call device resource`   | `resource_call type "device_resource" action "call" ids {device, resource}`    |
+| `device_data_send device data`           | `resource_call type "device" action "send" ids {device} body <data>`           |
+| `device_overview`                        | `resource_call type "device" action "overview"`                                |
+| `product_resource_call product resource` | `resource_call type "product_profile_api" action "call" ids {product, resource}` |
+| `plugin_call plugin path`                | `resource_call type "plugin" action "call" ids {plugin} body {path, method}`   |
+| `doc_read id`                            | `resource_get type "doc" ids {doc}` (`resource_list type "doc"` lists them)    |
+| `profile_list`                           | `resource_list type "profile"`                                                 |
+| `dashboard_init` / `_dev` / `_publish`   | `resource_call type "dashboard" action "init"` / `"dev"` / `"publish"`         |
+
+- `runCli({ mcpTools })` is gone, with `mcp/registry`'s `genericTools` and
+  `mcpTools`: a CLI adds types and actions (`resourceTypes`,
+  `resourceActions`) instead of tools, and `buildTools(opts)` builds the
+  eight. Texts refer to operations as `{op:<type>.<verb|action>}`.
+- `lib/mcp/tools-*.js` moved to `lib/mcp/types/` (as types and actions) and
+  `lib/commands/tools.js` to `lib/commands/data.js`.
+
+### Fixed
+
+- Account tokens created with an expiry as a duration ("30d") through
+  `resource_create` (and `createToken`) got it in seconds: the server takes
+  unix milliseconds and refused it. A timestamp too small to be
+  milliseconds is still read as seconds. Device tokens keep seconds.
+- Ids `.` and `..` are refused (`resource_*` tools too): the URL resolved
+  them to the parent, so deleting the property `..` of a device reached
+  the device.
+- The storage helpers (storage files, thinr's product scripts)
+  escape each segment of a file path and refuse empty, `.` and `..`
+  segments: `a#b` reached the file `a`, `..` the storage. The plugin
+  `call` action also refuses `%2e%2e`.
+- Listing a storage folder answered each file's path relative to that
+  folder: it is now the whole path, the one its `ids.file` reads.
+- The help of `bucket read` and `device resource` printed some defaults
+
+  twice ("(default: 10) (default: 10)", "(default: {})").
+
 ## [0.4.2] - 2026-10-17
 
 ### Fixed

package/README.md

@@ -19,7 +19,16 @@ It holds everything that is not specific to a product:
   `profile` (product profiles), `tokens`, `alarms`, `storage`, with every
   account path built in `paths`.
 - **Generic commands** (`cli`, `commands/*`) — login, logout, profile, device,
-  product, bucket, dashboard, mcp.
+  product, bucket, dashboard, mcp; `api` for any request to the server; and,
+  generated from the same catalog the MCP serves, the commands of every
+  resource type (`list`, `get`, `create`, `update`, `delete`, `clone`,
+  `describe`, `set` on properties, and its actions), run by the handlers and
+  hooks of the `resource_*` tools, so a type added to the catalog reaches the
+  CLI and the MCP at once. Commands over the data and files complete them:
+  `bucket write` and `export`, `storage file list|upload|download|delete`,
+  `device send`, `overview` and `resource list|call`, `product apply`,
+  `product profile api call`, `plugin call`, `doc list|get`. A command the
+  CLI registers itself keeps its name. They all follow one grammar (below).
 - **Dashboard apps** (`dashboard`, `dashboard-init`, `dashboard-dev`,
   `dashboard-sdk`) — create an app from a template of
   `@thinger-io/dashboard-sdk`, develop it on its own dev server (a link with
@@ -31,11 +40,12 @@ It holds everything that is not specific to a product:
   here, marking what needs a given server version), the dashboard SDK's
   reference and types (from its package: the project's version, else the
   CLI's), and the CLI's own.
-- **MCP** (`mcp/*`) — the stdio server and 25 generic tools: eight
-  `resource_*` tools over a catalog of the server's resource types, and the
-  operations that are not CRUD (bucket data, device resources, storage
-  files, dashboard development and publishing, the documentation…), plus that
-  documentation as MCP resources.
+- **MCP** (`mcp/*`) — the stdio server and its eight `resource_*` tools
+  over a catalog of the server's resource types, plus the types and actions
+  every CLI serves next to it (bucket data, storage files, device
+  resources, the guides, the profiles, dashboard apps…) and those of the
+  CLI; the guides are MCP resources too. `mcp --read-only` serves only what
+  reads.
 - **OpenAPI** (`openapi`) — the server's own API description, cached per
   server and version, with a bundled copy as fallback.
 
@@ -76,42 +86,83 @@ servers.
   or subcommands inside the generic groups.
 - `onNoCommand(program)` — what to do when called without arguments
   (default: help).
-- `mcpTools` — the CLI's own MCP tools, declared with bare names
-  (`name: 'device_exec'`) and referring to others in descriptions as
-  `{tool:resource_list}` or `{family:storage_file}`. Unknown references fail
-  at startup. A tool flagged `replaces: true` swaps out the generic tool of
-  the same name.
 - `resourceHooks` — the CLI's hooks on catalog types (`{ product: {
-afterDelete } }`), run after the core's: see `mcp/resource-hooks.js`.
+afterDelete } }`), run after the core's: see `mcp/resource-hooks.js`. A
+  `describe` hook adds to what `resource_describe` shows of the type.
 - `resourceTypes` — resource types of the CLI's own platform, served by the
   same `resource_*` tools as the server's: instead of a REST path each has
   functions for the verbs it supports (`list`, `get`, `create`, `update`,
-  `delete`), its `parent` and `id`, a `schema` and `notes` for
-  `resource_describe`, and `actions` for `resource_call` (`on: 'item'`,
-  `'collection'` or `'either'`). The core checks the parent and id, and
-  searches and pages what `list` returns. See `LocalType` in
+  `delete`), its `parent` and `id` (the keys of `ids`), a `schema`, `notes`
+  and `examples` for `resource_describe`, and `actions` for `resource_call`
+  (`on: 'item'`, `'collection'` or `'either'`; `readOnly`, `confirm`,
+  `bodyRequired`). The core checks the ids, the filter and the examples,
+  and searches and pages what `list` returns. See `LocalType` in
   `mcp/tools-resource.js`.
 - `resourceActions` — actions the CLI adds to the server's types
   (`{ device: { reboot: { description, run } } }`), run with
   `resource_call` like the server's. A type or action that clashes with the
-  catalog fails at startup.
-- `mcpInstructions` — server-level guidance sent to MCP clients.
+  catalog or the core fails at startup.
+- `mcpInstructions` — server-level guidance sent to MCP clients. Texts
+  refer to an operation as `{op:<type>.<verb|action>}` (`{op:doc.get}`),
+  checked when the tools are built.
+- `argumentHelp` — `{ byCommand, byName }`: help of the positional
+  arguments of the CLI's own commands (`{ 'device logs': { unit: '…' } }`).
+
+`buildProgram(opts)` builds the same command tree without running it, for
+tests.
+
+## Command grammar
+
+Every CLI on the core reads the same way:
+
+```
+<cli> <noun> [<noun>…] <verb> [<parent ids>…] [<id>] [<extra>] [options]
+```
+
+- **Nouns** are singular, kebab case, nested under their parent:
+  `device property`, `device bucket tag`, `product profile api`, at most
+  three deep; server types go under `admin`. Groups run nothing themselves.
+- **Verbs** form a closed set: for records, `list`, `get`, `create`,
+  `update`, `delete`, `clone`, `describe` and `set` (the value of a
+  property); for data, `read`, `write`, `send`, `export`, `import`,
+  `overview`, `call`, `upload` and `download`; the catalog's actions in
+  kebab case (`test-source`, `replace-all`); and the local `init`, `dev`,
+  `publish`, `login`, `logout`, `use`, `current` and `add`.
+- **Positionals** are ids, outermost parent first, named after their noun:
+  `device property get <device> <property>`.
+- **Options** keep one meaning: `-j --json`, `-o --output`, `-y --yes`,
+  `-s --set`, `-q --query`, `-X --method`, `-f --field`; `-n` and `-d` are
+  name and description on create and update. Bodies come from
+  `--from <file|->` and `-s key=value`; lists take `--search`, `--filter`,
+  `--count` and `--index`; deletes ask unless `-y`.
+
+`checkGrammar(program, { exceptions })` (`commands/grammar`) checks a whole
+tree and returns what breaks it; each CLI's tests run it over its
+`buildProgram`, stating what it adds (`root`, `verbs`), its short options
+with another meaning (`shorts`) and the rules a command does not follow
+(`skip`).
 
 ## MCP tools
 
-Tool names follow `<object>[_<subobject>]_<verb>`, with the verbs list, get,
-describe, create, update, delete, clone, call, read, write, send.
-
-The server's collections are reached through eight generic tools —
-`resource_describe`, `resource_list`, `resource_get`, `resource_create`,
-`resource_update`, `resource_delete`, `resource_clone`, `resource_call`
-(actions that are not CRUD) — that take a `type`
-from the catalog (`lib/mcp/catalog.js`), a `parent` for child types and an
-`id`. The catalog is a reviewed table, never discovered at run time: each
-type has its path, API version, parent, id and the verbs it allows, with the
-server's operationId for each (the tests check them against the bundled
-OpenAPI document). `resource_describe` reads the request schemas and
-examples from the OpenAPI document of the server the profile points at.
+The MCP serves eight tools — `resource_describe`, `resource_list`,
+`resource_get`, `resource_create`, `resource_update`, `resource_delete`,
+`resource_clone`, `resource_call` (actions that are not CRUD) — that take a
+`type` from the catalog (`lib/mcp/catalog.js`), the core's types
+(`lib/mcp/core-types.js`) or the CLI's, and `ids`: one key per level, named
+as the server's REST path names it (`{"device": "d1", "bucket": "b1"}`,
+`{"product": "p1", "resource": "temp"}`, `{"rule": "high_temp"}`). A record
+the tools answer carries its `ids`, ready to pass back. The catalog is a
+reviewed table, never discovered at run time: each type has its path, API
+version, parent, id and the verbs it allows, with the server's operationId
+for each (the tests check them against the bundled OpenAPI document).
+`resource_describe` reads the request schemas and examples from the OpenAPI
+document of the server the profile points at, and shows each type's ids,
+actions, permissions and ready-to-send examples (checked by the tests).
+Actions that change a lot at once (`replace_all`, a host's
+`update_settings`, `dashboard publish` with prune…) answer a plan first and
+run with `confirm: true`; MCP clients that support elicitation are asked
+instead. `mcp --read-only` (or `<PREFIX>_MCP_READ_ONLY=1`) serves only
+describe, list, get and the read-only actions.
 
 To draft catalog entries after an API change:
 

package/lib/bucket-export.js

@@ -0,0 +1,91 @@
+// @ts-check
+import { setTimeout as sleep } from 'node:timers/promises';
+import api from './api.js';
+import { TIMEOUTS } from './constants.js';
+import { apiError, inputError } from './errors.js';
+import { v1 } from './paths.js';
+import { rawApiCall } from './raw-api.js';
+
+/** States of an export record (buckets.cpp). */
+const READY = 1;
+const FAILED = 2;
+
+/**
+ * Export a bucket's data to a file and download it: the server writes the
+ * file in the background and lists it among the bucket's exports when
+ * ready. The export is deleted from the server afterwards unless `keep`.
+ *
+ * @param {{
+ *   bucket: string,
+ *   user?: string | null,
+ *   format?: 'csv' | 'json' | 'arff',
+ *   timestamps?: 'iso' | 'seconds' | 'milliseconds',
+ *   minTs?: number,
+ *   maxTs?: number,
+ *   keep?: boolean,
+ *   pollMs?: number,
+ *   timeoutMs?: number,
+ * }} opts
+ * @returns {Promise<{ file: string, data: Buffer | string }>}
+ */
+export async function exportBucket({
+    bucket,
+    user,
+    format = 'csv',
+    timestamps = 'iso',
+    minTs,
+    maxTs,
+    keep = false,
+    pollMs = 1000,
+    timeoutMs = TIMEOUTS.API_LONG_MS,
+}) {
+    if (!['csv', 'json', 'arff'].includes(format)) throw inputError('format: csv, json or arff');
+    if (!['iso', 'seconds', 'milliseconds'].includes(timestamps)) {
+        throw inputError('timestamps: iso, seconds or milliseconds');
+    }
+    const base = `${v1(user)}/buckets/${encodeURIComponent(bucket)}/exports`;
+    let file;
+    try {
+        const res = await api.post(base, {
+            data_type: format,
+            timestamp_format: timestamps,
+            ...(minTs !== undefined ? { min_ts: minTs } : {}),
+            ...(maxTs !== undefined ? { max_ts: maxTs } : {}),
+        });
+        file = res.data?.file;
+    } catch (e) {
+        throw apiError(e, { notFound: `Bucket not found: ${bucket}` });
+    }
+    if (!file) throw new Error('the server did not name the export file');
+
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        let state;
+        try {
+            const res = await api.get(base);
+            state = (Array.isArray(res.data) ? res.data : []).find((e) => e.file === file)?.state;
+        } catch (e) {
+            throw apiError(e);
+        }
+        if (state === READY) break;
+        if (state === FAILED) throw new Error(`the server could not export ${bucket}`);
+        if (Date.now() > deadline) {
+            throw new Error(
+                `the export ${file} is not ready yet: find it later with bucket export-file list`,
+            );
+        }
+        await sleep(pollMs);
+    }
+
+    const res = await rawApiCall({ path: `${base}/${encodeURIComponent(file)}` });
+    // The bytes as the server wrote them: parsing would round numbers.
+    const data = res.raw;
+    if (!keep) {
+        try {
+            await api.delete(`${base}/${encodeURIComponent(file)}`);
+        } catch {
+            // The data is downloaded: a leftover file on the server is no failure.
+        }
+    }
+    return { file, data };
+}

package/lib/cli.js

@@ -1,7 +1,8 @@
 // @ts-check
 import { Command } from 'commander';
 import { setActiveProfile } from './config.js';
-import { identity } from './identity.js';
+import { env, identity } from './identity.js';
+
 import { classifyError, detectJsonModeFromArgv } from './output.js';
 import { startMCPServer } from './mcp/server.js';
 import { registerAuthCommands } from './commands/auth.js';
@@ -10,66 +11,82 @@ import { registerDeviceCommands } from './commands/device.js';
 import { registerProductCommands } from './commands/product.js';
 import { registerBucketCommands } from './commands/bucket.js';
 import { registerDashboardCommands } from './commands/dashboard.js';
+import { registerApiCommand } from './commands/api.js';
+import { registerResourceCommands } from './commands/resources.js';
+import { registerDataCommands } from './commands/data.js';
+import { describeArguments } from './commands/arguments.js';
+import { NOUN_GROUPS, ROOT_GROUPS } from './commands/grammar.js';
+
+/** Verbs of the records, in the order the help shows them. */
+const RECORD_VERBS = ['list', 'get', 'create', 'update', 'delete', 'clone', 'set', 'describe'];
+
+/**
+ * Sort the commands of `cmd` (and below) by help group, records by verb,
+ * keeping the order they were added in otherwise: the hand-written ones
+ * and the generated ones of a group come together.
+ *
+ * @param {Command} cmd
+ * @param {string[]} groups
+ */
+function orderHelp(cmd, groups) {
+    const rank = (c) => {
+        const i = groups.indexOf(c.helpGroup());
+        // Other verbs of the records (thinr's `logs presets`) go after these.
+        const verb = RECORD_VERBS.indexOf(c.name());
+        const at = c.helpGroup() === 'Records:' ? (verb === -1 ? RECORD_VERBS.length : verb) : 0;
+        return (i === -1 ? groups.length : i) * 100 + at;
+    };
+    // `commands` is typed readonly, but it is a plain array the help reads in order.
+    /** @type {Command[]} */ (cmd.commands).sort((a, b) => rank(a) - rank(b));
+    for (const sub of cmd.commands) orderHelp(sub, NOUN_GROUPS);
+}
+
+/**
+ * @typedef {object} CliOptions
+ * @property {string} version
+ * @property {(program: Command, groups: { device: Command, product: Command, bucket: Command, dashboard: Command }) => void} [register]
+ *   Adds the CLI's own commands, at the top level or inside the generic
+ *   groups.
+ * @property {(program: Command) => Promise<void> | void} [onNoCommand]
+ *   Runs when the CLI is called without arguments (default: print the help).
+ * @property {string} [mcpInstructions]
+ * @property {Record<string, import('./mcp/resource-hooks.js').ResourceHooks>} [resourceHooks]
+ *   The CLI's hooks on the catalog types the generic `resource_*` tools
+ *   (and the generated commands) serve.
+ * @property {Record<string, import('./mcp/tools-resource.js').LocalType>} [resourceTypes]
+ *   Types the CLI adds to that catalog (its platform's own things).
+ * @property {Record<string, Record<string, import('./mcp/tools-resource.js').LocalAction>>} [resourceActions]
+ *   Actions it adds to the catalog's types and its own.
+ * @property {Parameters<typeof import('./docs.js').defineCliDocs>[0]} [docs]
+ *   Guides the CLI ships, served as type `doc` of the resource tools and as
+ *   MCP resources next to the server's documentation.
+ * @property {Parameters<typeof describeArguments>[1]} [argumentHelp]
+ *   Help of the positional arguments of the CLI's own commands.
+ */
 
 /**
- * Build and run a CLI on top of the core: global options, the generic
- * commands (login, logout, profile, device, product, bucket, dashboard) and `mcp`.
- * The identity must be defined before calling it.
+ * The command tree of a CLI on top of the core: global options, the
+ * commands written by hand (login, logout, profile, device, product,
+ * bucket, dashboard, api), the CLI's own (`register`), the commands over
+ * the MCP tools, the generated resource commands and `mcp`. The identity
+ * must be defined before calling it.
  *
- * @param {{
- *   version: string,
- *   argv?: string[],
- *   register?: (program: Command, groups: { device: Command, product: Command, bucket: Command, dashboard: Command }) => void,
- *   onNoCommand?: (program: Command) => Promise<void> | void,
- *   mcpTools?: Array<object>,
- *   mcpInstructions?: string,
- *   resourceHooks?: Record<string, import('./mcp/resource-hooks.js').ResourceHooks>,
- *   resourceTypes?: Record<string, import('./mcp/tools-resource.js').LocalType>,
- *   resourceActions?: Record<string, Record<string, import('./mcp/tools-resource.js').LocalAction>>,
- *   docs?: Parameters<typeof import('./docs.js').defineCliDocs>[0],
- * }} opts
- *   `register` adds the CLI's own commands, at the top level or inside the
- *   generic groups. `onNoCommand` runs when the CLI is called without
- *   arguments (default: print the help). `mcpTools` are the CLI's own MCP
- *   tools (see buildTools), and `resourceHooks` its hooks on the
- *   catalog types the generic `resource_*` tools serve; `resourceTypes` and
- *   `resourceActions` are types and actions it adds to that catalog (its
- *   platform's own things, served by the same tools). `docs` are guides
- *   the CLI ships, served by `doc_read` and as MCP resources next to the
- *   server's documentation.
+ * @param {CliOptions & { strict?: boolean }} opts
+ *   `strict` (tests): a generated group a CLI's command takes the place of
+ *   throws instead of being left out.
  */
-export async function runCli({
+export function buildProgram({
     version,
-    argv = process.argv,
     register,
-    onNoCommand,
-    mcpTools = [],
     mcpInstructions,
     resourceHooks,
     resourceTypes,
     resourceActions,
     docs,
+    argumentHelp,
+    strict = false,
 }) {
     const id = identity();
-
-    // Pick up --profile early so subsequent config reads use the right one.
-    // Commander parses options later, but the config is touched before that.
-    for (let i = 2; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--') break;
-        if (a === '--profile' && argv[i + 1]) {
-            setActiveProfile(argv[i + 1]);
-            break;
-        }
-        if (a.startsWith('--profile=')) {
-            setActiveProfile(a.slice('--profile='.length));
-            break;
-        }
-    }
-
-    // Set JSON mode before any command runs so spinners/logs can opt out.
-    detectJsonModeFromArgv(argv);
-
     const program = new Command();
     program
         .name(id.name)
@@ -86,17 +103,26 @@ export async function runCli({
     };
     registerAuthCommands(program);
     registerProfileCommands(program);
+    registerApiCommand(program);
     register?.(program, groups);
+    // After the CLI's own: a command it registers keeps its name.
+    registerDataCommands(program);
+    registerResourceCommands(program, { hooks: resourceHooks, strict });
+    describeArguments(program, argumentHelp);
 
     program
         .command('mcp')
         .helpGroup('Integration:')
         .description('Start the MCP server (stdio) for AI tool integration')
-        .action(async () => {
+        .option(
+            '--read-only',
+            `Serve only the tools that read: describe, list, get and the read-only actions (or set ${identity().envPrefix}_MCP_READ_ONLY=1)`,
+        )
+        .action(async (opts) => {
             try {
                 await startMCPServer({
                     version,
-                    tools: mcpTools,
+                    readOnly: !!opts.readOnly || /^(1|true|yes)$/i.test(env('MCP_READ_ONLY') ?? ''),
                     instructions: mcpInstructions,
                     resourceHooks,
                     resourceTypes,
@@ -109,6 +135,36 @@ export async function runCli({
             }
         });
 
+    orderHelp(program, ROOT_GROUPS);
+    return program;
+}
+
+/**
+ * Build and run a CLI on top of the core (see buildProgram). The identity
+ * must be defined before calling it.
+ *
+ * @param {CliOptions & { argv?: string[] }} opts
+ */
+export async function runCli({ argv = process.argv, onNoCommand, ...opts }) {
+    // Pick up --profile early so subsequent config reads use the right one.
+    // Commander parses options later, but the config is touched before that.
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') break;
+        if (a === '--profile' && argv[i + 1]) {
+            setActiveProfile(argv[i + 1]);
+            break;
+        }
+        if (a.startsWith('--profile=')) {
+            setActiveProfile(a.slice('--profile='.length));
+            break;
+        }
+    }
+
+    // Set JSON mode before any command runs so spinners/logs can opt out.
+    detectJsonModeFromArgv(argv);
+
+    const program = buildProgram(opts);
     if (argv.length <= 2) {
         if (onNoCommand) await onNoCommand(program);
         else program.help();