@batadata/cli 0.1.0 → 0.1.2

package/dist/commands/schema.js

@@ -1,38 +1,202 @@
-import { colors, log, heading } from "../utils/logger.js";
-function comingSoon(cmd) {
-    heading(`Schema: ${cmd}`);
-    log(`  ${colors.yellow("!")} ${colors.dim("Coming soon.")} Schema ${cmd} is not yet implemented.`);
+import { readFileSync } from "node:fs";
+import { api, apiError } from "../api.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
+const NOT_IMPLEMENTED_HINT = "Use `bata schema check <file.sql> --fail-on breaking` to gate migrations today.";
+/**
+ * Unimplemented schema subcommand. Never exits 0 for a no-op: emits the
+ * NOT_IMPLEMENTED envelope (exit 3) pointing at the capability that exists.
+ */
+function notImplemented(cmd) {
+    emitError("NOT_IMPLEMENTED", `Schema ${cmd} is not yet implemented.`, NOT_IMPLEMENTED_HINT);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * Parse `schema check` args, consuming flag VALUES so they can't be mistaken
+ * for the positional file path (e.g. `--branch main migration.sql` must not
+ * read a file called "main").
+ */
+function parseCheckArgs(args) {
+    const out = { stdin: false, window: "24h" };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--branch") {
+            out.branch = args[++i];
+            continue;
+        }
+        if (a === "--window") {
+            out.window = args[++i] ?? out.window;
+            continue;
+        }
+        if (a === "--fail-on") {
+            out.failOn = args[++i];
+            continue;
+        }
+        if (a === "-") {
+            out.stdin = true;
+            continue;
+        }
+        if (a.startsWith("-"))
+            continue; // unknown/global flag already handled upstream
+        if (out.file === undefined)
+            out.file = a;
+    }
+    return out;
+}
+const riskColor = (r) => r === "breaking" ? colors.red(r.toUpperCase())
+    : r === "risky" || r === "unknown" ? colors.yellow(r.toUpperCase())
+        : colors.green(r.toUpperCase());
+function affectedLabel(a) {
+    if (a.index)
+        return `index ${a.index}`;
+    if (a.constraint)
+        return `constraint ${a.constraint}`;
+    if (a.table && a.columns.length)
+        return `${a.table}.${a.columns.join(", ")}`;
+    if (a.table)
+        return a.table;
+    return "—";
+}
+async function schemaCheck(args) {
+    const jsonMode = isJsonMode();
+    const { file, stdin, branch: branchId, window: timeRange, failOn } = parseCheckArgs(args);
+    // Reject a typo'd --fail-on value rather than silently disabling the gate.
+    if (failOn !== undefined && failOn !== "breaking" && failOn !== "risky") {
+        emitError("INVALID_FLAG", `Invalid --fail-on value "${failOn}".`, "Use --fail-on breaking or --fail-on risky.");
+    }
+    // ── read DDL (file path, explicit "-", or piped stdin) ──
+    let ddl;
+    try {
+        if (file) {
+            ddl = readFileSync(file, "utf8");
+        }
+        else if (stdin || !process.stdin.isTTY) {
+            ddl = await readStdin();
+        }
+        else {
+            emitError("EMPTY_INPUT", "No DDL provided.", 'Usage: bata schema check <file.sql>  (or pipe SQL: echo "ALTER TABLE ..." | bata schema check -)');
+        }
+    }
+    catch {
+        emitError("FILE_NOT_FOUND", `Could not read DDL from "${file}".`, "Pass a readable .sql file path or pipe SQL on stdin.");
+    }
+    if (!ddl.trim()) {
+        emitError("EMPTY_INPUT", "DDL input was empty.", "Provide a schema change to check, e.g. ALTER TABLE orders DROP COLUMN status;");
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    const projectId = config.defaultProject;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+    }
+    const body = { sql: ddl, timeRange };
+    if (branchId)
+        body.branch_id = branchId;
+    const s = jsonMode ? null : spinner("Checking schema change against live query corpus");
+    const res = await api.post(`/v1/insights/${projectId}/schema-check`, body, token);
+    s?.stop();
+    if (!res.ok) {
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status === 404 ? "NO_PROJECT"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR";
+        emitError(code, apiError(res, "Schema check failed"), "");
+    }
+    const v = res.data;
+    if (jsonMode) {
+        json(v); // server is the single source of truth for the verdict shape
+    }
+    else {
+        renderReport(v);
+    }
+    // Exit 0 on a successful analysis (risk lives in the payload). --fail-on gates
+    // for CI and is FAIL-CLOSED: `unknown` (the checker couldn't assess the change,
+    // e.g. TRUNCATE / DROP SCHEMA) trips BOTH thresholds, so a gate never goes
+    // green on an unassessable-but-dangerous migration.
+    if (failOn === "breaking" && (v.overallRisk === "breaking" || v.overallRisk === "unknown"))
+        process.exit(2);
+    if (failOn === "risky" && v.overallRisk !== "safe")
+        process.exit(2);
+}
+function renderReport(v) {
+    heading("Schema check");
+    if (v.corpus.empty) {
+        log(`  ${colors.yellow("!")} No user query traffic in the last ${v.corpus.windowHours}h — cannot assert safety.`);
+    }
+    else {
+        const br = v.corpus.branchId ? ` on branch ${colors.cyan(v.corpus.branchId)}` : "";
+        log(`  ${colors.dim(`Checked against ${v.corpus.queryShapes} query shapes (${v.corpus.totalCalls.toLocaleString()} calls) over ${v.corpus.windowHours}h${br}`)}`);
+    }
     log();
-    log(`  ${colors.dim("Track progress at")} ${colors.cyan("https://github.com/zvndev")}`);
+    log(`  Verdict: ${riskColor(v.overallRisk)}   ${colors.dim(`${v.summary.breakingCount} breaking · ${v.summary.riskyCount} risky · ${v.summary.safeCount} safe · ${v.summary.unknownCount} unknown`)}`);
+    if (v.summary.totalCallsAtRisk > 0) {
+        log(`  ${colors.red(`${v.summary.totalCallsAtRisk.toLocaleString()} calls/window hit a breaking change`)}`);
+    }
+    log();
+    for (const f of v.findings) {
+        log(`  ${riskColor(f.risk)}  ${colors.bold(f.operation)}  ${colors.dim(affectedLabel(f.affected))}`);
+        log(`    ${colors.dim(f.statement)}`);
+        if (f.impactedQueries.length) {
+            const shown = f.impactedQueries.slice(0, 8);
+            table(["QUERY", "CALLS", "MEAN", "RISK"], shown.map((q) => [
+                q.query.length > 60 ? q.query.slice(0, 57) + "…" : q.query,
+                q.calls.toLocaleString(),
+                `${q.meanTimeMs}ms`,
+                q.risk,
+            ]));
+            if (f.impactedQueries.length > shown.length) {
+                log(`    ${colors.dim(`+ ${f.impactedQueries.length - shown.length} more`)}`);
+            }
+        }
+        if (f.note)
+            log(`    ${colors.yellow("note:")} ${colors.dim(f.note)}`);
+        if (f.suggestion)
+            log(`    ${colors.cyan("fix:")} ${colors.dim(f.suggestion)}`);
+        log();
+    }
+    for (const n of v.notes)
+        log(`  ${colors.dim(`· ${n}`)}`);
     log();
 }
 export async function handleSchema(args) {
     const sub = args[0];
     switch (sub) {
+        case "check":
+            return schemaCheck(args.slice(1));
         case "init":
-            comingSoon("init");
-            break;
+            notImplemented("init");
         case "push":
-            comingSoon("push");
-            break;
+            notImplemented("push");
         case "pull":
-            comingSoon("pull");
-            break;
+            notImplemented("pull");
         case "diff":
-            comingSoon("diff");
-            break;
+            notImplemented("diff");
         default:
             log();
-            log(`  ${colors.bold("bata schema")} ${colors.dim("— Turbine ORM schema management")}`);
+            log(`  ${colors.bold("bata schema")} ${colors.dim("— schema safety & management")}`);
             log();
             log(`  ${colors.dim("Commands:")}`);
-            log(`    ${colors.cyan("init")}    Initialize schema from existing database`);
-            log(`    ${colors.cyan("push")}    Push schema changes to database`);
-            log(`    ${colors.cyan("pull")}    Pull schema from database`);
-            log(`    ${colors.cyan("diff")}    Show pending schema changes`);
+            log(`    ${colors.cyan("check <file|->")}  Check a proposed DDL change against live query traffic`);
+            log(`    ${colors.cyan("init")}            Initialize schema from existing database ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("push")}            Push schema changes to database ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("pull")}            Pull schema from database ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("diff")}            Show pending schema changes ${colors.dim("(coming soon)")}`);
+            log();
+            log(`  ${colors.dim("Options:")}`);
+            log(`    ${colors.dim("--branch <id>      check against a branch's traffic")}`);
+            log(`    ${colors.dim("--window <1h|24h|7d|30d>   corpus window (default 24h)")}`);
+            log(`    ${colors.dim("--fail-on <breaking|risky>  exit 2 to gate CI (fail-closed: 'unknown' also trips)")}`);
             log();
-            log(`  ${colors.yellow("!")} ${colors.dim("All schema commands are coming soon.")}`);
+            log(`  ${colors.dim("Examples:")}`);
+            log(`    ${colors.dim("bata schema check migration.sql")}`);
+            log(`    ${colors.dim('echo "ALTER TABLE orders DROP COLUMN status;" | bata schema check - --json')}`);
+            log(`    ${colors.dim("bata schema check migration.sql --fail-on breaking   # CI gate")}`);
             log();
     }
 }
