@batadata/cli 0.1.7 → 0.1.9

package/dist/commands/link.js

@@ -0,0 +1,138 @@
+import { api, apiError, resolveTeamId, asList } from "../api.js";
+import { requireToken, isJsonMode } from "../config.js";
+import { colors, log, json, success, spinner } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
+import { select } from "../utils/prompts.js";
+import { LINK_DIR, findLinkFile, readLinkFile, writeLinkFile, removeLinkFile, } from "../link.js";
+/**
+ * Pull `--status` out of the args and return the remaining positionals. Global
+ * flags (`--json` etc.) are stripped upstream by parseGlobalFlags, so anything
+ * still `--`-prefixed here is a link-specific flag.
+ */
+function parseLinkArgs(args) {
+    let status = false;
+    let positional;
+    for (const arg of args) {
+        if (arg === "--status")
+            status = true;
+        else if (!arg.startsWith("-") && positional === undefined)
+            positional = arg;
+    }
+    return { status, positional };
+}
+/** Fetch the caller's projects (team-scoped, exactly like `projects list`). */
+async function fetchProjects(token) {
+    const teamId = await resolveTeamId(token);
+    if (!teamId) {
+        emitError("NO_TEAM", "No team found for this credential.", "This API key isn't attached to a team. Run `bata login` or check `bata whoami`.");
+    }
+    const res = await api.get("/v1/projects", token, { team_id: teamId });
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch projects"), "");
+    }
+    return asList(res.data);
+}
+/** Show what (if anything) the current directory resolves to. */
+function linkStatus() {
+    const found = readLinkFile();
+    const jsonMode = isJsonMode();
+    if (!found) {
+        if (jsonMode) {
+            json({ linked: false, project_id: null, branch_id: null, link_file: null });
+            return;
+        }
+        log();
+        log(`  ${colors.dim("No project linked in this directory.")}`);
+        log(`  Run ${colors.cyan("bata link <project>")} to link one.`);
+        log();
+        return;
+    }
+    const { path: linkFile, link } = found;
+    if (jsonMode) {
+        json({
+            linked: true,
+            project_id: link.projectId,
+            branch_id: link.branchId ?? null,
+            link_file: linkFile,
+        });
+        return;
+    }
+    log();
+    success(`Linked to project ${colors.cyan(link.projectId)}`);
+    log(`  ${colors.dim("Branch:")}    ${link.branchId ? colors.cyan(link.branchId) : colors.dim("(none)")}`);
+    log(`  ${colors.dim("Link file:")} ${colors.dim(linkFile)}`);
+    log();
+}
+export async function link(args) {
+    const { status, positional } = parseLinkArgs(args);
+    const jsonMode = isJsonMode();
+    if (status) {
+        linkStatus();
+        return;
+    }
+    // Input-contract check first (no token needed): headless with no project is a
+    // hard MISSING_ARG — never guess a project for an agent, never hang on a
+    // prompt. Doing this before requireToken() gives the clearer error.
+    if (!positional && (jsonMode || !process.stdin.isTTY)) {
+        emitError("MISSING_ARG", "No project specified.", "Pass a project id or name: bata link <project>  (interactive selection needs a TTY).");
+    }
+    const token = requireToken();
+    let target;
+    if (positional) {
+        // Resolve by id OR name — the same string a user passes to other commands
+        // (mirrors how connect.ts and db.ts resolve --branch by name|id).
+        const s = jsonMode ? null : spinner("Resolving project");
+        const projects = await fetchProjects(token);
+        s?.stop();
+        target = projects.find((p) => p.id === positional || p.name === positional);
+        if (!target) {
+            emitError("NOT_FOUND", `Project "${positional}" not found.`, "List your projects with: bata projects list --json");
+        }
+    }
+    else {
+        // No argument in an interactive TTY → pick from a list.
+        const projects = await fetchProjects(token);
+        if (projects.length === 0) {
+            emitError("NOT_FOUND", "You have no projects to link.", "Create one with: bata create <name>");
+        }
+        const chosen = await select("Select a project to link", projects.map((p) => ({ label: `${p.name} ${colors.dim(p.id)}`, value: p.id })));
+        target = projects.find((p) => p.id === chosen);
+    }
+    const linkFile = writeLinkFile(process.cwd(), { projectId: target.id, branchId: null });
+    if (jsonMode) {
+        json({
+            linked: true,
+            project_id: target.id,
+            project_name: target.name,
+            branch_id: null,
+            link_file: linkFile,
+        });
+        return;
+    }
+    log();
+    success(`Linked to ${colors.cyan(target.name)} ${colors.dim(target.id)}`);
+    log(`  ${colors.dim("Wrote")} ${colors.dim(linkFile)}`);
+    log();
+    log(`  ${colors.dim("Commands in this directory now target this project — no")} ${colors.cyan("--project")} ${colors.dim("needed.")}`);
+    log(`  ${colors.dim("Tip: add")} ${colors.cyan(`${LINK_DIR}/`)} ${colors.dim("to your .gitignore.")}`);
+    log();
+}
+export function unlink() {
+    const jsonMode = isJsonMode();
+    const existed = findLinkFile();
+    const removed = removeLinkFile();
+    if (jsonMode) {
+        json({ unlinked: Boolean(existed), link_file: removed });
+        return;
+    }
+    log();
+    if (removed) {
+        success(`Unlinked — removed ${colors.dim(removed)}`);
+    }
+    else {
+        log(`  ${colors.dim("No project link found in this directory.")}`);
+    }
+    log();
+}

