CLI reference

bata is the command-line interface for BataDB, built to be driven by people and by agents alike. Install it with npm install -g @batadata/cli (Node.js 20 or newer).

Agent contract#

• Auth. Every command works headlessly with BATA_API_KEY (or --api-key). Create a narrowly scoped key with bata keys create --scope read --scope sql --project <id>. Or approve the machine once with bata login: its CLI key renews itself on use (it expires after 90 days unused) and survives a password change, so agents on that machine never need a person again. --profile <name> / BATA_PROFILE keep several logins side by side.
• --json. Prints one JSON document on stdout: the API payload for most commands, a fixed summary for a few (create, status, projects create). Human output is for people and may change.
• Errors. In --json mode every failure prints one envelope, { "error", "code", "hint" }, and exits non-zero (table below).
• No prompts without a terminal. Destructive commands prompt on a terminal. Without one (a pipe, CI, an agent) or with --json, they refuse with CONFIRM_REQUIRED unless you pass --yes.
• Help never touches the network. --help on any command prints its usage, flags and the API routes it calls.
• Project and branch. --project falls back to the directory's link (bata link) and then to the saved default (bata import is the exception: without --project it creates a project). --branch takes a name or an id and defaults to the pinned branch (bata db branch checkout), then the primary.

Global flags#

Exit codes#

AUTH_REQUIRED means the saved login (a profile) was refused. The envelope carries reason (revoked, expired, signed_out_everywhere, logged_out, invalid_or_expired_session, unknown_key, no_membership), at (when, if known), profile, and next, the command that fixes it (bata login --json). A person approves that login once in the browser. INVALID_KEY means a --api-key or BATA_API_KEY key was refused. It carries the same reason and at, and next: null: replace that key, because a login does not override it. KEY_SCOPE_DENIED means the API key lacks the scope the endpoint needs; the hint names it (read, sql, admin). KEY_PROJECT_DENIED means a project-restricted key tried another project or a team-level endpoint. PAYMENT_METHOD_REQUIRED means the team needs a card on file before any database can be created or started. The hint and the envelope's add_card_url carry the link; a person adds the card there (bata billing card add makes a direct one). Nothing is charged while usage stays inside the free allowance. SPEND_CAP_REACHED means the team hit its spend cap, or used its free allowance while stopping there (the default on Free). An owner or admin raises the cap (bata billing spend-cap) or turns on pay as you go (bata billing stop-at-limit off).

Commands#

Quick start#

Create, connect to and inspect databases in one call.

bata new#

Create a database in your team in one call (no name or region to pick).

bata new [--team <id>] [--json]

Prints the direct and pooled connection strings and saves the new project as the default. It bills like any other project.

If the server has instant databases turned off, it exits 5 (NOT_FOUND): use bata create <name> instead.

API: POST /v1/claim/new

bata claim#

Legacy: redeem a claim token from the retired anonymous flow.

bata claim <token> [--json]

API: POST /v1/claim/redeem

bata create#

Create a project and wait until it is ready.

bata create <name> [--region <r>] [--set-default] [--json]

Creates a serverless 1 CU project, waits for its compute to answer, then prints the connection strings. For another tier or size use bata projects create.

Safe to re-run: if your team already has a project with this name, it reuses that project (existing: true in --json).

The new project becomes the saved default only when none is saved yet, or with --set-default. The output says whether the default changed.

API: POST /v1/projects, GET /v1/operations/:id, GET /v1/connection-info/:projectId

bata status#

Show all projects and their status.

bata status [--json]

API: GET /v1/projects

bata connect#

Open psql to a project (interactive; wakes a suspended compute).

bata connect [<project>]

API: GET /v1/connection-info/:projectId, GET /v1/branches/:id, POST /v1/computes/:id/start

bata usage#

Per-dimension usage and cost for the current period (un-metered dimensions are null, never $0).

bata usage [--project <id>] [--by-query [--window <w>] [--branch <b>] [--tag <t>]] [--json]

API: GET /v1/billing/current-usage, GET /v1/insights/:projectId/turbine-queries

bata link#

Link this directory to a project (writes .batadata/project.json).

bata link [<project>] [--status] [--json]

API: GET /v1/projects

bata unlink#

Remove this directory's project link.

bata unlink

Auth and identity#

Log in, see who you are and what your key can do.

bata login#

Approve this machine once in the browser (or --password for email + password).

bata login [--password] [--new] [--no-browser] [--json] [--profile <name>]

Prints a code and opens the console approval page, where you type that code and approve it for one team (you must be its owner or admin).

Saves an API key named cli-<hostname> in the active profile (~/.batarc by default). The key is never printed. It expires after 90 days unused: every use renews it, and a password change keeps it. Revoke it with bata logout, bata keys revoke <id>, or in the console (Settings).

