@deepsql/mcp 0.3.0 → 0.6.0

package/src/commands/admin.test.js

@@ -0,0 +1,135 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { parseArgs, buildOpts } = require("../cli");
+
+function opts(argv) {
+  return buildOpts(parseArgs(argv));
+}
+
+// users -----------------------------------------------------------------------
+
+test("users add positional email + role/name flags", () => {
+  const o = opts(["add", "x@y.com", "--role", "DEVELOPER", "--name", "X"]);
+  assert.deepEqual(o.positional, ["add", "x@y.com"]);
+  assert.equal(o.role, "DEVELOPER");
+  assert.equal(o.name, "X");
+});
+
+test("users delete --yes flag", () => {
+  const o = opts(["delete", "alice@x.com", "--yes"]);
+  assert.equal(o.yes, true);
+  assert.deepEqual(o.positional, ["delete", "alice@x.com"]);
+});
+
+test("users reset-password --password-stdin flag", () => {
+  const o = opts(["reset-password", "alice@x.com", "--password-stdin"]);
+  assert.equal(o.passwordStdin, true);
+  assert.equal(o.password, null); // stays null since it's a separate flag
+});
+
+// access ----------------------------------------------------------------------
+
+test("access grant requires user/connection/level", () => {
+  const o = opts([
+    "grant",
+    "--user",
+    "alice@x.com",
+    "--connection",
+    "mylocalpg",
+    "--level",
+    "read",
+  ]);
+  assert.equal(o.user, "alice@x.com");
+  assert.equal(o.connection, "mylocalpg");
+  assert.equal(o.level, "read");
+});
+
+test("access policy passes positional user + connection", () => {
+  const o = opts(["policy", "alice@x.com", "mylocalpg"]);
+  assert.deepEqual(o.positional, ["policy", "alice@x.com", "mylocalpg"]);
+});
+
+// permissions -----------------------------------------------------------------
+
+test("permissions override --grant + --reason", () => {
+  const o = opts([
+    "override",
+    "--role",
+    "DEVELOPER",
+    "--permission",
+    "USE_CHAT",
+    "--grant",
+    "--reason",
+    "Beta access",
+  ]);
+  assert.equal(o.role, "DEVELOPER");
+  assert.equal(o.permission, "USE_CHAT");
+  assert.equal(o.grant, true);
+  assert.equal(o.revoke, false);
+  assert.equal(o.reason, "Beta access");
+});
+
+test("permissions override --revoke flips to revoke", () => {
+  const o = opts(["override", "--role", "DEVELOPER", "--permission", "USE_CHAT", "--revoke"]);
+  assert.equal(o.grant, false);
+  assert.equal(o.revoke, true);
+});
+
+// slow-queries ----------------------------------------------------------------
+
+test("slow-queries history N positional", () => {
+  const o = opts(["history", "--connection", "mylocalpg", "5"]);
+  assert.deepEqual(o.positional, ["history", "5"]);
+  assert.equal(o.connection, "mylocalpg");
+});
+
+test("slow-queries analyze flags", () => {
+  const o = opts([
+    "analyze",
+    "--connection",
+    "mylocalpg",
+    "--time-range",
+    "LAST_HOUR",
+    "--threshold-ms",
+    "200",
+    "--limit",
+    "20",
+  ]);
+  assert.equal(o.timeRange, "LAST_HOUR");
+  assert.equal(o.thresholdMs, "200");
+  assert.equal(o.limit, "20");
+});
+
+test("slow-queries optimize uses --query-id", () => {
+  const o = opts(["optimize", "--connection", "mylocalpg", "--query-id", "q-123"]);
+  assert.equal(o.queryId, "q-123");
+});
+
+test("slow-queries delete --history-id with --yes", () => {
+  const o = opts(["delete", "--history-id", "42", "--yes"]);
+  assert.equal(o.historyId, "42");
+  assert.equal(o.yes, true);
+});
+
+// setup -----------------------------------------------------------------------
+
+test("setup --force --skip-email", () => {
+  const o = opts(["--force", "--skip-email"]);
+  assert.equal(o.force, true);
+  assert.equal(o.skipEmail, true);
+});
+
+// password flag stays a flag for login + value for users -----------------------
+
+test("--password alone (login flow) leaves password truthy", () => {
+  const o = opts(["--password"]);
+  assert.equal(!!o.password, true);
+});
+
+test("--password=secret keeps the string value (still truthy)", () => {
+  const o = opts(["--password=secret"]);
+  assert.equal(o.password, "secret");
+});

