@substrio/cli 0.0.0-stage → 0.1.1

package/src/commands/logs.mjs

@@ -0,0 +1,285 @@
+/**
+ * Substrio CLI: `substrio logs` command
+ *
+ * View and follow Cloud Function logs.
+ *   substrio logs                       : Show recent logs
+ *   --limit N, --since D|T, --until D|T : Bound the page (function.logs: Unix seconds; D is a duration ago, e.g. 1h)
+ *   substrio logs --follow              : Tail them live (WebSocket, function.logs.stream); --tail and -f are the same
+ *   --follow --for D | --lines N | --until-match TEXT : A follow that ends on its own (required with no terminal or under --json)
+ *   --function NAME (or --fn)       : Filter by function name
+ *   --request-id ID, --level LEVEL  : Filter by call, by level
+ */
+
+import { CliError, ErrorCode, emitLine, fail, globals } from '../cli.mjs';
+import { runOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m', magenta: '\x1b[95m',
+};
+
+// The close code the server ends a socket with when the reader fell behind
+// past its backlog bound (substrio_ws_send.h WsCloseCode::BACKLOG_LIMIT).
+export const BACKLOG_LIMIT_CLOSE = 4290;
+
+// The close code of a normal, intentional close (RFC 6455): the server ending
+// the stream itself, not an error.
+export const NORMAL_CLOSE = 1000;
+
+// The value after the first of `names` in args, or null.
+function flagValue(args, names) {
+    const at = args.findIndex((a) => names.includes(a));
+    return at >= 0 ? args[at + 1] ?? null : null;
+}
+
+// An integer with an optional unit (ms, s, m, h; s is the default), in ms.
+const DURATION_RE = /^(\d+)(ms|s|m|h)?$/;
+const DURATION_SCALE = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+
+export function parseDuration(text) {
+    const m = DURATION_RE.exec(text);
+    if (!m) throw new CliError(`"${text}" is not a duration (an integer with ms, s, m or h, e.g. 30s)`, { code: ErrorCode.INVALID_ARGUMENT });
+    return Number(m[1]) * DURATION_SCALE[m[2] || 's'];
+}
+
+// --since/--until: a duration (how long ago, from now; needs a unit, e.g.
+// 30s/5m/1h) or a Unix-second/ISO timestamp, resolved to the Unix seconds
+// function.logs' since/until take. A bare integer is a timestamp, not a
+// unitless duration, so it round-trips (substrio logs --until $(date +%s)).
+function resolveTimeFlag(text) {
+    const m = DURATION_RE.exec(text);
+    if (m && m[2]) return Math.floor((Date.now() - Number(m[1]) * DURATION_SCALE[m[2]]) / 1000);
+    if (m) return Number(text);
+    const parsed = Date.parse(text);
+    if (Number.isNaN(parsed)) throw new CliError(`"${text}" is not a duration or a timestamp`, { code: ErrorCode.INVALID_ARGUMENT });
+    return Math.floor(parsed / 1000);
+}
+
+// function.logs's own query options (`function`, `request_id`, `level`,
+// `limit`, `since`, `until`), never a spelling of the CLI's (the server
+// refuses an option it does not declare).
+export function logFilter(args) {
+    const filter = {};
+    const fn = flagValue(args, ['--fn', '--function']);
+    const requestId = flagValue(args, ['--request-id']);
+    const level = flagValue(args, ['--level']);
+    const limit = flagValue(args, ['--limit']);
+    const since = flagValue(args, ['--since']);
+    const until = flagValue(args, ['--until']);
+    if (fn) filter.function = fn;
+    if (requestId) filter.request_id = requestId;
+    if (level) filter.level = level;
+    if (limit !== null) {
+        const n = Number(limit);
+        if (!Number.isInteger(n) || n <= 0) throw new CliError(`--limit wants a positive integer, got "${limit}"`, { code: ErrorCode.INVALID_ARGUMENT });
+        filter.limit = n;
+    }
+    if (since !== null) filter.since = resolveTimeFlag(since);
+    if (until !== null) filter.until = resolveTimeFlag(until);
+    return filter;
+}
+
+// --follow's own end: --for DURATION, --lines N, --until-match TEXT (any
+// combination; the first met wins). null when none was given.
+export function followBound(args) {
+    const forText = flagValue(args, ['--for']);
+    const linesText = flagValue(args, ['--lines']);
+    const match = flagValue(args, ['--until-match']);
+    if (forText === null && linesText === null && match === null) return null;
+    const bound = {};
+    if (forText !== null) bound.forMs = parseDuration(forText);
+    if (linesText !== null) {
+        const n = Number(linesText);
+        if (!Number.isInteger(n) || n <= 0) throw new CliError(`--lines wants a positive integer, got "${linesText}"`, { code: ErrorCode.INVALID_ARGUMENT });
+        bound.lines = n;
+    }
+    if (match !== null) bound.match = match;
+    return bound;
+}
+
+/**
+ * One frame of the tail socket applied to its state (pure): `state.cursor` is
+ * where a reconnect resumes. Returns the entries to print. `connected` sets
+ * the cursor when none is held; `logs` and `lagged` move it to the frame's (on
+ * `lagged` the server keeps going from that cursor itself).
+ */
+export function applyTailFrame(state, frame) {
+    if (frame.type === 'connected') {
+        if (state.cursor === null) state.cursor = frame.cursor;
+        return [];
+    }
+    if (typeof frame.cursor === 'string') state.cursor = frame.cursor;
+    return frame.type === 'logs' && Array.isArray(frame.logs) ? frame.logs : [];
+}
+
+/** The socket URL of the tail with its filters and resume cursor (pure). */
+export function tailUrl(base, filter, cursor) {
+    const url = new URL('/v1/_logs/ws', base);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    for (const [key, value] of Object.entries(filter)) url.searchParams.set(key, value);
+    if (cursor) url.searchParams.set('cursor', cursor);
+    return url.toString();
+}
+
+// A self-initiated close (our own abort, not the server's) waits this long for
+// the peer's close frame before the socket is treated as ended anyway: our own
+// decision to stop must not depend on an unresponsive or slow-to-ack peer, or
+// the WebSocket's 'close' event (which Node never fires without that frame)
+// leaves this promise, and the whole follow, pending forever.
+const CLOSE_ACK_MS = 2000;
+
+// The spawned CLI process's own backstop, armed once --follow decides to
+// stop: CLOSE_ACK_MS already bounds tailOnce's promise, so cmdLogs reaches
+// this point well within it; this only fires if some other handle (not the
+// tail socket's own close handshake) is still keeping the process open.
+const FORCE_EXIT_MS = 5000;
+
+// One socket: resolves with its close code once it ends (or `signal` aborts
+// it, bounded by CLOSE_ACK_MS); each entry is handed to `onEntry` as frames
+// arrive.
+function tailOnce(api, filter, state, onEntry, signal, onConnected) {
+    return new Promise((resolve, reject) => {
+        const headers = { 'X-Substrio-Master-Key': api.masterKey };
+        if (api.tenant !== null) headers['X-Substrio-Tenant'] = api.tenant;
+        let opened = false;
+        let settled = false;
+        let ackTimer = null;
+        const settle = (fn, value) => {
+            if (settled) return;
+            settled = true;
+            if (ackTimer) clearTimeout(ackTimer);
+            fn(value);
+        };
+        const ws = new WebSocket(tailUrl(api.url, filter, state.cursor), { headers });
+        signal?.addEventListener('abort', () => {
+            ws.close();
+            ackTimer = setTimeout(() => settle(resolve, NORMAL_CLOSE), CLOSE_ACK_MS);
+            ackTimer.unref();
+        }, { once: true });
+        ws.addEventListener('open', () => { opened = true; });
+        ws.addEventListener('message', (event) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(event.data));
+            } catch {
+                return;
+            }
+            if (frame.type === 'connected') onConnected?.();
+            for (const entry of applyTailFrame(state, frame)) onEntry(entry);
+        });
+        ws.addEventListener('error', () => {
+            if (!opened) settle(reject, new CliError(`Cannot open the log stream at ${api.url}/v1/_logs/ws (the key, the tenant and the server version must allow function.logs.stream)`,
+                { code: ErrorCode.NETWORK_ERROR }));
+        });
+        ws.addEventListener('close', (event) => settle(resolve, event.code));
+    });
+}
+
+/**
+ * Follows the tenant's function logs, each entry handed to `onEntry`, until
+ * `signal` aborts. Reconnects only when the server asked the reader to resume
+ * (it fell behind past its bound): from the last cursor, so no line is skipped
+ * or repeated. Any other end is the stream's end: a CliError, unless aborted.
+ * `onConnected` is called each time the server confirms the subscription (nothing logged after it is missed).
+ */
+export async function followLogs(api, filter, onEntry, signal = undefined, onConnected = undefined) {
+    if (typeof WebSocket !== 'function') {
+        throw new CliError('Following logs needs Node 22 or newer (its built-in WebSocket)', { code: ErrorCode.INVALID_ARGUMENT });
+    }
+    const state = { cursor: null };
+    for (;;) {
+        const code = await tailOnce(api, filter, state, onEntry, signal, onConnected);
+        if (signal?.aborted || code === NORMAL_CLOSE) return;
+        if (code !== BACKLOG_LIMIT_CLOSE) {
+            throw new CliError(`The log stream closed (code ${code})${state.cursor ? `; resume with the cursor ${state.cursor}` : ''}`,
+                { code: ErrorCode.NETWORK_ERROR });
+        }
+    }
+}
+
+export async function cmdLogs(api, args) {
+    const follow = args.includes('--follow') || args.includes('--tail') || args.includes('-f');
+    let filter;
+    try {
+        filter = logFilter(args);
+    } catch (err) {
+        return fail(err);
+    }
+
+    if (!follow) {
+        // --json prints function.logs's answer whole ({logs, count}).
+        return runOperation(api, 'function.logs', [], { defaults: filter, render: printLogs });
+    }
+
+    let bound;
+    try {
+        bound = followBound(args);
+    } catch (err) {
+        return fail(err);
+    }
+    if (!bound && (globals.json || !process.stdout.isTTY)) {
+        return fail('substrio logs --follow with no terminal needs a way to stop: --for DURATION, --lines N or --until-match TEXT',
+            'substrio logs --follow --for 30s | --lines 100 | --until-match "fatal"', ErrorCode.INVALID_ARGUMENT);
+    }
+    if (!globals.json) console.log(`${C.cyan}Following logs...${C.reset} ${C.dim}(Ctrl+C to stop)${C.reset}\n`);
+
+    const controller = new AbortController();
+    let lines = 0;
+    let reason = null;
+    // Our own decision to stop must end the process even if the WebSocket's
+    // close handshake (its 'close' event) never completes: unref'd, so it
+    // never delays or forces anything on the path where the socket closes
+    // cleanly and the process exits on its own first.
+    const stop = (why) => {
+        if (controller.signal.aborted) return;
+        reason = why;
+        controller.abort();
+        setTimeout(() => process.exit(process.exitCode ?? 0), FORCE_EXIT_MS).unref();
+    };
+    const timer = bound?.forMs ? setTimeout(() => stop('duration'), bound.forMs) : null;
+    process.once('SIGINT', () => stop('closed'));
+    try {
+        await followLogs(api, filter, (entry) => {
+            // One frame can carry several entries: once a stop is met the rest
+            // of that frame is not printed, so --lines N is exactly N (the
+            // entries stay on the server for a later page or follow).
+            if (controller.signal.aborted) return;
+            lines++;
+            emitLine(entry, printLogEntry);
+            if (bound?.lines && lines >= bound.lines) stop('lines');
+            if (bound?.match && String(entry.message ?? entry.msg ?? '').includes(bound.match)) stop('match');
+        }, controller.signal);
+    } catch (err) {
+        clearTimeout(timer);
+        return fail(err);
+    }
+    clearTimeout(timer);
+    emitLine({ event: 'end', reason: reason ?? 'closed', lines }, () => console.log(`${C.dim}Stopped (${reason ?? 'closed'}).${C.reset}`));
+}
+
+function printLogs(data) {
+    const logs = data?.logs || [];
+    if (logs.length === 0) {
+        console.log(`${C.dim}No logs found.${C.reset}`);
+        return;
+    }
+    console.log(`\n${C.bold}Recent Logs${C.reset} ${C.dim}(${logs.length} entries)${C.reset}\n`);
+    for (const entry of logs) printLogEntry(entry);
+    console.log('');
+}
+
+export function printLogEntry(entry) {
+    const ts = entry.timestamp
+        ? new Date(entry.timestamp).toISOString().replace('T', ' ').replace('Z', '')
+        : '';
+    const level = (entry.level || 'info').toUpperCase();
+    const levelColor = level === 'ERROR' ? C.red : level === 'WARN' ? C.yellow : C.dim;
+    const fn = entry.function || entry.fn || '';
+    const msg = entry.message || entry.msg || (typeof entry === 'string' ? entry : JSON.stringify(entry));
+
+    console.log(
+        `${C.dim}${ts}${C.reset} ${levelColor}${level.padEnd(5)}${C.reset} ` +
+        `${fn ? C.cyan + fn + C.reset + ' ' : ''}` +
+        `${msg}`
+    );
+}