Running bata login again while a login is pending (same API, not expired) resumes it with the same code, so an agent whose call timed out just runs bata login --json again. --new starts over.

Headless machines (no TTY, SSH, no display) print the URL instead: open it on any device where you are logged in.

--json prints one JSON line when pending (with resumed) and one when approved.

API: POST /v1/cli-login/exchange

bata logout#

Log out: revoke the saved CLI key and clear the active profile.

bata logout [--profile <name>]

The saved CLI key is revoked (best effort) before the profile file (~/.batarc by default) is removed.

bata whoami#

Show the caller: user, team, role, and the credential (source, profile, kind, name, expiry, scopes).

bata whoami [--json]

For an API key, credential.scopes and credential.project_ids say exactly what it may call.

credential.source is profile, env (BATA_API_KEY) or flag (--api-key); credential.kind is cli, integration, or session for a leftover password login (with its expiry).

API: GET /v1/whoami

API keys#

Create, list, rotate and revoke scoped API keys.

bata keys create#

Create an API key (shown once); scopes are enforced by the server. --app makes a permanent, table-scoped deployment key.

bata keys create [--name <n>] [--scope <s>]... [--project <id>]... | --app [--project <id>] [--branch <b>] [--database <db>] --grant <privilege:table>... [--json]

admin: full access. read: read-only API. sql: read plus running SQL. telemetry:write: telemetry ingest only (needs a project).

An app key needs at least one --grant, unless it is telemetry-only (--scope telemetry:write). Privileges: select, insert, update, delete. INSERT ... RETURNING also needs select.

App keys can only call POST /v1/sql (as their own role) and the telemetry ingest routes; Postgres enforces the grants.

API: POST /v1/api-keys

bata keys list#

List active API keys: kind (cli, integration, app), access, last used, expiry.

bata keys list [--json]

An app key's rotated-out secret shows as kind app (retiring) until its overlap ends.

API: GET /v1/api-keys

bata keys expiring#

List keys that expire within 7 days.

bata keys expiring [--json]

API: GET /v1/api-keys/expiring

bata keys rotate#

Rotate a key: mint a replacement (shown once). CLI/integration keys: the old one is revoked now. App keys: the old secret keeps working for --overlap.

bata keys rotate <key-id> [--overlap <0|30m|24h|7d>] [--json]

API: POST /v1/api-keys/:id/rotate

bata keys grant#

Change an app key's table grants; applied to its database role immediately.

bata keys grant <key-id> [--grant <privilege:table>]... [--revoke <privilege:table>]... | --set <privilege:table>... [--json]

API: PATCH /v1/api-keys/:id/grants

bata keys revoke#