package/dist/commands/projects.js

@@ -3,6 +3,7 @@ import { requireToken, loadConfig, saveConfig, isJsonMode } from "../config.js";
 import { colors, log, json, success, spinner, table, kvList, heading } from "../utils/logger.js";
 import { prompt, confirmDestructive, select } from "../utils/prompts.js";
 import { emitError } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
 function projectCreatedAt(p) {
     return p.created_at ?? p.createdAt ?? "";
 }
@@ -134,11 +135,11 @@ export async function create() {
 }
 export async function info(projectId) {
     const token = requireToken();
-    const config = loadConfig();
     const jsonMode = isJsonMode();
-    const id = projectId || config.defaultProject;
+    // Precedence: explicit arg/--project > .batadata link > config default.
+    const id = resolveProjectId(projectId).projectId;
     if (!id) {
-        emitError("NO_PROJECT", "No project specified.", "Pass a project ID or set a default with bata projects create.");
+        emitError("NO_PROJECT", "No project specified.", "Pass a project ID, run `bata link <project>`, or set a default with bata projects create.");
     }
     const s = jsonMode ? null : spinner("Fetching project details");
     const teamId = await resolveTeamId(token);
@@ -213,7 +214,8 @@ export async function deleteProject(projectId) {
     const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
-    const id = projectId || config.defaultProject;
+    // Precedence: explicit arg/--project > .batadata link > config default.
+    const id = resolveProjectId(projectId).projectId;
     if (!id) {
         emitError("NO_PROJECT", "No project specified.", "Pass a project ID: bata projects delete <id>");
     }

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/commands/schema.js

@@ -1,8 +1,9 @@
 import { readFileSync } from "node:fs";
 import { api, apiError } from "../api.js";
-import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { requireToken, isJsonMode } from "../config.js";
 import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
 import { emitError } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
 const NOT_IMPLEMENTED_HINT = "Use `bata schema check <file.sql> --fail-on breaking` to gate migrations today.";
 /**
  * Unimplemented schema subcommand. Never exits 0 for a no-op: emits the
@@ -90,10 +91,10 @@ async function schemaCheck(args) {
         emitError("EMPTY_INPUT", "DDL input was empty.", "Provide a schema change to check, e.g. ALTER TABLE orders DROP COLUMN status;");
     }
     const token = requireToken();
-    const config = loadConfig();
-    const projectId = config.defaultProject;
+    // Precedence: .batadata link > config default (schema check has no --project).
+    const projectId = resolveProjectId().projectId;
     if (!projectId) {
-        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+        emitError("NO_PROJECT", "No default project set.", "Run `bata link <project>` or set a default with: bata projects info <id>");
     }
     const body = { sql: ddl, timeRange };
     if (branchId)

package/dist/index.js

@@ -11,6 +11,8 @@ 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";
 import { colors, log, banner } from "./utils/logger.js";
@@ -26,6 +28,8 @@ function help() {
     log(`    ${colors.cyan("connect <name>")}    Open psql to a project (auto-wakes if suspended)`);
     log(`    ${colors.cyan("status")}             Show all projects and their status`);
     log(`    ${colors.cyan("usage")}              Per-dimension cost for the current period`);
+    log(`    ${colors.cyan("link [project]")}     Link this directory to a project ${colors.dim("(no more --project)")}`);
+    log(`    ${colors.cyan("unlink")}             Remove this directory's project link`);
     log();
     log(`  ${colors.bold("Auth")}`);
     log(`    ${colors.cyan("login")}              Log in to BataDB`);
@@ -46,9 +50,14 @@ function help() {
     log(`    ${colors.cyan("db branches")}        List database branches ${colors.dim("(STATUS shows compute readiness)")}`);
     log(`    ${colors.cyan("db branch create")}   Create a new branch`);
     log(`    ${colors.cyan("db branch delete")}   Delete a branch`);
+    log(`    ${colors.cyan("db branch checkout")} Pin a branch into ${colors.dim(".batadata/project.json")}`);
     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`);
@@ -121,6 +130,12 @@ async function main() {
             case "usage":
                 await usage(rest);
                 break;
+            case "link":
+                await link(rest);
+                break;
+            case "unlink":
+                unlink();
+                break;
             // Auth
             case "login":
                 await login();
@@ -149,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);