@batadata/cli 0.1.6 → 0.1.8

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,6 +100,7 @@ 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 |
 | `schema check <file>` | Check a proposed schema change against live query traffic |
 | `generate` | Generate types from your database schema (`--watch` for watch mode) |
@@ -125,6 +167,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

@@ -14,6 +14,32 @@ export declare function request<T = unknown>(method: string, path: string, optio
  * generic placeholder so agents see what actually went wrong.
  */
 export declare function apiError(res: ApiResponse, fallback?: string): string;
+export interface ResolvedTeam {
+    teamId: string | undefined;
+    /** Set when a configured `defaultTeam` existed but the active credential
+     *  isn't a member of it, so the CLI fell back to the key's first team. */
+    mismatchNote?: string;
+}
+/**
+ * Pure team-resolution policy — no fs/network/process access, so it's
+ * unit-testable without mocking modules.
+ *
+ * - Happy path: the credential IS the stored login (tokenSource === "stored")
+ *   and it has a saved `defaultTeam`. That team was saved BY this login, so
+ *   it's trustworthy by construction — return it with zero requests.
+ * - Otherwise (a `--api-key` flag or `BATA_API_KEY` env may belong to a
+ *   different account/key than whatever last ran `bata login` on this
+ *   machine) — don't trust `defaultTeam` blindly. Fetch the key's actual
+ *   teams and only use `defaultTeam` if the key is really a member; else
+ *   fall back to the key's first team and report the mismatch.
+ */
+export declare function pickTeamId(params: {
+    tokenSource: "flag" | "env" | "stored" | "none";
+    savedDefaultTeam: string | undefined;
+    fetchTeams: () => Promise<Array<{
+        id: string;
+    }> | undefined>;
+}): Promise<ResolvedTeam>;
 export declare function resolveTeamId(token: string): Promise<string | undefined>;
 /**
  * List endpoints return `{ data: [...], pagination }` (not a bare array).

package/dist/api.js

@@ -1,7 +1,8 @@
 import * as https from "node:https";
 import * as http from "node:http";
 import { URL } from "node:url";
-import { getApiUrl, loadConfig } from "./config.js";
+import { getApiUrl, loadConfig, getTokenSource, isJsonMode } from "./config.js";
+import { colors } from "./utils/logger.js";
 export async function request(method, path, options = {}) {
     const baseUrl = getApiUrl();
     const url = new URL(path, baseUrl);
@@ -71,24 +72,65 @@ export function apiError(res, fallback = "Request failed") {
     return `${fallback} (HTTP ${res.status || "?"})`;
 }
 /**
- * Resolve the team id to operate on. Headless agents (just BATA_API_KEY, no
- * prior `bata login`) have no saved defaultTeam, and the API requires a team
- * for project list/create. So fall back to the user's first team. Cached for
- * the process lifetime. Returns undefined only if the user has no teams.
+ * Pure team-resolution policy — no fs/network/process access, so it's
+ * unit-testable without mocking modules.
+ *
+ * - Happy path: the credential IS the stored login (tokenSource === "stored")
+ *   and it has a saved `defaultTeam`. That team was saved BY this login, so
+ *   it's trustworthy by construction — return it with zero requests.
+ * - Otherwise (a `--api-key` flag or `BATA_API_KEY` env may belong to a
+ *   different account/key than whatever last ran `bata login` on this
+ *   machine) — don't trust `defaultTeam` blindly. Fetch the key's actual
+ *   teams and only use `defaultTeam` if the key is really a member; else
+ *   fall back to the key's first team and report the mismatch.
+ */
+export async function pickTeamId(params) {
+    const { tokenSource, savedDefaultTeam, fetchTeams } = params;
+    if (tokenSource === "stored" && savedDefaultTeam) {
+        return { teamId: savedDefaultTeam };
+    }
+    const teams = await fetchTeams();
+    if (!teams)
+        return { teamId: undefined };
+    if (savedDefaultTeam && teams.some((t) => t.id === savedDefaultTeam)) {
+        return { teamId: savedDefaultTeam };
+    }
+    const fallback = teams[0]?.id;
+    if (savedDefaultTeam && fallback) {
+        return {
+            teamId: fallback,
+            mismatchNote: `Configured default team "${savedDefaultTeam}" isn't accessible with this ` +
+                `API key — using "${fallback}" instead.`,
+        };
+    }
+    return { teamId: fallback };
+}
+/**
+ * Resolve the team id to operate on. Cached for the process lifetime (both
+ * the id and whether the mismatch note was already printed), since it never
+ * changes mid-run. Returns undefined only if the credential has no teams.
  */
 let _cachedTeamId;
+let _resolved = false;
 export async function resolveTeamId(token) {
-    const saved = loadConfig().defaultTeam;
-    if (saved)
-        return saved;
-    if (_cachedTeamId)
+    if (_resolved)
         return _cachedTeamId;
-    const res = await request("GET", "/v1/teams", { token });
-    if (!res.ok)
-        return undefined;
-    const data = res.data;
-    const teams = Array.isArray(data) ? data : data?.teams ?? [];
-    _cachedTeamId = teams[0]?.id;
+    const result = await pickTeamId({
+        tokenSource: getTokenSource(),
+        savedDefaultTeam: loadConfig().defaultTeam,
+        fetchTeams: async () => {
+            const res = await request("GET", "/v1/teams", { token });
+            if (!res.ok)
+                return undefined;
+            const data = res.data;
+            return Array.isArray(data) ? data : data?.teams ?? [];
+        },
+    });
+    _cachedTeamId = result.teamId;
+    _resolved = true;
+    if (result.mismatchNote && !isJsonMode()) {
+        console.error(colors.dim(`  ${result.mismatchNote}`));
+    }
     return _cachedTeamId;
 }
 /**

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,35 @@
+/**
+ * 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 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,9 @@ 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,
                 created_at: b.createdAt ?? null,
             })),
             count: branchList.length,
@@ -173,24 +231,37 @@ export async function branches() {
         log();
         return;
     }
-    table(["NAME", "PRIMARY", "STATUS", "CREATED"], branchList.map((b) => [
+    table(["NAME", "PRIMARY", "STATUS", "EXPIRES", "CREATED"], branchList.map((b) => [
         b.name,
         b.isPrimary ? colors.green("yes") : "-",
         // 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 +280,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 +291,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 +307,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 +317,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 +359,73 @@ export async function branchDelete(name) {
     log(`  ${colors.green(">")} Branch ${colors.cyan(name)} deleted`);
     log();
 }
-export async function studio() {
+/**
+ * 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 projectId = config.defaultProject;
+    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 +461,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 +593,16 @@ 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>]");
+            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).");
             break;
         case "url":
             log(`  ${colors.bold("bata db url")} — print the connection string`);
@@ -471,6 +628,7 @@ 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 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 +655,12 @@ 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));
+            emitError("INVALID_FLAG", `Unknown: db branch ${action || ""}`, "Available: create, delete, checkout");
         }
         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;

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

@@ -1,3 +1,11 @@
+/**
+ * Only surface `defaultProject` if it's actually one of the caller's real
+ * projects — a saved default from another team/key/stale config must never
+ * be echoed back as if it were live data. Returns null otherwise.
+ */
+export declare function validDefaultProject(projects: Array<{
+    id: string;
+}>, defaultProject: string | undefined): string | null;
 export declare function list(): Promise<void>;
 export declare function create(): Promise<void>;
 export declare function info(projectId?: string): Promise<void>;

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 ?? "";
 }