Revoke an API key (an app key's role is dropped from its database too).

bata keys revoke <key-id> --yes [--json]

Revoking an app key's rotated-out (retiring) secret only ends its overlap; the key keeps working.

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/api-keys/:id

Projects#

Create, inspect, update and delete projects.

bata projects list#

List projects (alias of status).

bata projects list [--json]

API: GET /v1/projects

bata projects create#

Create a project.

bata projects create <name> [--region <r>] [--tier serverless|always-on] [--size <cu>] [--engine postgres|powdb] [--set-default] [--json]

Returns once the project is accepted; its compute keeps starting. Poll bata db branches --json for ready, or use bata create to wait.

New projects run Postgres 17.

The new project becomes the saved default only when none is saved yet, or with --set-default. The output says whether the default changed.

API: POST /v1/projects

bata projects info#

Show a project's details, branches and connection strings.

bata projects info [<id>] [--json]

API: GET /v1/projects/:id, GET /v1/connection-info/:projectId

bata projects update#

Rename a project or replace its settings.

bata projects update [<id>] [--name <name>] [--settings <json>] [--json]

API: PATCH /v1/projects/:id

bata projects storage#

Show storage use against the quota, or change the project quota.

bata projects storage [<id>] [--quota-gb <n> | --clear-quota] [--block-writes <true|false>] [--json]

API: GET /v1/projects/:id/storage, PATCH /v1/projects/:id/storage-quota

bata projects delete#

Permanently delete a project and all its branches.

bata projects delete [<id>] --yes [--json]

Clears the saved default project only when the deleted project was the default, and says so.

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/projects/:id

bata projects pitr#

Show or change how far back a project can be restored.

bata projects pitr [<id>] [--days 1|7|14|30] [--confirm <project-name>] [--json]

API: GET /v1/projects/:id/pitr, PATCH /v1/projects/:id/pitr

Database: branches, SQL, tables, databases, roles#

Branches, SQL, table browsing, databases and roles.

bata db query#

Run SQL against a branch (rows as JSON with --json); --at time-travels.

bata db query <sql> [--project <id>] [--branch <name-or-id>] [--at <timestamp|LSN>] [--no-wait] [--json]

A just-created or idle branch may answer exit 6 (retryable) while its compute wakes.

--at forks a hidden ephemeral branch AS OF the point (auto-deleted ~10 min).

API: POST /v1/sql/execute, POST /v1/time-travel/query

bata db url#

Print a branch's connection strings (pooled and direct).

bata db url [--project <id>] [--branch <name-or-id>] [--json]

Pooled: app traffic and serverless functions. Direct: migrations, pg_dump, LISTEN/NOTIFY and session features.

API: GET /v1/connection-info/:projectId

bata db connect#

Open an interactive psql session.

bata db connect [--project <id>]

API: GET /v1/connection-info/:projectId

bata db studio#

Open the table browser in your browser.

bata db studio

bata db ping#

Test that a branch accepts connections (runs SELECT 1; never wakes a suspended compute).

bata db ping [--project <id>] [--branch <name-or-id>] [--json]

API: POST /v1/sql/test-connection

bata db tables#

List tables with columns, primary keys and row estimates.

bata db tables [--project <id>] [--branch <b>] [--schema <s>] [--database <d>] [--json]

API: GET /v1/sql/tables

bata db rows#

Browse a table's rows with filters, sort and paging.

bata db rows <[schema.]table> [--filter "col op value"]... [--match and|or] [--sort col[:asc|desc]] [--page <n>] [--page-size <n>] [--json]

Operators: = != > >= < <= LIKE ILIKE IN, IS NULL, IS NOT NULL, and eq neq gt gte lt lte contains not_contains starts_with ends_with in not_in is_null not_null is_true is_false. IN takes a comma list.

API: GET /v1/sql/rows

bata db rows insert#

Insert one row into a table.

bata db rows insert <[schema.]table> --values <json> [--json]

API: POST /v1/sql/rows

bata db rows update#

Update one row, addressed by its primary key.

bata db rows update <[schema.]table> --pk <json> --values <json> [--json]

API: PUT /v1/sql/rows

bata db rows delete#

Delete rows by primary key.

bata db rows delete <[schema.]table> --pk <json> [--pk <json>]... --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/sql/rows

bata db branches#

List branches with compute readiness (poll ready after create or a cold start).

bata db branches [--project <id>] [--include-ephemeral] [--json]

--include-ephemeral also lists hidden time-travel forks (uses GET /v1/branches).

API: GET /v1/projects/:id, GET /v1/branches

bata db branch create#

Create a branch (a copy-on-write fork of its parent); --expires-in makes it ephemeral.

bata db branch create <name> [--project <id>] [--parent <name-or-id>] [--expires-in <2h|30m|7d>] [--purpose <text>] [--json]

API: POST /v1/branches

bata db branch info#

Show a branch with its computes, databases and roles.

bata db branch info <name-or-id> [--project <id>] [--json]

API: GET /v1/branches/:id

bata db branch delete#

Delete a branch (protected branches are refused).

bata db branch delete <name-or-id> [--project <id>] --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/branches/:id

bata db branch reset#

Replace a branch's data with its parent's current state (async).

bata db branch reset <name-or-id> [--project <id>] --yes [--wait] [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: POST /v1/branches/:id/reset-from-parent, GET /v1/operations/:id

bata db branch rollback#

Overwrite a branch with the state of a source branch at a past timestamp or LSN (async).

bata db branch rollback <name-or-id> --to <timestamp|LSN> [--source <name-or-id>] [--project <id>] --yes [--wait] [--json]

The branch's current data is replaced. To keep it, use bata restore create (non-destructive) instead.

Destructive: needs --yes when no terminal can answer the prompt.

API: POST /v1/branches/:id/rollback, GET /v1/operations/:id

bata db branch set-primary#

Make a branch the project's primary branch.

bata db branch set-primary <name-or-id> [--project <id>] [--json]

API: POST /v1/branches/:id/set-primary

bata db branch expire#

Set, change or clear a branch's TTL (auto-delete time).

bata db branch expire <name-or-id> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]

A protected branch cannot carry a TTL, and the primary branch never expires.

API: PATCH /v1/branches/:id

bata db branch protect#

Lock a branch against delete, reset, rollback and TTL reaping.

bata db branch protect <name-or-id> [--project <id>] [--json]

API: PATCH /v1/branches/:id

bata db branch unprotect#

Remove a branch's protection.

bata db branch unprotect <name-or-id> [--project <id>] [--json]

API: PATCH /v1/branches/:id

bata db branch checkout#

Pin a branch into .batadata/project.json so later commands target it.

bata db branch checkout <name-or-id> [--project <id>]

API: GET /v1/projects/:id

bata db databases list#

List the databases on a branch.

bata db databases list [--project <id>] [--branch <b>] [--json]

API: GET /v1/databases

bata db databases create#

Create a database on a branch.

bata db databases create <name> [--owner-role <role-id>] [--project <id>] [--branch <b>] [--json]

API: POST /v1/databases

bata db databases delete#

Drop a database.

bata db databases delete <database-id> --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/databases/:id

bata db roles list#

List the Postgres roles on a branch.

bata db roles list [--project <id>] [--branch <b>] [--json]

API: GET /v1/roles

bata db roles create#

Create a Postgres role (the password is shown once).

bata db roles create <name> [--password <p>] [--project <id>] [--branch <b>] [--json]

API: POST /v1/roles

bata db roles delete#

Drop a Postgres role.

bata db roles delete <role-id> --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/roles/:id

bata db roles reset-password#

Rotate a role's password (the old one stops working; the new one is shown once).

bata db roles reset-password <role-id> --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: POST /v1/roles/:id/reset-password

Compute#

Start, suspend, resize and configure a branch's compute, and read replicas.

bata compute status#

Show each branch's compute: status, size and always-on state.

bata compute status [--project <id>] [--branch <name-or-id>] [--json]

API: GET /v1/projects/:id

bata compute show#

Show one compute in full (by branch).

bata compute show --branch <name-or-id> [--project <id>] [--json]

API: GET /v1/computes/:id

bata compute set#

Always-on tier and fixed size for a branch's compute.

bata compute set --branch <name-or-id> [--always-on|--no-always-on] [--size <cu>] [--project <id>] [--json]

API: PATCH /v1/computes/:id

bata compute start#

Start (wake) a branch's compute.

bata compute start [--branch <name-or-id>] [--project <id>] [--json]

API: POST /v1/computes/:id/start

bata compute suspend#

Suspend a branch's compute (scale to zero now).

bata compute suspend [--branch <name-or-id>] [--project <id>] [--json]

API: POST /v1/computes/:id/suspend

bata compute restart#

Gracefully restart an active compute in place.

bata compute restart <name-or-id> [--project <id>] [--json]

API: POST /v1/computes/:id/restart

bata compute resize#

Resize a branch's compute to a new CU size.

bata compute resize --size <cu> [--branch <name-or-id>] [--project <id>] [--json]

API: POST /v1/computes/:id/resize

bata compute logs#

Fetch a compute's recent log lines.

bata compute logs <name-or-id> [--limit <n>] [--project <id>] [--json]

API: GET /v1/computes/:id/logs

bata compute wakes#

How long wakes took: p50/p95/max, cold vs warm, timeouts, and each wake's phase breakdown.

bata compute wakes [--branch <name-or-id>] [--window 24h|7d|30d] [--limit <n>] [--project <id>] [--json]

A wake is a compute starting up for a request after scale-to-zero (or a manual start). Each one is timed from the request arriving to the first query served.

Phases: decide (the start is claimed), queue (the start begins), place (host chosen), boot (VM restored or booted), postgres (Postgres answers), first query (the first query is served).

Stalled after ready: shown only when Postgres reported ready but no query was answered before a request gave up.

Kinds: restore and already_running are warm; cold_attach and fresh_boot are cold (Postgres booted from scratch).

Outcomes: served, ready (no query seen yet), timeout (a request gave up waiting), failed, pending. GAVE UP counts requests that gave up on that wake.

API: GET /v1/projects/:id/wakes

bata compute create#

Create a compute for a branch that has none.

bata compute create --branch <name-or-id> [--size <cu>] [--min-cu <n>] [--max-cu <n>] [--autoscaling] [--project <id>] [--json]

API: POST /v1/computes

bata compute delete#

Delete a branch's compute (the branch's data is kept).

bata compute delete --branch <name-or-id> [--project <id>] --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/computes/:id

bata compute replicas list#

List read replicas of a branch's compute.

bata compute replicas list [--branch <name-or-id>] [--project <id>] [--json]

API: GET /v1/computes/:id/replicas

bata compute replicas add#

Attach a read replica to a branch's compute.

bata compute replicas add [--size <cu>] [--branch <name-or-id>] [--project <id>] [--json]

Read replicas are behind a server switch: while it is off, this exits 5 (NOT_FOUND).

API: POST /v1/computes/:id/replicas

bata compute replicas remove#

Remove a read replica.

bata compute replicas remove <replica-id> [--branch <name-or-id>] [--project <id>] --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/computes/:id/replicas/:replicaId

Operations#

Track and cancel asynchronous operations.

bata ops list#

List a project's operations (provision, reset, rollback, resize ...).

bata ops list [--project <id>] [--status <s>] [--type <t>] [--limit <n>] [--offset <n>] [--json]

API: GET /v1/operations

bata ops show#

Show one operation (poll this after an async command).

bata ops show <operation-id> [--json]

API: GET /v1/operations/:id

bata ops cancel#

Cancel a pending or running operation.

bata ops cancel <operation-id> [--json]

API: POST /v1/operations/:id/cancel

