@batadata/cli 0.1.1 → 0.1.2

package/README.md

@@ -2,7 +2,11 @@
 
 Command-line interface for [BataDB](https://batadata.com) — a serverless Postgres
 platform. Create projects, open `psql`, run queries, manage branches and API keys,
-and generate types, all from your terminal.
+inspect cost, and generate types, all from your terminal.
+
+Every command also runs **headlessly** with a single API key and `--json` output,
+so an AI coding agent can provision and operate a database with no human in the
+loop. See [Headless / agent use](#headless--agent-use).
 
 ## Install
 
@@ -36,6 +40,7 @@ control plane with `--api-url <url>` or `BATA_API_URL`.
 bata create my-app        # create a project and wait until it's ready
 bata status               # list all projects and their status
 bata connect my-app       # open psql (auto-wakes the compute if suspended)
+bata usage                # per-dimension cost for the current billing period
 ```
 
 ## Commands
@@ -45,33 +50,93 @@ bata connect my-app       # open psql (auto-wakes the compute if suspended)
 | `create <name>` | Create a project and wait for it to be ready |
 | `connect <name>` | Open `psql` to a project (auto-wakes if suspended) |
 | `status` | Show all projects and their status |
+| `usage` | Show per-dimension cost (compute, storage, transfer) for the current period |
 | `login` / `logout` / `whoami` | Manage your session |
 | `api-keys` | Create / list / revoke API keys |
 | `projects` | `list`, `create`, `info`, `delete` |
 | `db url` | Print a connection string |
-| `db connect` | Open `psql` to your database |
-| `db query` | Run a SQL query |
+| `db connect` | Open `psql` to your database (interactive only) |
+| `db query <sql>` | Run a SQL query and print the rows |
 | `db branches` | List database branches |
 | `db branch create` / `db branch delete` | Manage branches |
 | `db studio` | Open the table browser in your browser |
+| `schema check <file>` | Check a proposed schema change against live query traffic |
 | `generate` | Generate types from your database schema (`--watch` for watch mode) |
 | `dev` | Print the local development setup guide |
 
-`schema` and `migrate` are reserved and currently print a "coming soon" notice.
+`schema check` is implemented today. The remaining `schema` subcommands
+(`init`, `push`, `pull`, `diff`) and all of `migrate` are not implemented yet —
+they exit `3` (`NOT_IMPLEMENTED`) and point you at `schema check` for migration
+safety.
 
 Run `bata --help` for the full, authoritative command list, or `bata --version`.
 
 ## Headless / agent use
 
-The CLI is built to be scriptable:
+Every command runs headlessly with just `BATA_API_KEY` set — no `bata login`,
+no interactive prompts, no human in the loop. This is what makes BataDB
+agent-native: an AI coding agent can provision a database, run SQL, branch, and
+clean up entirely on its own.
+
+- **`--json`** — machine-readable output. The error envelope is JSON too and
+  always the same shape: `{ "error", "code", "hint" }`.
+- **Exit codes** — a stable contract so a script can branch on the failure mode:
+
+  | Code | Meaning |
+  |------|---------|
+  | `0` | Success |
+  | `1` | Generic error (`CLI_ERROR`) |
+  | `2` | Gate tripped (`schema check --fail-on`) |
+  | `3` | Not implemented (`NOT_IMPLEMENTED`) |
+  | `4` | Auth / credentials (`NO_CREDENTIALS`, `INVALID_KEY`) |
+  | `5` | Not found / bad input (`NO_PROJECT`, `BRANCH_NOT_FOUND`, `INVALID_FLAG`, `INTERACTIVE_ONLY`) |
+  | `6` | Upstream / transient (`API_UNAVAILABLE`, `TIMEOUT`) — safe to retry |
+
+- **`--yes` / `-y`** — skip confirmation prompts on destructive commands.
+
+`db connect` and `connect` open an interactive `psql` session and exit `5`
+(`INTERACTIVE_ONLY`) when run headlessly. Agents should use `db url` for a
+connection string or `db query <sql>` to execute SQL.
+
+### A full agent workflow
+
+Provision, query, branch, check cost, and tear down — no human, no login:
+
+```bash
+export BATA_API_KEY=bata_xxx
+
+# 1. Create a project and wait until it's ready
+bata create my-agent-app --json
+
+# 2. Run SQL headlessly (rows come back as JSON objects)
+bata db query "SELECT now()" --json
+
+# 3. Branch the database (copy-on-write)
+bata db branch create preview --json
+
+# 4. Inspect cost for the current period
+bata usage --json
+
+# 5. Clean up
+bata projects delete --yes --json
+```
+
+`db branch create` returns immediately with `"ready": false` — the branch row
+exists but its compute may still be provisioning. Poll `bata db branches --json`
+until the branch reports a ready status before connecting to it.
+
+### Cost truth
 
-- **`--json`** — machine-readable output on read commands. Errors are emitted as
-  JSON too, e.g. `{"error":"Not authenticated","code":"NO_CREDENTIALS","hint":"..."}`.
-- **Exit codes** — `0` on success, `1` on error (auth failures, unknown commands).
-- **`--yes` / `-y`** — skip confirmation prompts.
+`bata usage` reports cost per dimension and is deliberately honest about what is
+and isn't metered. Transfer (egress) is **not metered yet**, so it never shows a
+priced `$0` — in `--json` it reports `{ "metered": false, "value": null,
+"cost_cents": null, "status": "not_metered_yet" }`, and in the human view it
+reads `Not metered yet`. You only ever see a dollar figure for a dimension we
+genuinely meter end to end (compute and storage today).
 
 ```bash
-bata status --json | jq '.[].name'
+bata usage --json | jq '.projects[].transfer.status'   # "not_metered_yet"
+bata status --json | jq '.projects[].name'             # list project names
 ```
 
 ## Global options

package/dist/api.js

@@ -14,7 +14,7 @@ export async function request(method, path, options = {}) {
     }
     const headers = {
         "Content-Type": "application/json",
-        "User-Agent": "@batadata/cli 0.1.0",
+        "User-Agent": "@batadata/cli 0.1.2",
     };
     if (options.token) {
         headers["Authorization"] = `Bearer ${options.token}`;

package/dist/args.js

@@ -36,6 +36,6 @@ export function parseGlobalFlags(argv) {
             rest.push(arg);
         }
     }
-    setRuntime({ json: flags.json, apiKey: flags.apiKey, apiUrl: flags.apiUrl });
+    setRuntime({ json: flags.json, apiKey: flags.apiKey, apiUrl: flags.apiUrl, yes: flags.yes });
     return { rest, flags };
 }

package/dist/commands/api-keys.js

@@ -10,8 +10,15 @@
  */
 import { api, apiError } from "../api.js";
 import { requireToken, isJsonMode } from "../config.js";
-import { colors, log, json, success, error, warn, spinner, table, kvList, heading } from "../utils/logger.js";
-import { prompt, confirm } from "../utils/prompts.js";
+import { colors, log, json, success, warn, spinner, table, kvList, heading } from "../utils/logger.js";
+import { prompt, confirmDestructive } from "../utils/prompts.js";
+import { emitError } from "../utils/errors.js";
+/** Map an API-key endpoint failure to the right coded exit. */
+function apiKeyError(res, fallbackMsg) {
+    emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+        : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+            : "CLI_ERROR", fallbackMsg, "");
+}
 function parseFlag(args, name) {
     for (let i = 0; i < args.length; i++) {
         if (args[i] === name && args[i + 1])
@@ -60,13 +67,7 @@ async function create(args) {
     const res = await api.post("/v1/api-keys", { name }, token);
     s?.stop();
     if (!res.ok) {
-        if (jsonMode) {
-            json({ error: apiError(res, "Failed to create API key") });
-        }
-        else {
-            error(apiError(res, "Failed to create API key"));
-        }
-        process.exit(1);
+        apiKeyError(res, apiError(res, "Failed to create API key"));
     }
     const k = res.data;
     if (jsonMode) {
@@ -104,13 +105,7 @@ async function list(args) {
     const res = await api.get("/v1/api-keys", token);
     s?.stop();
     if (!res.ok) {
-        if (jsonMode) {
-            json({ error: apiError(res, "Failed to list API keys") });
-        }
-        else {
-            error(apiError(res, "Failed to list API keys"));
-        }
-        process.exit(1);
+        apiKeyError(res, apiError(res, "Failed to list API keys"));
     }
     const keys = Array.isArray(res.data) ? res.data : [];
     if (jsonMode) {
@@ -145,32 +140,22 @@ async function list(args) {
 async function revoke(args) {
     const token = requireToken();
     const jsonMode = isJsonMode();
-    const skipConfirm = args.includes("--yes") || args.includes("-y");
     const id = positional(args)[0];
     if (!id) {
-        const msg = "API key ID is required. Usage: bata api-keys revoke <id> [--yes]";
-        if (jsonMode)
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("MISSING_ARG", "API key ID is required.", "Usage: bata api-keys revoke <id> [--yes]");
     }
-    if (!skipConfirm && !jsonMode && process.stdin.isTTY) {
-        const ok = await confirm(`Revoke API key ${colors.cyan(id)}? This cannot be undone.`, false);
-        if (!ok) {
-            log("  Aborted.");
-            return;
-        }
+    // Shared headless-skip rule (--yes / --json / no TTY) so the prompt can't
+    // block an agent and the behavior can't drift from branch/project deletes.
+    const ok = await confirmDestructive(`Revoke API key ${colors.cyan(id)}? This cannot be undone.`);
+    if (!ok) {
+        log("  Aborted.");
+        return;
     }
     const s = jsonMode ? null : spinner("Revoking API key");
     const res = await api.del(`/v1/api-keys/${id}`, token);
     s?.stop();
     if (!res.ok) {
-        if (jsonMode)
-            json({ error: apiError(res, "Failed to revoke API key") });
-        else
-            error(apiError(res, "Failed to revoke API key"));
-        process.exit(1);
+        apiKeyError(res, apiError(res, "Failed to revoke API key"));
     }
     if (jsonMode) {
         json({ id, revoked: true });
@@ -215,8 +200,6 @@ export async function handleApiKeys(args) {
         case "revoke":
             return revoke(rest);
         default:
-            error(`Unknown subcommand: api-keys ${sub}`);
-            log(`  ${colors.dim("Available:")} create, list, revoke`);
-            process.exit(1);
+            emitError("INVALID_FLAG", `Unknown subcommand: api-keys ${sub}`, "Available: create, list, revoke");
     }
 }

package/dist/commands/connect.js

@@ -6,9 +6,15 @@
  */
 import { execSync, spawn } from "node:child_process";
 import { api } from "../api.js";
-import { requireToken, loadConfig } from "../config.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
 import { colors, log, error, spinner, info as logInfo } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
 export async function connect(args) {
+    // psql is an interactive session — there's no headless equivalent. Don't spawn
+    // it in --json or non-TTY contexts; point agents at the headless surfaces.
+    if (isJsonMode() || !process.stdin.isTTY) {
+        emitError("INTERACTIVE_ONLY", "bata connect opens an interactive psql session and can't run headlessly.", "Use `bata db url` for a connection string or `bata db query <sql>` for headless execution.");
+    }
     const token = requireToken();
     const config = loadConfig();
     // Accept project name as argument, or use default
@@ -23,21 +29,19 @@ export async function connect(args) {
         const projRes = await api.get("/v1/projects", token, query);
         s.stop();
         if (!projRes.ok) {
-            error("Failed to fetch projects.");
-            process.exit(1);
+            emitError(projRes.status === 401 || projRes.status === 403 ? "INVALID_KEY"
+                : projRes.status >= 500 || projRes.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", "Failed to fetch projects.", "");
         }
         const projects = Array.isArray(projRes.data) ? projRes.data : [];
         const found = projects.find((p) => p.name === projectName || p.id === projectName);
         if (!found) {
-            error(`Project "${projectName}" not found.`);
-            process.exit(1);
+            emitError("NOT_FOUND", `Project "${projectName}" not found.`, "");
         }
         projectId = found.id;
     }
     if (!projectId) {
-        error("No project specified. Usage: bata connect <project-name>");
-        log(`  Or set a default with ${colors.cyan("bata create <name>")}`);
-        process.exit(1);
+        emitError("NO_PROJECT", "No project specified.", "Usage: bata connect <project-name>  (or set a default with bata create <name>)");
     }
     const s = spinner("Fetching connection info");
     const connRes = await api.get(`/v1/connection-info/${projectId}`, token);

package/dist/commands/db.js

@@ -2,8 +2,9 @@ import { execSync, spawn } from "node:child_process";
 import { api, apiError } from "../api.js";
 import { requireToken, loadConfig, isJsonMode } from "../config.js";
 import { colors, log, json, error, spinner, table, heading, info as logInfo } from "../utils/logger.js";
-import { prompt, confirm } from "../utils/prompts.js";
+import { prompt, confirmDestructive } from "../utils/prompts.js";
 import { openBrowser } from "../utils/open.js";
+import { emitError } from "../utils/errors.js";
 async function getConnectionInfo(projectId, token) {
     // reveal=true so the returned string is actually usable (the owner is asking).
     const res = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
@@ -29,20 +30,39 @@ function formatDate(iso) {
     const d = new Date(iso);
     return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
 }
+/**
+ * Resolve a project's primary branch (the one to run a query against). Lists
+ * branches the same way `db branches` does (GET /v1/projects/:id) and returns
+ * the primary, falling back to the first branch. Returns null if the project
+ * has no branches or the lookup failed.
+ */
+async function getPrimaryBranch(projectId, token, teamId) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    if (!res.ok)
+        return null;
+    const list = res.data.branches ?? [];
+    return list.find((b) => b.is_primary) ?? list[0] ?? null;
+}
 export async function connect() {
+    // psql is an interactive session — there's no headless equivalent. Don't spawn
+    // it in --json or non-TTY contexts; point agents at the headless surfaces.
+    if (isJsonMode() || !process.stdin.isTTY) {
+        emitError("INTERACTIVE_ONLY", "bata db connect opens an interactive psql session and can't run headlessly.", "Use `bata db url` for a connection string or `bata db query <sql>` for headless execution.");
+    }
     const token = requireToken();
     const config = loadConfig();
     const projectId = config.defaultProject;
     if (!projectId) {
-        error("No default project. Run bata projects create or set one with bata projects info <id>.");
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project.", "Run bata projects create or set one with bata projects info <id>.");
     }
     const s = spinner("Fetching connection info");
     const conn = await getConnectionInfo(projectId, token);
     s.stop();
     if (!conn || !conn.connection_uri) {
-        error("Could not fetch connection string for this project.");
-        process.exit(1);
+        emitError("NOT_FOUND", "Could not fetch connection string for this project.", "");
     }
     log();
     logInfo(`Connecting to project ${colors.cyan(projectId)}`);
@@ -70,17 +90,11 @@ export async function url() {
     const config = loadConfig();
     const projectId = config.defaultProject;
     if (!projectId) {
-        error("No default project set.");
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const conn = await getConnectionInfo(projectId, token);
     if (!conn || !conn.connection_uri) {
-        const msg = "Could not fetch connection string.";
-        if (isJsonMode())
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("NOT_FOUND", "Could not fetch connection string.", "");
     }
     if (isJsonMode()) {
         json({ direct: conn.connection_uri, pooled: conn.pooled_uri ?? null });
@@ -95,12 +109,7 @@ export async function branches() {
     const jsonMode = isJsonMode();
     const projectId = config.defaultProject;
     if (!projectId) {
-        const msg = "No default project set.";
-        if (jsonMode)
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const s = jsonMode ? null : spinner("Fetching branches");
     const query = {};
@@ -109,11 +118,10 @@ export async function branches() {
     const res = await api.get(`/v1/projects/${projectId}`, token, query);
     s?.stop();
     if (!res.ok) {
-        if (jsonMode)
-            json({ error: apiError(res, "Failed to fetch branches") });
-        else
-            error(apiError(res, "Failed to fetch project branches"));
-        process.exit(1);
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status === 404 ? "NO_PROJECT"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Failed to fetch branches"), "");
     }
     const branchList = res.data.branches || [];
     if (jsonMode) {
@@ -146,19 +154,25 @@ export async function branches() {
     log();
 }
 export async function branchCreate(name) {
+    const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
     const projectId = config.defaultProject;
     if (!projectId) {
-        error("No default project set.");
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
-    const branchName = name || (await prompt("Branch name"));
+    // Don't block on an interactive prompt headlessly.
+    let branchName = name;
     if (!branchName) {
-        error("Branch name is required.");
-        process.exit(1);
+        if (jsonMode || !process.stdin.isTTY) {
+            emitError("MISSING_ARG", "Branch name is required.", "Usage: bata db branch create <name>");
+        }
+        branchName = await prompt("Branch name");
+    }
+    if (!branchName) {
+        emitError("MISSING_ARG", "Branch name is required.", "Usage: bata db branch create <name>");
     }
-    const s = spinner(`Creating branch ${colors.cyan(branchName)}`);
+    const s = jsonMode ? null : spinner(`Creating branch ${colors.cyan(branchName)}`);
     const body = {
         name: branchName,
         project_id: projectId,
@@ -166,54 +180,66 @@ export async function branchCreate(name) {
     if (config.defaultTeam)
         body.team_id = config.defaultTeam;
     const res = await api.post("/v1/branches", body, token);
-    s.stop();
+    s?.stop();
     if (!res.ok) {
-        error(apiError(res, "Failed to create branch"));
-        process.exit(1);
+        emitError(res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE" : "CLI_ERROR", apiError(res, "Failed to create branch"), "");
+    }
+    if (jsonMode) {
+        json({
+            branch: { id: res.data.id, name: res.data.name ?? branchName, project_id: projectId },
+            // The branch row exists immediately, but its compute may still be
+            // provisioning — poll `db branches` for status before connecting.
+            ready: false,
+            poll: "bata db branches --json",
+        });
+        return;
     }
     log();
     log(`  ${colors.green(">")} Branch ${colors.cyan(branchName)} created`);
+    log(`  ${colors.dim("Poll readiness with")} ${colors.cyan("bata db branches")}`);
     log();
 }
 export async function branchDelete(name) {
+    const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
     const projectId = config.defaultProject;
     if (!projectId) {
-        error("No default project set.");
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     if (!name) {
-        error("Branch name is required. Usage: bata db branch delete <name>");
-        process.exit(1);
+        emitError("MISSING_ARG", "Branch name is required.", "Usage: bata db branch delete <name>");
     }
-    const ok = await confirm(`Delete branch ${colors.cyan(name)}?`, false);
+    // Skip the prompt headlessly (--yes / --json / no TTY) so agents and CI can
+    // actually delete — and never report success without deleting.
+    const ok = await confirmDestructive(`Delete branch ${colors.cyan(name)}?`);
     if (!ok) {
         log("  Aborted.");
         return;
     }
-    const s = spinner(`Deleting branch ${name}`);
+    const s = jsonMode ? null : spinner(`Deleting branch ${name}`);
     // We need to find the branch ID first
     const query = {};
     if (config.defaultTeam)
         query.team_id = config.defaultTeam;
     const projRes = await api.get(`/v1/projects/${projectId}`, token, query);
     if (!projRes.ok || !projRes.data.branches) {
-        s.stop();
-        error("Failed to fetch branches.");
-        process.exit(1);
+        s?.stop();
+        emitError(projRes.status >= 500 || projRes.status === 0 ? "API_UNAVAILABLE" : "CLI_ERROR", apiError(projRes, "Failed to fetch branches."), "");
     }
     const branch = projRes.data.branches.find((b) => b.name === name);
     if (!branch) {
-        s.stop();
-        error(`Branch "${name}" not found.`);
-        process.exit(1);
+        s?.stop();
+        emitError("BRANCH_NOT_FOUND", `Branch "${name}" not found.`, "List branches with: bata db branches --json");
     }
     const res = await api.del(`/v1/branches/${branch.id}`, token, query);
-    s.stop();
+    s?.stop();
     if (!res.ok) {
-        error("Failed to delete branch.");
-        process.exit(1);
+        emitError(res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE" : "CLI_ERROR", apiError(res, "Failed to delete branch."), "");
+    }
+    if (jsonMode) {
+        json({ branch: { id: branch.id, name, project_id: projectId }, deleted: true });
+        return;
     }
     log();
     log(`  ${colors.green(">")} Branch ${colors.cyan(name)} deleted`);
@@ -234,55 +260,76 @@ export async function studio() {
 export async function query(sql) {
     const jsonMode = isJsonMode();
     if (!sql) {
-        const msg = 'SQL query is required. Usage: bata db query "SELECT 1"';
-        if (jsonMode)
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("MISSING_ARG", "SQL query is required.", 'Usage: bata db query "SELECT 1"');
     }
     const token = requireToken();
     const config = loadConfig();
     const projectId = config.defaultProject;
     if (!projectId) {
-        const msg = "No default project set.";
-        if (jsonMode)
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const s = jsonMode ? null : spinner("Running query");
-    const res = await api.post(`/v1/query/${projectId}`, { sql }, token);
+    // Resolve the primary branch — /v1/sql/execute is keyed on branch_id, not
+    // project. (The old code POSTed to /v1/query/:projectId, which 404s.)
+    const branch = await getPrimaryBranch(projectId, token, config.defaultTeam);
+    if (!branch) {
+        s?.stop();
+        emitError("BRANCH_NOT_FOUND", "No branch found for this project to run the query against.", "Check the project with: bata db branches --json");
+    }
+    const res = await api.post("/v1/sql/execute", { branch_id: branch.id, query: sql }, token);
     s?.stop();
     if (!res.ok) {
-        if (jsonMode)
-            json({ error: apiError(res, "Query failed") });
-        else
-            error(apiError(res, "Query failed"));
-        process.exit(1);
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR";
+        emitError(code, apiError(res, "Query failed"), "");
     }
-    const { columns, rows, rowCount } = res.data;
+    // The endpoint returns 200 even when the SQL itself errored (it executed and
+    // failed). Treat that as a real error, not a silent success.
+    if (res.data.error) {
+        emitError("CLI_ERROR", res.data.error, "");
+    }
+    const columns = res.data.columns ?? [];
+    const rows = res.data.rows ?? [];
+    const rowCount = res.data.rowCount ?? rows.length;
     if (jsonMode) {
         json({
-            columns: columns ?? [],
-            rows: rows ?? [],
-            row_count: rowCount ?? rows?.length ?? 0,
+            columns,
+            rows, // column-keyed objects, exactly as the server returned them
+            row_count: rowCount,
+            command: res.data.command ?? null,
         });
         return;
     }
-    if (columns && rows) {
+    if (columns.length && rows.length) {
         log();
-        table(columns.map((c) => c.toUpperCase()), rows.map((r) => r.map(String)));
+        table(columns.map((c) => c.toUpperCase()), rows.map((r) => columns.map((col) => fmtCell(r[col]))));
         log();
-        log(`  ${colors.dim(`${rowCount ?? rows.length} row(s)`)}`);
+        log(`  ${colors.dim(`${rowCount} row(s)`)}`);
+    }
+    else if (rows.length) {
+        // Rows with no field metadata (rare) — render whatever keys came back.
+        const keys = Object.keys(rows[0]);
+        log();
+        table(keys.map((k) => k.toUpperCase()), rows.map((r) => keys.map((k) => fmtCell(r[k]))));
+        log();
+        log(`  ${colors.dim(`${rowCount} row(s)`)}`);
     }
     else {
         log();
-        log(`  ${colors.dim("Query executed successfully.")}`);
+        const cmd = res.data.command ? `${res.data.command} ` : "";
+        log(`  ${colors.dim(`${cmd}OK — ${rowCount} row(s) affected.`)}`);
     }
     log();
 }
+/** Render a column-keyed value for the table (null → empty, objects → JSON). */
+function fmtCell(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "object")
+        return JSON.stringify(v);
+    return String(v);
+}
 export async function handleDb(args) {
     const sub = args[0];
     switch (sub) {
@@ -298,18 +345,13 @@ export async function handleDb(args) {
                 return branchCreate(args[2]);
             if (action === "delete")
                 return branchDelete(args[2]);
-            error(`Unknown: db branch ${action || ""}`);
-            log(`  ${colors.dim("Available:")} create, delete`);
-            process.exit(1);
-            break;
+            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete");
         }
         case "studio":
             return studio();
         case "query":
             return query(args.slice(1).join(" "));
         default:
-            error(`Unknown subcommand: db ${sub || ""}`);
-            log(`  ${colors.dim("Available:")} connect, url, branches, branch, studio, query`);
-            process.exit(1);
+            emitError("INVALID_FLAG", `Unknown subcommand: db ${sub || ""}`, "Available: connect, url, branches, branch, studio, query");
     }
 }