@motherbase/cli 0.2.5 → 0.2.8

package/src/commands/migration.js

@@ -1,108 +1,108 @@
-'use strict';
-
-// `migration`: Supabase's name for the group. The server-side lifecycle
-// (list/diff/get/create/apply/rollback) and the local `new` scaffold live
-// together here; `migrations` is registered as an alias of this entry.
-
-const fs = require('fs');
-const path = require('path');
-const api = require('../api');
-const ui = require('../ui');
-const { output, requireArg } = require('./_util');
-const { CliError } = require('../context');
-
-function readSql(cwd, file) {
-  if (!file) return undefined;
-  return fs.readFileSync(path.resolve(cwd, file), 'utf8');
-}
-
-const subcommands = {
-  new: {
-    summary: 'Scaffold a local migration .sql file',
-    usage: 'motherbase migration new <name>',
-    async run(ctx, args) {
-      const name = requireArg(args[0], 'name');
-      if (!/^[a-zA-Z0-9_-]+$/.test(name)) throw new CliError('name must be alphanumeric / dash / underscore');
-      const dir = path.join(ctx.cwd, 'motherbase', 'migrations');
-      fs.mkdirSync(dir, { recursive: true });
-      const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '');
-      const file = path.join(dir, `${stamp}_${name}.sql`);
-      fs.writeFileSync(file, `-- Migration: ${name}\n\n\n-- @down\n-- Optional: SQL that undoes the above, for \`migration down\`.\n`);
-      ui.success(`Created ${path.relative(ctx.cwd, file)}`);
-    },
-  },
-  list: {
-    summary: 'List schema migrations',
-    usage: 'motherbase migration list',
-    async run(ctx) {
-      const data = await api.adminRequest(ctx, 'GET', '/migrations');
-      const rows = (data && data.migrations) || [];
-      output(ctx, data, (_d, ui) =>
-        ui.table(rows, [
-          { key: 'id', label: 'ID' },
-          { key: 'name', label: 'NAME' },
-          { key: 'status', label: 'STATUS' },
-          { key: 'appliedAt', label: 'APPLIED' },
-        ]),
-      );
-    },
-  },
-  diff: {
-    summary: 'Show a diff between live schema and migrations',
-    usage: 'motherbase migration diff',
-    async run(ctx) {
-      const data = await api.adminRequest(ctx, 'GET', '/migrations/diff');
-      output(ctx, data, (d, ui) => ui.json(d));
-    },
-  },
-  get: {
-    summary: 'Show a single migration',
-    usage: 'motherbase migration get <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'GET', `/migrations/${id}`);
-      output(ctx, data, (d, ui) => ui.keyValue((d && d.migration) || d || {}));
-    },
-  },
-  create: {
-    summary: 'Create a migration from up/down SQL files',
-    usage: 'motherbase migration create --name <name> --up <file.sql> [--down <file.sql>]',
-    async run(ctx, args, flags) {
-      const name = flags.name || args[0];
-      if (!name) throw new CliError('--name is required');
-      const upSql = readSql(ctx.cwd, flags.up);
-      const downSql = readSql(ctx.cwd, flags.down);
-      if (!upSql) throw new CliError('--up <file.sql> is required');
-      const data = await api.adminRequest(ctx, 'POST', '/migrations', { body: { name, upSql, downSql } });
-      output(ctx, data, (d, ui) => ui.success(`Created migration ${name}`));
-    },
-  },
-  apply: {
-    summary: 'Apply a migration',
-    usage: 'motherbase migration apply <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'POST', `/migrations/${id}/apply`);
-      output(ctx, data, (d, ui) => ui.success(`Applied ${id}`));
-    },
-  },
-  rollback: {
-    summary: 'Roll back a migration',
-    usage: 'motherbase migration rollback <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'POST', `/migrations/${id}/rollback`);
-      output(ctx, data, (d, ui) => ui.success(`Rolled back ${id}`));
-    },
-  },
-};
-
-// The local-files workflow (list/up/down/repair/squash/fetch) lives with its
-// helpers in ../migration.
-Object.assign(subcommands, require('../migration/commands').migrationSubcommands);
-
-module.exports = {
-  summary: 'Schema migrations: local files and the remote history',
-  usage: 'motherbase migration <new|list|up|down|repair|squash|fetch|diff|get|create|apply|rollback> ...',
-  subcommands,
-};
+'use strict';
+
+// `migration`: Supabase's name for the group. The server-side lifecycle
+// (list/diff/get/create/apply/rollback) and the local `new` scaffold live
+// together here; `migrations` is registered as an alias of this entry.
+
+const fs = require('fs');
+const path = require('path');
+const api = require('../api');
+const ui = require('../ui');
+const { output, requireArg } = require('./_util');
+const { CliError } = require('../context');
+
+function readSql(cwd, file) {
+  if (!file) return undefined;
+  return fs.readFileSync(path.resolve(cwd, file), 'utf8');
+}
+
+const subcommands = {
+  new: {
+    summary: 'Scaffold a local migration .sql file',
+    usage: 'motherbase migration new <name>',
+    async run(ctx, args) {
+      const name = requireArg(args[0], 'name');
+      if (!/^[a-zA-Z0-9_-]+$/.test(name)) throw new CliError('name must be alphanumeric / dash / underscore');
+      const dir = path.join(ctx.cwd, 'motherbase', 'migrations');
+      fs.mkdirSync(dir, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '');
+      const file = path.join(dir, `${stamp}_${name}.sql`);
+      fs.writeFileSync(file, `-- Migration: ${name}\n\n\n-- @down\n-- Optional: SQL that undoes the above, for \`migration down\`.\n`, { flag: 'wx' });
+      ui.success(`Created ${path.relative(ctx.cwd, file)}`);
+    },
+  },
+  list: {
+    summary: 'List schema migrations',
+    usage: 'motherbase migration list',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/migrations');
+      const rows = (data && data.migrations) || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(rows, [
+          { key: 'id', label: 'ID' },
+          { key: 'name', label: 'NAME' },
+          { key: 'status', label: 'STATUS' },
+          { key: 'appliedAt', label: 'APPLIED' },
+        ]),
+      );
+    },
+  },
+  diff: {
+    summary: 'Show a diff between live schema and migrations',
+    usage: 'motherbase migration diff',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/migrations/diff');
+      output(ctx, data, (d, ui) => ui.json(d));
+    },
+  },
+  get: {
+    summary: 'Show a single migration',
+    usage: 'motherbase migration get <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'GET', `/migrations/${id}`);
+      output(ctx, data, (d, ui) => ui.keyValue((d && d.migration) || d || {}));
+    },
+  },
+  create: {
+    summary: 'Create a migration from up/down SQL files',
+    usage: 'motherbase migration create --name <name> --up <file.sql> [--down <file.sql>]',
+    async run(ctx, args, flags) {
+      const name = flags.name || args[0];
+      if (!name) throw new CliError('--name is required');
+      const upSql = readSql(ctx.cwd, flags.up);
+      const downSql = readSql(ctx.cwd, flags.down);
+      if (!upSql) throw new CliError('--up <file.sql> is required');
+      const data = await api.adminRequest(ctx, 'POST', '/migrations', { body: { name, upSql, downSql } });
+      output(ctx, data, (d, ui) => ui.success(`Created migration ${name}`));
+    },
+  },
+  apply: {
+    summary: 'Apply a migration',
+    usage: 'motherbase migration apply <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'POST', `/migrations/${id}/apply`);
+      output(ctx, data, (d, ui) => ui.success(`Applied ${id}`));
+    },
+  },
+  rollback: {
+    summary: 'Roll back a migration',
+    usage: 'motherbase migration rollback <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'POST', `/migrations/${id}/rollback`);
+      output(ctx, data, (d, ui) => ui.success(`Rolled back ${id}`));
+    },
+  },
+};
+
+// The local-files workflow (list/up/down/repair/squash/fetch) lives with its
+// helpers in ../migration.
+Object.assign(subcommands, require('../migration/commands').migrationSubcommands);
+
+module.exports = {
+  summary: 'Schema migrations: local files and the remote history',
+  usage: 'motherbase migration <new|list|up|down|repair|squash|fetch|diff|get|create|apply|rollback> ...',
+  subcommands,
+};