package/src/commands/ask.js

@@ -3,13 +3,15 @@
 const os = require("node:os");
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
   const question = opts.positional.join(" ").trim();
-  if (!question) throw new Error("Pass a question: `deepsql ask \"why is this query slow?\" --connection <id>`.");
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!question) throw new Error("Pass a question: `deepsql ask \"why is this query slow?\" --connection <name>`.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const userId = opts.user || `cli-${os.userInfo().username}`;
   const projectId = opts.project || "deepsql-cli";
 
@@ -18,7 +20,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     token: session.token,
     timeoutMs: 240000,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       message: question,
       chatId: opts.chat || null,
       userId,

package/src/commands/connections.js

@@ -18,11 +18,23 @@ async function run(opts, { stdout = process.stdout } = {}) {
     stdout.write("No connections.\n");
     return;
   }
-  for (const conn of data) {
-    const id = conn.id || conn.connectionId;
-    const name = conn.connectionName || conn.name || "(unnamed)";
-    const dbType = conn.databaseType || conn.dbType || "?";
-    stdout.write(`${id}  ${dbType.padEnd(10)}  ${name}\n`);
+  // Name first — it's what users will pass to --connection. ID kept on the
+  // right for back-compat / scripting.
+  const rows = data.map((conn) => ({
+    name: conn.connectionName || conn.name || "(unnamed)",
+    type: conn.databaseType || conn.dbType || "?",
+    id: conn.id || conn.connectionId || "",
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    type: Math.max(4, ...rows.map((r) => r.type.length)),
+  };
+  stdout.write(
+    `${"NAME".padEnd(widths.name)}  ${"TYPE".padEnd(widths.type)}  ID\n` +
+      `${"-".repeat(widths.name)}  ${"-".repeat(widths.type)}  ${"-".repeat(36)}\n`,
+  );
+  for (const row of rows) {
+    stdout.write(`${row.name.padEnd(widths.name)}  ${row.type.padEnd(widths.type)}  ${row.id}\n`);
   }
 }
 

package/src/commands/digest.js

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * `deepsql digest` — surface the daily DeepSQL digest from the terminal.
+ *
+ *   deepsql digest                   → show the single most recent digest, full body
+ *   deepsql digest <N>               → list the last N digests (compact, one per row)
+ *   deepsql digest list [--count N]  → same as above; explicit form
+ *   deepsql digest show <id>         → show a specific digest by id
+ *   --connection <id>                → filter to one connection
+ *   --json                           → raw JSON output
+ *
+ * Backend: GET /admin/slack/digests?connectionId=&page=0&size=N
+ *   Returns a Spring Data Page<SlackDigestLog>: { content: [...], totalElements, ... }
+ *   Requires ADMIN role on the calling user's MCP token.
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const DEFAULT_LIST_COUNT = 10;
+const MAX_COUNT = 100;
+
+async function run(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!opts.connection) {
+    throw new Error(
+      "--connection <name> is required. Digests are per-connection — pick one from `deepsql connections list`.",
+    );
+  }
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const sub = opts.positional[0];
+
+  // `deepsql digest <N>` shorthand — first positional is a number.
+  if (sub && /^\d+$/.test(sub)) {
+    return runList(session, connectionId, parseCount(sub), opts, { stdout, stderr });
+  }
+  if (!sub || sub === "latest") {
+    return runLatest(session, connectionId, opts, { stdout, stderr });
+  }
+  if (sub === "list") {
+    const count = parseCount(opts.count) || parseCount(opts.positional[1]) || DEFAULT_LIST_COUNT;
+    return runList(session, connectionId, count, opts, { stdout, stderr });
+  }
+  if (sub === "show") {
+    const id = opts.positional[1];
+    if (!id) throw new Error("Pass the digest id: `deepsql digest show <id> --connection <name>`.");
+    return runShow(session, connectionId, id, opts, { stdout, stderr });
+  }
+  throw new Error(`Unknown digest subcommand: ${sub}. Try \`latest\`, \`list\`, \`show <id>\`, or pass a number.`);
+}
+
+async function runLatest(session, connectionId, opts, { stdout }) {
+  const page = await fetchPage(session, connectionId, 0, 1);
+  const digest = page.content?.[0];
+  if (!digest) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(digest, null, 2)}\n`);
+    return;
+  }
+  printFull(stdout, digest);
+}
+
+async function runList(session, connectionId, requestedCount, opts, { stdout }) {
+  const count = Math.min(requestedCount, MAX_COUNT);
+  const page = await fetchPage(session, connectionId, 0, count);
+  const items = page.content || [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  printTable(stdout, items);
+  if (page.totalElements && page.totalElements > items.length) {
+    stdout.write(`\n${items.length} of ${page.totalElements} shown — pass a larger N to see more.\n`);
+  }
+}
+
+async function runShow(session, connectionId, id, opts, { stdout }) {
+  // No single-digest backend endpoint exists yet, so locate by paging.
+  // Cheap enough for typical digest counts; we cap at a few pages.
+  const target = String(id);
+  for (let page = 0; page < 10; page++) {
+    const result = await fetchPage(session, connectionId, page, 50);
+    const hit = (result.content || []).find((d) => String(d.id) === target);
+    if (hit) {
+      if (opts.json) {
+        stdout.write(`${JSON.stringify(hit, null, 2)}\n`);
+        return;
+      }
+      printFull(stdout, hit);
+      return;
+    }
+    if (result.last || (result.content || []).length === 0) break;
+  }
+  throw new Error(`Digest ${id} not found in the most recent 500 entries for "${opts.connection}".`);
+}
+
+async function fetchPage(session, connectionId, page, size) {
+  try {
+    return await request(session.baseUrl, "/admin/slack/digests", {
+      token: session.token,
+      query: {
+        connectionId,
+        page,
+        size,
+      },
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 403) {
+      throw new Error(
+        "Access denied — fetching digests requires ADMIN role. Ask an administrator to mint a token, or run `deepsql login` as an admin.",
+      );
+    }
+    throw err;
+  }
+}
+
+function printTable(stdout, items) {
+  const rows = items.map((d) => ({
+    id: String(d.id ?? ""),
+    sentAt: formatTimestamp(d.sentAt),
+    status: d.status || "?",
+    connection: trim(d.connectionName || d.connectionId || "—", 24),
+    headline: trim(d.headline || firstLine(d.content) || "(no headline)", 60),
+  }));
+  const cols = [
+    { key: "id", label: "ID" },
+    { key: "sentAt", label: "Sent" },
+    { key: "status", label: "Status" },
+    { key: "connection", label: "Connection" },
+    { key: "headline", label: "Headline" },
+  ];
+  const widths = cols.map((c) => Math.max(c.label.length, ...rows.map((r) => r[c.key].length)));
+  const header = cols.map((c, i) => c.label.padEnd(widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  stdout.write(`${header}\n${sep}\n`);
+  for (const row of rows) {
+    stdout.write(`${cols.map((c, i) => row[c.key].padEnd(widths[i])).join("  ")}\n`);
+  }
+}
+
+function printFull(stdout, d) {
+  const sent = formatTimestamp(d.sentAt);
+  stdout.write(`Digest #${d.id}  ·  ${sent}  ·  ${d.status || "?"}\n`);
+  if (d.connectionName || d.connectionId) {
+    stdout.write(`Connection: ${d.connectionName || d.connectionId}\n`);
+  }
+  if (d.headline) {
+    stdout.write(`Headline:   ${d.headline}\n`);
+  }
+  stdout.write("\n");
+  if (d.status === "FAILED" && d.errorMessage) {
+    stdout.write(`Error: ${d.errorMessage}\n`);
+    return;
+  }
+  stdout.write(`${d.content || "(empty)"}\n`);
+}
+
+function parseCount(value) {
+  if (value == null) return null;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n;
+}
+
+function formatTimestamp(value) {
+  if (!value) return "—";
+  try {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return String(value);
+    return d.toISOString().replace("T", " ").slice(0, 16) + "Z";
+  } catch {
+    return String(value);
+  }
+}
+
+function trim(text, maxLen) {
+  if (!text) return "";
+  const s = String(text).replace(/\s+/g, " ").trim();
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + "…" : s;
+}
+
+function firstLine(text) {
+  if (!text) return "";
+  const idx = text.indexOf("\n");
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+module.exports = { run };

package/src/commands/explain.js

@@ -4,19 +4,21 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const sql = readSqlInput(opts);
   // EXPLAIN ANALYZE is mutating; require plain EXPLAIN.
   const validation = validateReadOnlySql(sql, { allowExplain: false });
   if (!validation.ok) throw new Error(validation.reason);
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const response = await request(session.baseUrl, "/mcp/explain-readonly", {
     method: "POST",
     token: session.token,
-    json: { connectionId: opts.connection, query: validation.normalizedQuery },
+    json: { connectionId, query: validation.normalizedQuery },
   });
 
   if (opts.json) {

package/src/commands/permissions.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * `deepsql permissions` — global role-based permission overrides.
+ *
+ *   deepsql permissions list [--role <r>] [--json]
+ *   deepsql permissions override --role <r> --permission <p> --grant|--revoke [--reason "..."]
+ *   deepsql permissions reset --role <r> --permission <p>
+ *
+ * Backed by /permissions/** (overrides require ROLE_ADMIN).
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+
+const SUBCOMMANDS = {
+  list: cmdList,
+  override: cmdOverride,
+  reset: cmdReset,
+};
+
+async function run(opts, io = {}) {
+  const sub = opts.positional[0];
+  if (!sub) throw new Error("Usage: deepsql permissions <list|override|reset> ...");
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) throw new Error(`Unknown permissions subcommand: ${sub}.`);
+  return wrap(handler)(
+    { ...opts, positional: opts.positional.slice(1) },
+    io,
+  );
+}
+
+function wrap(handler) {
+  return async (opts, io) => {
+    try {
+      return await handler(opts, io);
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 403) {
+        throw new Error("Access denied — managing permissions requires ADMIN role.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── list ──────────────────────────────────────────────────────────────────
+
+async function cmdList(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const [registry, roles, overrides] = await Promise.all([
+    request(session.baseUrl, "/permissions/registry", { token: session.token }),
+    request(session.baseUrl, "/permissions/roles", { token: session.token }),
+    request(session.baseUrl, "/permissions/overrides", { token: session.token }),
+  ]);
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify({ registry, roles, overrides }, null, 2)}\n`);
+    return;
+  }
+
+  const roleList = Array.isArray(roles) ? roles : roles?.roles || [];
+  const overrideList = Array.isArray(overrides) ? overrides : overrides?.overrides || [];
+
+  if (opts.role) {
+    const wanted = String(opts.role).toUpperCase();
+    const role = roleList.find(
+      (r) => (r.code || r.role || r.name || "").toUpperCase() === wanted,
+    );
+    if (!role) {
+      const available = roleList.map((r) => r.code || r.role || r.name).filter(Boolean).join(", ");
+      throw new Error(`Role "${opts.role}" not found. Available: ${available}.`);
+    }
+    const code = role.code || role.role || role.name;
+    stdout.write(`${code} permissions (effective):\n`);
+    const perms = role.effectivePermissions || role.permissions || [];
+    for (const p of perms) {
+      stdout.write(`  - ${typeof p === "string" ? p : p.code || p.name}\n`);
+    }
+    return;
+  }
+
+  if (overrideList.length === 0) {
+    stdout.write("No active overrides — every role has its default permissions.\n");
+  } else {
+    stdout.write("Active overrides:\n");
+    for (const o of overrideList) {
+      const role = o.role || "";
+      const perm = o.permissionCode || o.permission || "";
+      const granted = o.granted ? "GRANT" : "REVOKE";
+      const reason = o.reason ? ` — ${o.reason}` : "";
+      stdout.write(`  ${role.padEnd(12)} ${granted.padEnd(7)} ${perm}${reason}\n`);
+    }
+  }
+
+  if (roleList.length > 0) {
+    stdout.write("\nRoles:\n");
+    for (const r of roleList) {
+      const name = r.code || r.role || r.name || "?";
+      const count = (r.effectivePermissions || r.permissions || []).length;
+      stdout.write(`  ${name.padEnd(12)} ${count} permission(s)\n`);
+    }
+    stdout.write("\nUse `--role <NAME>` to see one role's full permission list.\n");
+  }
+}
+
+// ─── override ──────────────────────────────────────────────────────────────
+
+async function cmdOverride(opts, { stdout = process.stdout } = {}) {
+  if (!opts.role) throw new Error("--role <ROLE> is required.");
+  if (!opts.permission) throw new Error("--permission <PERMISSION> is required.");
+  if (!opts.grant && !opts.revoke) {
+    throw new Error("Pass --grant or --revoke.");
+  }
+  if (opts.grant && opts.revoke) {
+    throw new Error("--grant and --revoke are mutually exclusive.");
+  }
+  const granted = !!opts.grant;
+  const session = resolveSession(opts);
+  const result = await request(session.baseUrl, "/permissions/overrides", {
+    method: "POST",
+    token: session.token,
+    json: {
+      role: String(opts.role).toUpperCase(),
+      permission: String(opts.permission).toUpperCase(),
+      granted,
+      reason: opts.reason || null,
+    },
+  });
+  stdout.write(`${result?.message || "Override applied."}\n`);
+}
+
+// ─── reset ─────────────────────────────────────────────────────────────────
+
+async function cmdReset(opts, { stdout = process.stdout } = {}) {
+  if (!opts.role) throw new Error("--role <ROLE> is required.");
+  if (!opts.permission) throw new Error("--permission <PERMISSION> is required.");
+  const session = resolveSession(opts);
+  const result = await request(session.baseUrl, "/permissions/overrides", {
+    method: "DELETE",
+    token: session.token,
+    json: {
+      role: String(opts.role).toUpperCase(),
+      permission: String(opts.permission).toUpperCase(),
+    },
+  });
+  stdout.write(`${result?.message || "Override removed."}\n`);
+}
+
+module.exports = { run };

package/src/commands/query.js

@@ -4,14 +4,16 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const sql = readSqlInput(opts);
   const validation = validateReadOnlySql(sql, { allowExplain: true });
   if (!validation.ok) throw new Error(validation.reason);
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const limit = clampInt(opts.limit, 1, 1000, 100);
   const timeout = opts.timeoutSeconds == null ? null : clampInt(opts.timeoutSeconds, 1, 60, null);
 
@@ -19,7 +21,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     method: "POST",
     token: session.token,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       query: validation.normalizedQuery,
       limit,
       timeoutSeconds: timeout,
@@ -48,19 +50,49 @@ function clampInt(value, min, max, fallback) {
 }
 
 function printRows(stdout, response) {
-  const rows = response?.rows || response?.data || [];
-  const columns = response?.columns || (rows[0] ? Object.keys(rows[0]) : []);
-  if (columns.length === 0) {
+  // Backend returns: { result: { columns: [...], rows: [[v1,v2,...], ...],
+  //                            rowCount, totalRowCount, isLimited, ... },
+  //                   success, queryType }
+  // Tolerate older shapes too — `rows` directly on the response, with rows as
+  // either arrays or row-objects.
+  const result = response?.result ?? response ?? {};
+  const rawRows = result.rows ?? result.data ?? [];
+  let columns = result.columns;
+  if (!Array.isArray(columns) || columns.length === 0) {
+    columns = rawRows[0] && !Array.isArray(rawRows[0]) ? Object.keys(rawRows[0]) : [];
+  }
+  if (columns.length === 0 || rawRows.length === 0) {
     stdout.write("(no rows)\n");
     return;
   }
-  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+  const cellAt = (row, idx, col) =>
+    Array.isArray(row) ? row[idx] : row?.[col];
+  const widths = columns.map((c, i) =>
+    Math.max(
+      String(c).length,
+      ...rawRows.map((r) => String(cellAt(r, i, c) ?? "").length),
+    ),
+  );
   const sep = widths.map((w) => "-".repeat(w)).join("  ");
-  stdout.write(`${columns.map((c, i) => c.padEnd(widths[i])).join("  ")}\n${sep}\n`);
-  for (const row of rows) {
-    stdout.write(`${columns.map((c, i) => String(row[c] ?? "").padEnd(widths[i])).join("  ")}\n`);
+  stdout.write(
+    `${columns.map((c, i) => String(c).padEnd(widths[i])).join("  ")}\n${sep}\n`,
+  );
+  for (const row of rawRows) {
+    stdout.write(
+      `${columns
+        .map((c, i) => String(cellAt(row, i, c) ?? "").padEnd(widths[i]))
+        .join("  ")}\n`,
+    );
+  }
+  if (result.isLimited || result.truncated) {
+    const shown = rawRows.length;
+    const total = result.totalRowCount;
+    stdout.write(
+      total != null && total > shown
+        ? `(showing ${shown} of ${total} rows)\n`
+        : `(result limited to ${shown} rows)\n`,
+    );
   }
-  if (response?.truncated) stdout.write(`(truncated to ${rows.length} rows)\n`);
 }
 
 module.exports = { run };

package/src/commands/schema.js

@@ -2,15 +2,17 @@
 
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const sub = opts.positional[0] || "tables";
   const path =
     sub === "objects"
-      ? `/connections/${encodeURIComponent(opts.connection)}/objects`
-      : `/connections/${encodeURIComponent(opts.connection)}/schema`;
+      ? `/connections/${encodeURIComponent(connectionId)}/objects`
+      : `/connections/${encodeURIComponent(connectionId)}/schema`;
   const response = await request(session.baseUrl, path, { token: session.token });
   stdout.write(`${JSON.stringify(response, null, 2)}\n`);
 }