@substrio/cli 0.0.0-stage → 0.1.1

package/src/command-table.mjs

@@ -0,0 +1,436 @@
+/**
+ * Substrio CLI: the command table. Every command is one entry here: its names,
+ * the credentials it needs, its usage lines and how it runs. Top-level help,
+ * `substrio COMMAND --help` and dispatch are all generated from this table, and
+ * the registry groups (data, collections, webhooks, ...) come from GROUPS in
+ * commands/groups.mjs, so no command, usage line or operation is written
+ * twice.
+ */
+
+import { EXIT_CODE_HELP, fail } from './cli.mjs';
+import { GROUPS, GROUP_ALIASES, GroupFlow, entryOf, registryGroupsOf, resolveGroup } from './commands/groups.mjs';
+
+const importCmd = (mod) => import(`./commands/${mod}`);
+
+/** What a command needs before it runs. */
+export const Needs = Object.freeze({
+    NOTHING: 'nothing', // no config (init, login)
+    CONFIG: 'config',   // the resolved config, no server
+    URL: 'url',         // a server URL, no key
+    KEY: 'key',         // a server URL and a key
+});
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+// Hand-written commands: flows that are more than one registry operation
+// (build, push, promote with backup, site upload, bundles) or that work on
+// local files and profiles. Anything that is one operation is a group
+// command (below) or `substrio op`.
+const FLOWS = [
+    {
+        names: ['init'], section: 'START', needs: Needs.NOTHING,
+        usage: [['init [--url URL] [--tenant SLUG] [--yes]', 'Scaffold a project (substrio.toml holds no key; the key lives in a profile)']],
+        run: async ({ args }) => (await importCmd('init.mjs')).cmdInit(args),
+    },
+    {
+        names: ['signup'], section: 'START', needs: Needs.NOTHING,
+        usage: [
+            ['signup --url URL --tenant SLUG [--email E] [--code CODE | --password -] [--account NAME] [--save-profile NAME] [--print]',
+                'An outside developer or agent, no master key: the email is proven by a mailed code (without --code it sends one and says the next command), then an account and its first key, saved as a profile like "substrio login" does'],
+        ],
+        run: async ({ args }) => (await importCmd('signup.mjs')).cmdSignup(args),
+    },
+    {
+        names: ['login'], section: 'START', needs: Needs.NOTHING,
+        usage: [
+            ['login [--url URL] --key - [--tenant SLUG] [--profile NAME] [--default]', 'Save a profile; the key from stdin, the tenant found from it, the server https://mcp.substrio.com unless --url names another. Without --profile it is the default; with --profile the default changes only with --default (or when there is none)'],
+            ['login --offline --url URL --tenant SLUG --key - [--profile NAME] [--default]', 'Saves the profile with no round trip (the server need not be up yet); --tenant is required, the profile is marked unchecked until a login without --offline saves it again'],
+            ['login --list | --remove NAME', 'List or remove saved profiles'],
+        ],
+        run: async ({ args }) => (await importCmd('login.mjs')).cmdLogin(args),
+    },
+    {
+        names: ['whoami'], section: 'START', needs: Needs.CONFIG,
+        usage: [['whoami', 'Tenant, server and profile in use, and where each came from']],
+        run: async ({ config }) => (await importCmd('status.mjs')).cmdWhoami(config),
+    },
+    {
+        names: ['status'], section: 'START', needs: Needs.URL,
+        usage: [['status', 'Server health and config']],
+        run: async ({ api, config }) => (await importCmd('status.mjs')).cmdStatus(api, config),
+    },
+    {
+        names: ['open'], section: 'START', needs: Needs.CONFIG,
+        usage: [['open', 'Open the server in a browser']],
+        run: async ({ config }) => (await importCmd('open.mjs')).cmdOpen(config),
+    },
+    {
+        names: ['skills'], section: 'START', needs: Needs.URL,
+        usage: [
+            ['skills list', "The server's agent skills: name, title, description"],
+            ['skills show NAME', "One skill's markdown"],
+            ['skills install [NAME...] [--for claude|cursor|codex|agents-md|all] [--dir DIR]',
+                'Write skills (default: every one) where each client reads its own (default --for all, --dir the project root)'],
+        ],
+        run: async ({ api, args }) => (await importCmd('skills.mjs')).cmdSkills(api, args),
+    },
+    {
+        names: ['key'], section: 'START', needs: (args) => (args[0] === 'export' ? Needs.CONFIG : Needs.KEY),
+        usage: [
+            ['key rotate [--overlap 1h] [--expires-in 90d] [--print]', 'Replace the tenant key; saved to the profile'],
+            ['key list', 'The tenant keys: ids, created, expires, state'],
+            ['key revoke ID', 'End the previous key overlap now'],
+            ['key export --env FILE [--var NAME] [--force]', 'Write NAME=KEY (default SUBSTRIO_KEY) of the key in use to FILE, owner-only, never printed; for an MCP client config'],
+        ],
+        run: async ({ api, config, args }) => (await importCmd('key.mjs')).cmdKey(api, config, args),
+    },
+    {
+        names: ['tenants', 'tenant', 'apps', 'app'], section: 'APPS', needs: Needs.KEY,
+        usage: [
+            ['tenants list | show SLUG', 'Every tenant; one tenant (platform-admin key)'],
+            ['tenants create SLUG [--save-profile N] [--print]', 'Create a tenant; its key is saved to profile N'],
+            ['tenants delete SLUG --yes', 'Delete a tenant and all its data'],
+        ],
+        run: async ({ api, config, args }) => (await importCmd('tenants.mjs')).cmdTenants(api, config, args),
+    },
+    {
+        names: ['pull'], section: 'APPS', needs: Needs.KEY,
+        usage: [['pull (--for PROFILE | --seal-to PUBKEY) [--out FILE]', "Stream the app's bundle, sealed to one server's key"]],
+        run: async ({ config, args }) => (await importCmd('bundle.mjs')).cmdPull(config, args),
+    },
+    {
+        names: ['push-bundle'], section: 'APPS', needs: Needs.NOTHING,
+        usage: [['push-bundle FILE --to PROFILE [--slug S] [--replace]', "Stream a bundle into PROFILE's server as an app"]],
+        run: async ({ args }) => (await importCmd('bundle.mjs')).cmdPushBundle(args),
+    },
+    {
+        names: ['move'], section: 'APPS', needs: Needs.KEY,
+        usage: [
+            ['move --to PROFILE [--slug S] [--replace] [--save-profile NAME]', "Pipe the app, sealed, into PROFILE's server"],
+            ['move --live --to PROFILE', "Move the app to PROFILE's server while it takes writes: copy, follow, fence, drain, flip (both profiles hold their server's master key; a failed drain rolls back)"],
+            ['move --failover --to PROFILE', "PROFILE's server, a replica of the app, takes its writes because this profile's server no longer answers (one that answers is moved live instead)"],
+        ],
+        run: async ({ config, args }) => (await importCmd('bundle.mjs')).cmdMove(config, args),
+    },
+    {
+        names: ['push'], section: 'SHIP', needs: (args) => (args.includes('--dry-run') ? Needs.CONFIG : Needs.KEY),
+        usage: [['push [-m MSG] [--branch NAME] [--no-build] [--dry-run] [--sandbox NAME]', 'Build, upload a new version (functions, rules, collections, site), run it in dev; --branch commits it on that branch of the history instead of main']],
+        run: async ({ api, config, args }) => (await importCmd('push.mjs')).cmdPush(api, config, args),
+    },
+    {
+        names: ['dev'], section: 'SHIP', needs: Needs.NOTHING,
+        usage: [['dev [--attach URL] [--server PATH] [--port N] [--data DIR] [--no-build] [--no-logs] [--prune]', 'The app on a local server with hot reload: a saved function redeploys alone, logs stream. Data and keys stay in .substrio/dev (or --data DIR, made when missing). The server reports its port on a pipe (substrio_server --ready-fd). It saves the profile TENANT-dev (never the default): substrio --dev COMMAND uses it from a second terminal. Reports a server declaration the files no longer name (drift); --prune drops it']],
+        run: async ({ args }) => (await importCmd('dev.mjs')).cmdDev(args),
+    },
+    {
+        names: ['test'], section: 'SHIP', needs: Needs.NOTHING,
+        usage: [['test [FILES...] [--server PATH] [--attach URL] [--no-build] [--filter NAME] [--timeout MS] [--keep]', 'Run the app\'s tests (test/*.test.mjs) on a local server, each test on a tenant of its own']],
+        run: async ({ args }) => (await importCmd('test.mjs')).cmdTest(args),
+    },
+    {
+        names: ['promote'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['promote [N] [--no-backup]', 'Make N live (default: what dev runs); the data is backed up first']],
+        run: async ({ api, args }) => (await importCmd('versions.mjs')).cmdPromote(api, args),
+    },
+    {
+        names: ['rollback'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['rollback [--no-backup]', 'Make the version before live live again']],
+        run: async ({ api, args }) => (await importCmd('versions.mjs')).cmdRollback(api, args),
+    },
+    {
+        names: ['restore'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['restore [BACKUP_ID] [--yes] [--wait S]', "Put the data back from a promote's backup"]],
+        run: async ({ api, args }) => (await importCmd('versions.mjs')).cmdRestore(api, args),
+    },
+    {
+        names: ['versions', 'version'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['versions', 'List versions: which is live, what each sandbox runs, each backup']],
+        run: async ({ api, args }) => (await importCmd('versions.mjs')).cmdVersions(api, args),
+    },
+    {
+        names: ['diff'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['diff [A] [B]', 'What changed (default: live to dev)']],
+        run: async ({ api, args }) => (await importCmd('versions.mjs')).cmdDiff(api, args),
+    },
+    // VERSIONING: the app's own history in the words a developer who knows git
+    // already types. Each is one call to one operation (commands/history.mjs).
+    {
+        names: ['branch', 'branches'], section: 'HISTORY', needs: Needs.KEY,
+        usage: [
+            ['branch', 'The app\'s branches: the version each points at, when it last moved, whether it is protected (branch.list)'],
+            ['branch create NAME [--from REF]', 'Make a branch at REF (a branch name or a version id; default: the main branch\'s head)'],
+            ['branch delete NAME [--yes]', 'Free a branch\'s name; its versions and its log are kept (substrio ref restore branch NAME puts it back)'],
+            ['branch protect NAME [--off] [--checks A,B]', 'A commit or merge onto NAME needs those checks green; --off unprotects it'],
+        ],
+        run: async ({ api, args }) => (await importCmd('history.mjs')).cmdBranch(api, args),
+    },
+    {
+        names: ['log'], section: 'HISTORY', needs: Needs.KEY,
+        usage: [['log [PATH] [--branch NAME] [--limit N]', 'The commits of a branch, newest first; with PATH, only the commits that changed that one unit (version.log). Function logs are substrio logs']],
+        run: async ({ api, args }) => (await importCmd('history.mjs')).cmdLog(api, args),
+    },
+    {
+        names: ['tag', 'tags'], section: 'HISTORY', needs: Needs.KEY,
+        usage: [
+            ['tag', 'The app\'s tags: the version each marks (tag.list)'],
+            ['tag NAME [VERSION] [--branch NAME]', 'Mark a version with a name that never moves again (default: the head of main, or of --branch)'],
+        ],
+        run: async ({ api, args }) => (await importCmd('history.mjs')).cmdTag(api, args),
+    },
+    {
+        names: ['merge'], section: 'HISTORY', needs: Needs.KEY,
+        usage: [
+            ['merge FROM [--into NAME]', 'Work out the merge of FROM into a branch (default: main) and keep it as that branch\'s draft; publishes nothing (merge.plan)'],
+            ['merge status [--into NAME]', 'The merge in hand: both sides, every unit it touched and what is still conflicted (merge.get)'],
+            ['merge resolve PATH (--file F | --text T | -) [--into NAME]', 'Settle one conflicted unit with these bytes (merge.resolve)'],
+            ['merge commit [-m MSG] [--into NAME] [--checks-green]', 'Publish the merge as one commit on the branch (merge.commit)'],
+            ['merge abort [--into NAME] [--yes]', 'Throw the merge in hand away; the branch never moved (merge.abort)'],
+        ],
+        run: async ({ api, args }) => (await importCmd('history.mjs')).cmdMerge(api, args),
+    },
+    {
+        names: ['gc'], section: 'HISTORY', needs: Needs.KEY,
+        usage: [
+            ['gc [--yes]', 'Erase every object of the app\'s history no branch, tag, environment, ref log or merge reaches (version.gc)'],
+            ['gc --dry-run | --status', 'What a collection would take, erasing nothing; or where the last one got to (version.gc.status)'],
+        ],
+        run: async ({ api, args }) => (await importCmd('history.mjs')).cmdGc(api, args),
+    },
+    {
+        names: ['git'], section: 'HISTORY', needs: Needs.CONFIG,
+        usage: [
+            ['git export DIR [--data DIR] [--server PATH] [--owner ID]', "The app's whole history as commits in a git repository (made when DIR is empty). Not an HTTP call: it opens the app's database file, so --data names it and the app has to be on this machine"],
+            ['git import DIR [--data DIR] [--server PATH] [--author ID]', "A git repository's commits as the app's history (git fast-export piped into the server)"],
+        ],
+        run: async ({ config, args }) => (await importCmd('git.mjs')).cmdGit(config, args),
+    },
+    {
+        names: ['deploy'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['deploy [NAME...] [--dry-run] [--prune]', "Make the declared collections (collections/NAME.json: schema, rules, indexes, expire, aggregates), deploy functions (routes, vars from substrio.toml) and set the rules. Reports a server declaration the files no longer name (drift); --prune drops it. With one or more NAME, only those functions are built and replaced: nothing else is read or sent (--prune, --functions and --assets are refused with names)"]],
+        run: async ({ api, config, args }) => (await importCmd('deploy.mjs')).cmdDeploy(api, config, args),
+    },
+    {
+        names: ['site'], section: 'SHIP', needs: Needs.KEY,
+        usage: [
+            ['site deploy DIR', 'Publish a website as a release (uploads only changes)'],
+            ['site releases | activate RELEASE_ID', 'List releases; serve an earlier one'],
+        ],
+        run: async ({ api, config, args }) => (await importCmd('site.mjs')).cmdSite(api, config, args),
+    },
+    {
+        names: ['env'], section: 'SHIP', needs: Needs.KEY,
+        usage: [['env pull | push', 'Sync secrets with a .env file']],
+        run: async ({ api, args }) => (await importCmd('env.mjs')).cmdEnv(api, args),
+    },
+    {
+        names: ['files', 'file'], section: 'SHIP', needs: Needs.KEY,
+        usage: [
+            ['files ls [PATH] | upload LOCAL [REMOTE] | rm PATH', 'Static files'],
+            ['files sync LOCAL_DIR PREFIX [--concurrency N]', 'Upload every file of a folder the store lacks or holds at another size, N at a time'],
+        ],
+        run: async ({ api, args }) => (await importCmd('files.mjs')).cmdFiles(api, args),
+    },
+    {
+        // "log" is the app's own history (version.log), as git spells it; the
+        // function logs keep the plural they always had.
+        names: ['logs'], section: 'SHIP', needs: Needs.KEY,
+        usage: [
+            ['logs [--limit N] [--since D|T] [--until D|T] [--function NAME] [--request-id ID] [--level LEVEL]',
+                'Cloud function logs; D is a duration ago (30s, 5m, 1h) or T a Unix-second/ISO timestamp'],
+            ['logs --follow (--for D | --lines N | --until-match TEXT)',
+                'Tails them live over a WebSocket until the given stop is met (ends exit 0); required with no terminal or under --json; on a terminal with none given, Ctrl+C stops it'],
+        ],
+        run: async ({ api, args }) => (await importCmd('logs.mjs')).cmdLogs(api, args),
+    },
+    {
+        names: ['op', 'call'], section: 'ANY OPERATION', needs: Needs.KEY,
+        usage: [
+            ['op list [FILTER]', 'Every operation of the server: name, route, summary'],
+            ['op NAME --help', 'Its routes and input schema (read from the server)'],
+            ["op NAME [key=value ...] [--data '{...}' | --file F]", 'Call it; prints JSON'],
+        ],
+        help: async ({ api, args }) => {
+            if (!args[0] || args[0] === 'list' || args[0] === 'ls') return false;
+            await (await importCmd('op.mjs')).showOperationHelp(api, args[0]);
+            return true;
+        },
+        run: async ({ api, args }) => (await importCmd('op.mjs')).cmdOp(api, args),
+    },
+    // Aliases onto one operation each.
+    operationAlias(['invoke'], 'function.invoke', 'invoke NAME [key=value ...] [--data \'{...}\']', 'Call a cloud function; --data or key=value is its JSON event (none: {})', [], { body: 'event', emptyBody: {} }),
+    operationAlias(['undo'], 'undo', 'undo TOKEN', 'Undo a change by its undo_token (null means nothing to undo); prints the token that redoes it', ['token']),
+];
+
+// A top-level command that is one registry operation: bare words fill the
+// route's path parameters, or `fields` when given. A field given neither as a
+// bare word, key=value nor --data/--file prints the usage and runs nothing.
+// `body` names the input field that is the whole body (as for data insert): --data, --file and key=value make that
+// field's value; `emptyBody` is what it is when none is given (an operation whose body may be empty).
+function operationAlias(names, operation, syntax, summary, fields = [], { body = null, emptyBody = null } = {}) {
+    return {
+        names, section: 'ANY OPERATION', needs: Needs.KEY, operation,
+        usage: [[syntax, `${summary} (${operation}; substrio op ${operation} --help for its input)`]],
+        run: async ({ api, args }) => {
+            const { parseOpArgs, splitPositional } = await import('./ops.mjs');
+            const { positional, rest } = splitPositional(args);
+            const whole = rest.some((a) => a === '--data' || a === '--file');
+            const missing = fields.slice(positional.length)
+                .filter((field) => !rest.some((a) => a.startsWith(`${field}=`)));
+            if (missing.length && !whole) {
+                fail(`Usage: substrio ${names[0]} ${fields.map((f) => `<${f}>`).join(' ')}`, `substrio ${names[0]} --help for more`);
+            }
+            const named = fields.slice(0, positional.length).map((field, i) => `${field}==${positional[i]}`);
+            const given = [...named, ...rest];
+            // Arguments that do not parse are runOperation's own error to report.
+            const noInput = body !== null && emptyBody !== null && (() => { try { return parseOpArgs(given).input === undefined; } catch { return false; } })();
+            return (await importCmd('op.mjs')).runOperation(api, operation, noInput ? [...given, '--data', JSON.stringify(emptyBody)] : given, {
+                positional: positional.slice(fields.length), body,
+            });
+        },
+    };
+}
+
+// The registry groups a command runs, as help shows them: "kv.*, ai.*".
+const registryText = (command) => registryGroupsOf(command).map((g) => `${g}.*`).join(', ');
+
+// The usage line for running a command's registry operations by their words.
+const registryUsage = (command) => [`${command} WORD ... [ARG ...] [key=value ...]`, `any ${registryText(command)} operation by its words (${registryGroupsOf(command)[0]}.a.b: ${command} a b)`];
+
+// What a flow of a group needs, when it is not a call to the server (the others need a URL and a key).
+const FLOW_NEEDS = Object.freeze({ [GroupFlow.MCP_CONFIG]: Needs.URL });
+
+// What the words of a group command need: a flow's own, else a server URL and a key.
+function groupNeeds(group, args) {
+    let flow = null;
+    try {
+        ({ flow } = resolveGroup(group, args));
+    } catch {
+        // Unknown words are the command's to report, once it runs.
+    }
+    return FLOW_NEEDS[flow] ?? Needs.KEY;
+}
+
+// One entry per registry group, generated from GROUPS.
+function groupCommand(group) {
+    const table = GROUPS[group];
+    const aliases = Object.entries(GROUP_ALIASES).filter(([, g]) => g === group).map(([a]) => a);
+    const operations = [...new Set(Object.values(table).map((e) => entryOf(e).operation))];
+    const subs = Object.keys(table);
+    return {
+        names: [group, ...aliases], section: 'REGISTRY GROUPS', needs: (args) => groupNeeds(group, args), group,
+        usage: [
+            ...Object.entries(table).map(([sub, e]) => {
+                const { operation, trailing, note } = entryOf(e);
+                return [`${group} ${sub}${trailing.map((t) => ` ${t.toUpperCase()}`).join('')} [ARG ...] [key=value ...]`, note ?? operation];
+            }),
+            ...(registryGroupsOf(group).length ? [registryUsage(group)] : []),
+        ],
+        summary: [`${group} ${subs.length ? subs.join('|') : 'WORD ...'}`, registryText(group) || operations.join(', ')],
+        help: async ({ api, args }) => {
+            if (!args[0]) return false;
+            let { operation, flow } = resolveGroup(group, args);  // throws on an unknown subcommand
+            if (flow !== null && !operation) return false;  // a word of the CLI's own: its usage line is its help
+            if (!operation) ({ operation } = await (await importCmd('groups-runtime.mjs')).findRegistryOperation(api, group, args));
+            await (await importCmd('op.mjs')).showOperationHelp(api, operation);
+            return true;
+        },
+        run: async ({ api, config, args, command }) => (await importCmd('groups-runtime.mjs')).cmdGroup(api, command, args, { config }),
+    };
+}
+
+// A flow that also runs registry groups (tenants: tenant.*, app.*) says so
+// in its usage; its words run them when they are not its own.
+for (const flow of FLOWS) {
+    if (registryGroupsOf(flow.names[0]).length && !flow.operation) flow.usage.push(registryUsage(flow.names[0]));
+}
+
+/** Every command, flows first, then the registry groups. */
+export const COMMANDS = [...FLOWS, ...Object.keys(GROUPS).map(groupCommand)];
+
+/** The entry for a command name, or null. */
+export function findCommand(name) {
+    return COMMANDS.find((c) => c.names.includes(name)) ?? null;
+}
+
+/** What `entry` needs for these arguments. */
+export function needsOf(entry, args) {
+    return typeof entry.needs === 'function' ? entry.needs(args) : entry.needs;
+}
+
+const GLOBAL_FLAGS = [
+    ['--help, -h', 'Usage of any command; nothing runs'],
+    ['--json', 'Results as JSON on stdout; an error as JSON on stderr'],
+    ['--yes, -y', 'Confirm a destructive command'],
+    ['--profile NAME', 'Use a saved profile (SUBSTRIO_PROFILE)'],
+    ['--tenant SLUG', 'Use this tenant (SUBSTRIO_TENANT)'],
+    ['--dev', 'Use the dev server of "substrio dev" in this directory (its profile TENANT-dev)'],
+    ['--', 'End of options: the rest are arguments, even when they start with - (substrio undo -- -abc)'],
+];
+
+function rows(lines, width) {
+    return lines.map(([syntax, text]) => `  ${C.green}${`substrio ${syntax}`.padEnd(width)}${C.reset}  ${C.dim}${text}${C.reset}`).join('\n');
+}
+
+/**
+ * Every GROUPS command word that destroys data or cannot be undone
+ * (entryOf's own destructive, so a new one is listed the moment it is
+ * marked); needs --yes, or a prompt on a terminal. tenants delete and
+ * restore are their own flows, not from this table, documented in their own
+ * usage line above (both already show --yes).
+ */
+function destructiveRows() {
+    const rows = [];
+    for (const [command, table] of Object.entries(GROUPS)) {
+        for (const sub of Object.keys(table)) {
+            const { destructive, operation } = entryOf(table[sub], sub);
+            if (destructive) rows.push([`${command} ${sub}`, operation]);
+        }
+    }
+    return rows;
+}
+
+/** The top-level help text. */
+export function topHelp(version) {
+    const sections = new Map();
+    const add = (section, lines) => {
+        if (!sections.has(section)) sections.set(section, []);
+        sections.get(section).push(...lines);
+    };
+    for (const c of COMMANDS) add(c.section, c.summary ? [c.summary] : c.usage);
+    // Every registry group under a named command, flows and aliases too.
+    for (const c of FLOWS) {
+        if (registryGroupsOf(c.names[0]).length) add('REGISTRY GROUPS', [[`${c.names[0]} ...`, registryText(c.names[0])]]);
+    }
+    const out = [`\n${C.bold}${C.cyan}Substrio CLI${C.reset} ${C.dim}v${version}${C.reset}\n`, `${C.bold}USAGE${C.reset}\n  substrio <command> [options]   substrio <command> --help\n`];
+    for (const [section, lines] of sections) out.push(`${C.bold}${section}${C.reset}\n${rows(lines, 58)}\n`);
+    out.push(`${C.bold}GLOBAL FLAGS${C.reset}\n${GLOBAL_FLAGS.map(([f, t]) => `  ${f.padEnd(20)}${C.dim}${t}${C.reset}`).join('\n')}\n`);
+    out.push(`${C.bold}EXIT CODES${C.reset}\n${EXIT_CODE_HELP.map(([n, t]) => `  ${String(n).padEnd(20)}${C.dim}${t}${C.reset}`).join('\n')}\n`);
+    out.push(`${C.bold}DESTRUCTIVE${C.reset} (need --yes, or a prompt on a terminal)\n` +
+        `${rows(destructiveRows(), 28)}\n  ${C.green}substrio tenants delete, substrio restore${C.reset}  ${C.dim}(their own usage above)${C.reset}\n`);
+    out.push(`${C.bold}CONFIGURATION${C.reset}
+  ~/.substrio/config.toml  Saved profiles (url, key, tenant), from "substrio login"; owner-only
+  substrio.toml        Project config (profile, tenant, functions_dir, [auth]); never a key
+  SUBSTRIO_URL, SUBSTRIO_TENANT, SUBSTRIO_MASTER_KEY, SUBSTRIO_PROFILE  Environment overrides
+
+${C.bold}EXAMPLES${C.reset}
+  substrio login --url http://localhost:9000 --tenant demo --profile local --key - < key.txt
+  substrio init --yes
+  substrio deploy
+  substrio invoke hello --data '{"name": "world"}'
+  substrio data query users where.age:='{"$gt":30}' limit=10
+`);
+    return out.join('\n');
+}
+
+/** One command's help text. */
+export function commandHelp(entry) {
+    const lines = [`\n${C.bold}substrio ${entry.names[0]}${C.reset}${entry.names.length > 1 ? ` ${C.dim}(also ${entry.names.slice(1).join(', ')})${C.reset}` : ''}\n`];
+    lines.push(rows(entry.usage, 58));
+    if (entry.group || entry.names[0] === 'op') {
+        lines.push(`\n  ${C.dim}substrio ${entry.names[0]} ${entry.group ? 'SUB' : 'NAME'} --help shows the operation's routes and input schema.${C.reset}`);
+    }
+    lines.push(`\n${C.bold}Global flags${C.reset}\n${GLOBAL_FLAGS.map(([f, t]) => `  ${f.padEnd(20)}${C.dim}${t}${C.reset}`).join('\n')}\n`);
+    return lines.join('\n');
+}