-//# sourceMappingURL=schema.js.map

package/dist/commands/status.js

@@ -4,9 +4,10 @@
  * Lists projects with branch count, compute status, and storage size.
  * Colorized output: green for running, yellow for suspended, red for error.
  */
-import { api, apiError } from "../api.js";
+import { api, apiError, resolveTeamId } from "../api.js";
 import { requireToken, loadConfig, isJsonMode } from "../config.js";
-import { colors, log, json, error, spinner, table, heading } from "../utils/logger.js";
+import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
 function statusBadge(status) {
     switch (status?.toLowerCase()) {
         case "active":
@@ -36,19 +37,21 @@ export async function status() {
     const config = loadConfig();
     const jsonMode = isJsonMode();
     const s = jsonMode ? null : spinner("Fetching projects");
-    const query = {};
-    if (config.defaultTeam)
-        query.team_id = config.defaultTeam;
-    const res = await api.get("/v1/projects", token, query);
+    // GET /v1/projects requires a team_id. On the API-key path config.defaultTeam
+    // is empty, so resolve it the way `create` does (falls back to the user's
+    // first team) — otherwise this 400s headlessly.
+    const teamId = await resolveTeamId(token);
+    if (!teamId) {
+        s?.stop();
+        emitError("NO_TEAM", "No team found for this credential.", "This API key isn't attached to a team. Run `bata login` or check `bata whoami`.");
+    }
+    const res = await api.get("/v1/projects", token, { team_id: teamId });
     if (!res.ok) {
         s?.stop();
-        if (jsonMode) {
-            json({ error: apiError(res, "Failed to fetch projects") });
-        }
-        else {
-            error(apiError(res, "Failed to fetch projects"));
-        }
-        process.exit(1);
+        // Surface the server's validation message, not a bare "HTTP 400".
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch projects"), "");
     }
     s?.stop();
     const projects = Array.isArray(res.data) ? res.data : [];
@@ -103,4 +106,3 @@ export async function status() {
     log(`  ${colors.dim(`${projects.length} project(s). ${colors.cyan("*")} = default`)}`);
     log();
 }
-//# sourceMappingURL=status.js.map

package/dist/commands/usage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * bata usage — Cost truth for the current billing period.
+ *
+ * Calls the control-plane current-usage endpoint (GET /v1/billing/current-usage)
+ * and renders per-dimension cost for the credential's team.
+ *
+ * HONESTY RULE (the whole point of the cost-truth wedge):
+ *   A dimension that is NOT actually metered must render "Not metered yet" and
+ *   NEVER a priced $0. Today transfer is not metered end-to-end, so it reports
+ *   { metered: false, value: null, cost_cents: null, status: "not_metered_yet" }.
+ *   We will only show a dollar figure for a dimension we genuinely meter.
+ */
+export declare function usage(args: string[]): Promise<void>;

package/dist/commands/usage.js

@@ -0,0 +1,164 @@
+/**
+ * bata usage — Cost truth for the current billing period.
+ *
+ * Calls the control-plane current-usage endpoint (GET /v1/billing/current-usage)
+ * and renders per-dimension cost for the credential's team.
+ *
+ * HONESTY RULE (the whole point of the cost-truth wedge):
+ *   A dimension that is NOT actually metered must render "Not metered yet" and
+ *   NEVER a priced $0. Today transfer is not metered end-to-end, so it reports
+ *   { metered: false, value: null, cost_cents: null, status: "not_metered_yet" }.
+ *   We will only show a dollar figure for a dimension we genuinely meter.
+ */
+import { api, apiError } from "../api.js";
+import { requireToken, isJsonMode } from "../config.js";
+import { colors, log, json, spinner, table, heading, kvList } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
+/**
+ * Decide whether a dimension is truly metered. A dimension is metered only when
+ * the API explicitly says so (`metered === true`). A missing `metered` field is
+ * treated as not-metered for transfer (the API doesn't meter it yet); compute
+ * and storage default to metered because those ARE wired up end-to-end.
+ */
+function dimensionView(dim, value, unit, meteredDefault) {
+    const metered = dim?.metered ?? meteredDefault;
+    if (!metered) {
+        return { metered: false, value: null, unit, cost_cents: null, status: "not_metered_yet" };
+    }
+    return {
+        metered: true,
+        value,
+        unit,
+        cost_cents: dim?.costCents ?? null,
+        status: "metered",
+    };
+}
+function dollars(cents) {
+    if (cents === null)
+        return colors.dim("Not metered yet");
+    return `$${(cents / 100).toFixed(cents % 100 === 0 ? 2 : 4)}`;
+}
+function valueLabel(d) {
+    if (!d.metered || d.value === null)
+        return colors.dim("—");
+    return `${d.value} ${d.unit}`;
+}
+function parseProjectFlag(args) {
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--project" && args[i + 1])
+            return args[i + 1];
+        if (args[i].startsWith("--project="))
+            return args[i].slice("--project=".length);
+    }
+    return undefined;
+}
+export async function usage(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const projectFilter = parseProjectFlag(args);
+    const s = jsonMode ? null : spinner("Fetching usage");
+    // current-usage derives the team from the credential — no team_id needed.
+    const res = await api.get("/v1/billing/current-usage", token);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch usage"), "");
+    }
+    const data = res.data ?? {};
+    let projects = data.projects ?? [];
+    if (projectFilter) {
+        projects = projects.filter((p) => p.projectId === projectFilter || p.projectName === projectFilter);
+        if (projects.length === 0) {
+            emitError("NOT_FOUND", `No usage for project "${projectFilter}".`, "Check the project id/name with: bata projects list --json");
+        }
+    }
+    // Build per-project, per-dimension views. compute + storage are metered;
+    // transfer is NOT metered end-to-end yet → "Not metered yet", never $0.
+    const projectViews = projects.map((p) => {
+        const compute = dimensionView(p.compute, p.compute?.hours ?? null, "CU-hr", true);
+        const storage = dimensionView(p.storage, p.storage?.gb ?? null, "GB", true);
+        const transfer = dimensionView(p.transfer, p.transfer?.gb ?? null, "GB", false);
+        return { project: p, compute, storage, transfer };
+    });
+    // Recommendations: top-level + any per-project ones, normalized with an action.
+    const recommendations = [
+        ...(data.recommendations ?? []),
+        ...projects
+            .filter((p) => p.recommendation)
+            .map((p) => ({ ...p.recommendation, projectId: p.projectId })),
+    ]
+        .filter((r) => r && (r.message || r.action))
+        .map((r) => ({
+        kind: r.kind ?? "suspend_idle",
+        message: r.message ?? "",
+        action: r.action ?? null,
+    }));
+    if (jsonMode) {
+        json({
+            period_start: data.periodStart ?? null,
+            plan: data.plan ?? null,
+            pricing: data.pricing ?? null,
+            projects: projectViews.map(({ project, compute, storage, transfer }) => ({
+                project_id: project.projectId,
+                project_name: project.projectName,
+                status: project.status ?? null,
+                // Honest envelope: metered dimensions carry a number, un-metered ones
+                // carry nulls and status:"not_metered_yet" — never a priced $0.
+                compute,
+                storage,
+                transfer,
+                active_computes: project.activeComputes?.length ?? 0,
+            })),
+            totals: data.totals
+                ? {
+                    estimated_cost_cents: data.totals.estimatedCostCents ?? 0,
+                    compute_hours: data.totals.computeHours ?? null,
+                    storage_gb: data.totals.storageGb ?? null,
+                    // transfer is not metered yet → null + status, not 0
+                    transfer: { metered: false, value: null, unit: "GB", cost_cents: null, status: "not_metered_yet" },
+                    active_computes: data.totals.activeComputes ?? 0,
+                }
+                : null,
+            recommendations,
+        });
+        return;
+    }
+    // ── Human output ──
+    heading("Usage — current period");
+    const planName = data.plan?.name ?? "free";
+    const base = data.plan?.monthlyBaseCents ?? 0;
+    kvList([
+        ["Plan", `${planName}${base ? ` (${dollars(base)}/mo base)` : ""}`],
+        ["Period start", data.periodStart ? new Date(data.periodStart).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" }) : "-"],
+    ]);
+    log();
+    if (projectViews.length === 0) {
+        log(`  ${colors.dim("No projects with usage in this period.")}`);
+        log();
+        return;
+    }
+    for (const { project, compute, storage, transfer } of projectViews) {
+        log(`  ${colors.bold(project.projectName)} ${colors.dim(project.projectId)}`);
+        table(["DIMENSION", "USAGE", "COST"], [
+            ["Compute", valueLabel(compute), dollars(compute.cost_cents)],
+            ["Storage", valueLabel(storage), dollars(storage.cost_cents)],
+            ["Transfer", valueLabel(transfer), dollars(transfer.cost_cents)],
+        ]);
+        log();
+    }
+    if (data.totals) {
+        const total = data.totals.estimatedCostCents ?? 0;
+        log(`  ${colors.bold("Total estimated:")} ${dollars(total + base)}  ${colors.dim("(metered dimensions only — transfer not metered yet)")}`);
+        log();
+    }
+    if (recommendations.length) {
+        log(`  ${colors.bold("Recommendations")}`);
+        for (const r of recommendations) {
+            log(`    ${colors.yellow("·")} ${r.message}`);
+            if (r.action)
+                log(`      ${colors.cyan(r.action)}`);
+        }
+        log();
+    }
+}

package/dist/config.d.ts

@@ -13,9 +13,12 @@ interface RuntimeContext {
     apiKey?: string;
     apiUrl?: string;
     json: boolean;
+    yes: boolean;
 }
 export declare function setRuntime(ctx: Partial<RuntimeContext>): void;
 export declare function isJsonMode(): boolean;
+/** Was `--yes` / `-y` passed? (Skips destructive confirmation prompts.) */
+export declare function isYes(): boolean;
 export declare function loadConfig(): BataConfig;
 export declare function saveConfig(config: Partial<BataConfig>): void;
 export declare function clearConfig(): void;

package/dist/config.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 const CONFIG_PATH = path.join(os.homedir(), ".batarc");
 const DEFAULT_API_URL = "https://api.batadata.com";
-const runtime = { json: false };
+const runtime = { json: false, yes: false };
 export function setRuntime(ctx) {
     if (ctx.apiKey !== undefined)
         runtime.apiKey = ctx.apiKey;
@@ -11,10 +11,16 @@ export function setRuntime(ctx) {
         runtime.apiUrl = ctx.apiUrl;
     if (ctx.json !== undefined)
         runtime.json = ctx.json;
+    if (ctx.yes !== undefined)
+        runtime.yes = ctx.yes;
 }
 export function isJsonMode() {
     return runtime.json;
 }
+/** Was `--yes` / `-y` passed? (Skips destructive confirmation prompts.) */
+export function isYes() {
+    return runtime.yes;
+}
 export function loadConfig() {
     try {
         const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
@@ -70,7 +76,8 @@ export function requireToken() {
                 "\x1b[36m--api-key\x1b[0m, set \x1b[36mBATA_API_KEY\x1b[0m, or run " +
                 "\x1b[36mbata login\x1b[0m.");
         }
-        process.exit(1);
+        // Exit 4 = auth/credentials per the documented exit-code contract.
+        process.exit(4);
     }
     return token;
 }
@@ -93,4 +100,3 @@ export function getDefaultProject() {
 export function getDefaultTeam() {
     return loadConfig().defaultTeam;
 }
-//# sourceMappingURL=config.js.map

package/dist/index.js

@@ -10,10 +10,12 @@ import { dev } from "./commands/dev.js";
 import { create } from "./commands/create.js";
 import { status } from "./commands/status.js";
 import { connect } from "./commands/connect.js";
+import { usage } from "./commands/usage.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
 import { colors, log, banner } from "./utils/logger.js";
-const VERSION = "0.1.0";
+import { exitCodeFor } from "./utils/errors.js";
+const VERSION = "0.1.2";
 function help() {
     banner();
     log(`  ${colors.bold("Usage")}`);
@@ -23,6 +25,7 @@ function help() {
     log(`    ${colors.cyan("create <name>")}     Create a project and wait for it to be ready`);
     log(`    ${colors.cyan("connect <name>")}    Open psql to a project (auto-wakes if suspended)`);
     log(`    ${colors.cyan("status")}             Show all projects and their status`);
+    log(`    ${colors.cyan("usage")}              Per-dimension cost for the current period`);
     log();
     log(`  ${colors.bold("Auth")}`);
     log(`    ${colors.cyan("login")}              Log in to BataDB`);
@@ -63,11 +66,27 @@ function help() {
     log(`    ${colors.dim("--help, -h")}         Show this help message`);
     log(`    ${colors.dim("--version, -v")}      Show version`);
     log();
-    log(`  ${colors.bold("Headless / agents")}`);
+    log(`  ${colors.bold("Agents")} ${colors.dim("(headless, machine-readable)")}`);
     log(`    ${colors.dim("Every command works with just")} ${colors.cyan("BATA_API_KEY")} ${colors.dim("set — no login needed.")}`);
-    log(`    ${colors.dim("Mint a key with")} ${colors.cyan("bata api-keys create")}${colors.dim(".")}`);
+    log(`    ${colors.dim("Mint a key with")} ${colors.cyan("bata api-keys create --json")}${colors.dim(".")}`);
     log();
-    log(`  ${colors.dim("Documentation:")} ${colors.cyan("https://batadata.com/docs")}`);
+    log(`    ${colors.cyan("schema check <file.sql> --fail-on breaking")}  Gate a migration (exit 2 if breaking)`);
+    log(`    ${colors.cyan("db url --json")}                               Print connection string as JSON`);
+    log(`    ${colors.cyan("db query <sql> --json")}                       Run SQL headlessly, rows as JSON objects`);
+    log(`    ${colors.cyan("usage --json")}                                Per-dimension cost (honest: un-metered → null)`);
+    log();
+    log(`    ${colors.dim("All errors in --json mode share one envelope:")} ${colors.dim('{ "error", "code", "hint" }')} ${colors.dim("on stderr.")}`);
+    log();
+    log(`  ${colors.bold("Exit codes")}`);
+    log(`    ${colors.dim("0")}  success`);
+    log(`    ${colors.dim("1")}  generic error ${colors.dim("(CLI_ERROR)")}`);
+    log(`    ${colors.dim("2")}  gate tripped ${colors.dim("(schema check --fail-on)")}`);
+    log(`    ${colors.dim("3")}  not implemented ${colors.dim("(NOT_IMPLEMENTED)")}`);
+    log(`    ${colors.dim("4")}  auth / credentials ${colors.dim("(NO_CREDENTIALS, INVALID_KEY)")}`);
+    log(`    ${colors.dim("5")}  not-found / bad input ${colors.dim("(NO_PROJECT, BRANCH_NOT_FOUND, INVALID_FLAG, INTERACTIVE_ONLY)")}`);
+    log(`    ${colors.dim("6")}  upstream / transient ${colors.dim("(API_UNAVAILABLE, TIMEOUT — retryable)")}`);
+    log();
+    log(`  ${colors.dim("Documentation:")} ${colors.cyan("https://www.npmjs.com/package/@batadata/cli")}`);
     log();
 }
 async function main() {
@@ -99,6 +118,9 @@ async function main() {
             case "connect":
                 await connect(rest);
                 break;
+            case "usage":
+                await usage(rest);
+                break;
             // Auth
             case "login":
                 await login();
@@ -144,26 +166,39 @@ async function main() {
                 await dev();
                 break;
             default:
-                log();
-                log(`  ${colors.red("Error:")} Unknown command ${colors.white(command)}`);
-                log();
-                log(`  Run ${colors.cyan("bata --help")} to see available commands.`);
-                log();
-                process.exit(1);
+                if (isJsonMode()) {
+                    log(JSON.stringify({
+                        error: `Unknown command "${command}".`,
+                        code: "INVALID_FLAG",
+                        hint: "Run `bata --help` to see available commands.",
+                    }, null, 2));
+                }
+                else {
+                    log();
+                    log(`  ${colors.red("Error:")} Unknown command ${colors.white(command)}`);
+                    log();
+                    log(`  Run ${colors.cyan("bata --help")} to see available commands.`);
+                    log();
+                }
+                process.exit(exitCodeFor("INVALID_FLAG"));
         }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        // Network/transport throws (e.g. the request timed out, DNS/connection
+        // refused) are upstream/transient — surface them with a retryable code so
+        // agents know to back off rather than treating it as a hard CLI bug.
+        const transient = /timed out|ECONNREFUSED|ENOTFOUND|ECONNRESET|EAI_AGAIN|socket hang up/i.test(message);
+        const code = transient ? (/timed out/i.test(message) ? "TIMEOUT" : "API_UNAVAILABLE") : "CLI_ERROR";
         if (isJsonMode()) {
-            log(JSON.stringify({ error: message, code: "CLI_ERROR" }, null, 2));
+            log(JSON.stringify({ error: message, code, hint: "" }, null, 2));
         }
         else {
             log();
             log(`  ${colors.red("Error:")} ${message}`);
             log();
         }
-        process.exit(1);
+        process.exit(exitCodeFor(code));
     }
 }
 main();
-//# sourceMappingURL=index.js.map

package/dist/utils/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared error / exit-code contract for the whole CLI.
+ *
+ * Every command emits ONE JSON error envelope in --json mode:
+ *   { "error": string, "code": SCREAMING_SNAKE, "hint": string }
+ * Errors always go to stderr (via error()); the envelope is the only thing on
+ * stdout in --json mode, so machine consumers can parse stdout cleanly.
+ *
+ * ── Exit-code contract (documented + surfaced in `bata --help`) ──
+ *   0  success
+ *   1  generic CLI_ERROR (genuinely-unknown failure)
+ *   2  gate tripped (schema check --fail-on)
+ *   3  NOT_IMPLEMENTED (coming-soon command — never a silent no-op exit 0)
+ *   4  auth / creds        — NO_CREDENTIALS, INVALID_KEY
+ *   5  not-found/bad-input — NO_PROJECT, BRANCH_NOT_FOUND, INVALID_FLAG, INTERACTIVE_ONLY, ...
+ *   6  upstream/transient  — API_UNAVAILABLE, TIMEOUT (retryable)
+ */
+export type ErrorCode = "CLI_ERROR" | "NOT_IMPLEMENTED" | "NO_CREDENTIALS" | "INVALID_KEY" | "NO_PROJECT" | "BRANCH_NOT_FOUND" | "INVALID_FLAG" | "INTERACTIVE_ONLY" | "NO_TEAM" | "EMPTY_INPUT" | "FILE_NOT_FOUND" | "MISSING_ARG" | "NOT_FOUND" | "API_UNAVAILABLE" | "TIMEOUT" | "GATE_TRIPPED";
+/** Map an error code to its documented process exit code. */
+export declare function exitCodeFor(code: string): number;
+/**
+ * Emit the single error envelope and exit with the code that matches `code`.
+ * In --json mode: `{ error, code, hint }` to stdout-as-JSON (errors stay clean).
+ * In human mode: a red "Error:" line to stderr plus a dim hint.
+ *
+ * Promoted from schema.ts so every command shares one contract. Pass an explicit
+ * `exitCode` only to override the table (rare — e.g. forcing 1 on an unknown).
+ */
+export declare function emitError(code: ErrorCode | string, message: string, hint?: string, exitCode?: number): never;