package/src/commands/projects.js

@@ -99,13 +99,14 @@ const subcommands = {
   },
   limits: {
     summary: 'Get or set per-project resource limits',
-    usage: 'motherbase projects limits <id> [--api-cpus n --api-mem mb --db-cpus n --db-mem mb --minio-cpus n --minio-mem mb]',
+    usage: 'motherbase projects limits <id> [--api-cpus n --api-mem mb --db-cpus n --db-mem mb --minio-cpus n --minio-mem mb --edge-cpus n --edge-mem mb]',
     async run(ctx, args, flags) {
       const id = requireArg(args[0], 'id');
       const map = {
         'api-cpus': 'apiCpus', 'api-mem': 'apiMemMb',
         'db-cpus': 'dbCpus', 'db-mem': 'dbMemMb',
         'minio-cpus': 'minioCpus', 'minio-mem': 'minioMemMb',
+        'edge-cpus': 'edgeCpus', 'edge-mem': 'edgeMemMb',
       };
       const body = {};
       for (const [flag, key] of Object.entries(map)) {

package/src/commands/storage.js

@@ -8,7 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const api = require('../api');
-const { output, requireArg, splitRef } = require('./_util');
+const { output, requireArg, splitRef, resolveInside } = require('./_util');
 const { CliError } = require('../context');
 const remote = require('../storage/remote');
 
@@ -108,7 +108,7 @@ async function download(ctx, srcArg, dstArg, recursive) {
     const prefix = remote.asPrefix(src.key);
     const keys = await sourceKeys(ctx, src, true);
     return each(keys, 'download', key => {
-      const target = path.join(local, ...key.slice(prefix.length).split('/'));
+      const target = resolveInside(local, ...key.slice(prefix.length).split('/'));
       fs.mkdirSync(path.dirname(target), { recursive: true });
       return api.downloadFile(ctx, objectPath(src.bucket, key), target);
     });

package/src/commands/users.js

@@ -1,142 +1,142 @@
-'use strict';
-
-const api = require('../api');
-const { output, requireArg } = require('./_util');
-const { CliError } = require('../context');
-
-// Collect known user fields from flags into a body.
-function userBody(flags) {
-  const body = {};
-  for (const key of ['email', 'password', 'name', 'role']) {
-    if (flags[key] !== undefined) body[key] = flags[key];
-  }
-  return body;
-}
-
-const subcommands = {
-  list: {
-    summary: 'List project users',
-    usage: 'motherbase users list',
-    async run(ctx) {
-      const data = await api.adminRequest(ctx, 'GET', '/users');
-      const users = (data && data.users) || data || [];
-      output(ctx, data, (_d, ui) =>
-        ui.table(Array.isArray(users) ? users : [], [
-          { key: 'id', label: 'ID' },
-          { key: 'email', label: 'EMAIL' },
-          { key: 'role', label: 'ROLE' },
-        ]),
-      );
-    },
-  },
-  get: {
-    summary: 'Get a user by id',
-    usage: 'motherbase users get <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'GET', `/users/${id}`);
-      output(ctx, data, (d, ui) => ui.keyValue(d || {}));
-    },
-  },
-  create: {
-    summary: 'Create a user',
-    usage: 'motherbase users create --email <e> --password <p> [--name <n>] [--role <r>]',
-    async run(ctx, args, flags) {
-      const body = userBody(flags);
-      if (!body.email || !body.password) throw new CliError('--email and --password are required');
-      const data = await api.adminRequest(ctx, 'POST', '/users', { body });
-      output(ctx, data, (d, ui) => ui.success(`Created user ${body.email}`));
-    },
-  },
-  update: {
-    summary: 'Update a user',
-    usage: 'motherbase users update <id> [--email ...] [--name ...] [--role ...]',
-    async run(ctx, args, flags) {
-      const id = requireArg(args[0], 'id');
-      const body = userBody(flags);
-      const data = await api.adminRequest(ctx, 'PATCH', `/users/${id}`, { body });
-      output(ctx, data, (d, ui) => ui.success(`Updated user ${id}`));
-    },
-  },
-  delete: {
-    summary: 'Delete a user',
-    usage: 'motherbase users delete <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'DELETE', `/users/${id}`);
-      output(ctx, data, (d, ui) => ui.success(`Deleted user ${id}`));
-    },
-  },
-  'reset-password': {
-    summary: 'Reset a user password',
-    usage: 'motherbase users reset-password <id> [--password <p>]',
-    async run(ctx, args, flags) {
-      const id = requireArg(args[0], 'id');
-      const body = flags.password ? { password: flags.password } : {};
-      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/reset-password`, { body });
-      output(ctx, data, (d, ui) => ui.success(`Password reset for ${id}`));
-    },
-  },
-  promote: {
-    summary: 'Promote a user to ADMIN',
-    usage: 'motherbase users promote <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/promote`);
-      output(ctx, data, (d, ui) => ui.success(`Promoted ${id}`));
-    },
-  },
-  demote: {
-    summary: 'Demote a user to USER',
-    usage: 'motherbase users demote <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/demote`);
-      output(ctx, data, (d, ui) => ui.success(`Demoted ${id}`));
-    },
-  },
-  'revoke-sessions': {
-    summary: 'Revoke all sessions for a user',
-    usage: 'motherbase users revoke-sessions <id>',
-    async run(ctx, args) {
-      const id = requireArg(args[0], 'id');
-      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/revoke-sessions`);
-      output(ctx, data, (d, ui) => ui.success(`Sessions revoked for ${id}`));
-    },
-  },
-  audit: {
-    summary: 'Read the auth audit log, newest first',
-    usage: 'motherbase users audit [--action <a>] [--actor <email|id>] [--type <log type>] [--from <iso>] [--to <iso>] [--limit <n>]',
-    async run(ctx, args, flags) {
-      const query = {
-        action: flags.action,
-        actor: flags.actor,
-        log_type: flags.type,
-        from: flags.from,
-        to: flags.to,
-        per_page: flags.limit || 50,
-      };
-      const data = await api.adminRequest(ctx, 'GET', '/auth/audit-logs', { query });
-      const entries = ((data && data.entries) || []).map(e => ({
-        at: e.created_at,
-        action: e.payload.action,
-        actor: e.payload.actor_username || e.payload.actor_id,
-        ip: e.ip_address,
-      }));
-      output(ctx, data, (_d, ui) =>
-        ui.table(entries, [
-          { key: 'at', label: 'AT' },
-          { key: 'action', label: 'ACTION' },
-          { key: 'actor', label: 'ACTOR' },
-          { key: 'ip', label: 'IP' },
-        ]),
-      );
-    },
-  },
-};
-
-module.exports = {
-  summary: 'Project auth users',
-  usage: 'motherbase users <list|get|create|update|delete|reset-password|promote|demote|revoke-sessions|audit> ...',
-  subcommands,
-};
+'use strict';
+
+const api = require('../api');
+const { output, requireArg } = require('./_util');
+const { CliError } = require('../context');
+
+// Collect known user fields from flags into a body.
+function userBody(flags) {
+  const body = {};
+  for (const key of ['email', 'password', 'name', 'role']) {
+    if (flags[key] !== undefined) body[key] = flags[key];
+  }
+  return body;
+}
+
+const subcommands = {
+  list: {
+    summary: 'List project users',
+    usage: 'motherbase users list',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/users');
+      const users = (data && data.users) || data || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(Array.isArray(users) ? users : [], [
+          { key: 'id', label: 'ID' },
+          { key: 'email', label: 'EMAIL' },
+          { key: 'role', label: 'ROLE' },
+        ]),
+      );
+    },
+  },
+  get: {
+    summary: 'Get a user by id',
+    usage: 'motherbase users get <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'GET', `/users/${id}`);
+      output(ctx, data, (d, ui) => ui.keyValue(d || {}));
+    },
+  },
+  create: {
+    summary: 'Create a user',
+    usage: 'motherbase users create --email <e> --password <p> [--name <n>] [--role <r>]',
+    async run(ctx, args, flags) {
+      const body = userBody(flags);
+      if (!body.email || !body.password) throw new CliError('--email and --password are required');
+      const data = await api.adminRequest(ctx, 'POST', '/users', { body });
+      output(ctx, data, (d, ui) => ui.success(`Created user ${body.email}`));
+    },
+  },
+  update: {
+    summary: 'Update a user',
+    usage: 'motherbase users update <id> [--email ...] [--name ...] [--role ...]',
+    async run(ctx, args, flags) {
+      const id = requireArg(args[0], 'id');
+      const body = userBody(flags);
+      const data = await api.adminRequest(ctx, 'PATCH', `/users/${id}`, { body });
+      output(ctx, data, (d, ui) => ui.success(`Updated user ${id}`));
+    },
+  },
+  delete: {
+    summary: 'Delete a user',
+    usage: 'motherbase users delete <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'DELETE', `/users/${id}`);
+      output(ctx, data, (d, ui) => ui.success(`Deleted user ${id}`));
+    },
+  },
+  'reset-password': {
+    summary: 'Reset a user password',
+    usage: 'motherbase users reset-password <id> [--password <p>]',
+    async run(ctx, args, flags) {
+      const id = requireArg(args[0], 'id');
+      const body = typeof flags.password === 'string' ? { password: flags.password } : {};
+      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/reset-password`, { body });
+      output(ctx, data, (d, ui) => ui.success(`Password reset for ${id}`));
+    },
+  },
+  promote: {
+    summary: 'Promote a user to ADMIN',
+    usage: 'motherbase users promote <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/promote`);
+      output(ctx, data, (d, ui) => ui.success(`Promoted ${id}`));
+    },
+  },
+  demote: {
+    summary: 'Demote a user to USER',
+    usage: 'motherbase users demote <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/demote`);
+      output(ctx, data, (d, ui) => ui.success(`Demoted ${id}`));
+    },
+  },
+  'revoke-sessions': {
+    summary: 'Revoke all sessions for a user',
+    usage: 'motherbase users revoke-sessions <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'POST', `/users/${id}/revoke-sessions`);
+      output(ctx, data, (d, ui) => ui.success(`Sessions revoked for ${id}`));
+    },
+  },
+  audit: {
+    summary: 'Read the auth audit log, newest first',
+    usage: 'motherbase users audit [--action <a>] [--actor <email|id>] [--type <log type>] [--from <iso>] [--to <iso>] [--limit <n>]',
+    async run(ctx, args, flags) {
+      const query = {
+        action: flags.action,
+        actor: flags.actor,
+        log_type: flags.type,
+        from: flags.from,
+        to: flags.to,
+        per_page: flags.limit || 50,
+      };
+      const data = await api.adminRequest(ctx, 'GET', '/auth/audit-logs', { query });
+      const entries = ((data && data.entries) || []).map(e => ({
+        at: e.created_at,
+        action: e.payload.action,
+        actor: e.payload.actor_username || e.payload.actor_id,
+        ip: e.ip_address,
+      }));
+      output(ctx, data, (_d, ui) =>
+        ui.table(entries, [
+          { key: 'at', label: 'AT' },
+          { key: 'action', label: 'ACTION' },
+          { key: 'actor', label: 'ACTOR' },
+          { key: 'ip', label: 'IP' },
+        ]),
+      );
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Project auth users',
+  usage: 'motherbase users <list|get|create|update|delete|reset-password|promote|demote|revoke-sessions|audit> ...',
+  subcommands,
+};

package/src/context.js

@@ -36,9 +36,13 @@ function createContext(flags = {}, env = process.env, cwd = process.cwd()) {
   );
   const normConsoleUrl = consoleUrl ? config.normalizeUrl(consoleUrl) : undefined;
 
+  // The link file is committed to the repo, so a URL that came only from it is
+  // not trusted with a token the user supplied for some other console.
+  const urlFromLinkOnly = !firstDefined(flags.url, env.MOTHERBASE_CONSOLE_URL) && Boolean(link.consoleUrl);
+
   const token = firstDefined(
-    flags.token,
-    env.MOTHERBASE_TOKEN,
+    urlFromLinkOnly ? undefined : flags.token,
+    urlFromLinkOnly ? undefined : env.MOTHERBASE_TOKEN,
     normConsoleUrl ? (config.consoleEntry(normConsoleUrl) || {}).token : undefined,
   );
 

package/src/docs.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Renders the command registry as the Markdown table published in the docs.
+//
+// `main.js` already builds every help screen from `registry` + `groups`, so the
+// terminal could never disagree with the code. The published CLI reference
+// could, and did: thirteen whole groups (`orgs`, `branches`, `domains`,
+// `vanity-subdomains`, `backups`, `test`, `postgres-config`, `queues`, `vault`,
+// `wrappers`, `network-restrictions`, `ssl-enforcement`, `snippets`) existed in
+// `motherbase --help` and not in the reference, so the documented CLI was a
+// strict subset of the shipped one.
+//
+// Writing it from the same two objects the help screens use is what stops that
+// happening again. `scripts/generate-cli-docs.js` writes the file;
+// `test/docs.test.js` fails when the committed copy no longer matches.
+
+const { registry, groups } = require('./commands');
+
+/** Escape the pipe so a usage string containing one cannot break the table. */
+const cell = value => String(value ?? '').replace(/\|/g, '\\|');
+
+/** `motherbase db sql -e <sql>` → `` `motherbase db sql` `` plus its arguments. */
+function usageCell(usage) {
+  return usage ? `\`${cell(usage)}\`` : '—';
+}
+
+/**
+ * Commands in group order, then whatever the registry holds that no group
+ * names. A command with no group still renders: adding one to the registry and
+ * forgetting the group list must not make it vanish from the docs.
+ */
+function sections() {
+  const grouped = new Set(groups.flatMap(group => group.names));
+  const ungrouped = Object.keys(registry).filter(name => !grouped.has(name));
+  const all = groups.map(group => ({ title: group.title, names: group.names }));
+  if (ungrouped.length) all.push({ title: 'Ungrouped', names: ungrouped });
+  return all;
+}
+
+function renderCommandDocs() {
+  const lines = [
+    '<!-- GENERATED by `npm run docs:cli` from packages/cli/src/commands. Do not edit by hand. -->',
+    '',
+  ];
+
+  for (const section of sections()) {
+    const entries = section.names.map(name => [name, registry[name]]).filter(([, entry]) => entry);
+    if (!entries.length) continue;
+
+    lines.push(`### ${section.title}`, '');
+    lines.push('| Command | Usage | What it does |');
+    lines.push('|---|---|---|');
+
+    for (const [name, entry] of entries) {
+      lines.push(`| \`${cell(name)}\` | ${usageCell(entry.usage)} | ${cell(entry.summary)} |`);
+      for (const [sub, subEntry] of Object.entries(entry.subcommands ?? {})) {
+        lines.push(
+          `| \`${cell(name)} ${cell(sub)}\` | ${usageCell(subEntry.usage)} | ${cell(subEntry.summary)} |`,
+        );
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderCommandDocs };