@batadata/cli 0.1.7 → 0.1.9

package/README.md

@@ -43,6 +43,45 @@ bata connect my-app       # open psql (auto-wakes the compute if suspended)
 bata usage                # per-dimension cost for the current billing period
 ```
 
+## Project linking
+
+Tired of threading `--project <id>` through every command? Link a directory to a
+project once — Vercel/Neon-style — and every command run inside it (or any
+subdirectory) targets that project automatically.
+
+```bash
+bata link my-app          # resolves by name or id, writes .batadata/project.json
+bata link                 # no argument, in a TTY: pick from a list
+bata link --status        # show what this directory resolves to
+bata db query "SELECT 1"  # no --project needed anymore
+bata unlink               # remove the link
+```
+
+`bata link` writes `.batadata/project.json` in the current directory:
+
+```json
+{ "projectId": "proj_abc123", "branchId": null }
+```
+
+**Add `.batadata/` to your `.gitignore`** — the link is per-checkout, not shared.
+
+### Pin a branch
+
+```bash
+bata db branch checkout preview   # writes the branch id into .batadata/project.json
+bata db query "SELECT 1"          # now runs against `preview` — no --branch flag
+```
+
+### Resolution precedence
+
+Everywhere a project or branch is resolved, the same rule applies — **an explicit
+flag always wins**, so linking never silently overrides an intentional request:
+
+1. an explicit `--project` / `--branch` flag (or a positional id)
+2. `.batadata/project.json`, discovered by walking **up** from the current
+   directory like git (stops at `$HOME` or the filesystem root)
+3. `defaultProject` in `~/.batarc` (the per-machine fallback)
+
 ## Commands
 
 | Command | Description |
@@ -51,6 +90,8 @@ bata usage                # per-dimension cost for the current billing period
 | `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 |