@@ -19,6 +20,16 @@ function formatDate(iso) {
     const d = new Date(iso);
     return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
 }
+/**
+ * Only surface `defaultProject` if it's actually one of the caller's real
+ * projects — a saved default from another team/key/stale config must never
+ * be echoed back as if it were live data. Returns null otherwise.
+ */
+export function validDefaultProject(projects, defaultProject) {
+    if (!defaultProject)
+        return null;
+    return projects.some((p) => p.id === defaultProject) ? defaultProject : null;
+}
 function statusBadge(status) {
     switch (status?.toLowerCase()) {
         case "active":
@@ -55,6 +66,7 @@ export async function list() {
     }
     s?.stop();
     const projects = asList(res.data);
+    const defaultProj = validDefaultProject(projects, config.defaultProject);
     if (jsonMode) {
         json({
             projects: projects.map((p) => ({
@@ -64,7 +76,7 @@ export async function list() {
                 status: p.status,
                 created_at: projectCreatedAt(p),
             })),
-            default_project: config.defaultProject ?? null,
+            default_project: defaultProj,
             count: projects.length,
         });
         return;
@@ -75,7 +87,6 @@ export async function list() {
         log();
         return;
     }
-    const defaultProj = config.defaultProject;
     table(["NAME", "REGION", "STATUS", "CREATED"], projects.map((p) => [
         p.id === defaultProj ? `${p.name} ${colors.cyan("*")}` : p.name,
         p.region || "-",
@@ -124,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);
@@ -203,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/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/commands/status.js

@@ -8,6 +8,7 @@ import { api, apiError, resolveTeamId } from "../api.js";
 import { requireToken, loadConfig, isJsonMode } from "../config.js";
 import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
 import { emitError } from "../utils/errors.js";
+import { validDefaultProject } from "./projects.js";
 function statusBadge(status) {
     switch (status?.toLowerCase()) {
         case "active":
@@ -55,6 +56,7 @@ export async function status() {
     }
     s?.stop();
     const projects = Array.isArray(res.data) ? res.data : [];
+    const defaultProj = validDefaultProject(projects, config.defaultProject);
     if (jsonMode) {
         json({
             projects: projects.map((p) => ({
@@ -66,7 +68,7 @@ export async function status() {
                 branch_count: p.branches?.length ?? 0,
                 compute_status: p.computes?.[0]?.status ?? p.status ?? null,
             })),
-            default_project: config.defaultProject ?? null,
+            default_project: defaultProj,
             count: projects.length,
         });
         return;
@@ -77,7 +79,6 @@ export async function status() {
         log();
         return;
     }
-    const defaultProj = config.defaultProject;
     // Fetch branch/compute details for each project
     const rows = [];
     for (const p of projects) {

package/dist/config.d.ts

@@ -30,6 +30,14 @@ export declare function clearConfig(): void;
  * Returns undefined if none is available.
  */
 export declare function getToken(): string | undefined;
+export type TokenSource = "flag" | "env" | "stored" | "none";
+/**
+ * Where the active credential came from, in the same priority order as
+ * getToken(). Callers use this to decide whether it's safe to trust
+ * config saved by a *different* credential (e.g. a `defaultTeam` written by
+ * a previous `bata login`) — it only is when the token IS that stored login.
+ */
+export declare function getTokenSource(): TokenSource;
 /**
  * Like getToken() but exits with a clear, agent-friendly error if no
  * credential can be found anywhere.

package/dist/config.js

@@ -68,6 +68,21 @@ export function getToken() {
         return process.env.BATA_API_KEY;
     return loadConfig().token;
 }
+/**
+ * Where the active credential came from, in the same priority order as
+ * getToken(). Callers use this to decide whether it's safe to trust
+ * config saved by a *different* credential (e.g. a `defaultTeam` written by
+ * a previous `bata login`) — it only is when the token IS that stored login.
+ */
+export function getTokenSource() {
+    if (runtime.apiKey)
+        return "flag";
+    if (process.env.BATA_API_KEY)
+        return "env";
+    if (loadConfig().token)
+        return "stored";
+    return "none";
+}
 /**
  * Like getToken() but exits with a clear, agent-friendly error if no
  * credential can be found anywhere.

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 { 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 +27,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,6 +49,7 @@ 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();
@@ -121,6 +125,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();

package/dist/link.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Project linking — Vercel/Neon-style. A linked directory carries its project
+ * (and optionally its branch) in `.batadata/project.json`, so an agent no longer
+ * has to thread `--project <id>` through every invocation.
+ *
+ * ── Resolution precedence (the ONE rule, used everywhere) ─────────────────
+ *   1. an explicit `--project` / `--branch` flag        (per-invocation intent)
+ *   2. `.batadata/project.json`, discovered by walking UP from CWD like git    (per-directory intent)
+ *   3. `defaultProject` in `~/.batarc`                  (per-machine fallback)
+ *
+ * Flags always win, so linking never silently overrides an explicit request.
+ * The precedence itself lives in the pure `pickProjectId` / `pickBranchId`
+ * helpers (unit-testable without fs), and `resolveProjectId` / `resolveBranchId`
+ * compose them with the on-disk sources.
+ */
+export declare const LINK_DIR = ".batadata";
+export declare const LINK_FILE = "project.json";
+export interface LinkFile {
+    projectId: string;
+    /** Optional pinned branch (set by `bata db branch checkout`). */
+    branchId?: string | null;
+}
+export type ProjectSource = "flag" | "link" | "config" | "none";
+export type BranchSource = "flag" | "link" | "none";
+/**
+ * The ordered list of directories to search for a link file, from `startDir`
+ * up to (and including) the ceiling — the user's HOME dir or the filesystem
+ * root, whichever comes first. Exactly how git bounds its repo discovery.
+ *
+ * Pure: no fs, no env — just path math — so the walk-up order is unit-testable
+ * without ever writing to a real HOME.
+ */
+export declare function linkSearchDirs(startDir: string, homeDir: string): string[];
+/**
+ * Absolute path to the nearest `.batadata/project.json` at or above `startDir`,
+ * or null if none exists within the ceiling. Walks up like git.
+ */
+export declare function findLinkFile(startDir?: string, homeDir?: string): string | null;
+/**
+ * Read and parse the nearest link file. Returns its absolute path alongside the
+ * parsed contents, or null if there's no (valid) link file. A malformed file is
+ * treated as absent rather than throwing, so a stray/corrupt file can't wedge
+ * every command.
+ */
+export declare function readLinkFile(startDir?: string, homeDir?: string): {
+    path: string;
+    link: LinkFile;
+} | null;
+/**
+ * Write `.batadata/project.json` inside `dir` (creating `.batadata/` if needed)
+ * and return the absolute path written. `branchId` is normalized to null when
+ * absent so the file shape is stable.
+ */
+export declare function writeLinkFile(dir: string, link: LinkFile): string;
+/**
+ * Delete the nearest link file (and its now-empty `.batadata/` dir, if empty).
+ * Returns the path removed, or null if there was nothing to remove. Idempotent.
+ */
+export declare function removeLinkFile(startDir?: string, homeDir?: string): string | null;
+/**
+ * Pure precedence policy for the project id: flag > linked > config > none.
+ * No fs/env access, so the ordering is unit-testable in isolation (mirrors the
+ * `pickTeamId` pattern in api.ts).
+ */
+export declare function pickProjectId(params: {
+    flag?: string;
+    linked?: string | null;
+    config?: string;
+}): {
+    projectId?: string;
+    source: ProjectSource;
+};
+/**
+ * Pure precedence policy for the branch id: flag > linked > none. There is no
+ * config-level default branch, so config isn't a source here.
+ */
+export declare function pickBranchId(params: {
+    flag?: string;
+    linked?: string | null;
+}): {
+    branchId?: string;
+    source: BranchSource;
+};
+/**
+ * Resolve the active project id from all sources in precedence order. `explicit`
+ * is an already-parsed `--project` value (or a positional id) — pass it through
+ * so a flag always wins over a link file or config default.
+ */
+export declare function resolveProjectId(explicit?: string, opts?: {
+    startDir?: string;
+    homeDir?: string;
+}): {
+    projectId?: string;
+    source: ProjectSource;
+};
+/**
+ * Resolve the active branch id from all sources in precedence order. `explicit`
+ * is an already-parsed `--branch` value (id or name); the link file's pinned
+ * branch is the fallback.
+ */
+export declare function resolveBranchId(explicit?: string, opts?: {
+    startDir?: string;
+    homeDir?: string;
+}): {
+    branchId?: string;
+    source: BranchSource;
+};

package/dist/link.js

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { loadConfig } from "./config.js";
+/**
+ * Project linking — Vercel/Neon-style. A linked directory carries its project
+ * (and optionally its branch) in `.batadata/project.json`, so an agent no longer
+ * has to thread `--project <id>` through every invocation.
+ *
+ * ── Resolution precedence (the ONE rule, used everywhere) ─────────────────
+ *   1. an explicit `--project` / `--branch` flag        (per-invocation intent)
+ *   2. `.batadata/project.json`, discovered by walking UP from CWD like git    (per-directory intent)
+ *   3. `defaultProject` in `~/.batarc`                  (per-machine fallback)
+ *
+ * Flags always win, so linking never silently overrides an explicit request.
+ * The precedence itself lives in the pure `pickProjectId` / `pickBranchId`
+ * helpers (unit-testable without fs), and `resolveProjectId` / `resolveBranchId`
+ * compose them with the on-disk sources.
+ */
+export const LINK_DIR = ".batadata";
+export const LINK_FILE = "project.json";
+/** Resolve HOME at call time (env-first) so a redirected HOME — every test does
+ *  this to avoid touching the developer's real home — is honored. Mirrors the
+ *  same rule in config.ts. */
+function defaultHome() {
+    return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+/**
+ * The ordered list of directories to search for a link file, from `startDir`
+ * up to (and including) the ceiling — the user's HOME dir or the filesystem
+ * root, whichever comes first. Exactly how git bounds its repo discovery.
+ *
+ * Pure: no fs, no env — just path math — so the walk-up order is unit-testable
+ * without ever writing to a real HOME.
+ */
+export function linkSearchDirs(startDir, homeDir) {
+    const dirs = [];
+    let dir = path.resolve(startDir);
+    const home = path.resolve(homeDir);
+    // Guard against a pathological loop; the parent === dir root check is the
+    // real terminator.
+    for (let i = 0; i < 4096; i++) {
+        dirs.push(dir);
+        if (dir === home)
+            break; // don't search above HOME
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return dirs;
+}
+/**
+ * Absolute path to the nearest `.batadata/project.json` at or above `startDir`,
+ * or null if none exists within the ceiling. Walks up like git.
+ */
+export function findLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    for (const dir of linkSearchDirs(startDir, homeDir)) {
+        const candidate = path.join(dir, LINK_DIR, LINK_FILE);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Read and parse the nearest link file. Returns its absolute path alongside the
+ * parsed contents, or null if there's no (valid) link file. A malformed file is
+ * treated as absent rather than throwing, so a stray/corrupt file can't wedge
+ * every command.
+ */
+export function readLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    const filePath = findLinkFile(startDir, homeDir);
+    if (!filePath)
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.projectId !== "string" || !parsed.projectId) {
+            return null;
+        }
+        return { path: filePath, link: parsed };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write `.batadata/project.json` inside `dir` (creating `.batadata/` if needed)
+ * and return the absolute path written. `branchId` is normalized to null when
+ * absent so the file shape is stable.
+ */
+export function writeLinkFile(dir, link) {
+    const linkDir = path.join(path.resolve(dir), LINK_DIR);
+    fs.mkdirSync(linkDir, { recursive: true });
+    const filePath = path.join(linkDir, LINK_FILE);
+    const body = {
+        projectId: link.projectId,
+        branchId: link.branchId ?? null,
+    };
+    fs.writeFileSync(filePath, JSON.stringify(body, null, 2) + "\n", "utf-8");
+    return filePath;
+}
+/**
+ * Delete the nearest link file (and its now-empty `.batadata/` dir, if empty).
+ * Returns the path removed, or null if there was nothing to remove. Idempotent.
+ */
+export function removeLinkFile(startDir = process.cwd(), homeDir = defaultHome()) {
+    const filePath = findLinkFile(startDir, homeDir);
+    if (!filePath)
+        return null;
+    try {
+        fs.unlinkSync(filePath);
+        // Best-effort cleanup of an empty .batadata dir.
+        const linkDir = path.dirname(filePath);
+        if (path.basename(linkDir) === LINK_DIR && fs.readdirSync(linkDir).length === 0) {
+            fs.rmdirSync(linkDir);
+        }
+    }
+    catch {
+        // Already gone / racing removal — unlink is best-effort.
+    }
+    return filePath;
+}
+/**
+ * Pure precedence policy for the project id: flag > linked > config > none.
+ * No fs/env access, so the ordering is unit-testable in isolation (mirrors the
+ * `pickTeamId` pattern in api.ts).
+ */
+export function pickProjectId(params) {
+    if (params.flag)
+        return { projectId: params.flag, source: "flag" };
+    if (params.linked)
+        return { projectId: params.linked, source: "link" };
+    if (params.config)
+        return { projectId: params.config, source: "config" };
+    return { source: "none" };
+}
+/**
+ * Pure precedence policy for the branch id: flag > linked > none. There is no
+ * config-level default branch, so config isn't a source here.
+ */
+export function pickBranchId(params) {
+    if (params.flag)
+        return { branchId: params.flag, source: "flag" };
+    if (params.linked)
+        return { branchId: params.linked, source: "link" };
+    return { source: "none" };
+}
+/**
+ * Resolve the active project id from all sources in precedence order. `explicit`
+ * is an already-parsed `--project` value (or a positional id) — pass it through
+ * so a flag always wins over a link file or config default.
+ */
+export function resolveProjectId(explicit, opts = {}) {
+    const linked = readLinkFile(opts.startDir, opts.homeDir)?.link.projectId ?? null;
+    return pickProjectId({
+        flag: explicit,
+        linked,
+        config: loadConfig().defaultProject,
+    });
+}
+/**
+ * Resolve the active branch id from all sources in precedence order. `explicit`
+ * is an already-parsed `--branch` value (id or name); the link file's pinned
+ * branch is the fallback.
+ */
+export function resolveBranchId(explicit, opts = {}) {
+    const linked = readLinkFile(opts.startDir, opts.homeDir)?.link.branchId ?? null;
+    return pickBranchId({ flag: explicit, linked });
+}

package/package.json

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