@deepsql/mcp 0.6.0 → 0.10.0

package/deepsql-phase1-lib.js

@@ -66,29 +66,104 @@ const TOOL_DEFINITIONS = [
     },
   },
   {
-    name: "answer_question",
-    description: "Ask DeepSQL a natural-language database question using the full chat pipeline.",
+    name: "get_brain_context",
+    description:
+      "Retrieve DeepSQL's brain context for a question: relevant tables, columns, FKs, training docs, business rules, anti-patterns, and embedding-ranked snippets. Use this to give your own coding agent the same retrieval context the DeepSQL agent uses, then have your agent generate the SQL/answer.",
     inputSchema: {
       type: "object",
       properties: {
-        connectionId: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        question: {
           type: "string",
-          description: "DeepSQL connection ID.",
+          description: "Natural-language question used for retrieval ranking.",
+        },
+        topK: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description:
+            "Optional retrieval breadth. When provided, returns ranked diagnostic results from /training/retrieve; otherwise returns the rich /training/context payload.",
         },
+      },
+      required: ["connectionId", "question"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_business_rules",
+    description:
+      "List active business rules and SQL guardrails for a connection. Optional `question` filters to rules applicable to that question.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
         question: {
           type: "string",
-          description: "Natural-language database question.",
+          description: "Optional natural-language question to scope rules.",
         },
-        chatId: {
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_relationships",
+    description:
+      "Get inferred and validated foreign-key relationships for a connection (source/target table+column with confidence and inference method).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_anti_patterns",
+    description:
+      "Get DeepSQL-detected anti-patterns. `kind=table` returns table/schema-level anti-patterns; `kind=query` returns query-level anti-patterns (with optional limit).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        kind: {
           type: "string",
-          description: "Optional DeepSQL chat ID for conversation continuity.",
+          enum: ["table", "query"],
+          description: "Which anti-pattern catalog to fetch. Defaults to 'table'.",
         },
-        userId: {
-          type: "string",
-          description: "Optional user ID for attribution in feedback/history.",
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 500,
+          description: "Optional row limit (only used for kind='query').",
         },
       },
-      required: ["connectionId", "question"],
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "analyze_slow_queries",
+    description:
+      "Analyze recent slow queries for a connection over the last 24 hours, returning fingerprints, durations, and example statements.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        thresholdMs: {
+          type: "number",
+          minimum: 1,
+          description: "Minimum query duration in milliseconds. Defaults to 100.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 500,
+          description: "Maximum queries to return. Defaults to 10.",
+        },
+      },
+      required: ["connectionId"],
       additionalProperties: false,
     },
   },
@@ -374,18 +449,64 @@ function summarizeObjects(payload) {
     : "No database objects were returned.";
 }
 
