@deepsql/mcp 0.10.1 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",

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 = {
@@ -36,128 +37,379 @@ 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"],
+  ["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"],
+    ],
+  },
+
+  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: {} };
@@ -264,15 +516,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 +543,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 +570,4 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   }
 }
 
-module.exports = { main, parseArgs, buildOpts };
+module.exports = { main, parseArgs, buildOpts, renderRootHelp, renderCommandHelp, COMMAND_HELP };

package/src/cli.test.js

@@ -3,7 +3,18 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 
-const { parseArgs, buildOpts } = require("./cli");
+const { parseArgs, buildOpts, main, renderRootHelp, renderCommandHelp, COMMAND_HELP } = require("./cli");
+
+function captureStreams() {
+  let out = "";
+  let err = "";
+  return {
+    stdout: { write: (s) => { out += s; }, isTTY: false },
+    stderr: { write: (s) => { err += s; }, isTTY: false },
+    out: () => out,
+    err: () => err,
+  };
+}
 
 test("parseArgs collects positional args", () => {
   const { positional, flags } = parseArgs(["how", "many", "rows"]);
@@ -36,3 +47,72 @@ test("buildOpts maps known flags", () => {
   assert.equal(opts.limit, "50");
   assert.deepEqual(opts.positional, ["SELECT 1"]);
 });
+
+test("renderRootHelp lists every command and marks subcommand-bearing ones with *", () => {
+  const text = renderRootHelp(false);
+  assert.match(text, /🐬 DeepSQL/);
+  assert.match(text, /Hint: commands suffixed with \* have subcommands/);
+  // Leaf command — no star.
+  assert.match(text, /\n\s+login\s+ /);
+  // Parent commands — must carry a star.
+  for (const name of ["config", "connections", "digest", "users", "access", "permissions", "slow-queries"]) {
+    assert.match(text, new RegExp(`\\n\\s+${name} \\*`), `expected "${name} *" in root help`);
+  }
+});
+
+test("renderCommandHelp emits subcommands and options for parent commands", () => {
+  const text = renderCommandHelp("connections", false);
+  assert.match(text, /Usage: deepsql connections/);
+  assert.match(text, /Subcommands:/);
+  assert.match(text, /Options:/);
+  assert.match(text, /list \[--json\]/);
+});
+
+test("every command in the catalog has a COMMAND_HELP entry", () => {
+  // Sourced from the dispatcher map so the lists stay in lockstep.
+  const { main: _main } = require("./cli");
+  void _main;
+  const expected = [
+    "login","logout","whoami","config","mcp","connections","query","explain","schema",
+    "digest","brain-context","business-rules","relationships","anti-patterns",
+    "users","access","permissions","slow-queries","setup",
+  ];
+  for (const name of expected) {
+    assert.ok(COMMAND_HELP[name], `missing COMMAND_HELP for ${name}`);
+    assert.ok(COMMAND_HELP[name].usage, `missing usage for ${name}`);
+  }
+});
+
+test("main prints root help on no args and on --help", async () => {
+  for (const argv of [[], ["--help"], ["-h"]]) {
+    const io = captureStreams();
+    const code = await main(argv, io);
+    assert.equal(code, 0);
+    assert.match(io.out(), /Usage: deepsql \[options\] \[command\]/);
+  }
+});
+
+test("main prints per-command help when --help follows the command", async () => {
+  const io = captureStreams();
+  const code = await main(["connections", "--help"], io);
+  assert.equal(code, 0);
+  assert.match(io.out(), /Usage: deepsql connections/);
+  assert.match(io.out(), /Subcommands:/);
+});
+
+test("main rejects unknown commands and shows the root help", async () => {
+  const io = captureStreams();
+  const code = await main(["nope-not-real"], io);
+  assert.equal(code, 2);
+  assert.match(io.err(), /Unknown command: nope-not-real/);
+  assert.match(io.err(), /Usage: deepsql/);
+});
+
+test("--no-color suppresses ANSI escapes in help output", async () => {
+  const io = captureStreams();
+  // Force a TTY so the only thing turning color off is --no-color itself.
+  io.stdout.isTTY = true;
+  await main(["--help", "--no-color"], io);
+  // No ESC bytes anywhere.
+  assert.equal(/\x1b\[/.test(io.out()), false, "help output should be plain when --no-color is set");
+});

package/CLAUDE.md

@@ -1,330 +0,0 @@
-# DeepSQL — guidance for AI agents (Claude Code / Cursor / Codex / etc.)
-
-> Read this file before invoking DeepSQL tools. It exists because there are
-> **two surfaces** (MCP tools + CLI commands) that look similar and agents
-> tend to pick the wrong one or use the right one inefficiently.
-
-DeepSQL is an autonomous database performance assistant. It exposes itself
-to AI agents in two ways:
-
-| Surface | Where it lives | When you use it |
-|---|---|---|
-| **MCP tools** (programmatic) | The stdio server you connected via `deepsql mcp` | Default. You're an MCP client and these are first-class tool calls. |
-| **CLI** (`deepsql` binary) | The user's `$PATH`, invoked via Bash | Only when an MCP tool can't do it (admin ops, auth, multi-step user flows) **or** the user explicitly asked you to "run `deepsql ...`". |
-
-If you have both available, **prefer MCP tools.** They're structured, typed,
-faster, and don't depend on the user's shell environment.
-
----
-
-## Decision tree — "I want to..."
-
-```
-1. Find which databases I can query
-   → list_connections          (returns id, name, type for each)
-
-2. Understand a database's structure
-   → get_brain_context         (RAG retrieval — best when you have a
-                                natural-language question; returns ranked
-                                tables/columns/FKs/docs/business rules)
-   → get_schema                (full deterministic schema dump — when you
-                                need every table; expensive on large DBs)
-   → get_database_objects      (tables/views/functions/procedures only)
-
-3. Answer a business question about data
-   → get_brain_context first   (retrieves what tables hold what, FK edges,
-                                business rules; gives you grounded context)
-   → then construct SQL yourself, then:
-   → explain_readonly_sql      (validate the plan)
-   → execute_readonly_sql      (run it)
-
-4. Find inferred relationships between tables
-   → get_relationships         (returns FK candidates with confidence scores)
-
-5. Read business rules / data-access policies
-   → list_business_rules       (active rules + guardrails for a connection;
-                                pass `question` to scope to relevant ones)
-
-6. Find anti-patterns
-   → get_anti_patterns kind=table   (schema/structural anti-patterns)
-   → get_anti_patterns kind=query   (slow/expensive query patterns)
-
-7. Investigate slow queries
-   → analyze_slow_queries      (recent slow queries with fingerprints + ms)
-
-8. Run SQL to inspect data
-   → execute_readonly_sql      (read-only — backend rejects mutations)
-```
-
-**Rule of thumb for question-answering:** start with `get_brain_context`,
-not `execute_readonly_sql`. The brain context tells you which tables matter,
-their FKs, what the columns mean, and what business rules apply. Skipping
-straight to SQL is how you write queries against the wrong tables.
-
----
-
-## MCP tool reference (10 tools)
-
-Every tool requires a `connectionId` (string UUID) **except** `list_connections`.
-Always call `list_connections` first if you don't already know the ID.
-
-### Discovery
-
-#### `list_connections`
-- **Args:** none
-- **Returns:** array of `{ id, connectionName, databaseType, ... }`
-- **Use when:** the user mentions a DB by name and you need its ID, or you
-  don't know which DBs are available.
-
-#### `get_schema(connectionId)`
-- **Returns:** the cached schema metadata for the whole DB.
-- **Use when:** you need an exhaustive listing. **Avoid** when the DB is
-  large (hundreds of tables) — `get_brain_context` ranks the relevant
-  subset much faster.
-
-#### `get_database_objects(connectionId)`
-- **Returns:** tables, views, functions, procedures.
-- **Use when:** the user asks "what views/functions exist?" — narrower
-  than `get_schema`.
-
-### RAG / brain retrieval (preferred for question-answering)
-
-#### `get_brain_context(connectionId, question, topK?)`
-- **Args:**
-  - `question` — natural-language question used for retrieval ranking
-  - `topK` (optional, 1–100) — when provided, returns ranked diagnostic
-    snippets (good for "show me the top 5 most relevant tables"). When
-    omitted, returns the rich training-context payload (tables + columns
-    + FKs + business rules + docs assembled for prompt-grounding).
-- **Use when:** the user asks any analytical question. This is the cheapest
-  way to ground yourself before generating SQL.
-- **Output:** typically includes `trainingContext` (text block ready to feed
-  into your own context window) plus structured ranked results.
-
-#### `list_business_rules(connectionId, question?)`
-- **Returns:** `activeRules` + `applicableGuardrails` + `guardrailContext`.
-- **Use when:** before generating SQL that touches sensitive entities. If
-  the rules say "PII columns are blocked," respect that in your output.
-  Pass `question` to filter to rules applicable to the user's intent.
-
-#### `get_relationships(connectionId)`
-- **Returns:** array of `{ sourceTable, sourceColumn, targetTable, targetColumn, confidence, inferenceMethod, validationStatus }`.
-- **Use when:** writing JOINs and the actual FK constraint isn't declared
-  in the schema. Anything `confidence >= 0.8` is safe; lower confidence
-  means inferred from naming patterns or data — verify with the user.
-
-#### `get_anti_patterns(connectionId, kind?, limit?)`
-- **`kind="table"` (default):** schema-level anti-patterns (missing
-  indexes, wide tables, etc.).
-- **`kind="query":** query-level patterns; pass `limit` (1–500).
-- **Use when:** the user asks "what's wrong with this DB?" or you've
-  generated a query and want to sanity-check it.
-
-### Operations
-
-#### `analyze_slow_queries(connectionId, thresholdMs?, limit?)`
-- **Args:** `thresholdMs` defaults 100, `limit` defaults 10.
-- **Returns:** recent slow queries from `pg_stat_statements` with
-  fingerprints, durations, example statements.
-- **Use when:** the user asks "what's slow?" or you're triaging a
-  performance incident.
-
-### Execution
-
-#### `execute_readonly_sql(connectionId, query, limit?, timeoutSeconds?)`
-- **Read-only enforced at four layers:** client SQL parser, backend SQL
-  parser, per-connection ACL on the calling user's token, and the DB
-  role itself usually only has SELECT/EXPLAIN. Mutations (INSERT, UPDATE,
-  DELETE, DDL, etc.) are rejected — **don't try to work around this**.
-- **Multi-statement SQL is rejected** in phase 1. Send one statement.
-- **Defaults:** 100-row `limit`, backend default `timeoutSeconds`.
-- **Use when:** you've grounded yourself with `get_brain_context` and need
-  to fetch concrete numbers.
-
-#### `explain_readonly_sql(connectionId, query)`
-- **Don't include `EXPLAIN` in the query string** — the tool wraps it.
-  `ANALYZE` is also rejected (read-only).
-- **Use when:** you want to validate a plan before running it, or you're
-  diagnosing why a query is slow.
-
----
-
-## CLI commands (run via Bash, only when MCP isn't enough)
-
-The CLI exposes the same data plane plus admin operations the MCP server
-deliberately doesn't expose. **Only run CLI commands when the user explicitly
-asks you to**, or when an MCP tool can't do what's needed (admin, auth,
-multi-step flows).
-
-### Quick reference
-
-```
-# Auth (the user typically did this once; don't re-run unless asked)
-deepsql login --url https://<host>
-deepsql whoami
-deepsql logout
-
-# Connections — the human's "active DB" pin (CLI-only; MCP tools don't read this)
-deepsql connections list                     # marks active with *
-deepsql connections use <name>               # pin
-deepsql connections current                  # show pinned
-deepsql connections unset
-
-# Read-only data ops (mirror MCP tools — same backend, same guardrails)
-deepsql query "SELECT ..." --connection <name>
-deepsql explain "SELECT ..." --connection <name>
-deepsql schema [tables|objects] --connection <name>
-
-# Brain / RAG (mirror the MCP brain tools)
-deepsql brain-context "<question>" --connection <name> [--top-k N]
-deepsql business-rules --connection <name> [--question "..."]
-deepsql relationships --connection <name>
-deepsql anti-patterns --connection <name> [--kind table|query] [--limit N]
-
-# Slack daily digest
-deepsql digest [N] --connection <name>
-
-# Slow-query operations
-deepsql slow-queries latest --connection <name>
-deepsql slow-queries history --connection <name> [N]
-deepsql slow-queries analyze --connection <name>
-deepsql slow-queries optimize --connection <name> --query-id <id>   # SSE stream
-
-# Admin (require ADMIN role)
-deepsql users list | get | add | set-role | lock | unlock | disable | delete
-deepsql access list | grant | revoke | policy
-deepsql permissions list | override | reset
-deepsql setup [--skip-email] [--skip-slack]   # post-install wizard
-```
-
-### When CLI is the right call (vs MCP)
-
-- The user said "run `deepsql ...`" or "use the CLI."
-- The operation is admin (`users`, `access`, `permissions`, `setup`) — these
-  aren't exposed via MCP intentionally.
-- The user wants Slack digest content (`digest`).
-- You're in a script context where structured stdin/stdout is preferable.
-
-### When CLI is the **wrong** call
-
-- For everything in the decision tree above. The MCP equivalents are
-  faster and don't depend on the user's `$PATH`, env, or saved auth.
-- For executing SQL the user is paying you to write — use
-  `execute_readonly_sql`, not `Bash("deepsql query ...")`.
-
----
-
-## Common mistakes — and how to avoid them
-
-### ❌ Generating SQL without retrieving brain context first
-The user asks: *"How many active customers do we have?"*
-
-**Wrong:** call `execute_readonly_sql("SELECT COUNT(*) FROM customers WHERE active = true")` —
-guesses at the table name (`customers` vs `dim_customer` vs `users`),
-guesses at the column (`active` vs `is_active` vs `status='ACTIVE'`),
-ignores any business rule that defines what "active" means.
-
-**Right:**
-1. `get_brain_context(connectionId, "how many active customers")` — returns the
-   right table (`dim_customer`) and the column convention.
-2. `list_business_rules(connectionId, "active customers")` — returns the rule
-   if "active" has a workspace-specific definition.
-3. Generate SQL using the names + rules from #1 and #2.
-4. `explain_readonly_sql(...)` — sanity check.
-5. `execute_readonly_sql(...)` — run it.
-
-### ❌ Calling `get_schema` on every analysis question
-`get_schema` returns the entire DB. On a 200-table OLAP warehouse that's a
-huge response and most of it is irrelevant to the question. **Use
-`get_brain_context` for question-scoped retrieval.** Reserve `get_schema`
-for exhaustive listing tasks.
-
-### ❌ Trying to mutate data
-Every execution path is read-only. INSERT/UPDATE/DELETE/CREATE/DROP/ALTER/
-TRUNCATE are all rejected at the SQL parser layer. If the user asks for a
-mutation, **stop and tell them DeepSQL is read-only**, then offer to draft
-the SQL for them to run themselves.
-
-### ❌ Forgetting the connectionId
-Every tool except `list_connections` requires it. If the user mentions a DB
-by name (e.g., "look at prod-replica"), call `list_connections` first to
-resolve the name → UUID. Don't guess.
-
-### ❌ Re-fetching context on every turn
-Schema and brain context don't change minute-to-minute. If you already
-called `get_brain_context` for a related question this conversation, reuse
-the result. Don't re-call unless the question has shifted topics.
-
-### ❌ Mixing CLI invocations and MCP tool calls in the same session
-Pick one. If you have MCP available, stay in MCP. If you only have Bash,
-use the CLI. Mixing forces the user to debug two surfaces.
-
-### ❌ Calling `analyze_slow_queries` and immediately querying the slow-query log table directly
-The MCP tool already does the right query against `pg_stat_statements` (or
-the equivalent for MySQL) with the right thresholds. Don't reinvent it.
-
----
-
-## Output handling tips
-
-- **`get_brain_context` returns a `trainingContext` text block.** It's
-  designed to drop into your prompt as-is. Don't summarize it before
-  generating SQL — let the structured names flow through.
-- **`execute_readonly_sql` returns `{ result: { columns, rows, rowCount, totalRowCount, isLimited, ... }, success, queryType }`.**
-  `rows` is array-of-arrays (column-positional), not array-of-objects. The
-  CLI's `query` command renders this; if you're consuming the structured
-  response yourself, zip `columns` and `rows[i]` to get an object.
-- **`explain_readonly_sql` returns the plan as JSON.** Postgres-style
-  textual EXPLAIN is in `plan` if available; structured form may be
-  alongside.
-- **`analyze_slow_queries` returns slow queries with fingerprints, not raw
-  SQL.** Fingerprints are normalized (`?` for literals). Use the
-  `queryId` to feed back into `optimize` flows.
-
----
-
-## Multi-database situations
-
-DeepSQL doesn't support cross-connection JOINs at the SQL layer. If the user
-asks a question that spans DBs:
-
-1. Call `list_connections` to enumerate.
-2. For each relevant DB, call `get_brain_context` and/or `execute_readonly_sql`.
-3. Combine the results in your reasoning, not in SQL.
-
-The CLI's "active connection" pin (`deepsql connections use`) is **not** read
-by MCP tools — it only saves typing for human CLI users. As an MCP client,
-always pass `connectionId` explicitly per call.
-
----
-
-## Authentication & security model
-
-You don't need to manage auth — the MCP server was launched with a saved
-token from `~/.config/deepsql/auth.json`. Every tool call carries that
-token. The token is bound to a specific user identity:
-
-- The user's role and per-connection ACLs are enforced **server-side**.
-  If you call a tool and get an authorization error, surface it to the
-  user — don't retry with different parameters.
-- The user may have **chat-access policies** (plain-English rules
-  attached to a connection). The brain context already reflects them; if
-  a query you generate triggers a policy violation, the backend rejects
-  it. Trust the rejection and ask the user how to proceed.
-- **Read-only is enforced at four independent layers** (client parser,
-  backend parser, per-connection ACL, DB role). Don't try to bypass any of
-  them — each rejection is a real signal that the operation isn't safe.
-
----
-
-## When in doubt
-
-1. Call `list_connections` first if you don't have a connectionId.
-2. Call `get_brain_context` second if you have a question.
-3. Generate your SQL using the names and rules from those calls.
-4. Call `explain_readonly_sql` if performance matters.
-5. Call `execute_readonly_sql` last.
-
-That five-step flow handles 80% of legitimate analytical workloads. Anything
-that doesn't fit this pattern probably warrants asking the user a
-clarifying question instead of guessing.