@thinger-io/cli-core 0.4.2 → 0.5.1

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();

package/lib/commands/_shared.js

@@ -34,6 +34,16 @@ export function getGlobalUser(cmd) {
     return root.opts().user || null;
 }
 
+export function parseNonNegativeInt(label) {
+    return (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+            throw new InvalidArgumentError(`${label} must be a non-negative integer`);
+        }
+        return n;
+    };
+}
+
 export function parsePositiveInt(label) {
     return (value) => {
         const n = Number(value);
@@ -54,6 +64,37 @@ export function collectKeyValue(value, previous = {}) {
     return { ...previous, [value.slice(0, idx)]: parseJsonValue(value.slice(idx + 1)) };
 }
 
+// Like collectKeyValue, values kept as written: query parameters, where
+// "007" must not become 7.
+export function collectKeyString(value, previous = {}) {
+    const idx = value.indexOf('=');
+    if (idx === -1) throw new InvalidArgumentError('must be key=value');
+    return { ...previous, [value.slice(0, idx)]: value.slice(idx + 1) };
+}
+
+/**
+ * Set `value` at a dot path of `target` (`data.source` → target.data.source),
+ * creating the objects on the way. Keys that would reach the prototype are
+ * refused.
+ *
+ * @param {Record<string, any>} target
+ * @param {string} path
+ * @param {any} value
+ */
+export function setPath(target, path, value) {
+    const keys = path.split('.');
+    if (keys.some((k) => !k || k === '__proto__' || k === 'constructor' || k === 'prototype')) {
+        throw new InvalidArgumentError(`invalid field: ${path}`);
+    }
+    let node = target;
+    for (const k of keys.slice(0, -1)) {
+        if (!node[k] || typeof node[k] !== 'object' || Array.isArray(node[k])) node[k] = {};
+        node = node[k];
+    }
+    node[keys[keys.length - 1]] = value;
+    return target;
+}
+
 // Parse a command-line value as JSON, falling back to the raw string so
 // `property set dev name foo` works without shell-escaping quotes.
 export function parseJsonValue(raw) {
@@ -66,7 +107,9 @@ export function parseJsonValue(raw) {
 }
 
 // Read a JSON document from a file path, or from stdin when the path is `-`.
-export async function readJsonArgument(source) {
+// With `lines`, a file of one JSON document per line (NDJSON) is read as
+// the array of them.
+export async function readJsonArgument(source, { lines = false } = {}) {
     let text;
     if (source === '-') {
         const chunks = [];
@@ -78,10 +121,55 @@ export async function readJsonArgument(source) {
     try {
         return JSON.parse(text);
     } catch (error) {
+        if (lines) {
+            try {
+                return text
+                    .split('\n')
+                    .filter((l) => l.trim())
+                    .map((l) => JSON.parse(l));
+            } catch {
+                // Report the error of the whole document.
+            }
+        }
         throw new InvalidArgumentError(`${source} is not valid JSON: ${error.message}`);
     }
 }
 
+/**
+ * The body a command builds from `--from <file|->` and repeatable
+ * `--set key=value` (dot paths nest) on top of it. Undefined when neither
+ * is given.
+ *
+ * @param {{ from?: string, set?: Record<string, any> }} opts
+ * @param {{ lines?: boolean }} [read]  Passed to readJsonArgument.
+ */
+export async function bodyFromOptions(opts, read) {
+    let body;
+    if (opts.from) body = await readJsonArgument(opts.from, read);
+    if (opts.set) {
+        if (
+            body !== undefined &&
+            (typeof body !== 'object' || body === null || Array.isArray(body))
+        ) {
+            throw new InvalidArgumentError('--set needs the --from body to be a JSON object');
+        }
+        body = body ?? {};
+        for (const [k, v] of Object.entries(opts.set)) setPath(body, k, v);
+    }
+    return body;
+}
+
+/** `--from` and `--set`, the options of bodyFromOptions. */
+export function bodyOptions(cmd, setFlag = '-s, --set <key=value>') {
+    return cmd
+        .option('--from <file>', 'JSON body from a file, or - for stdin')
+        .option(
+            setFlag,
+            'Body field (repeatable; values parsed as JSON when they are; dots nest: data.source=resource)',
+            collectKeyValue,
+        );
+}
+
 /**
  * Ask before an irreversible action unless `--yes` was given. Refuses in a
  * non-interactive shell (or JSON mode) without `--yes` rather than

package/lib/commands/api.js

@@ -0,0 +1,90 @@
+// @ts-check
+import { writeFile } from 'node:fs/promises';
+import { rawApiCall } from '../raw-api.js';
+import { inputError } from '../errors.js';
+import { classifyError, isJsonMode, printErr, printOk } from '../output.js';
+import {
+    applyJsonFlag,
+    collectKeyString,
+    ensureConfigured,
+    getGlobalUser,
+    bodyFromOptions,
+    bodyOptions,
+} from './_shared.js';
+
+/** `<cli> api <path>` — any request to the server, as `gh api` does for GitHub. */
+export function registerApiCommand(program) {
+    bodyOptions(
+        program
+            .command('api <path>')
+            .helpGroup('Integration:')
+            .description('Send a request to the server API (anything the commands do not cover)')
+            .option(
+                '-X, --method <method>',
+                'GET, POST, PUT, PATCH or DELETE (default: GET, or POST with a body)',
+            ),
+    )
+        .option('-q, --query <key=value>', 'Query parameter (repeatable)', collectKeyString)
+        .option('-o, --output <file>', 'Write the answer to a file (downloads, binary answers)')
+        .option('-j, --json', 'Output as JSON ({ ok, data })')
+        .addHelpText(
+            'after',
+            `
+The path is relative to the profile's server; {user} stands for the account
+(the profile's, or --user). The answer is printed as it comes: JSON pretty
+printed, text as is.
+
+Examples:
+  $ <cli> api /v1/users/{user}/endpoints
+  $ <cli> api /v1/users/{user}/buckets -s bucket=temps -s name=Temperatures -s source=write
+  $ <cli> api -X PUT /v1/users/{user}/devices/sensor1 --from device.json
+  $ <cli> api /v1/users/{user}/buckets/temps/data -q items=100 -q sort=desc
+  $ <cli> api /v2/users/{user}/storages/web/files/index.html -o index.html`.replaceAll(
+                '<cli>',
+                program.name(),
+            ),
+        )
+        .action(async (path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            try {
+                const body = await bodyFromOptions(opts);
+                if (
+                    body !== undefined &&
+                    ['GET', 'DELETE'].includes(String(opts.method).toUpperCase())
+                ) {
+                    throw inputError(
+                        `${opts.method.toUpperCase()} takes no body: pass query parameters with -q`,
+                    );
+                }
+                const res = await rawApiCall({
+                    method: opts.method,
+                    path,
+                    query: opts.query,
+                    body,
+                    user: getGlobalUser(cmd),
+                });
+                if (opts.output) {
+                    await writeFile(opts.output, res.raw);
+                    if (isJsonMode()) printOk({ status: res.status, file: opts.output });
+                    else process.stderr.write(`Saved to ${opts.output}\n`);
+                    return;
+                }
+                if (res.kind === 'binary') {
+                    if (isJsonMode() || process.stdout.isTTY) {
+                        throw inputError(
+                            `the answer is binary (${res.contentType || 'unknown type'}, ${res.body.length} bytes): save it with -o <file>`,
+                        );
+                    }
+                    process.stdout.write(res.body);
+                    return;
+                }
+                if (isJsonMode()) printOk(res.body);
+                else if (res.kind === 'json') console.log(JSON.stringify(res.body, null, 2));
+                else if (res.kind === 'text') process.stdout.write(res.raw);
+            } catch (error) {
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+            }
+        });
+}

package/lib/commands/arguments.js

@@ -0,0 +1,62 @@
+// @ts-check
+
+/**
+ * Help for the positional arguments of the commands written by hand, kept
+ * in one table instead of spread over every `.command('x <id>')`. A command
+ * path ('dashboard init') wins over the argument name alone; a CLI adds its
+ * own tables (runCli's `argumentHelp`).
+ */
+const BY_COMMAND = {
+    api: { path: 'API path, e.g. /v1/users/{user}/devices ({user}: your account)' },
+    'device set-product': { product: 'Product ID ("" removes the device from its product)' },
+    'device resource call': { resource: 'Resource of the device to call' },
+    'product profile api call': { resource: 'API resource of the product profile' },
+    'doc get': { doc: 'ID of the guide (doc list gives them)' },
+
+    'dashboard init': { dir: 'New or empty folder for the app' },
+    'dashboard dev': {
+        url: 'Address of the app on its dev server (default: dev.url of the manifest)',
+    },
+    'dashboard publish': { dir: 'Folder to upload (default: dir of the manifest)' },
+    'storage file list': { folder: 'Folder of the storage to list (default: all the files)' },
+    'storage file upload': { local: 'Local file or folder' },
+    'storage file download': { path: 'Path of the file in the storage' },
+    'storage file delete': { path: 'Path of the file in the storage' },
+    'plugin call': { path: 'Path in the API of the plugin, e.g. /api/status' },
+    'profile add': { name: 'Profile name (asked when missing)' },
+};
+
+const BY_NAME = {
+    device: 'Device ID',
+    product: 'Product ID',
+    bucket: 'Data Bucket ID',
+    property: 'Property ID',
+    value: 'Value, parsed as JSON (text when it is not JSON)',
+    storage: 'File storage ID',
+    plugin: 'Plugin ID',
+    name: 'Profile name',
+};
+
+/**
+ * Describe the arguments that have no description yet, in the whole tree.
+ *
+ * @param {import('commander').Command} program
+ * @param {{ byCommand?: Record<string, Record<string, string>>, byName?: Record<string, string> }} [extra]
+ *   A CLI's own tables, read before the core's.
+ */
+export function describeArguments(program, { byCommand = {}, byName = {} } = {}) {
+    const walk = (cmd, path) => {
+        for (const arg of cmd.registeredArguments) {
+            if (arg.description) continue;
+            const name = arg.name();
+            arg.description =
+                byCommand[path]?.[name] ??
+                BY_COMMAND[path]?.[name] ??
+                byName[name] ??
+                BY_NAME[name] ??
+                '';
+        }
+        for (const sub of cmd.commands) walk(sub, path ? `${path} ${sub.name()}` : sub.name());
+    };
+    walk(program, '');
+}

package/lib/commands/bucket.js

@@ -2,6 +2,7 @@
 import { getBucketData, getBuckets } from '../bucket.js';
 import { hint, info, label, success } from '../format.js';
 import { isJsonMode, printOk } from '../output.js';
+import { hasListOptions, listOptions, listRecords } from './resources.js';
 import {
     applyJsonFlag,
     ensureConfigured,
@@ -10,71 +11,78 @@ import {
     runCommand,
 } from './_shared.js';
 
-/** `<cli> bucket list|read` — data buckets and their time series. */
+/**
+ * `<cli> bucket list|read` — data buckets as a table and their time
+ * series; the rest of the group (write, export, records, tags…) comes from
+ * the tool and resource commands.
+ */
 export function registerBucketCommands(program) {
     const bucket = program
         .command('bucket')
-        .helpGroup('Operations:')
-        .description('Data buckets: list them and read their time series');
+        .helpGroup('Resources:')
+        .description('Data buckets: records, time series, exports and tags');
 
-    bucket
-        .command('list')
-        .description('List the data buckets of the account')
-        .option('-j, --json', 'Output as JSON')
-        .action(async (opts, cmd) => {
-            applyJsonFlag(opts);
-            ensureConfigured();
-            const user = getGlobalUser(cmd);
-            await runCommand({
-                start: 'Fetching buckets...',
-                fn: () => getBuckets(user),
-                success: (buckets) => `Found ${buckets.length} bucket(s)`,
-                failure: 'Failed to list buckets',
-                onSuccess: (buckets) => {
-                    if (isJsonMode()) {
-                        printOk(buckets);
-                        return;
-                    }
-                    const idWidth = buckets.reduce(
-                        (w, b) => Math.max(w, String(b.bucket ?? '').length),
-                        0,
+    listOptions(
+        bucket
+            .command('list')
+            .helpGroup('Records:')
+            .description('List the data buckets of the account')
+            .option('-j, --json', 'Output as JSON'),
+    ).action(async (opts, cmd) => {
+        applyJsonFlag(opts);
+        ensureConfigured();
+        const user = getGlobalUser(cmd);
+        await runCommand({
+            start: 'Fetching buckets...',
+            fn: () => (hasListOptions(opts) ? listRecords('bucket', opts, user) : getBuckets(user)),
+            success: (buckets) => `Found ${buckets.length} bucket(s)`,
+            failure: 'Failed to list buckets',
+            onSuccess: (buckets) => {
+                if (isJsonMode()) {
+                    printOk(buckets);
+                    return;
+                }
+                const idWidth = buckets.reduce(
+                    (w, b) => Math.max(w, String(b.bucket ?? '').length),
+                    0,
+                );
+                for (const b of buckets) {
+                    const flag = b.enabled === false ? hint('disabled') : success('enabled ');
+                    const extras = [
+                        b.name && b.name !== b.bucket ? hint(`(${b.name})`) : '',
+                        b.product ? info(`[${b.product}]`) : '',
+                        b.config?.source ? hint(`source: ${b.config.source}`) : '',
+                    ].filter(Boolean);
+                    console.log(
+                        `  ${flag}  ${label(String(b.bucket ?? '(no id)').padEnd(idWidth))}${extras.length ? '  ' + extras.join('  ') : ''}`,
                     );
-                    for (const b of buckets) {
-                        const flag = b.enabled === false ? hint('disabled') : success('enabled ');
-                        const extras = [
-                            b.name && b.name !== b.bucket ? hint(`(${b.name})`) : '',
-                            b.product ? info(`[${b.product}]`) : '',
-                            b.config?.source ? hint(`source: ${b.config.source}`) : '',
-                        ].filter(Boolean);
-                        console.log(
-                            `  ${flag}  ${label(String(b.bucket ?? '(no id)').padEnd(idWidth))}${extras.length ? '  ' + extras.join('  ') : ''}`,
-                        );
-                    }
-                },
-            });
+                }
+            },
         });
+    });
 
     bucket
-        .command('read <bucketId>')
+        .command('read <bucket>')
+        .helpGroup('Data:')
         .description('Read samples from a bucket (latest first by default)')
-        .option('-d, --device <deviceId>', 'Series a product bucket keeps for this device')
-        .option('-n, --items <n>', 'Number of samples (default: 10)', parsePositiveInt('items'), 10)
+        .option('-d, --device <device>', 'Series a product bucket keeps for this device')
+        .option('-n, --items <n>', 'Number of samples', parsePositiveInt('items'), 10)
         .option('-m, --minutes <n>', 'Only the last N minutes', parsePositiveInt('minutes'))
-        .option('--sort <order>', 'asc or desc (default: desc)', 'desc')
+        .option('--sort <order>', 'asc or desc', 'desc')
         .option('--agg <window>', 'Aggregation window, e.g. 5m, 1h')
         .option('--agg-type <reducer>', 'Reducer: mean, max, min, sum, count, first, last…')
         .option('--fields <list>', 'Comma-separated fields to return')
         .option('--group-by <key>', 'Group key, e.g. device')
         .option('-j, --json', 'Output as JSON')
-        .action(async (bucketId, opts, cmd) => {
+        .action(async (id, opts, cmd) => {
             applyJsonFlag(opts);
             ensureConfigured();
             const user = getGlobalUser(cmd);
             await runCommand({
-                start: `Reading ${bucketId}...`,
+                start: `Reading ${id}...`,
                 fn: () =>
                     getBucketData({
-                        bucket: bucketId,
+                        bucket: id,
                         device: opts.device,
                         user,
                         items: opts.items,

package/lib/commands/dashboard.js

@@ -35,9 +35,9 @@ export function registerDashboardCommands(program) {
     const cli = identity().name;
     const dashboard = program
         .command('dashboard')
-        .helpGroup('Operations:')
+        .helpGroup('Resources:')
         .description(
-            'Dashboard apps (HTML + the dashboard SDK): develop them on their dev server and publish them',
+            'Dashboards: apps on the dashboard SDK (create, develop and publish them) and their records',
         )
         .addHelpText(
             'after',
@@ -52,6 +52,7 @@ In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace
 
     dashboard
         .command('init <dir>')
+        .helpGroup('Apps:')
         .description(
             'Create a dashboard app (TypeScript, on @thinger-io/dashboard-sdk) from a template of the SDK',
         )
@@ -111,6 +112,7 @@ In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace
 
     dashboard
         .command('dev [url]')
+        .helpGroup('Apps:')
         .description(
             'Link that opens the app on its own dev server (ng serve, Vite…) against the server, with a temporary token',
         )
@@ -200,6 +202,7 @@ token (one per project).`,
 
     dashboard
         .command('publish [dir]')
+        .helpGroup('Apps:')
         .description('Upload an app to a public storage and point dashboards at it')
         .option('-s, --storage <id>', 'Storage of the app (created public if missing)')
         .option(