@deepsql/mcp 0.10.1 → 0.11.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
-    "deepsql": "./bin/deepsql.js",
-    "deepsql-mcp": "./deepsql-phase1-server.js"
+    "deepsql": "bin/deepsql.js",
+    "deepsql-mcp": "deepsql-phase1-server.js"
   },
   "main": "./deepsql-phase1-server.js",
   "files": [

package/src/cli.js

@@ -10,6 +10,7 @@
  *   - value flags:    --url <url>, --token <t>, --connection <name>, --limit 50
  *   - subcommands:    deepsql connections list, deepsql config show
  *   - positional:     deepsql brain-context "which tables hold orders?"
+ *   - per-command -h/--help: prints that command's usage block.
  */
 
 const COMMANDS = {
@@ -29,6 +30,7 @@ const COMMANDS = {
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  indexes: () => require("./commands/indexes"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
   permissions: () => require("./commands/permissions"),
@@ -36,128 +38,400 @@ const COMMANDS = {
   setup: () => require("./commands/setup"),
 };
 
-const HELP = `deepsql — ask the database what's wrong. It already knows.
-
-Self-hosted AI for database performance: profile slow queries, stream
-live optimization plans, audit access, and run day-to-day admin ops —
-all from the terminal, without leaving your VPC.
-
-Usage:
-  deepsql <command> [options]
-
-Commands:
-  login [--url <url>] [--device|--browser|--password] [--no-browser] [--label <name>]
-        [--email <email>] [--password-stdin]
-                                  Authorize this CLI with a DeepSQL instance.
-                                  Default: browser callback (PKCE), or device-code
-                                  on headless boxes. Use --password for direct
-                                  email+password login on a fresh self-host VM
-                                  with no browser; pipe the password via stdin
-                                  with --password-stdin for non-interactive use.
-  logout [--url <url>]            Revoke and forget the saved token.
-  whoami                          Show the user behind the saved token.
-  config show                     List saved profiles.
-  config set-default <url>        Set the default profile.
-  config path                     Print the auth file path.
-  mcp                             Run the stdio MCP server using the saved token.
-  connections list [--json]       List database connections (active default
-                                  is marked with \`*\`).
-  connections use <name>          Pin <name> as the active default; commands
-                                  drop --connection from then on.
-  connections current             Print the active default (exit 1 if none).
-  connections unset               Clear the active default for this profile.
-  connections schema [--json]     Print the JSON Schema for the connection
-                                  config (the input format for \`add\`).
-  connections add [--from-file <p>] [--from-stdin] [--upsert] [--no-test]
-                  [--wait] [--delete-after] [--cloud]
-                  [--allow-plaintext-secrets]
-                                  Create a connection. Default is interactive
-                                  prompts; use --from-file for AI-agent flows.
-  connections update <name> --from-file <p>
-                                  PATCH-style update; omitted secrets are
-                                  preserved.
-  connections remove <name> [--yes]
-                                  Delete a connection (DELETE /connections).
-  connections test [<name> | --from-file <p>]
-                                  Validate a connection without saving.
-                                  Prints the privilege report.
-  connections show <name> [--json]
-                                  Show a connection's config (secrets masked).
-  connections init <name> [--force] [--wait]
-                                  Trigger brain re-initialization.
-  query "<sql>" --connection <name> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
-                                  Run a read-only SQL statement. Enforced
-                                  read-only at the backend (parser-level) and
-                                  ACL-checked per connection.
-  explain "<sql>" --connection <name> [--file <path>] [--json]
-                                  Get an EXPLAIN plan (no ANALYZE — also
-                                  read-only enforced).
-  schema [tables|objects] --connection <name>
-                                  Dump connection schema or database objects
-                                  as JSON.
-  digest [N] [--connection <name>] [--json]
-                                  Show the latest DeepSQL digest, or pass a
-                                  number to list the last N (e.g. digest 5).
-  digest list [--count N] [--connection <name>] [--json]
-                                  Explicit list form (same as digest <N>).
-  digest show <id> [--connection <name>] [--json]
-                                  Show one digest by id.
-
-Brain commands (give a coding agent DeepSQL's retrieved context — agentless V1):
-  brain-context "<question>" --connection <name> [--top-k <n>] [--json]
-                                  Retrieve embedding-ranked tables/columns/FKs,
-                                  training docs, and business rules for a
-                                  question. With --top-k, returns ranked
-                                  diagnostic snippets; otherwise returns the
-                                  rich training-context payload.
-  business-rules --connection <name> [--question "..."] [--json]
-                                  List active business rules and SQL guardrails
-                                  for a connection (optionally scoped by
-                                  question).
-  relationships --connection <name> [--json]
-                                  Inferred and validated foreign-key
-                                  relationships with confidence scores.
-  anti-patterns --connection <name> [--kind table|query] [--limit <n>] [--json]
-                                  Schema-level (table) or query-level
-                                  anti-patterns detected by the brain.
-
-Admin commands (require ADMIN role on the calling token):
-  users list | get <ref> | add [<email>] [--role <r>] [--name <n>] [--password-stdin]
-        | set-role <ref> <role> | lock|unlock|disable <ref>
-        | resend-invite <ref> | reset-password <ref> [--password-stdin]
-        | delete <ref> [--yes]
-                                  Manage workspace users.
-  access list --user <ref> | --connection <name>
-        | grant   --user <ref> --connection <name> --level read|write|admin
-        | revoke  --user <ref> --connection <name>
-        | policy  <user> <connection>     (opens $EDITOR)
-                                  Per-connection access grants and chat policies.
-  permissions list [--role <ROLE>] [--json]
-        | override --role <ROLE> --permission <PERM> --grant|--revoke [--reason "..."]
-        | reset    --role <ROLE> --permission <PERM>
-                                  Role-based permission overrides.
-  slow-queries latest --connection <name>
-        | history --connection <name> [N]
-        | analyze --connection <name> [--time-range LAST_24_HOURS|LAST_HOUR]
-                                       [--threshold-ms <n>] [--limit <n>]
-        | optimize --connection <name> --query-id <id>
-                  (streams AI optimization steps to stderr; result to stdout)
-        | delete (--history-id <id> | --connection <name>) [--yes]
-                                  Read, trigger, and clean up slow-query analyses.
-  setup [--skip-email] [--skip-slack] [--skip-complete]
-                                  Post-install wizard: SMTP/email, Slack
-                                  (digests + bot), then mark setup complete.
-                                  Org and LLM config are set at install time
-                                  and are NOT touched by this wizard.
-
-Global options:
-  --url <url>           Override the DeepSQL base URL.
-  --token <tok>         Override the auth token (also: DEEPSQL_AUTH_TOKEN).
-  --connection <name>   Override the active connection (also: DEEPSQL_CONNECTION,
-                        or pin one with \`deepsql connections use <name>\`).
-  -h, --help            Show help.
-  -v, --version         Show version.
-`;
+// ─── Top-level command catalog (rendered into the root help) ────────────────
+//
+// `sub: true` marks commands that have nested subcommands. They get a `*`
+// suffix in the listing and reveal their full usage via `<command> --help`.
+
+const COMMAND_LIST = [
+  ["login",          false, "Authorize this CLI with a DeepSQL instance"],
+  ["logout",         false, "Revoke and forget the saved token"],
+  ["whoami",         false, "Show the user behind the saved token"],
+  ["config",         true,  "Manage saved CLI profiles"],
+  ["mcp",            false, "Run the stdio MCP server using the saved token"],
+  ["connections",    true,  "Manage database connections"],
+  ["query",          false, "Run a read-only SQL statement"],
+  ["explain",        false, "Get an EXPLAIN plan (no ANALYZE)"],
+  ["schema",         false, "Dump connection schema or DB objects as JSON"],
+  ["digest",         true,  "Show DeepSQL daily digests"],
+  ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
+  ["business-rules", false, "List active business rules and SQL guardrails"],
+  ["relationships",  false, "List inferred and validated FK relationships"],
+  ["anti-patterns",  false, "List schema- or query-level anti-patterns"],
+  ["indexes",        true,  "Index suggestions, usage, and health (read-only)"],
+  ["users",          true,  "Manage workspace users (admin)"],
+  ["access",         true,  "Manage per-connection access grants (admin)"],
+  ["permissions",    true,  "Manage role-based permission overrides (admin)"],
+  ["slow-queries",   true,  "Read, trigger, and stream slow-query analyses (admin)"],
+  ["setup",          false, "Post-install wizard for SMTP/email and Slack"],
+];
+
+const GLOBAL_OPTIONS = [
+  ["--url <url>",         "Override the DeepSQL base URL"],
+  ["--token <tok>",       "Override the auth token (also: DEEPSQL_AUTH_TOKEN)"],
+  ["--connection <name>", "Override the active connection (also: DEEPSQL_CONNECTION)"],
+  ["--no-color",          "Disable ANSI colors"],
+  ["-h, --help",          "Display help for command"],
+  ["-v, --version",       "Show version"],
+];
+
+// ─── Per-command help blocks ────────────────────────────────────────────────
+//
+// Each entry is { description, usage, subcommands?, options?, notes? }.
+// Subcommands and options render as two-column tables (name | description).
+// Centralized here so individual command modules don't each carry a HELP
+// constant; the dispatcher renders them on `<command> --help`.
+
+const COMMAND_HELP = {
+  login: {
+    description: "Authorize this CLI with a DeepSQL instance.",
+    usage: "deepsql login [options]",
+    options: [
+      ["--url <url>",        "DeepSQL base URL to authorize against"],
+      ["--browser",          "Use browser callback (PKCE) — default on desktops"],
+      ["--device",           "Use device-code flow — default on headless boxes"],
+      ["--password",         "Direct email+password login (fresh self-host VMs)"],
+      ["--no-browser",       "Force device-code even on a desktop"],
+      ["--email <email>",    "Email for --password flow"],
+      ["--password-stdin",   "Read password from stdin (non-interactive)"],
+      ["--label <name>",     "Label the saved token for `whoami`"],
+    ],
+  },
+
+  logout: {
+    description: "Revoke and forget the saved token.",
+    usage: "deepsql logout [--url <url>]",
+    options: [
+      ["--url <url>", "Profile to log out of (default: current default profile)"],
+    ],
+  },
+
+  whoami: {
+    description: "Show the user behind the saved token.",
+    usage: "deepsql whoami [--url <url>]",
+  },
+
+  mcp: {
+    description: "Run the stdio MCP server using the saved token.",
+    usage: "deepsql mcp [--url <url>]",
+    notes: "Used by editor MCP configs (Cursor, Claude Desktop) so the config never has to embed a raw token.",
+  },
+
+  config: {
+    description: "Manage saved CLI profiles (one per DeepSQL URL).",
+    usage: "deepsql config <subcommand> [options]",
+    subcommands: [
+      ["show",                "List saved profiles (default)"],
+      ["set-default <url>",   "Set the default profile"],
+      ["path",                "Print the auth file path"],
+    ],
+  },
+
+  connections: {
+    description: "Manage database connections — list, pin, full CRUD.",
+    usage: "deepsql connections <subcommand> [options]",
+    subcommands: [
+      ["list [--json]",                              "List database connections (active default marked with *)"],
+      ["use <name>",                                 "Pin <name> as the active default for this profile"],
+      ["current",                                    "Print the active default (exit 1 if none)"],
+      ["unset",                                      "Clear the active default for this profile"],
+      ["schema [--json]",                            "Print the JSON Schema for the connection config"],
+      ["add [options]",                              "Create a connection (interactive or from JSON)"],
+      ["update <name> --from-file <p>",              "PATCH-style update; omitted secrets preserved"],
+      ["remove <name> [--yes]",                      "Delete a connection (DELETE /connections)"],
+      ["test [<name> | --from-file <p>]",            "Validate a connection without saving"],
+      ["show <name> [--json]",                       "Show a connection's config (secrets masked)"],
+      ["init <name> [--force] [--wait]",             "Trigger brain re-initialization"],
+    ],
+    options: [
+      ["--from-file <p>",            "Read connection JSON from file"],
+      ["--from-stdin",               "Read connection JSON from stdin"],
+      ["--upsert",                   "PUT instead of POST on add if name collision"],
+      ["--no-test",                  "Skip pre-save POST /connections/test"],
+      ["--wait",                     "Poll brain init to COMPLETED/FAILED"],
+      ["--delete-after",             "rm the --from-file path on success"],
+      ["--cloud",                    "Prompt for cloud/instance metadata"],
+      ["--allow-plaintext-secrets",  "Allow plaintext secrets in JSON input"],
+      ["--json",                     "Print JSON output where supported"],
+      ["--yes",                      "Assume yes for confirmations"],
+    ],
+  },
+
+  query: {
+    description: "Run a read-only SQL statement (parser-enforced, ACL-checked).",
+    usage: 'deepsql query "<sql>" --connection <name> [options]',
+    options: [
+      ["--connection <name>",    "Connection to run against"],
+      ["--limit <n>",            "Row limit (1–1000, default 100)"],
+      ["--timeout-seconds <n>",  "Statement timeout in seconds (1–60)"],
+      ["--file <path>",          "Read SQL from a file instead of argv"],
+      ["--json",                 "Raw JSON output"],
+    ],
+  },
+
+  explain: {
+    description: "Get an EXPLAIN plan (no ANALYZE — read-only enforced).",
+    usage: 'deepsql explain "<sql>" --connection <name> [options]',
+    options: [
+      ["--connection <name>", "Connection to run against"],
+      ["--file <path>",       "Read SQL from a file instead of argv"],
+      ["--json",              "Raw JSON output"],
+    ],
+  },
+
+  schema: {
+    description: "Dump connection schema or database objects as JSON.",
+    usage: "deepsql schema [tables|objects] --connection <name>",
+    subcommands: [
+      ["tables",   "Tables, columns, FKs (default)"],
+      ["objects",  "Database objects (views, procedures, etc.)"],
+    ],
+  },
+
+  digest: {
+    description: "Surface the daily DeepSQL digest from the terminal.",
+    usage: "deepsql digest [N|<subcommand>] [options]",
+    subcommands: [
+      ["(no args)",         "Show the most recent digest, full body"],
+      ["<N>",               "List the last N digests, compact"],
+      ["list [--count N]",  "Explicit list form (same as digest <N>)"],
+      ["show <id>",         "Show one digest by id"],
+    ],
+    options: [
+      ["--connection <name>", "Filter to one connection"],
+      ["--json",              "Raw JSON output"],
+    ],
+  },
+
+  "brain-context": {
+    description: "Retrieve embedding-ranked tables/columns/FKs, training docs, and business rules for a question.",
+    usage: 'deepsql brain-context "<question>" --connection <name> [options]',
+    options: [
+      ["--connection <name>", "Connection to retrieve from"],
+      ["--top-k <n>",         "Return ranked diagnostic snippets (else: rich training payload)"],
+      ["--json",              "Raw JSON output"],
+    ],
+  },
+
+  "business-rules": {
+    description: "List active business rules and SQL guardrails for a connection.",
+    usage: "deepsql business-rules --connection <name> [options]",
+    options: [
+      ["--connection <name>", "Connection to inspect"],
+      ['--question "..."',    "Scope rules to a specific question"],
+      ["--json",              "Raw JSON output"],
+    ],
+  },
+
+  relationships: {
+    description: "Inferred and validated foreign-key relationships with confidence scores.",
+    usage: "deepsql relationships --connection <name> [--json]",
+    options: [
+      ["--connection <name>", "Connection to inspect"],
+      ["--json",              "Raw JSON output"],
+    ],
+  },
+
+  "anti-patterns": {
+    description: "Schema-level (table) or query-level anti-patterns detected by the brain.",
+    usage: "deepsql anti-patterns --connection <name> [options]",
+    options: [
+      ["--connection <name>",   "Connection to inspect"],
+      ["--kind table|query",    "Anti-pattern flavor (default: table)"],
+      ["--limit <n>",           "Limit results (query mode)"],
+      ["--json",                "Raw JSON output"],
+    ],
+  },
+
+  indexes: {
+    description: "Index suggestions, usage, and health — read-only in V1.",
+    usage: "deepsql indexes <subcommand> [options]",
+    subcommands: [
+      ["list [--all] [--status <s>]", "Index recommendations (defaults to PENDING)"],
+      ["missing",                     "Missing-index suggestions from the advisor"],
+      ["health",                      "Comprehensive index health report"],
+      ["unused",                      "Indexes the engine has not used"],
+      ["duplicates",                  "Duplicate or redundant indexes"],
+      ["usage <table>",               "Per-table index usage statistics"],
+    ],
+    options: [
+      ["--connection <name>",            "Connection to inspect"],
+      ["--all",                          "Include APPLIED and DISMISSED in `list`"],
+      ["--status PENDING|APPLIED|DISMISSED", "Filter `list` by status"],
+      ["--json",                         "Raw JSON output"],
+    ],
+    notes: "V1 is read-only. Apply, dismiss, delete, and generate are not exposed by the CLI yet.",
+  },
+
+  users: {
+    description: "Manage workspace users (admin).",
+    usage: "deepsql users <subcommand> [options]",
+    subcommands: [
+      ["list [--json]",                   "List all users"],
+      ["get <ref>",                       "Show one user by email or id"],
+      ["add [<email>] [options]",         "Invite or create a user"],
+      ["set-role <ref> <role>",           "Change a user's role"],
+      ["lock <ref>",                      "Lock a user account"],
+      ["unlock <ref>",                    "Unlock a user account"],
+      ["disable <ref>",                   "Disable a user account"],
+      ["resend-invite <ref>",             "Resend an invitation email"],
+      ["reset-password <ref>",            "Reset a user's password"],
+      ["delete <ref> [--yes]",            "Permanently delete a user"],
+    ],
+    options: [
+      ["--role <r>",         "Role for `add` / `set-role`"],
+      ["--name <n>",         "Display name for `add`"],
+      ["--password-stdin",   "Read password from stdin"],
+      ["--json",             "Raw JSON output (list)"],
+      ["--yes",              "Assume yes for confirmations"],
+    ],
+    notes: "All endpoints under /admin/users/** require ROLE_ADMIN.",
+  },
+
+  access: {
+    description: "Per-connection access grants and chat policies (admin).",
+    usage: "deepsql access <subcommand> [options]",
+    subcommands: [
+      ["list --user <ref>",                                          "Connections this user can see"],
+      ["list --connection <name>",                                   "Users who can see this connection"],
+      ["grant --user <ref> --connection <name> --level <lvl>",       "Grant access (read|write|admin)"],
+      ["revoke --user <ref> --connection <name>",                    "Revoke access"],
+      ["policy <user> <connection>",                                 "Edit chat policy in $EDITOR"],
+    ],
+  },
+
+  permissions: {
+    description: "Global role-based permission overrides (admin).",
+    usage: "deepsql permissions <subcommand> [options]",
+    subcommands: [
+      ["list [--role <r>] [--json]",                                                        "List permissions, optionally filtered by role"],
+      ["override --role <r> --permission <p> --grant|--revoke [--reason \"...\"]",  "Override a role's permission"],
+      ["reset --role <r> --permission <p>",                                                 "Remove an override (revert to default)"],
+    ],
+  },
+
+  "slow-queries": {
+    description: "Read, trigger, and stream slow-query analyses (admin).",
+    usage: "deepsql slow-queries <subcommand> [options]",
+    subcommands: [
+      ["latest --connection <name>",                                  "Most recent analysis for the connection"],
+      ["history --connection <name> [N]",                             "Last N analyses"],
+      ["analyze --connection <name> [options]",                       "Trigger a new analysis"],
+      ["optimize --connection <name> --query-id <id>",                "Stream AI optimization steps live (SSE)"],
+      ["delete (--history-id <id> | --connection <name>) [--yes]",    "Clean up history"],
+    ],
+    options: [
+      ["--time-range LAST_24_HOURS|LAST_HOUR", "Window for analyze"],
+      ["--threshold-ms <n>",                   "Min duration to consider"],
+      ["--limit <n>",                          "Cap results"],
+      ["--json",                               "Raw JSON output"],
+    ],
+    notes: "`optimize` follows the SSE protocol from /slow-queries/optimize/stream — step events go to stderr, the final result to stdout. Honors SIGINT.",
+  },
+
+  setup: {
+    description: "Post-install wizard: SMTP/email, Slack (digests + bot), then mark setup complete.",
+    usage: "deepsql setup [options]",
+    options: [
+      ["--skip-email",     "Skip the SMTP/email step"],
+      ["--skip-slack",     "Skip the Slack step"],
+      ["--skip-complete",  "Don't mark setup complete at the end"],
+    ],
+    notes: "Org and LLM config are set at install time and are NOT touched by this wizard.",
+  },
+};
+
+// ─── Color helpers ──────────────────────────────────────────────────────────
+
+function colorEnabled(stream, rawArgv) {
+  if (process.env.NO_COLOR) return false;
+  if (rawArgv && (rawArgv.includes("--no-color") || rawArgv.includes("--no-colors"))) return false;
+  if (process.env.FORCE_COLOR === "1") return true;
+  return !!(stream && stream.isTTY);
+}
+
+function paint(useColor) {
+  if (!useColor) {
+    const id = (s) => s;
+    return { brand: id, accent: id, bold: id, dim: id, reset: "" };
+  }
+  return {
+    brand:  (s) => `\x1b[1;38;5;75m${s}\x1b[0m`,   // bold sky-blue
+    accent: (s) => `\x1b[38;5;75m${s}\x1b[0m`,     // sky-blue
+    bold:   (s) => `\x1b[1m${s}\x1b[0m`,
+    dim:    (s) => `\x1b[2m${s}\x1b[0m`,
+    reset:  "\x1b[0m",
+  };
+}
+
+function pad(str, width) {
+  return str + " ".repeat(Math.max(0, width - str.length));
+}
+
+function renderTable(rows, c, { nameMin = 16, gap = 2 } = {}) {
+  const nameWidth = Math.max(nameMin, ...rows.map((r) => r[0].length));
+  return rows
+    .map(([name, desc]) => `  ${c.accent(pad(name, nameWidth))}${" ".repeat(gap)}${desc}`)
+    .join("\n");
+}
+
+// ─── Renderers ──────────────────────────────────────────────────────────────
+
+function renderRootHelp(useColor) {
+  const c = paint(useColor);
+  const pkg = require("../package.json");
+
+  const header =
+    `${c.brand("🐬 DeepSQL")} ${c.accent(pkg.version)} ` +
+    c.dim("— ask the database what's wrong. It already knows.");
+
+  const usage = `${c.bold("Usage:")} deepsql [options] [command]`;
+
+  const optionsBlock =
+    `${c.bold("Options:")}\n` + renderTable(GLOBAL_OPTIONS, c, { nameMin: 22 });
+
+  const commandRows = COMMAND_LIST.map(([name, hasSub, desc]) => [
+    hasSub ? `${name} *` : name,
+    desc,
+  ]);
+  const commandsBlock =
+    `${c.bold("Commands:")}\n` +
+    `  ${c.dim("Hint: commands suffixed with * have subcommands. Run <command> --help for details.")}\n` +
+    renderTable(commandRows, c, { nameMin: 16 });
+
+  return [header, "", usage, "", optionsBlock, "", commandsBlock, ""].join("\n");
+}
+
+function renderCommandHelp(name, useColor) {
+  const c = paint(useColor);
+  const help = COMMAND_HELP[name];
+  if (!help) {
+    return `${c.bold("deepsql " + name)}\n  No detailed help available — run \`deepsql --help\` for the command list.\n`;
+  }
+
+  const lines = [];
+  lines.push(`${c.brand("deepsql " + name)} ${c.dim("— " + help.description)}`);
+  lines.push("");
+  lines.push(`${c.bold("Usage:")} ${help.usage}`);
+  if (help.subcommands && help.subcommands.length > 0) {
+    lines.push("");
+    lines.push(`${c.bold("Subcommands:")}`);
+    lines.push(renderTable(help.subcommands, c, { nameMin: 24 }));
+  }
+  if (help.options && help.options.length > 0) {
+    lines.push("");
+    lines.push(`${c.bold("Options:")}`);
+    lines.push(renderTable(help.options, c, { nameMin: 24 }));
+  }
+  if (help.notes) {
+    lines.push("");
+    lines.push(c.dim(help.notes));
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ─── Argv parser ────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
   const result = { positional: [], flags: {} };
@@ -248,6 +522,9 @@ function buildOpts(parsed) {
     queryText: f.queryText || null,
     sampleQuery: f.sampleQuery || null,
     historyId: f.historyId || null,
+    // Indexes
+    all: !!f.all,
+    status: f.status || null,
     // Setup wizard
     force: !!f.force,
     skipEmail: !!f.skipEmail,
@@ -264,15 +541,22 @@ function buildOpts(parsed) {
     deleteAfter: !!f.deleteAfter,
     cloud: !!f.cloud,
     allowPlaintextSecrets: !!f.allowPlaintextSecrets,
+    // Display
+    noColor: !!f.noColor,
   };
 }
 
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
+
 async function main(rawArgv = process.argv.slice(2), io = {}) {
   const stderr = io.stderr || process.stderr;
   const stdout = io.stdout || process.stdout;
+  const useColor = colorEnabled(stdout, rawArgv);
 
-  if (rawArgv.length === 0 || rawArgv[0] === "--help" || rawArgv[0] === "-h") {
-    stdout.write(`${HELP}\n`);
+  if (rawArgv.length === 0 || isHelpFlag(rawArgv[0])) {
+    stdout.write(`${renderRootHelp(useColor)}\n`);
     return 0;
   }
   if (rawArgv[0] === "--version" || rawArgv[0] === "-v") {
@@ -284,11 +568,18 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   const command = rawArgv[0];
   const loader = COMMANDS[command];
   if (!loader) {
-    stderr.write(`Unknown command: ${command}\n\n${HELP}\n`);
+    stderr.write(`Unknown command: ${command}\n\n${renderRootHelp(colorEnabled(stderr, rawArgv))}\n`);
     return 2;
   }
 
-  const parsed = parseArgs(rawArgv.slice(1));
+  // Per-command help: `deepsql <command> --help` / `-h` (anywhere in args).
+  const restArgs = rawArgv.slice(1);
+  if (restArgs.some(isHelpFlag)) {
+    stdout.write(`${renderCommandHelp(command, useColor)}\n`);
+    return 0;
+  }
+
+  const parsed = parseArgs(restArgs);
   const opts = buildOpts(parsed);
 
   try {
@@ -304,4 +595,4 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   }
 }
 
-module.exports = { main, parseArgs, buildOpts };
+module.exports = { main, parseArgs, buildOpts, renderRootHelp, renderCommandHelp, COMMAND_HELP };