-function summarizeChat(payload) {
-  const lines = [];
-  if (payload?.chatId) {
-    lines.push(`chatId: ${payload.chatId}`);
+function summarizeBrainContext(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Brain context unavailable.";
   }
-  if (payload?.sql) {
-    lines.push(`sql: ${compactWhitespace(payload.sql)}`);
+  // /training/retrieve diagnostic shape
+  if (Array.isArray(payload?.results) || payload?.totalResults != null) {
+    const total =
+      payload.totalResults ?? (Array.isArray(payload.results) ? payload.results.length : 0);
+    const tableCount = Array.isArray(payload.tablesCovered) ? payload.tablesCovered.length : 0;
+    return `Retrieved ${total} ranked snippet(s) covering ${tableCount} table(s).`;
   }
-  if (payload?.message) {
-    lines.push(`answer: ${payload.message}`);
+  // /training/context rich shape (RetrievedContextResult)
+  const tables = Array.isArray(payload.ragTableNames)
+    ? payload.ragTableNames.length
+    : payload.ragTableNames
+      ? Object.keys(payload.ragTableNames).length
+      : 0;
+  const types = payload.typeCounts
+    ? Object.entries(payload.typeCounts).map(([k, v]) => `${k}=${v}`).join(", ")
+    : "";
+  const intent = payload.retrievalIntent || "n/a";
+  const skipped = payload.skipped ? ` (skipped: ${payload.skipReason || "?"})` : "";
+  return `Brain context: intent=${intent}, topK=${payload.retrievalTopK ?? "?"}, results=${payload.resultCount ?? 0}, tables=${tables}${types ? `, types[${types}]` : ""}${skipped}.`;
+}
+
+function summarizeBusinessRules(payload) {
+  const active = payload?.activeRuleCount ?? (payload?.activeRules?.length ?? 0);
+  const guards = payload?.applicableGuardrailCount ?? (payload?.applicableGuardrails?.length ?? 0);
+  return `Business rules: ${active} active, ${guards} applicable guardrail(s).`;
+}
+
+function summarizeRelationships(payload) {
+  const list = Array.isArray(payload) ? payload : payload?.relationships || [];
+  const high = list.filter((r) => (r.confidence ?? 0) >= 0.8).length;
+  return `${list.length} relationship(s) (${high} high-confidence).`;
+}
+
+function summarizeAntiPatterns(payload, kind) {
+  if (kind === "table") {
+    const tables = payload && typeof payload === "object" ? Object.keys(payload).length : 0;
+    return `Anti-patterns across ${tables} table(s).`;
   }
-  return lines.join("\n");
+  const list = Array.isArray(payload) ? payload : payload?.patterns || [];
+  const sev = list.reduce((acc, p) => {
+    const s = p.severity || "UNKNOWN";
+    acc[s] = (acc[s] || 0) + 1;
+    return acc;
+  }, {});
+  const sevStr = Object.entries(sev).map(([k, v]) => `${k}=${v}`).join(", ");
+  return `${list.length} query anti-pattern(s)${sevStr ? ` (${sevStr})` : ""}.`;
+}
+
+function summarizeSlowQueries(payload) {
+  const list = Array.isArray(payload?.queries) ? payload.queries : [];
+  const total = payload?.totalCount ?? list.length;
+  const avg = payload?.avgDurationMs;
+  const max = payload?.maxDurationMs;
+  return `${total} slow query/queries${avg != null ? `, avg=${avg}ms` : ""}${max != null ? `, max=${max}ms` : ""}.`;
 }
 
 function summarizeQueryResult(payload) {
@@ -405,7 +526,7 @@ function summarizeExplain(payload) {
   return `EXPLAIN completed for ${planType}.`;
 }
 
-function buildToolResult(name, payload) {
+function buildToolResult(name, payload, extra = {}) {
   let summary;
 
   switch (name) {
@@ -418,8 +539,20 @@ function buildToolResult(name, payload) {
     case "get_database_objects":
       summary = summarizeObjects(payload);
       break;
-    case "answer_question":
-      summary = summarizeChat(payload);
+    case "get_brain_context":
+      summary = summarizeBrainContext(payload);
+      break;
+    case "list_business_rules":
+      summary = summarizeBusinessRules(payload);
+      break;
+    case "get_relationships":
+      summary = summarizeRelationships(payload);
+      break;
+    case "get_anti_patterns":
+      summary = summarizeAntiPatterns(payload, extra.kind || "table");
+      break;
+    case "analyze_slow_queries":
+      summary = summarizeSlowQueries(payload);
       break;
     case "execute_readonly_sql":
       summary = summarizeQueryResult(payload);
@@ -484,23 +617,84 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
-    case "answer_question": {
+    case "get_brain_context": {
       const connectionId = String(args.connectionId || "").trim();
       const question = String(args.question || "").trim();
-      const chatId = args.chatId ? String(args.chatId) : null;
-      const userId = args.userId ? String(args.userId) : config.defaultUserId;
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!question) return buildToolError("question is required.");
+
+      // Route based on whether the caller wants ranked diagnostics (topK) or
+      // the rich training-context payload.
+      let payload;
+      if (args.topK != null) {
+        const topK = clampInteger(args.topK, 1, 100, 20);
+        const path =
+          `/training/retrieve/${encodeURIComponent(connectionId)}` +
+          `?q=${encodeURIComponent(question)}&topK=${topK}`;
+        payload = await callDeepSqlApi(config, path);
+      } else {
+        payload = await callDeepSqlApi(
+          config,
+          `/training/context/${encodeURIComponent(connectionId)}`,
+          { method: "POST", json: { question } },
+        );
+      }
+      return buildToolResult(name, payload);
+    }
 
-      const payload = await callDeepSqlApi(config, "/chat", {
-        method: "POST",
-        json: {
-          connectionId,
-          message: question,
-          chatId,
-          userId,
-          projectId: config.defaultProjectId,
-        },
-      });
+    case "list_business_rules": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      let path = `/business-rules/connection/${encodeURIComponent(connectionId)}`;
+      if (args.question) {
+        path += `?question=${encodeURIComponent(String(args.question))}`;
+      }
+      const payload = await callDeepSqlApi(config, path);
+      return buildToolResult(name, payload);
+    }
 
+    case "get_relationships": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/inferred-relationships/${encodeURIComponent(connectionId)}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_anti_patterns": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const kind = args.kind === "query" ? "query" : "table";
+      let path;
+      if (kind === "query") {
+        path = `/brain/query-anti-patterns/${encodeURIComponent(connectionId)}`;
+        if (args.limit != null) {
+          path += `?limit=${clampInteger(args.limit, 1, 500, 50)}`;
+        }
+      } else {
+        path = `/brain/table-anti-patterns/${encodeURIComponent(connectionId)}`;
+      }
+      const payload = await callDeepSqlApi(config, path);
+      return buildToolResult(name, payload, { kind });
+    }
+
+    case "analyze_slow_queries": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const params = [];
+      if (args.thresholdMs != null) {
+        params.push(`threshold=${Number(args.thresholdMs)}`);
+      }
+      if (args.limit != null) {
+        params.push(`limit=${clampInteger(args.limit, 1, 500, 10)}`);
+      }
+      const qs = params.length ? `?${params.join("&")}` : "";
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-queries/analyze/${encodeURIComponent(connectionId)}${qs}`,
+      );
       return buildToolResult(name, payload);
     }
 

package/deepsql-phase1-server.js

@@ -193,7 +193,7 @@ class DeepSqlPhase1McpServer {
             },
             serverInfo: SERVER_INFO,
             instructions:
-              "DeepSQL phase 1 MCP exposes read-only database access through DeepSQL. Prefer answer_question for high-level tasks. execute_readonly_sql and explain_readonly_sql reject mutating SQL.",
+              "DeepSQL phase 1 MCP exposes read-only database access plus DeepSQL's brain (retrieved context, business rules, inferred relationships, anti-patterns, slow-query analysis). Prefer get_brain_context to ground SQL/answer generation in retrieved schema knowledge, then call execute_readonly_sql / explain_readonly_sql to validate. Mutating SQL is rejected by both client and backend.",
           });
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.6.0",
+  "version": "0.10.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",
@@ -9,6 +9,8 @@
   "main": "./deepsql-phase1-server.js",
   "files": [
     "README.md",
+    "CLAUDE.md",
+    "AGENT-SETUP.md",
     "bin",
     "src",
     "deepsql-phase1-server.js",

package/src/api/client.js

@@ -8,7 +8,7 @@
  * needs:
  *   - profile-based base URL resolution (not env-only)
  *   - to talk to the unauthenticated /auth/cli endpoints
- *   - to stream responses for `ask`
+ *   - per-call query string composition for brain endpoints
  */
 
 class ApiError extends Error {

package/src/auth/store.js

@@ -11,10 +11,18 @@
  *   {
  *     "default": "http://localhost:8080",
  *     "profiles": {
- *       "<base-url>": { token, username, tokenId, createdAt }
+ *       "<base-url>": {
+ *         token, username, tokenId, createdAt,
+ *         defaultConnection?: "<connection-name-or-uuid>"
+ *       }
  *     }
  *   }
  *
+ * `defaultConnection` is the active connection for commands that need one
+ * (query/explain/schema/digest/slow-queries/brain-*). Set via
+ * `deepsql connections use <name>`. Resolution order in commands:
+ *   --connection flag  →  DEEPSQL_CONNECTION env  →  profile.defaultConnection
+ *
  * The file is written with mode 0600 and the parent dir with 0700. We refuse to
  * read a file with looser perms unless DEEPSQL_INSECURE_AUTH=1 is set, since
  * tokens grant access to the user's databases.
@@ -133,6 +141,27 @@ function defaultBaseUrl() {
   return state.default || null;
 }
 
+function getDefaultConnection(baseUrl) {
+  const profile = getProfile(baseUrl);
+  return profile && profile.defaultConnection ? profile.defaultConnection : null;
+}
+
+function setDefaultConnection(baseUrl, connectionName) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl);
+  if (!state.profiles[key]) {
+    throw new Error(
+      `No profile saved for ${key}. Run \`deepsql login --url ${key}\` first.`,
+    );
+  }
+  if (connectionName == null || connectionName === "") {
+    delete state.profiles[key].defaultConnection;
+  } else {
+    state.profiles[key].defaultConnection = connectionName;
+  }
+  save(state);
+}
+
 function listProfiles() {
   return load();
 }
@@ -141,6 +170,7 @@ module.exports = {
   authFilePath,
   configDir,
   defaultBaseUrl,
+  getDefaultConnection,
   getProfile,
   listProfiles,
   load,
@@ -148,5 +178,6 @@ module.exports = {
   removeProfile,
   save,
   setDefault,
+  setDefaultConnection,
   setProfile,
 };

package/src/auth/store.test.js

@@ -63,6 +63,28 @@ test("auth file is written with mode 0600", { skip: process.platform === "win32"
   });
 });
 
+test("setDefaultConnection round-trips and clearing it removes the field", () => {
+  withTempStore((store) => {
+    store.setProfile("http://x", { token: "t", username: "a" });
+    assert.equal(store.getDefaultConnection("http://x"), null);
+
+    store.setDefaultConnection("http://x", "prod-replica");
+    assert.equal(store.getDefaultConnection("http://x"), "prod-replica");
+
+    store.setDefaultConnection("http://x", null);
+    assert.equal(store.getDefaultConnection("http://x"), null);
+  });
+});
+
+test("setDefaultConnection refuses to write when the profile doesn't exist", () => {
+  withTempStore((store) => {
+    assert.throws(
+      () => store.setDefaultConnection("http://no-such-profile", "x"),
+      /No profile saved/,
+    );
+  });
+});
+
 test("rejects loose perms unless DEEPSQL_INSECURE_AUTH=1", { skip: process.platform === "win32" }, () => {
   withTempStore((store, dir) => {
     store.setProfile("http://localhost:8080", { token: "t", username: "a" });

package/src/cli.js

@@ -9,7 +9,7 @@
  *   - boolean flags:  --json, --device, --browser, --no-browser
  *   - value flags:    --url <url>, --token <t>, --connection <name>, --limit 50
  *   - subcommands:    deepsql connections list, deepsql config show
- *   - positional:     deepsql ask "what tables exist?"
+ *   - positional:     deepsql brain-context "which tables hold orders?"
  */
 
 const COMMANDS = {
@@ -19,10 +19,15 @@ const COMMANDS = {
   config: () => require("./commands/config"),
   mcp: () => require("./commands/mcp"),
   connections: () => require("./commands/connections"),
-  ask: () => require("./commands/ask"),
   query: () => require("./commands/query"),
   explain: () => require("./commands/explain"),
   schema: () => require("./commands/schema"),
+  // Brain tools — give a coding agent the same retrieval context the chat
+  // pipeline uses, then let the agent generate SQL/answers itself.
+  "brain-context": () => require("./commands/brain-context"),
+  "business-rules": () => require("./commands/business-rules"),
+  relationships: () => require("./commands/relationships"),
+  "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
@@ -31,7 +36,11 @@ const COMMANDS = {
   setup: () => require("./commands/setup"),
 };
 
-const HELP = `deepsql — DeepSQL CLI
+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]
@@ -51,15 +60,41 @@ Commands:
   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.
-  ask "<question>" --connection <name> [--chat <id>] [--json]
-                                  Ask DeepSQL a question.
+  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 query.
+                                  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.
+                                  Get an EXPLAIN plan (no ANALYZE — also
+                                  read-only enforced).
   schema [tables|objects] --connection <name>
-                                  Dump schema or database objects as JSON.
+                                  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).
@@ -68,6 +103,24 @@ Commands:
   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>
@@ -98,10 +151,12 @@ Admin commands (require ADMIN role on the calling token):
                                   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).
-  -h, --help      Show help.
-  -v, --version   Show version.
+  --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.
 `;
 
 function parseArgs(argv) {
@@ -182,6 +237,10 @@ function buildOpts(parsed) {
     grant: !!f.grant,
     revoke: !!f.revoke,
     reason: f.reason || null,
+    // Brain tools
+    topK: f.topK ?? null,
+    kind: f.kind || null,
+    question: f.question || null,
     // Slow queries
     timeRange: f.timeRange || null,
     thresholdMs: f.thresholdMs || null,
@@ -196,6 +255,15 @@ function buildOpts(parsed) {
     skipComplete: !!f.skipComplete,
     // Confirmations
     yes: !!f.yes || !!f.y,
+    // Connection management
+    fromFile: f.fromFile || null,
+    fromStdin: !!f.fromStdin,
+    upsert: !!f.upsert,
+    noTest: !!f.noTest,
+    wait: !!f.wait,
+    deleteAfter: !!f.deleteAfter,
+    cloud: !!f.cloud,
+    allowPlaintextSecrets: !!f.allowPlaintextSecrets,
   };
 }
 

package/src/commands/_connections.js

@@ -29,11 +29,34 @@ async function listConnections(session) {
   return cachedList;
 }
 
+/**
+ * Resolution chain for the connection a command should hit:
+ *
+ *   1. explicit `input` argument (i.e. opts.connection from --connection flag)
+ *   2. DEEPSQL_CONNECTION env var
+ *   3. session.defaultConnection (set via `deepsql connections use <name>`)
+ *
+ * If none of those produce a value, throw a friendly message that points the
+ * user at all three escape hatches.
+ */
 async function resolveConnectionId(session, input) {
-  if (!input || typeof input !== "string") {
-    throw new Error("Pass a connection name or id with --connection.");
+  let raw = input;
+  let source = "--connection";
+  if (raw == null || raw === "") {
+    raw = process.env.DEEPSQL_CONNECTION || null;
+    source = "DEEPSQL_CONNECTION";
+  }
+  if (raw == null || raw === "") {
+    raw = session && session.defaultConnection ? session.defaultConnection : null;
+    source = "saved default";
+  }
+  if (!raw || typeof raw !== "string") {
+    throw new Error(
+      "No connection specified. Pass --connection <name>, set DEEPSQL_CONNECTION, " +
+        "or run `deepsql connections use <name>` to pin a default.",
+    );
   }
-  const trimmed = input.trim();
+  const trimmed = raw.trim();
   if (UUID_RE.test(trimmed)) return trimmed;
 
   const connections = await listConnections(session);