Query insights#

Performance series, top queries, recommendations with evidence and fixes.

bata insights overview#

Headline query stats: totals, slowest and most frequent queries.

bata insights overview [--project <id>] [--source <s>] [--json]

API: GET /v1/insights/:projectId/overview

bata insights top#

Top queries across Turbine and pg_stat_statements, attributed to model and action.

bata insights top [--window <w>] [--order-by totalTime|calls|p95|mean] [--source all|turbine|pg_stat] [--tag <t>] [--limit <n>] [--json]

API: GET /v1/insights/:projectId/top-queries

bata insights performance#

Performance series (calls, latency percentiles, errors) per model and action.

bata insights performance [--window <w>] [--granularity minute|hour|day] [--model <m>] [--action <a>] [--json]

API: GET /v1/insights/:projectId/observe

bata insights queries#

Server-side query stats (pg_stat_statements).

bata insights queries [--time-range <w>] [--order-by total_time|calls|mean_time] [--limit <n>] [--json]

API: GET /v1/insights/:projectId/queries

bata insights query#

One query's detail by its hash.

bata insights query <query-hash> [--project <id>] [--json]

API: GET /v1/insights/:projectId/queries/:queryHash

bata insights timeseries#

Throughput, latency or connection series.

bata insights timeseries [--metric throughput|latency|connections] [--time-range 1h|24h|7d] [--json]

API: GET /v1/insights/:projectId/timeseries

bata insights size#

Database, table and index sizes.

bata insights size [--branch <b>] [--json]

API: GET /v1/insights/:projectId/size

bata insights live#

Live activity: running queries, connections, locks.

bata insights live [--branch <b>] [--json]

API: GET /v1/insights/:projectId/live

bata insights cold-start#

Measured cold-start (wake) times for the project.

bata insights cold-start [--json]

API: GET /v1/insights/:projectId/cold-start

bata insights trends#

A query shape's latency and volume trend.

bata insights trends <fingerprint> [--window 24h|7d|30d|90d] [--json]

API: GET /v1/insights/:projectId/trends

bata insights regressions#

Detected query regressions.

bata insights regressions [--status open|resolved] [--limit <n>] [--json]

API: GET /v1/insights/:projectId/regressions

bata insights turbine#

Turbine ORM overview (client-reported totals and cost basis).

bata insights turbine [--time-range <w>] [--json]

API: GET /v1/insights/:projectId/turbine-overview

bata insights health#

Telemetry and insights health for the project (is data arriving?).

bata insights health [--branch <b>] [--json]

API: GET /v1/insights/:projectId/health

bata insights explain#

EXPLAIN a statement (--analyze runs it); needs the sql scope.

bata insights explain <sql> [--analyze] [--branch <b>] [--json]

API: POST /v1/insights/:projectId/explain

bata insights recommendations#

Recommendations with evidence, impact and a suggested fix.

bata insights recommendations [--status open|dismissed|resolved|all] [--kind <k>] [--branch <b>] [--json]

resolved is set by the server when the evidence disappears; you can dismiss or reopen.

API: GET /v1/insights/:projectId/recommendations

bata insights recommendations refresh#

Re-evaluate recommendations now.

bata insights recommendations refresh [--project <id>] [--json]

API: POST /v1/insights/:projectId/recommendations/refresh

bata insights recommendations dismiss#

Dismiss a recommendation (it stays dismissed).

bata insights recommendations dismiss <recommendation-id> [--project <id>] [--json]

API: PATCH /v1/insights/:projectId/recommendations/:recommendationId, GET /v1/insights/:projectId/recommendations

bata insights recommendations reopen#

Reopen a dismissed recommendation.

bata insights recommendations reopen <recommendation-id> [--project <id>] [--json]

API: PATCH /v1/insights/:projectId/recommendations/:recommendationId, GET /v1/insights/:projectId/recommendations

Index advice and trials#

Index advice, and proving an index on a throwaway branch before applying it.

bata doctor upload#

Import a turbine doctor JSON report into the project's index advice.

bata doctor upload [--project <id>] [--branch <b>] [--dry-run] [--unused] [--audit] [--json]

Runs turbine doctor --json locally against the branch's direct connection, then uploads the report.

API: GET /v1/connection-info/:projectId, POST /v1/projects/:projectId/index-advice/import

bata index advice#

List index advice (create, drop-unused, drop-redundant ...).

bata index advice [--status <s>] [--kind <k>] [--project <id>] [--json]

