@batadata/cli 0.1.1 → 0.1.3

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.3",
     };
     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.d.ts

@@ -4,5 +4,5 @@ export declare function branches(): Promise<void>;
 export declare function branchCreate(name?: string): Promise<void>;
 export declare function branchDelete(name?: string): Promise<void>;
 export declare function studio(): Promise<void>;
-export declare function query(sql?: string): Promise<void>;
+export declare function query(args?: string[]): Promise<void>;
 export declare function handleDb(args: string[]): Promise<void>;