package/src/commands/mcp-config.mjs

@@ -0,0 +1,102 @@
+/**
+ * Substrio CLI: `substrio mcp config [--client claude|cursor|generic] [--name NAME] [--env VAR]`.
+ *
+ * Prints, as JSON on stdout, the config an MCP client needs to reach the app
+ * of the current profile: its server's `POST /mcp` endpoint, the tenant, and
+ * the key as a reference to an environment variable (default SUBSTRIO_KEY), in the
+ * spelling of the client. The key itself is never read, printed or written:
+ * the person sets the variable. What to do with the output goes to stderr, so
+ *   substrio mcp config > .mcp.json
+ * is the file.
+ */
+
+import { CliError, ErrorCode, emit, fail, globals } from '../cli.mjs';
+import { FlagKind, parseFlags } from '../local/args.mjs';
+
+/** The MCP clients a config can be made for (the file each reads is in `MCP_CLIENT_FILES`). */
+export const McpClient = Object.freeze({
+    CLAUDE: 'claude',   // Claude Code: .mcp.json
+    CURSOR: 'cursor',   // Cursor: .cursor/mcp.json
+    GENERIC: 'generic', // any other: the endpoint, transport and headers, to be translated
+});
+
+const MCP_CLIENT_FILES = Object.freeze({
+    [McpClient.CLAUDE]: '.mcp.json',
+    [McpClient.CURSOR]: '.cursor/mcp.json',
+    [McpClient.GENERIC]: null,
+});
+
+/** The environment variable the key is read from unless --env names another. */
+export const MCP_KEY_ENV = 'SUBSTRIO_KEY';
+/** The path of an app's MCP endpoint on its server. */
+export const MCP_PATH = '/mcp';
+
+const FLAGS = Object.freeze({ '--client': FlagKind.VALUE, '--name': FlagKind.VALUE, '--env': FlagKind.VALUE });
+const USAGE = 'substrio mcp config [--client claude|cursor|generic] [--name NAME] [--env VAR]';
+
+// The spelling of an environment variable reference in each client.
+const REFERENCE = Object.freeze({
+    [McpClient.CLAUDE]: (name) => `\${${name}}`,
+    [McpClient.CURSOR]: (name) => `\${env:${name}}`,
+    [McpClient.GENERIC]: (name) => `\${${name}}`,
+});
+
+const isNameChar = (c, first) => c === '_' || (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (!first && c >= '0' && c <= '9');
+
+/** An environment variable name: letters, digits and underscores, not starting with a digit. */
+export function isEnvName(name) {
+    return name.length > 0 && [...name].every((c, i) => isNameChar(c, i === 0));
+}
+
+/**
+ * The config of `client` for the app `tenant` of the server at `url` (pure):
+ * the server `name` (default: the tenant), the key read from `env`.
+ * Throws a CliError when the client is none of McpClient or `env` is not a name.
+ */
+export function mcpClientConfig({ client, url, tenant, name = null, env = MCP_KEY_ENV }) {
+    if (!Object.hasOwn(REFERENCE, client)) {
+        throw new CliError(`unknown client "${client}"; it is one of ${Object.values(McpClient).join(', ')}`, { code: ErrorCode.INVALID_ARGUMENT });
+    }
+    if (!isEnvName(env)) throw new CliError(`--env must be an environment variable name, not "${env}"`, { code: ErrorCode.INVALID_ARGUMENT });
+    const endpoint = `${url}${MCP_PATH}`;
+    const server = name ?? (tenant || 'substrio');
+    const headers = {
+        Authorization: `Bearer ${REFERENCE[client](env)}`,
+        ...(tenant ? { 'X-Substrio-Tenant': tenant } : {}),
+    };
+    switch (client) {
+        case McpClient.CLAUDE:
+            return { mcpServers: { [server]: { type: 'http', url: endpoint, headers } } };
+        case McpClient.CURSOR:
+            return { mcpServers: { [server]: { url: endpoint, headers } } };
+        default:
+            return { name: server, url: endpoint, method: 'POST', transport: 'streamable-http', headers, env: [env] };
+    }
+}
+
+/** `substrio mcp config`: `resolved` is resolveGroup's {positional, rest}; `context.config` the resolved config. */
+export async function cmdMcpConfig(_api, { positional, rest }, { config }) {
+    let flags;
+    let words;
+    try {
+        ({ flags, positional: words } = parseFlags(rest, FLAGS));
+    } catch (err) {
+        return fail(err, USAGE);
+    }
+    if (positional.length || words.length) fail(`unexpected argument "${[...positional, ...words][0]}"`, USAGE);
+    const client = flags.get('--client') ?? McpClient.CLAUDE;
+    let result;
+    try {
+        result = mcpClientConfig({
+            client, url: config.url, tenant: config.tenant ?? null, name: flags.get('--name') ?? null, env: flags.get('--env') ?? MCP_KEY_ENV,
+        });
+    } catch (err) {
+        return fail(err, USAGE);
+    }
+    emit(result);
+    if (!globals.json) {
+        const file = MCP_CLIENT_FILES[client];
+        const env = flags.get('--env') ?? MCP_KEY_ENV;
+        console.error(`${file ? `Save this as ${file}. ` : ''}Set ${env} to the tenant key before the client starts; the key is not in this config.`);
+    }
+}

package/src/commands/op.mjs

@@ -0,0 +1,265 @@
+/**
+ * Substrio CLI: `substrio op` (alias `substrio call`), every registry operation.
+ *
+ *   substrio op list [filter] [--json]     Operations the server has, by name
+ *   substrio op NAME --help                Its route and input schema
+ *   substrio op NAME [--data '{...}' | --file f.json | key=value ...] [--raw]
+ *                [--method M]      (an operation with routes of several methods)
+ *                [--page]          (a paged list: one page; else every page)
+ *
+ * NAME is the dotted name (webhook.get) or the MCP tool name
+ * (substrio_webhook_get). The result is printed as JSON; a failed call prints the
+ * error body on stderr and exits with its ExitCode (cli.mjs). Operations come from the server
+ * (GET /v1/_openapi), so a new one works as soon as the server has it.
+ */
+
+import { CliError, ErrorCode, emit, errorText, fail, globals } from '../cli.mjs';
+import {
+    PAGE_CURSOR_INPUT, PAGE_NEXT_CURSOR_FIELD, buildRequest, findOperation, indexOperations, matchesFilter,
+    mergePages, parseOpArgs, pickRoute,
+} from '../ops.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+const USAGE = "Usage: substrio op list [filter] | substrio op NAME [--data '{...}' | --file f.json | key=value ...] [--help]";
+
+export class OpError extends Error {}
+
+// The wait a 429/503 asked for (Retry-After: delta-seconds or an HTTP date), else null.
+function retryAfterMsOf(resp) {
+    const header = resp.headers.get('retry-after');
+    if (header === null) return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+    const at = Date.parse(header);
+    return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+
+async function readBody(resp) {
+    const text = await resp.text();
+    if (!text) return { text, data: null };
+    try {
+        return { text, data: JSON.parse(text) };
+    } catch {
+        return { text, data: undefined };
+    }
+}
+
+/** The server's operations, indexed (see ops.mjs indexOperations). */
+export async function loadOperations(api) {
+    const resp = await api.get('/v1/_openapi');
+    const { data } = await readBody(resp);
+    if (!resp.ok) throw CliError.fromResponse(`Could not read the server's operations: ${errorText(data, resp.status)}`, data, resp.status);
+    return indexOperations(data);
+}
+
+/**
+ * Calls the operation `name` with `input`; returns {ok, status, data, text,
+ * request, retryAfterMs}. `retryAfterMs` is the server's Retry-After wait
+ * (null unless the status is 429 or 503, or it sent none). Throws OpError
+ * when the name or input does not fit. `body` and
+ * `headers` are for an operation whose HTTP body is raw bytes (file.upload,
+ * site.blob.upload, app.import): the bytes go as the body of the route the
+ * input picks. With `stream`, a successful answer is not read: the result's
+ * `response` is the fetch Response, its body unread (app.export; the Response
+ * is what keeps the body open, so the caller holds it while it reads); a
+ * failed one is read as any error.
+ */
+export async function callOperation(api, ops, name, input, method = null, { body, headers, stream = false } = {}) {
+    let routes;
+    let request;
+    try {
+        routes = findOperation(ops, name);
+        const route = pickRoute(routes, input, method);
+        request = buildRequest(route, input, { rawBody: body !== undefined });
+    } catch (err) {
+        throw new OpError(err.message);
+    }
+    const resp = await api.raw(request.method, request.path, body ?? request.body, headers);
+    if (stream && resp.ok) return { ok: true, status: resp.status, response: resp, request };
+    const { data, text } = await readBody(resp);
+    const retryAfterMs = (resp.status === 429 || resp.status === 503) ? retryAfterMsOf(resp) : null;
+    return { ok: resp.ok, status: resp.status, data, text, request, retryAfterMs };
+}
+
+/**
+ * Calls `name` with `input` and returns the server's answer; a name or input
+ * that does not fit, or a failed call, ends the run with its typed error
+ * (failResult). `ops` is the catalog when the caller has read it already;
+ * `transport` is callOperation's {body, headers, stream} (with stream, the
+ * unread Response is returned); `hint(result)` says what to do about
+ * a failed call.
+ */
+export async function invokeOperation(api, name, input, { method = null, ops = null, hint = null, ...transport } = {}) {
+    let result;
+    try {
+        result = await callOperation(api, ops ?? await loadOperations(api), name, input, method, transport);
+    } catch (err) {
+        if (err instanceof OpError) return fail(err, `substrio op ${name} --help shows its route and input`);
+        throw err;
+    }
+    if (!result.ok) failResult(result, hint?.(result));
+    return transport.stream ? result.response : result.data;
+}
+
+/**
+ * The operation `name` with `input` as one step of a longer run: the server's data, or a
+ * thrown CliError (the server's typed error, or a name or input that does not fit), never
+ * the end of the run. `ops` is the catalog, read once by the caller.
+ */
+export async function callOrThrow(api, ops, name, input) {
+    let result;
+    try {
+        result = await callOperation(api, ops, name, input);
+    } catch (err) {
+        if (err instanceof OpError) throw new CliError(err.message);
+        throw err;
+    }
+    if (result.ok) return result.data;
+    throw CliError.fromResponse(errorText(result.data, result.status), result.data, result.status);
+}
+
+/**
+ * Ends the run on a failed callOperation result: the server's error (its
+ * body under --json, with its code and status, so its exit code).
+ */
+export function failResult(result, hint = null) {
+    if (!globals.json && result.data !== null) console.error(result.data === undefined ? result.text : JSON.stringify(result.data, null, 2));
+    fail(CliError.fromResponse(`${result.request.method} ${result.request.path}: ${errorText(result.data, result.status)}`,
+        result.data, result.status), hint);
+}
+
+// Prints a result: JSON pretty unless --raw; text as it came. A failed call
+// is the server's error (failResult).
+function printResult(result, raw) {
+    if (!result.ok) failResult(result);
+    if (result.data === undefined) emit(result.text, console.log);
+    else if (result.data !== null) emit(result.data, (data) => console.log(raw ? JSON.stringify(data) : JSON.stringify(data, null, 2)));
+}
+
+/**
+ * Runs `name` with CLI arguments; `positional` values fill the route's path
+ * parameters in order (for the group commands such as `substrio webhooks get ID`),
+ * `method` picks among the operation's routes, `defaults` are input fields
+ * used when the arguments give none, `present`, when given, turns a
+ * successful result into what is printed, `render`, when given, prints it
+ * as text (JSON under --json or --raw), and `ops` is the catalog when the
+ * caller has read it already. `body`, when given, names the input field
+ * that is the operation's whole body (data.insert: document): what --data,
+ * --file and key=value make is that field's value, so --data is the body
+ * itself, with no wrapper, and giving none is an error.
+ */
+export async function runOperation(api, name, args, { positional = [], present = null, render = null, method = null, defaults = {}, body = null, ops: catalog = null } = {}) {
+    let parsed;
+    try {
+        parsed = parseOpArgs(args);
+    } catch (err) {
+        return fail(err, USAGE);
+    }
+    if (body !== null) {
+        if (parsed.input === undefined) return fail(`${name} needs its ${body}: --data '{...}', --file F or key=value fields`, `substrio op ${name} --help shows its input`);
+        parsed.input = { [body]: parsed.input };
+    }
+    let ops = catalog;
+    try {
+        ops ??= await loadOperations(api);
+    } catch (err) {
+        return fail(err);
+    }
+    const chosen = parsed.flags.method || method;
+    let input = parsed.input;
+    if (positional.length || Object.keys(defaults).length) {
+        let routes;
+        try {
+            routes = findOperation(ops, name);
+        } catch (err) {
+            return fail(err);
+        }
+        const route = routes.find((r) => !chosen || r.method === chosen) || routes[0];
+        const { params } = route;
+        if (positional.length > params.length) {
+            return fail(`${name} takes ${params.length ? params.join(', ') : 'no'} positional argument${params.length === 1 ? '' : 's'}`);
+        }
+        input = { ...defaults, ...Object.fromEntries(positional.map((v, i) => [params[i], v])), ...(input || {}) };
+    }
+    try {
+        const result = await callOperation(api, ops, name, input, chosen);
+        // A paged list is read whole: each next_cursor is followed and the
+        // pages merged, unless --page or a cursor was given.
+        const follow = !parsed.flags.page && !(input && input[PAGE_CURSOR_INPUT] !== undefined);
+        for (let last = input?.[PAGE_CURSOR_INPUT]; follow && result.ok && result.data?.[PAGE_NEXT_CURSOR_FIELD];) {
+            const cursor = result.data[PAGE_NEXT_CURSOR_FIELD];
+            if (cursor === last) return fail(`${name} answered the cursor it was given (${cursor}) as its next one`, null, ErrorCode.UNKNOWN);
+            last = cursor;
+            const next = await callOperation(api, ops, name, { ...(input || {}), [PAGE_CURSOR_INPUT]: cursor }, chosen);
+            if (!next.ok) return failResult(next);
+            result.data = mergePages(result.data, next.data ?? {});
+        }
+        if (result.ok && present && result.data) result.data = present(result.data);
+        if (result.ok && render && result.data && !parsed.flags.raw) emit(result.data, render);
+        else printResult(result, parsed.flags.raw);
+    } catch (err) {
+        if (err instanceof OpError) return fail(err, `substrio op ${name} --help shows its route and input`);
+        throw err;
+    }
+}
+
+/**
+ * Prints one operation's routes and input schema, from the server's catalog
+ * (a read). Throws when the catalog cannot be read or has no such operation.
+ */
+export async function showOperationHelp(api, name) {
+    printHelp(findOperation(await loadOperations(api), name));
+}
+
+function printHelp(routes) {
+    const first = routes[0];
+    console.log(`\n${C.bold}${first.name}${C.reset}${first.id ? ` ${C.dim}(operation ${first.id})${C.reset}` : ''}`);
+    if (first.summary) console.log(`  ${first.summary}`);
+    console.log('');
+    for (const r of routes) {
+        const { params } = r;
+        console.log(`  ${C.cyan}${r.method} ${r.path}${C.reset}${params.length ? ` ${C.dim}path: ${params.join(', ')}${C.reset}` : ''}` +
+            `${r.query.length ? ` ${C.dim}query: ${r.query.join(', ')}${C.reset}` : ''}`);
+    }
+    const declared = first.parameters.filter((p) => p.in !== 'path');
+    if (declared.length) {
+        console.log(`\n${C.bold}Parameters${C.reset}`);
+        for (const p of declared) console.log(`  ${p.name} ${C.dim}(${p.in}${p.required ? ', required' : ''})${C.reset}${p.description ? ` ${p.description}` : ''}`);
+    }
+    console.log(`\n${C.bold}Input schema${C.reset}`);
+    console.log(first.bodySchema ? JSON.stringify(first.bodySchema, null, 2) : `${C.dim}  (none: the route's parameters only)${C.reset}`);
+    console.log(`\n${C.dim}  substrio op ${first.name} key=value ... | --data '{...}' | --file f.json${C.reset}\n`);
+}
+
+async function listOperations(api, args) {
+    const filter = args.filter((a) => !a.startsWith('--')).join(' ');
+    let ops;
+    try {
+        ops = await loadOperations(api);
+    } catch (err) {
+        return fail(err);
+    }
+    const shown = ops.filter((op) => matchesFilter(op, filter));
+    if (globals.json) return emit(shown.map(({ name, id, method, path, summary }) => ({ name, id, method, path, summary })));
+    if (shown.length === 0) {
+        console.log(`${C.dim}No operation matches "${filter}".${C.reset}`);
+        return;
+    }
+    const width = Math.max(...shown.map((op) => op.name.length));
+    const routeWidth = Math.max(...shown.map((op) => op.method.length + op.path.length + 1));
+    for (const op of shown) {
+        console.log(`  ${C.cyan}${op.name.padEnd(width)}${C.reset}  ${`${op.method} ${op.path}`.padEnd(routeWidth)}  ${C.dim}${op.summary}${C.reset}`);
+    }
+    console.log(`\n${C.dim}  ${shown.length} of ${ops.length} routes. substrio op NAME --help for one.${C.reset}\n`);
+}
+
+export async function cmdOp(api, args) {
+    const sub = args[0];
+    if (!sub) fail('an operation name is needed', USAGE);
+    if (sub === 'list' || sub === 'ls') return listOperations(api, args.slice(1));
+    return runOperation(api, sub, args.slice(1));
+}