API: GET /v1/projects/:projectId/index-advice

bata index report#

The latest imported doctor report, summarized.

bata index report [--project <id>] [--json]

API: GET /v1/projects/:projectId/index-advice/report

bata index status#

Mark index advice open, applied or dismissed.

bata index status <advice-id> <open|applied|dismissed> [--project <id>] [--json]

API: PATCH /v1/projects/:projectId/index-advice/:adviceId

bata index apply#

Build an advised index on a branch (CREATE INDEX CONCURRENTLY).

bata index apply <advice-id> [--branch <b>] [--project <id>] [--json]

API: POST /v1/projects/:projectId/index-advice/:adviceId/apply

bata index trial start#

Prove an index on a throwaway branch: plans before and after, per query.

bata index trial start (--advice <id> | --table <t> --columns <a,b>) [--where <pred>] [--using <method>] [--unique] [--branch <b>] [--corpus turbine|pg_stat|both] [--top <n>] [--json]

Asynchronous: poll bata index trial show <id> until it reports a verdict.

API: POST /v1/projects/:projectId/index-trials

bata index trial list#

List index trials.

bata index trial list [--project <id>] [--json]

API: GET /v1/projects/:projectId/index-trials

bata index trial show#

Show a trial's state and verdict.

bata index trial show <trial-id> [--project <id>] [--json]

API: GET /v1/projects/:projectId/index-trials/:trialId

bata index trial cancel#

Abort a trial and drop its branch.

bata index trial cancel <trial-id> [--project <id>] [--json]

API: DELETE /v1/projects/:projectId/index-trials/:trialId

Turbine telemetry#

Set up and check Turbine ORM telemetry for a project.

bata telemetry setup#

Mint a telemetry-only key for a project and print the app setup.

bata telemetry setup [--project <id>] [--branch <b>] [--name <n>] [--json]

The key has only the telemetry:write scope for this one project: it cannot read data or run SQL.

The key is shown once. BATA_TELEMETRY=off disables telemetry without a code change.

API: POST /v1/api-keys

bata telemetry status#

Is telemetry arriving for this project?.

bata telemetry status [--project <id>] [--branch <b>] [--json]

API: GET /v1/insights/:projectId/health

Restore (PITR)#

Recovery points and point-in-time restore.

bata restore points#

List recovery points and the PITR window.

bata restore points [--project <id>] [--json]

API: GET /v1/recovery-points/:projectId

bata restore create#

Restore a branch to a timestamp or LSN as a NEW branch (non-destructive).

bata restore create --branch <name-or-id> --at <timestamp|LSN> [--name <new-branch>] [--json]

API: POST /v1/restore

Schema#

Schema introspection, diff and the migration safety gate.

bata schema dump#

Dump a branch's live schema.

bata schema dump [--branch <b>] [--project <id>] [--json]

API: GET /v1/schema/:projectId

bata schema diff#

Diff two branches' schemas.

bata schema diff <from> <to> [--project <id>] [--json]

API: GET /v1/schema/:projectId/diff

bata schema check#

Check a DDL change against live query traffic.

bata schema check <file|-> [--window <w>] [--fail-on breaking|risky] [--json]

API: POST /v1/insights/:projectId/schema-check

bata schema init#

Reserved (not implemented).

bata schema init

Reserved: exits 3 (NOT_IMPLEMENTED).

bata schema push#

Reserved (not implemented).

bata schema push

Reserved: exits 3 (NOT_IMPLEMENTED).

bata schema pull#

Reserved (not implemented).

bata schema pull

Reserved: exits 3 (NOT_IMPLEMENTED).

Migrations#

Gate a migration in CI, and the server-side migration pipeline.

bata migrate check#

Gate a migration against live query traffic (exit 2 if breaking).

bata migrate check <file.sql|-> [--project <id>] [--branch <b>] [--window <w>] [--fail-on breaking|risky] [--json]

Exits 2 when the change is breaking or cannot be assessed (fail-closed). --fail-on risky also trips on risky changes.

API: POST /v1/insights/:projectId/schema-check

bata migrate test-connection#

Check the server can reach a source database (server-side pipeline).

bata migrate test-connection <source-uri> [--json]

API: POST /v1/migrate/test-connection

bata migrate estimate#

Estimate size and duration of a server-side migration into a project.

bata migrate estimate --source <uri> [--project <id>] [--json]

API: POST /v1/migrate/estimate

bata migrate start#

Run a server-side pg_dump | pg_restore from a source into a target connection string.

bata migrate start --source <uri> --target <uri> [--schema-only|--data-only] [--table <t>]... [--json]

Distinct from bata import, which streams from this machine with preflight checks and verification.

API: POST /v1/migrate/start

bata migrate create#