+| `link [project]` | Link the current directory to a project (see [Project linking](#project-linking)) |
+| `unlink` | Remove the current directory's project link |
 | `login` / `logout` / `whoami` | Manage your session |
 | `api-keys` | Create / list / revoke API keys |
 | `projects` | `list`, `create`, `info`, `delete` |
@@ -59,7 +100,10 @@ bata usage                # per-dimension cost for the current billing period
 | `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 branch checkout <name-or-id>` | Pin a branch into the directory's link |
 | `db studio` | Open the table browser in your browser |
+| `restore points` | List recovery points and the PITR window (see [Point-in-time restore](#point-in-time-restore-pitr)) |
+| `restore create` | Restore a branch to a timestamp/LSN as a **new** branch |
 | `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 |
@@ -71,6 +115,38 @@ safety.
 
 Run `bata --help` for the full, authoritative command list, or `bata --version`.
 
+## Point-in-time restore (PITR)
+
+Recover a branch to an earlier point in time. Restore is **non-destructive**: it
+creates a **new** branch at the chosen point and never overwrites the source
+branch's data.
+
+```bash
+bata restore points                         # what can I restore to?
+bata restore create \
+  --branch main \
+  --at 2026-07-04T12:00:00Z \
+  --name before-the-bad-migration          # → a new branch at that timestamp
+```
+
+`--at` accepts either an **ISO-8601 timestamp** (e.g. `2026-07-04T12:00:00Z`) or
+a Postgres **LSN** (e.g. `0/15994B0`); the CLI detects which you passed. If
+`--name` is omitted the new branch is named `restore-<branch>-<timestamp>`. The
+new branch's compute may still be provisioning when the command returns — poll
+`bata db branches` before you query it.
+
+### How far back can I restore? (honest window)
+
+Recovery points are **timeline-metadata snapshots** the control plane's backup
+scheduler records about **every 6 hours** (`BACKUP_INTERVAL_HOURS`, default `6`).
+They are *not* full physical backups, and the earliest point `restore points`
+lists is simply the oldest metadata row we have — **not** a guaranteed floor on
+how far back you can restore. Actual restorability to an arbitrary timestamp
+depends on how much WAL the storage engine still retains: if the WAL no longer
+covers your timestamp, the server returns *"No data available at the requested
+timestamp"* and the restore is refused. We surface that verbatim rather than
+implying the window is deeper than it is.
+
 ## Headless / agent use
 
 Every command runs headlessly with just `BATA_API_KEY` set — no `bata login`,
@@ -125,6 +201,11 @@ bata projects delete --yes --json
 exists but its compute may still be provisioning. Poll `bata db branches --json`
 until the branch reports a ready status before connecting to it.
 
+To avoid passing `--project` on every call, an agent can `bata link <id> --json`
+once (it emits `{ "linked": true, "project_id", "project_name", "branch_id",
+"link_file" }`) and drop the flag from every subsequent command in that
+directory. `bata link --status --json` reports the current link.
+
 ### Cost truth
 
 `bata usage` reports cost per dimension and is deliberately honest about what is

package/dist/api.d.ts

@@ -50,5 +50,6 @@ export declare function asList<T = unknown>(data: unknown): T[];
 export declare const api: {
     get: <T = unknown>(path: string, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
     post: <T = unknown>(path: string, body: Record<string, unknown>, token?: string) => Promise<ApiResponse<T>>;
+    patch: <T = unknown>(path: string, body: Record<string, unknown>, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
     del: <T = unknown>(path: string, token?: string, query?: Record<string, string>) => Promise<ApiResponse<T>>;
 };

package/dist/api.js

@@ -152,5 +152,6 @@ export function asList(data) {
 export const api = {
     get: (path, token, query) => request("GET", path, { token, query }),
     post: (path, body, token) => request("POST", path, { token, body }),
+    patch: (path, body, token, query) => request("PATCH", path, { token, body, query }),
     del: (path, token, query) => request("DELETE", path, { token, query }),
 };

package/dist/commands/connect.js

@@ -9,6 +9,7 @@ import { api } from "../api.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";
+import { resolveProjectId } from "../link.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.
@@ -17,8 +18,9 @@ export async function connect(args) {
     }
     const token = requireToken();
     const config = loadConfig();
-    // Accept project name as argument, or use default
-    let projectId = config.defaultProject;
+    // Accept project name as argument, or use the resolved default
+    // (--project isn't a connect flag; precedence is link > config here).
+    let projectId = resolveProjectId().projectId;
     const projectName = args[0];
     if (projectName && !projectName.startsWith("-")) {
         // Resolve project name to ID

package/dist/commands/db.d.ts

@@ -1,8 +1,42 @@
+/**
+ * Parse a relative duration like `30m`, `2h`, `7d` (units: s/m/h/d/w) into
+ * milliseconds. Returns `{ error }` for anything malformed or non-positive so
+ * the caller can surface a clean CLI error instead of minting a bad TTL.
+ * Exported for unit testing.
+ */
+export declare function parseDuration(input: string): {
+    ms?: number;
+    error?: string;
+};
+/**
+ * Split `db branch create` args into the positional name plus the
+ * `--expires-in` / `--purpose` flags (both `--flag value` and `--flag=value`
+ * forms). Keeps the command order-independent, like `db query`'s `--branch`.
+ */
+export declare function parseBranchCreateArgs(args: string[]): {
+    name?: string;
+    expiresIn?: string;
+    purpose?: string;
+};
 export declare function connect(): Promise<void>;
 export declare function url(): Promise<void>;
 export declare function branches(): Promise<void>;
-export declare function branchCreate(name?: string): Promise<void>;
+export declare function branchCreate(args?: string[]): Promise<void>;
 export declare function branchDelete(name?: string): Promise<void>;
+/**
+ * `bata db branch protect <name-or-id>` / `unprotect <name-or-id>` — flip a
+ * branch's protection flag (PATCH /v1/branches/:id). A protected branch refuses
+ * delete/reset/rollback/reap — the safety rail for headless/agent ops. The ref
+ * is resolved by name OR id, like the other branch commands.
+ */
+export declare function branchSetProtected(ref: string | undefined, wantProtected: boolean): Promise<void>;
+/**
+ * `bata db branch checkout <name-or-id>` — pin a branch into the directory's
+ * `.batadata/project.json` so later `db query` / `db url` target it with no
+ * `--branch` flag. Requires a linked project (or an explicit `--project`); the
+ * branch ref is resolved by name OR id, just like `db query --branch`.
+ */
+export declare function branchCheckout(args: string[]): Promise<void>;
 export declare function studio(): Promise<void>;
 export declare function query(args?: string[]): Promise<void>;
 export declare function handleDb(args: string[]): Promise<void>;

package/dist/commands/db.js

@@ -1,10 +1,12 @@
 import { execSync, spawn } from "node:child_process";
+import * as path from "node:path";
 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 { colors, log, json, error, success, spinner, table, heading, info as logInfo } from "../utils/logger.js";
 import { prompt, confirmDestructive } from "../utils/prompts.js";
 import { openBrowser } from "../utils/open.js";
 import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId, resolveBranchId, findLinkFile, writeLinkFile } from "../link.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" });
@@ -30,6 +32,59 @@ function formatDate(iso) {
     const d = new Date(iso);
     return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
 }
+const DURATION_UNIT_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/**
+ * Parse a relative duration like `30m`, `2h`, `7d` (units: s/m/h/d/w) into
+ * milliseconds. Returns `{ error }` for anything malformed or non-positive so
+ * the caller can surface a clean CLI error instead of minting a bad TTL.
+ * Exported for unit testing.
+ */
+export function parseDuration(input) {
+    const match = /^(\d+)(s|m|h|d|w)$/.exec(input.trim());
+    if (!match) {
+        return { error: `Invalid duration "${input}". Use forms like 30m, 2h, 7d (units: s/m/h/d/w).` };
+    }
+    const n = parseInt(match[1], 10);
+    if (n <= 0) {
+        return { error: `Duration "${input}" must be greater than zero.` };
+    }
+    return { ms: n * DURATION_UNIT_MS[match[2]] };
+}
+/**
+ * Split `db branch create` args into the positional name plus the
+ * `--expires-in` / `--purpose` flags (both `--flag value` and `--flag=value`
+ * forms). Keeps the command order-independent, like `db query`'s `--branch`.
+ */
+export function parseBranchCreateArgs(args) {
+    let name;
+    let expiresIn;
+    let purpose;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--expires-in") {
+            expiresIn = args[++i];
+        }
+        else if (arg.startsWith("--expires-in=")) {
+            expiresIn = arg.slice("--expires-in=".length);
+        }
+        else if (arg === "--purpose") {
+            purpose = args[++i];
+        }
+        else if (arg.startsWith("--purpose=")) {
+            purpose = arg.slice("--purpose=".length);
+        }
+        else if (!arg.startsWith("--") && name === undefined) {
+            name = arg;
+        }
+    }
+    return { name, expiresIn, purpose };
+}
 /**
  * Human-readable STATUS cell for a branch. Prefers the live compute lifecycle
  * (computeStatus) over the static branch row status, and appends a green check
@@ -85,7 +140,7 @@ export async function connect() {
     }
     const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project.", "Run bata projects create or set one with bata projects info <id>.");
     }
@@ -119,7 +174,7 @@ export async function connect() {
 export async function url() {
     const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
@@ -138,7 +193,7 @@ export async function branches() {
     const token = requireToken();
     const config = loadConfig();
     const jsonMode = isJsonMode();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
@@ -161,6 +216,11 @@ export async function branches() {
                 // and a successful query.
                 computeStatus: b.computeStatus ?? null,
                 ready: b.ready ?? null,
+                // Ephemeral-branch TTL: when set, the branch is auto-reaped after this.
+                expires_at: b.expiresAt ?? null,
+                purpose: b.purpose ?? null,
+                // Protection flag — a protected branch refuses delete/reset/rollback/reap.
+                protected: b.isProtected ?? false,
                 created_at: b.createdAt ?? null,
             })),
             count: branchList.length,
@@ -173,24 +233,40 @@ export async function branches() {
         log();
         return;
     }
-    table(["NAME", "PRIMARY", "STATUS", "CREATED"], branchList.map((b) => [
+    table(["NAME", "PRIMARY", "PROTECTED", "STATUS", "EXPIRES", "CREATED"], branchList.map((b) => [
         b.name,
         b.isPrimary ? colors.green("yes") : "-",
+        // Protected branches are locked against destructive ops — flag them so the
+        // column is scannable.
+        b.isProtected ? colors.yellow("locked") : "-",
         // Live compute lifecycle (computeStatus), with a check once ready so the
         // column is scannable.
         branchStatusLabel(b),
+        // TTL'd branches show their reap date; permanent branches show "-".
+        b.expiresAt ? formatDate(b.expiresAt) : "-",
         formatDate(b.createdAt ?? ""),
     ]));
     log();
 }
-export async function branchCreate(name) {
+export async function branchCreate(args = []) {
     const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
+    const { name, expiresIn, purpose } = parseBranchCreateArgs(args);
+    // A relative TTL (--expires-in 2h) becomes an absolute expires_at the server
+    // enforces. Parse it up front so a bad duration fails fast, before any call.
+    let expiresAt;
+    if (expiresIn !== undefined) {
+        const parsed = parseDuration(expiresIn);
+        if (parsed.error) {
+            emitError("INVALID_FLAG", parsed.error, "Usage: bata db branch create <name> --expires-in 2h");
+        }
+        expiresAt = new Date(Date.now() + parsed.ms).toISOString();
+    }
     // Don't block on an interactive prompt headlessly.
     let branchName = name;
     if (!branchName) {
@@ -209,6 +285,10 @@ export async function branchCreate(name) {
     };
     if (config.defaultTeam)
         body.team_id = config.defaultTeam;
+    if (expiresAt)
+        body.expires_at = expiresAt;
+    if (purpose)
+        body.purpose = purpose;
     const res = await api.post("/v1/branches", body, token);
     s?.stop();
     if (!res.ok) {
@@ -216,7 +296,13 @@ export async function branchCreate(name) {
     }
     if (jsonMode) {
         json({
-            branch: { id: res.data.id, name: res.data.name ?? branchName, project_id: projectId },
+            branch: {
+                id: res.data.id,
+                name: res.data.name ?? branchName,
+                project_id: projectId,
+                expires_at: res.data.expiresAt ?? expiresAt ?? null,
+                purpose: res.data.purpose ?? purpose ?? null,
+            },
             // The branch row exists immediately, but its compute may still be
             // provisioning — poll `db branches` for status before connecting.
             ready: false,
@@ -226,6 +312,9 @@ export async function branchCreate(name) {
     }
     log();
     log(`  ${colors.green(">")} Branch ${colors.cyan(branchName)} created`);
+    if (expiresAt) {
+        log(`  ${colors.dim("Expires")} ${formatDate(expiresAt)} ${colors.dim("(auto-deleted)")}`);
+    }
     log(`  ${colors.dim("Poll readiness with")} ${colors.cyan("bata db branches")}`);
     log();
 }
@@ -233,7 +322,7 @@ export async function branchDelete(name) {
     const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
@@ -275,9 +364,123 @@ export async function branchDelete(name) {
     log(`  ${colors.green(">")} Branch ${colors.cyan(name)} deleted`);
     log();
 }
-export async function studio() {
+/**
+ * `bata db branch protect <name-or-id>` / `unprotect <name-or-id>` — flip a
+ * branch's protection flag (PATCH /v1/branches/:id). A protected branch refuses
+ * delete/reset/rollback/reap — the safety rail for headless/agent ops. The ref
+ * is resolved by name OR id, like the other branch commands.
+ */
+export async function branchSetProtected(ref, wantProtected) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
+    const verb = wantProtected ? "protect" : "unprotect";
+    if (!projectId) {
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+    }
+    if (!ref) {
+        emitError("MISSING_ARG", "Branch name or id is required.", `Usage: bata db branch ${verb} <name-or-id>`);
+    }
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(ref)}`);
+    const branch = await resolveBranchRef(projectId, token, config.defaultTeam, ref);
+    s?.stop();
+    if (!branch) {
+        emitError("BRANCH_NOT_FOUND", `Branch "${ref}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    const s2 = jsonMode ? null : spinner(`${wantProtected ? "Protecting" : "Unprotecting"} branch ${colors.cyan(branch.name)}`);
+    const query = {};
+    if (config.defaultTeam)
+        query.team_id = config.defaultTeam;
+    const res = await api.patch(`/v1/branches/${branch.id}`, { protected: wantProtected }, token, query);
+    s2?.stop();
+    if (!res.ok) {
+        emitError(res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE" : "CLI_ERROR", apiError(res, `Failed to ${verb} branch.`), "");
+    }
+    if (jsonMode) {
+        json({
+            branch: { id: branch.id, name: branch.name, project_id: projectId },
+            protected: res.data.isProtected ?? wantProtected,
+        });
+        return;
+    }
+    log();
+    if (wantProtected) {
+        log(`  ${colors.green(">")} Branch ${colors.cyan(branch.name)} is now ${colors.yellow("protected")}`);
+        log(`  ${colors.dim("It can't be deleted, reset, rolled back, or auto-reaped until unprotected.")}`);
+    }
+    else {
+        log(`  ${colors.green(">")} Branch ${colors.cyan(branch.name)} is no longer protected`);
+    }
+    log();
+}
+/**
+ * Pull a `--project <id>` / `--project=<id>` flag out of args, returning the
+ * explicit project id (if any) and the remaining positionals. Lets `db branch
+ * checkout` accept `--project` while the positional stays the branch ref.
+ */
+function parseProjectFlag(args) {
+    let projectId;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--project")
+            projectId = args[++i];
+        else if (arg.startsWith("--project="))
+            projectId = arg.slice("--project=".length);
+        else
+            rest.push(arg);
+    }
+    return { projectId, rest };
+}
+/**
+ * `bata db branch checkout <name-or-id>` — pin a branch into the directory's
+ * `.batadata/project.json` so later `db query` / `db url` target it with no
+ * `--branch` flag. Requires a linked project (or an explicit `--project`); the
+ * branch ref is resolved by name OR id, just like `db query --branch`.
+ */
+export async function branchCheckout(args) {
+    const jsonMode = isJsonMode();
+    const { projectId: projectFlag, rest } = parseProjectFlag(args);
+    const ref = rest[0];
+    if (!ref) {
+        emitError("MISSING_ARG", "Branch name or id is required.", "Usage: bata db branch checkout <name-or-id>");
+    }
+    const { projectId } = resolveProjectId(projectFlag);
+    if (!projectId) {
+        emitError("NO_PROJECT", "No linked project.", "Run `bata link <project>` first, or pass --project <id>.");
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(ref)}`);
+    const branch = await resolveBranchRef(projectId, token, config.defaultTeam, ref);
+    s?.stop();
+    if (!branch) {
+        emitError("BRANCH_NOT_FOUND", `Branch "${ref}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    // Write into the nearest existing link file's directory if there is one
+    // (so `checkout` updates the same link `link`/`query` read); else create one
+    // in the CWD.
+    const existing = findLinkFile();
+    const targetDir = existing ? path.dirname(path.dirname(existing)) : process.cwd();
+    const linkFile = writeLinkFile(targetDir, { projectId, branchId: branch.id });
+    if (jsonMode) {
+        json({
+            project_id: projectId,
+            branch_id: branch.id,
+            branch_name: branch.name,
+            link_file: linkFile,
+        });
+        return;
+    }
+    log();
+    success(`Checked out branch ${colors.cyan(branch.name)} ${colors.dim(branch.id)}`);
+    log(`  ${colors.dim("Project:")}   ${colors.dim(projectId)}`);
+    log(`  ${colors.dim("Link file:")} ${colors.dim(linkFile)}`);
+    log();
+}
+export async function studio() {
+    const projectId = resolveProjectId().projectId;
     const studioUrl = projectId
         ? `https://bench-app-one.vercel.app/studio?project=${projectId}`
         : "https://bench-app-one.vercel.app/studio";
@@ -313,14 +516,17 @@ function parseBranchFlag(args) {
 }
 export async function query(args = []) {
     const jsonMode = isJsonMode();
-    const { branchId, rest } = parseBranchFlag(args);
+    const { branchId: branchFlag, rest } = parseBranchFlag(args);
+    // Branch precedence: an explicit --branch wins, else the branch pinned by
+    // `bata db branch checkout` in .batadata/project.json, else the primary.
+    const branchId = resolveBranchId(branchFlag).branchId;
     const sql = rest.join(" ").trim();
     if (!sql) {
         emitError("MISSING_ARG", "SQL query is required.", 'Usage: bata db query "SELECT 1"');
     }
     const token = requireToken();
     const config = loadConfig();
-    const projectId = config.defaultProject;
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
@@ -442,10 +648,20 @@ function dbHelp(sub) {
             note("--json includes computeStatus + ready — poll these after create/cold start.");
             break;
         case "branch":
-            log(`  ${colors.bold("bata db branch")} — create or delete a branch`);
+            log(`  ${colors.bold("bata db branch")} — create, delete, or check out a branch`);
             log();
-            usage("bata db branch create <name>");
+            usage("bata db branch create <name> [--expires-in <2h|30m|7d>] [--purpose <text>]");
             usage("bata db branch delete <name> [--yes]");
+            usage("bata db branch checkout <name-or-id> [--project <id>]");
+            usage("bata db branch protect <name-or-id>");
+            usage("bata db branch unprotect <name-or-id>");
+            log();
+            note("--expires-in  Auto-delete the branch after this long (units: s/m/h/d/w).");
+            note("--purpose     Free-text note describing why the branch exists.");
+            note("checkout pins the branch into .batadata/project.json so db query/url");
+            note("target it without a --branch flag. Needs a linked project (bata link).");
+            note("protect/unprotect lock a branch against delete/reset/rollback/auto-reap.");
+            note("A protected branch cannot also carry a TTL (they're mutually exclusive).");
             break;
         case "url":
             log(`  ${colors.bold("bata db url")} — print the connection string`);
@@ -471,6 +687,9 @@ function dbHelp(sub) {
             usage("bata db branches         List branches + compute status");
             usage("bata db branch create    Create a new branch");
             usage("bata db branch delete    Delete a branch");
+            usage("bata db branch checkout  Pin a branch into .batadata/project.json");
+            usage("bata db branch protect   Lock a branch against destructive ops");
+            usage("bata db branch unprotect Remove a branch's protection");
             usage("bata db studio           Open the table browser");
             usage("bata db query <sql>      Run a SQL query (--branch <id-or-name> to target a branch)");
             log();
@@ -497,10 +716,16 @@ export async function handleDb(args) {
         case "branch": {
             const action = args[1];
             if (action === "create")
-                return branchCreate(args[2]);
+                return branchCreate(args.slice(2));
             if (action === "delete")
                 return branchDelete(args[2]);
-            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete");
+            if (action === "checkout")
+                return branchCheckout(args.slice(2));
+            if (action === "protect")
+                return branchSetProtected(args[2], true);
+            if (action === "unprotect")
+                return branchSetProtected(args[2], false);
+            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete, checkout, protect, unprotect");
         }
         case "studio":
             return studio();

package/dist/commands/link.d.ts

@@ -0,0 +1,2 @@
+export declare function link(args: string[]): Promise<void>;
+export declare function unlink(): void;