@batadata/cli 0.1.8 → 0.1.9

package/README.md

@@ -102,6 +102,8 @@ flag always wins**, so linking never silently overrides an intentional request:
 | `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 |
@@ -113,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`,

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/db.d.ts

@@ -23,6 +23,13 @@ export declare function url(): Promise<void>;
 export declare function branches(): 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

package/dist/commands/db.js

@@ -219,6 +219,8 @@ export async function branches() {
                 // 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,
@@ -231,9 +233,12 @@ export async function branches() {
         log();
         return;
     }
-    table(["NAME", "PRIMARY", "STATUS", "EXPIRES", "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),
@@ -359,6 +364,56 @@ export async function branchDelete(name) {
     log(`  ${colors.green(">")} Branch ${colors.cyan(name)} deleted`);
     log();
 }
+/**
+ * `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 = 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
@@ -598,11 +653,15 @@ function dbHelp(sub) {
             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`);
@@ -629,6 +688,8 @@ function dbHelp(sub) {
             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();
@@ -660,7 +721,11 @@ export async function handleDb(args) {
                 return branchDelete(args[2]);
             if (action === "checkout")
                 return branchCheckout(args.slice(2));
-            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete, checkout");
+            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/restore.d.ts

@@ -0,0 +1,71 @@
+/**
+ * bata restore — Point-in-time restore (PITR).
+ *
+ * Two subcommands:
+ *   restore points [--project <id>] [--json]
+ *       List the recovery points recorded for a project (GET
+ *       /v1/recovery-points/:projectId) plus each branch's live LSN and the
+ *       honest PITR window.
+ *
+ *   restore create --branch <name-or-id> --at <ISO-timestamp|LSN>
+ *                  [--name <newBranchName>] [--project <id>] [--json]
+ *       Restore a branch to a point in time by creating a NEW branch at that
+ *       point (POST /v1/restore). This is non-destructive: the source branch's
+ *       data is never overwritten.
+ *
+ * HONESTY RULE (documented, never overclaimed):
+ *   Recovery points are timeline-metadata snapshots the backup scheduler records
+ *   about every 6 hours (BACKUP_INTERVAL_HOURS) — they are NOT full physical
+ *   backups, and the earliest listed point is the oldest metadata row we have,
+ *   not a guaranteed floor on how far back you can restore. Restorability to an
+ *   arbitrary timestamp depends on how much WAL the pageserver still retains; if
+ *   the WAL doesn't extend that far the server returns "No data available at the
+ *   requested timestamp." We surface that verbatim rather than pretending the
+ *   window is deeper than it is.
+ */
+export interface RestorePoint {
+    /** How the input was interpreted. */
+    kind: "lsn" | "timestamp";
+    /**
+     * The value to send to the server. For an LSN it's the input as-is; for a
+     * timestamp it's normalized to offset-aware ISO 8601 so the server's
+     * `datetime({ offset: true })` validation accepts it.
+     */
+    value: string;
+    /** The raw user input (for human display). */
+    raw: string;
+}
+/**
+ * Classify a `--at` value as an LSN or a timestamp. An LSN (`0/15994B0`) is
+ * matched structurally; anything else is parsed as a date and normalized to
+ * offset-aware ISO 8601. Returns `{ error }` for input that is neither.
+ * Exported for unit testing.
+ */
+export declare function classifyRestorePoint(input: string): {
+    point?: RestorePoint;
+    error?: string;
+};
+/**
+ * Parse `restore create` args: `--branch`, `--at`, `--name`, `--project`
+ * (each accepting both `--flag value` and `--flag=value`). Order-independent,
+ * mirroring `parseBranchCreateArgs`. Exported for unit testing.
+ */
+export declare function parseRestoreCreateArgs(args: string[]): {
+    branch?: string;
+    at?: string;
+    name?: string;
+    projectId?: string;
+};
+/** Parse `restore points` args — only `--project` is meaningful here. */
+export declare function parseRestorePointsArgs(args: string[]): {
+    projectId?: string;
+};
+/**
+ * A default name for the restored branch when `--name` is omitted. Includes a
+ * compact UTC stamp so repeated restores don't collide, e.g.
+ * `restore-main-20260704T120000Z`.
+ */
+export declare function defaultRestoreBranchName(sourceName: string, now?: Date): string;
+export declare function restorePoints(args: string[]): Promise<void>;
+export declare function restoreCreate(args: string[]): Promise<void>;
+export declare function handleRestore(args: string[]): Promise<void>;

package/dist/commands/restore.js

@@ -0,0 +1,356 @@
+/**
+ * bata restore — Point-in-time restore (PITR).
+ *
+ * Two subcommands:
+ *   restore points [--project <id>] [--json]
+ *       List the recovery points recorded for a project (GET
+ *       /v1/recovery-points/:projectId) plus each branch's live LSN and the
+ *       honest PITR window.
+ *
+ *   restore create --branch <name-or-id> --at <ISO-timestamp|LSN>
+ *                  [--name <newBranchName>] [--project <id>] [--json]
+ *       Restore a branch to a point in time by creating a NEW branch at that
+ *       point (POST /v1/restore). This is non-destructive: the source branch's
+ *       data is never overwritten.
+ *
+ * HONESTY RULE (documented, never overclaimed):
+ *   Recovery points are timeline-metadata snapshots the backup scheduler records
+ *   about every 6 hours (BACKUP_INTERVAL_HOURS) — they are NOT full physical
+ *   backups, and the earliest listed point is the oldest metadata row we have,
+ *   not a guaranteed floor on how far back you can restore. Restorability to an
+ *   arbitrary timestamp depends on how much WAL the pageserver still retains; if
+ *   the WAL doesn't extend that far the server returns "No data available at the
+ *   requested timestamp." We surface that verbatim rather than pretending the
+ *   window is deeper than it is.
+ */
+import { api, apiError } from "../api.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { colors, log, json, spinner, table, heading, kvList, success } from "../utils/logger.js";
+import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
+// A Postgres LSN is two hex words joined by a slash, e.g. `0/15994B0`. That
+// shape can never collide with an ISO-8601 timestamp (which carries `-`/`:`),
+// so the slash-of-hex is a safe discriminator.
+const LSN_RE = /^[0-9A-Fa-f]+\/[0-9A-Fa-f]+$/;
+/**
+ * Classify a `--at` value as an LSN or a timestamp. An LSN (`0/15994B0`) is
+ * matched structurally; anything else is parsed as a date and normalized to
+ * offset-aware ISO 8601. Returns `{ error }` for input that is neither.
+ * Exported for unit testing.
+ */
+export function classifyRestorePoint(input) {
+    const raw = (input ?? "").trim();
+    if (!raw) {
+        return { error: "A restore point is required. Pass --at <ISO-timestamp|LSN>." };
+    }
+    if (LSN_RE.test(raw)) {
+        return { point: { kind: "lsn", value: raw, raw } };
+    }
+    const d = new Date(raw);
+    if (!Number.isNaN(d.getTime())) {
+        return { point: { kind: "timestamp", value: d.toISOString(), raw } };
+    }
+    return {
+        error: `Could not parse "${raw}" as an ISO-8601 timestamp or an LSN (e.g. 0/15994B0).`,
+    };
+}
+/**
+ * Parse `restore create` args: `--branch`, `--at`, `--name`, `--project`
+ * (each accepting both `--flag value` and `--flag=value`). Order-independent,
+ * mirroring `parseBranchCreateArgs`. Exported for unit testing.
+ */
+export function parseRestoreCreateArgs(args) {
+    let branch;
+    let at;
+    let name;
+    let projectId;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--branch")
+            branch = args[++i];
+        else if (arg.startsWith("--branch="))
+            branch = arg.slice("--branch=".length);
+        else if (arg === "--at")
+            at = args[++i];
+        else if (arg.startsWith("--at="))
+            at = arg.slice("--at=".length);
+        else if (arg === "--name")
+            name = args[++i];
+        else if (arg.startsWith("--name="))
+            name = arg.slice("--name=".length);
+        else if (arg === "--project")
+            projectId = args[++i];
+        else if (arg.startsWith("--project="))
+            projectId = arg.slice("--project=".length);
+    }
+    return { branch, at, name, projectId };
+}
+/** Parse `restore points` args — only `--project` is meaningful here. */
+export function parseRestorePointsArgs(args) {
+    let projectId;
+    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);
+    }
+    return { projectId };
+}
+/**
+ * A default name for the restored branch when `--name` is omitted. Includes a
+ * compact UTC stamp so repeated restores don't collide, e.g.
+ * `restore-main-20260704T120000Z`.
+ */
+export function defaultRestoreBranchName(sourceName, now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    return `restore-${sourceName}-${stamp}`;
+}
+// ─── Shared helpers ────────────────────────────────────────────────────────
+function requireProject(projectFlag) {
+    const { projectId } = resolveProjectId(projectFlag);
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project. Pass --project <id>, or link one with `bata link <project>`.", "Run `bata link <project>` once, then restore commands need no --project.");
+    }
+    return projectId;
+}
+/**
+ * Resolve a `--branch` reference (id OR name) to a concrete branch via
+ * GET /v1/projects/:id. Agents pass the same name they branched with, so
+ * accepting only ids would be a footgun — mirrors `db query --branch`.
+ */
+async function resolveBranchRef(projectId, token, teamId, ref) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    if (!res.ok)
+        return null;
+    const branches = res.data.branches ?? [];
+    return branches.find((b) => b.id === ref || b.name === ref) ?? null;
+}
+function formatDateTime(iso) {
+    if (!iso)
+        return "-";
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return d.toLocaleString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}
+function formatBytes(bytes) {
+    if (bytes === null || bytes === undefined)
+        return "-";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+// ─── restore points ────────────────────────────────────────────────────────
+export async function restorePoints(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const { projectId: projectFlag } = parseRestorePointsArgs(args);
+    const projectId = requireProject(projectFlag);
+    const query = {};
+    if (config.defaultTeam)
+        query.team_id = config.defaultTeam;
+    const s = jsonMode ? null : spinner("Fetching recovery points");
+    const res = await api.get(`/v1/recovery-points/${projectId}`, token, query);
+    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 recovery points"), "");
+    }
+    const data = res.data;
+    const points = data.recovery_points ?? [];
+    const live = data.live_state ?? [];
+    const window = data.pitr_window;
+    if (jsonMode) {
+        json({
+            project_id: data.project_id ?? projectId,
+            recovery_points: points,
+            live_state: live,
+            pitr_window: window,
+        });
+        return;
+    }
+    // Map branch_id → name from live_state so the table shows names, not ids.
+    const nameById = new Map(live.map((b) => [b.branch_id, b.branch_name]));
+    heading(`Recovery points — ${projectId}`);
+    kvList([
+        ["Earliest recorded", formatDateTime(window?.earliest_available ?? null)],
+        ["Latest (live)", formatDateTime(window?.latest_available ?? null)],
+    ]);
+    log();
+    if (points.length === 0) {
+        log(`  ${colors.dim("No recorded recovery points yet.")}`);
+        log(`  ${colors.dim("The backup scheduler records a point about every 6 hours.")}`);
+        log();
+    }
+    else {
+        table(["RECORDED", "BRANCH", "LSN", "SIZE", "TYPE"], points.map((p) => [
+            formatDateTime(p.recorded_at),
+            nameById.get(p.branch_id) ?? p.branch_id,
+            p.lsn ?? "-",
+            formatBytes(p.size_bytes),
+            p.type,
+        ]));
+        log();
+    }
+    // Honest window note — never overclaim depth. A recorded point is a metadata
+    // snapshot, and restorability past it depends on WAL retention.
+    log(`  ${colors.dim("Recovery points are timeline-metadata snapshots (recorded ~every 6h),")}`);
+    log(`  ${colors.dim("not full backups. Restore to any timestamp the WAL still covers with:")}`);
+    log(`  ${colors.cyan('bata restore create --branch <name> --at <ISO-timestamp|LSN>')}`);
+    log();
+}
+// ─── restore create ─────────────────────────────────────────────────────────
+export async function restoreCreate(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const config = loadConfig();
+    const { branch, at, name, projectId: projectFlag } = parseRestoreCreateArgs(args);
+    const projectId = requireProject(projectFlag);
+    if (!branch) {
+        emitError("MISSING_ARG", "A source branch is required.", "Usage: bata restore create --branch <name-or-id> --at <ISO-timestamp|LSN>");
+    }
+    if (!at) {
+        emitError("MISSING_ARG", "A restore point is required.", "Pass --at <ISO-timestamp|LSN> (an LSN looks like 0/15994B0).");
+    }
+    const classified = classifyRestorePoint(at);
+    if (classified.error) {
+        emitError("INVALID_FLAG", classified.error, "");
+    }
+    const point = classified.point;
+    const s = jsonMode ? null : spinner(`Resolving branch ${colors.cyan(branch)}`);
+    const sourceBranch = await resolveBranchRef(projectId, token, config.defaultTeam, branch);
+    if (!sourceBranch) {
+        s?.stop();
+        emitError("BRANCH_NOT_FOUND", `Branch "${branch}" not found in this project.`, "List branches with: bata db branches --json");
+    }
+    const targetName = name || defaultRestoreBranchName(sourceBranch.name);
+    s?.update(`Restoring ${colors.cyan(sourceBranch.name)} to ${colors.cyan(point.raw)}`);
+    const body = {
+        project_id: projectId,
+        source_branch_id: sourceBranch.id,
+        target_branch_name: targetName,
+        restore_point: point.kind === "lsn" ? { lsn: point.value } : { timestamp: point.value },
+    };
+    const res = await api.post("/v1/restore", body, token);
+    s?.stop();
+    if (!res.ok) {
+        const respBody = res.data;
+        if (isRetryable({ status: res.status, code: respBody?.code, message: respBody?.error })) {
+            emitError("API_UNAVAILABLE", apiError(res, "Restore failed"), "transient upstream error — retry in a few seconds");
+        }
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY" : "CLI_ERROR";
+        emitError(code, apiError(res, "Restore failed"), "");
+    }
+    const restored = res.data.restored_branch;
+    if (!restored) {
+        emitError("CLI_ERROR", res.data.error || "Restore did not return a branch.", "");
+    }
+    const queryHint = `bata db query "SELECT 1" --branch ${restored.id}`;
+    if (jsonMode) {
+        json({
+            restored_branch: {
+                id: restored.id,
+                name: restored.name,
+                parent_branch_id: restored.parent_branch_id,
+                restore_point: restored.restore_point,
+                resolved_lsn: restored.resolved_lsn,
+                compute_id: restored.compute_id,
+            },
+            source_branch_id: sourceBranch.id,
+            operation_id: res.data.operation_id ?? null,
+            // A NEW branch — the source branch's data is untouched.
+            non_destructive: true,
+            // The branch row exists immediately; its compute may still be
+            // provisioning — poll before querying.
+            ready: false,
+            poll: "bata db branches --json",
+            query_hint: queryHint,
+        });
+        return;
+    }
+    log();
+    success(`Restore initiated — created a NEW branch (no data on ${colors.cyan(sourceBranch.name)} was changed)`);
+    log();
+    kvList([
+        ["New branch", `${colors.cyan(restored.name)} ${colors.dim(restored.id)}`],
+        ["Restored from", `${sourceBranch.name} at ${point.raw} ${colors.dim(`(${point.kind})`)}`],
+        ["Resolved LSN", restored.resolved_lsn],
+        ["Operation", res.data.operation_id ?? "-"],
+    ]);
+    log();
+    log(`  ${colors.dim("Poll readiness with")} ${colors.cyan("bata db branches")}${colors.dim(", then query it:")}`);
+    log(`  ${colors.cyan(queryHint)}`);
+    log();
+}
+// ─── Help + dispatch ─────────────────────────────────────────────────────────
+function hasHelpFlag(args) {
+    return args.some((a) => a === "--help" || a === "-h");
+}
+function restoreHelp(sub) {
+    const usage = (line) => log(`  ${colors.cyan(line)}`);
+    const note = (line) => log(`  ${colors.dim(line)}`);
+    log();
+    switch (sub) {
+        case "points":
+            log(`  ${colors.bold("bata restore points")} — list recovery points for a project`);
+            log();
+            usage("bata restore points [--project <id>] [--json]");
+            log();
+            note("Shows recorded recovery points, each branch's live LSN, and the PITR window.");
+            note("Points are metadata snapshots (~every 6h), not full backups — see below.");
+            break;
+        case "create":
+            log(`  ${colors.bold("bata restore create")} — restore a branch to a point in time`);
+            log();
+            usage("bata restore create --branch <name-or-id> --at <ISO-timestamp|LSN> [--name <newBranch>] [--json]");
+            log();
+            note("Non-destructive: creates a NEW branch at the chosen point; the source");
+            note("branch's data is never overwritten. --at accepts an ISO-8601 timestamp");
+            note("(e.g. 2026-07-04T12:00:00Z) or an LSN (e.g. 0/15994B0).");
+            note("--name defaults to restore-<branch>-<timestamp> if omitted.");
+            break;
+        default:
+            log(`  ${colors.bold("bata restore")} — point-in-time restore (PITR)`);
+            log();
+            usage("bata restore points   List recovery points + the PITR window");
+            usage("bata restore create   Restore a branch to a timestamp/LSN as a NEW branch");
+            log();
+            note("Restore is non-destructive — it always creates a new branch.");
+            note("Add --help to a subcommand for details (e.g. bata restore create --help).");
+    }
+    log();
+}
+export async function handleRestore(args) {
+    const sub = args[0];
+    if (hasHelpFlag(args) || !sub) {
+        restoreHelp(sub);
+        return;
+    }
+    switch (sub) {
+        case "points":
+            return restorePoints(args.slice(1));
+        case "create":
+            return restoreCreate(args.slice(1));
+        default:
+            emitError("INVALID_FLAG", `Unknown subcommand: restore ${sub}`, "Available: points, create");
+    }
+}

package/dist/index.js

@@ -11,6 +11,7 @@ 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 { handleRestore } from "./commands/restore.js";
 import { link, unlink } from "./commands/link.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
@@ -53,6 +54,10 @@ function help() {
     log(`    ${colors.cyan("db studio")}          Open table browser in browser`);
     log(`    ${colors.cyan("db query")}           Run a SQL query ${colors.dim("(--branch <id> to target a branch)")}`);
     log();
+    log(`  ${colors.bold("Restore (PITR)")}`);
+    log(`    ${colors.cyan("restore points")}     List recovery points + the PITR window`);
+    log(`    ${colors.cyan("restore create")}     Restore a branch to a timestamp/LSN ${colors.dim("(creates a NEW branch)")}`);
+    log();
     log(`  ${colors.bold("Schema & Types")}`);
     log(`    ${colors.cyan("generate")}           Generate types from database schema`);
     log(`    ${colors.cyan("generate --watch")}   Watch mode for type generation`);
@@ -159,6 +164,10 @@ async function main() {
             case "db":
                 await handleDb(rest);
                 break;
+            // Restore (PITR)
+            case "restore":
+                await handleRestore(rest);
+                break;
             // Schema
             case "schema":
                 await handleSchema(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"