Reserved (not implemented).

bata migrate create

Reserved: exits 3 (NOT_IMPLEMENTED).

bata migrate deploy#

Reserved (not implemented).

bata migrate deploy

Reserved: exits 3 (NOT_IMPLEMENTED).

bata migrate status#

Reserved (not implemented).

bata migrate status

Reserved: exits 3 (NOT_IMPLEMENTED).

bata migrate reset#

Reserved (not implemented).

bata migrate reset

Reserved: exits 3 (NOT_IMPLEMENTED).

Import#

Move a Postgres or Neon database into BataDB.

bata import#

Migrate a Postgres or Neon database into BataDB (streamed, preflighted, verified).

bata import --source <uri> [--name <n> | --project <id>] [--pg <major>] [--allow-pooled-source] [--yes] [--json]

Needs local pg_dump and psql at least as new as the source server.

--project and --name are mutually exclusive. --yes proceeds even if the target already has tables.

The source must be a direct connection, not a pooler: a pooled URL (a -pooler host, port 6543 or 6432, pgbouncer=true) is refused with POOLED_SOURCE (exit 5), because pg_dump's session settings would leak through a transaction pooler to the source's other clients.

API: POST /v1/projects, GET /v1/projects/:id, GET /v1/branches, GET /v1/connection-info/:projectId, DELETE /v1/projects/:id

PowDB lane#

PowDB projects: query, exec, park, wake, upgrade, pull.

bata powdb pull#

Pull a branch's schema and data into a local PowDB-loadable PowQL script.

bata powdb pull [--branch <b>] [--out <file|->] [--limit <n>] [--project <id>] [--json]

--json prints a summary with per-table compat notes; with --out - the script rides in the JSON payload.

API: GET /v1/schema/:projectId, POST /v1/sql/execute

bata powdb status#

Show a PowDB project's server state.

bata powdb status [<project>] [--json]

API: GET /v1/powdb/:projectId

bata powdb query#

Run a PowQL query.

bata powdb query <powql> [--project <id>] [--json]

API: POST /v1/powdb/:projectId/query

bata powdb exec#

Run a multi-statement PowQL script.

bata powdb exec "<script>" | --file <path|-> [--transactional | --continue-on-error] [--project <id>] [--json]

Statements are separated by ;. --transactional and --continue-on-error are mutually exclusive.

API: POST /v1/powdb/:projectId/exec

bata powdb park#

Park (stop) a PowDB server.

bata powdb park [<project>] [--json]

API: POST /v1/powdb/:projectId/park

bata powdb wake#

Wake a parked PowDB server.

bata powdb wake [<project>] [--json]

API: POST /v1/powdb/:projectId/wake

bata powdb upgrade#

Upgrade a PowDB server version (format changes are one-way).

bata powdb upgrade --to <x.y.z> [<project>] --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: POST /v1/powdb/:projectId/upgrade

Team and members#

Teams, members and roles.

bata team list#

List your teams and your role in each.

bata team list [--json]

API: GET /v1/teams

bata team info#

Show a team and its members.

bata team info [<team-id>] [--json]

API: GET /v1/teams/:id

bata team members#

List the team's members and roles.

bata team members [--team <id>] [--json]

API: GET /v1/teams/:id

bata team create#

Create a team (you become its owner).

bata team create <name> [--slug <slug>] [--json]

API: POST /v1/teams

bata team rename#

Rename the team.

bata team rename <name> [--team <id>] [--json]

API: PATCH /v1/teams/:id

bata team invite#

Add a member by email.

bata team invite <email> [--role admin|member|viewer] [--team <id>] [--json]

API: POST /v1/teams/:id/members

bata team remove#

Remove a member from the team.

bata team remove <user-id> [--team <id>] --yes [--json]

Destructive: needs --yes when no terminal can answer the prompt.

API: DELETE /v1/teams/:id/members/:user_id

bata team role#

Change a member's role.

bata team role <user-id> <owner|admin|member|viewer> [--team <id>] [--json]

API: PATCH /v1/teams/:id/members/:user_id

Billing#

Usage, plans, invoices, card on file, spend cap and reservations.

bata billing plans#

List the available plans.

bata billing plans [--json]

API: GET /v1/billing/plans

bata billing usage#

The team's billed usage for the current period.

bata billing usage [--team <id>] [--json]

API: GET /v1/billing/usage/:teamId

bata billing history#

Past billing periods and invoices.

bata billing history [--team <id>] [--json]

API: GET /v1/billing/history/:teamId

bata billing subscribe#

Switch the team to a plan.

bata billing subscribe --plan <plan-id> [--team <id>] [--json]

Retired plans answer 409 (PLAN_ARCHIVED). Usage past the free allowance is billed pay as you go, with no subscription needed.

API: POST /v1/billing/subscribe

bata billing checkout#

Create a checkout link for a paid plan (a human completes payment).

bata billing checkout --plan pro|team --success-url <url> --cancel-url <url> [--team <id>] [--json]

Both plans are retired listings today and answer 409 (PLAN_ARCHIVED). Usage past the free allowance is billed pay as you go, with no subscription needed.

Both URLs must be on the BataDB console (app.batadata.com).

API: POST /v1/billing/checkout

bata billing portal#

Create a billing portal link (a human manages payment methods and invoices).

bata billing portal --return-url <url> [--team <id>] [--json]

The return URL must be on the BataDB console (app.batadata.com).

API: POST /v1/billing/portal

bata billing spend-cap#

Show, set or clear the monthly spend cap.

bata billing spend-cap [--set <dollars> | --set-cents <n> | --clear] [--json]

API: GET /v1/billing/spend-cap, PATCH /v1/billing/spend-cap

bata billing card#

Whether the team has a card on file, and whether its plan needs one.

bata billing card [--json]

A Free team cannot create or start a database until a card is on file: those commands exit 7 (PAYMENT_METHOD_REQUIRED) with the link a person uses to add one. Nothing is charged while usage stays inside the free allowance.

--json prints { required, cardOnFile, card: { brand, last4, addedAt } | null, stopAtAllowance, addCardUrl }.

API: GET /v1/billing/card

bata billing card add#

Get a secure link where a person adds the team's card.

bata billing card add [--open] [--success-url <url>] [--cancel-url <url>] [--json]

The link opens a Stripe-hosted page. An agent cannot add a card: hand the link to a person on the team. Needs an owner or admin and an admin-scoped key. Both URLs must be on the BataDB console (app.batadata.com).

API: POST /v1/billing/card

bata billing stop-at-limit#

Show, or turn on or off, stopping at the free limit instead of billing overage.

bata billing stop-at-limit [on|off] [--json]

On (the default on Free): the team's databases stop at the free allowance instead of billing overage, and starting one exits 7 (SPEND_CAP_REACHED) until the next period or until you turn it off. Off (pay as you go): usage past the allowance is billed to the card on file, with warnings at 80% and 100%.

With no argument it shows the current setting. Changing it needs an owner or admin and an admin-scoped key. --json prints the API payload; both shapes carry stopAtAllowance.

API: GET /v1/billing/card, PATCH /v1/billing/spend-cap

bata billing events#

Recent billing events (cap reached, invoice, plan change ...).

bata billing events [--limit <n>] [--json]

API: GET /v1/billing/events

bata billing reservations#

Show the team's reserved capacity.

bata billing reservations [--json]

API: GET /v1/billing/reservations

bata billing reservations tiers#

List reservation tiers and their discounts.

bata billing reservations tiers [--json]

API: GET /v1/billing/reservation-tiers

bata billing reservations set#

Set reserved capacity for the period.

bata billing reservations set [--compute-cu-hours <n>] [--storage-gb-months <n>] [--transfer-gb <n>] [--json]

API: PUT /v1/billing/reservations

Account activity#

Audit log, notifications, compute health checks and platform config.

bata audit-log#

The team's audit log.

bata audit-log [--event-type <t>] [--actor-type user|api_key|system] [--resource-type <t>] [--resource-id <id>] [--since <iso>] [--until <iso>] [--limit <n>] [--cursor <id>] [--json]

API: GET /v1/audit-log

bata notifications list#

List notifications (compute health, billing, operations).

bata notifications list [--unread] [--limit <n>] [--json]

API: GET /v1/notifications

bata notifications read#

Mark one notification read.

bata notifications read <notification-id> [--json]

API: PATCH /v1/notifications/:id/read

bata notifications read-all#

Mark every notification read.

bata notifications read-all [--json]

API: POST /v1/notifications/read-all

bata config#

Platform limits and options (sizes, regions, versions).

bata config [--json]

API: GET /v1/config

bata health#

Compute health-check summary per branch, or the raw history.

bata health [--project <id>] [--branch <b>] [--hours <n>] [--history [--limit <n>]] [--json]

API: GET /v1/health-checks/:projectId, GET /v1/health-checks/:projectId/history

Local tools#

Local development helpers.

bata studio#

Run Turbine Studio locally against a branch (local UI over direct TCP).

bata studio [--project <id>] [--branch <b>] [--port <port>] [--write] [--show-pii] [--no-open]

API: GET /v1/connection-info/:projectId, GET /v1/branches/:id, POST /v1/computes/:id/start

bata generate#

Generate types from the database schema.

bata generate

Runs turbine generate from turbine-orm (installed in the project or on your PATH). Re-run it after a schema change.

bata dev#

Local development setup guide.

bata dev