db-drifter-cli 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# dbd — db_drifter CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plain ESM JavaScript (runs on **Node ≥ 18** or **Bun**). No build step.
+
+## Install
+
+```sh
+npm i -g db-drifter-cli     # gives you the `dbd` command
+# or, per-project / one-off:
+npx db-drifter-cli --help
+
+# from a checkout (no install):
+node cli/src/index.js --help
+```
+
+## Quick start
+
+```sh
+dbd auth                    # browser sign-in; auto-selects your workspace (prompts if you have several)
+
+dbd use staging             # pick the source DB (auto if the workspace has just one)
+
+dbd branch pr-42            # create an isolated, writable database and print its DSN
+# postgresql://you@wire.db-drifter.com/ws1.staging.pr-42?sslmode=require
+
+psql "$(dbd conn staging --branch pr-42)"   # …or any Postgres client / your app
+dbd branch rm pr-42                         # throw it away
+```
+
+`dbd auth` auto-selects your workspace when you have one (and prompts a
+radio list when you have several), then remembers a single source DB.
+`dbd branch <name>` creates an isolated overlay on that source DB and prints its
+connection string — hand it straight to your app, tests or an agent. Run
+`dbd add-source-db <name> <url>` first if you're an admin connecting a database.
+
+```sh
+dbd conn staging                           # the `main` branch DSN
+dbd conn staging --branch pr-42
+dbd sql staging "select count(*) from orders"
+dbd branch ls
+dbd use staging                            # default source DB for `dbd branch`
+```
+
+## All commands
+
+```
+auth [--username U] [--password P] [--token T]   log in (device flow by default)
+logout | whoami
+use <source-db>                                  set the default source DB
+
+add-source-db <name> <url>                          connect a source DB (admin)
+source-db ls | add <name> <url> | rm <name> | reset <name>
+
+branch <name> [--source-db S] [--ttl-days N]        create a branch, print its DSN
+branch ls | rm <name>
+
+conn <source-db> [--branch <name>]               print a connection string
+sql  <source-db> [--branch <name>] <query>       run SQL over the wire
+workspace ls | use <id>
+token ls | create <name> [--scopes a,b] [--workspace-id N] [--expires-in-days N] | rm <id>
+```
+
+## Configuration
+
+- Credentials: `~/.config/db_drifter/config.json` (mode 0600). The stored
+  password is reused by `dbd sql`; the token (or `DBDRIFTER_TOKEN`) is used by
+  every other call.
+- Environment: `DBDRIFTER_API_URL` (default `https://app.db-drifter.com`),
+  `DBDRIFTER_TOKEN` (wins over the stored token), `XDG_CONFIG_HOME`.
+- There is no `listen` tunnel: the wire host is reachable, so `dbd conn` prints
+  a DSN you can give any Postgres client.
+
+## Notes
+
+- `dbd sql` uses the [`postgres`](https://github.com/porsager/postgres) driver
+  (`ssl: require`). It works for everyday queries; a few exotic column types
+  aren't parsed by every driver — use `dbd conn` with `psql` if you hit one.
+- `dbd token create <name> --scopes branch` prints just the secret, so
+  `dbd token create ci --scopes branch > token.txt` works.
+
+## CI: a database branch per pull request
+
+1. Create a branch-scoped token once:
+
+   ```sh
+   dbd token create ci --scopes branch
+   ```
+
+2. Copy `examples/github-actions-preview.yml` into your app repo as
+   `.github/workflows/db-drifter-preview.yml`, and set `DBDRIFTER_API_URL`,
+   `DBDRIFTER_SOURCE_DB` (vars) and `DBDRIFTER_TOKEN` (secret).
+
+The workflow creates (or reuses) a branch named `pr-<number>`, exports its DSN
+as `DATABASE_URL`, and deletes it on PR close. Ephemeral branches also carry a
+TTL; the server's nightly cleanup removes expired branches and drops their
+overlays.
+
+The token can create/delete branches (scope `branch`) but not add source DBs (scope `admin`) — CI can provision its own database without being able
+to widen access.
+
+## Releasing
+
+The package lives in `cli/` and is published as **`db-drifter-cli`** (it installs
+the `dbd` command). Publishing needs your npm 2FA:
+
+```sh
+cd cli
+npm version patch            # or minor / major — bumps package.json + tags
+npm publish --otp=<6-digit code>
+git push --follow-tags
+```
+
+`publishConfig` pins the public registry and `access: public`, so no extra flags
+are needed. After publishing, `latest` follows the highest version — check with:
+
+```sh
+npm view db-drifter-cli dist-tags
+```
+
+Sanity-check the tarball before releasing (it should include `src/index.js`):
+
+```sh
+npm pack --dry-run
+```
+
+If you ever need to publish from a repo checkout before npm has it:
+
+```sh
+npm i -g ./cli          # installs `dbd` from the local folder
+node ./cli/src/index.js --help
+```

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "db-drifter-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "db-drifter-cli",
+	"version": "0.3.1",
+	"description": "db_drifter command-line client — connect a source database, create isolated branches, print connection strings.",
+	"type": "module",
+	"bin": { "dbd": "src/index.js" },
+	"files": ["src", "README.md"],
+	"engines": { "node": ">=18" },
+	"keywords": [
+		"db_drifter",
+		"dbd",
+		"postgres",
+		"postgresql",
+		"database",
+		"database-branching",
+		"cli"
+	],
+	"license": "MIT",
+	"homepage": "https://db-drifter.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/M-Dahab/db_drifter.git",
+		"directory": "cli"
+	},
+	"dependencies": {
+		"postgres": "^3.4.9"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"start": "node src/index.js",
+		"build": "bun build --compile --outfile dbd src/index.js"
+	}
+}

package/src/index.js

@@ -0,0 +1,655 @@
+#!/usr/bin/env node
+/**
+ * dbd — the db_drifter command-line client.
+ *
+ * Plain ESM JavaScript so it runs anywhere: `npx dbd`, `npm i -g dbd`, or
+ * `bun src/index.js`. No build step. The only dependency (`postgres`) is loaded
+ * lazily, and only by `dbd sql`.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_API = "https://app.db-drifter.com";
+const VERSION = "0.3.1";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+function configPath() {
+	const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+	return join(base, "db_drifter", "config.json");
+}
+
+function loadConfig() {
+	try {
+		return { api_url: DEFAULT_API, ...JSON.parse(readFileSync(configPath(), "utf8")) };
+	} catch {
+		return { api_url: DEFAULT_API };
+	}
+}
+
+function saveConfig(cfg) {
+	const p = configPath();
+	mkdirSync(dirname(p), { recursive: true });
+	writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+	try {
+		chmodSync(p, 0o600);
+	} catch {
+		/* best effort */
+	}
+}
+
+/** `DBDRIFTER_TOKEN` wins over the stored token. */
+function tokenOf(cfg) {
+	const env = (process.env.DBDRIFTER_TOKEN || "").trim();
+	return env.length > 0 ? env : cfg.token || null;
+}
+
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+
+class Api {
+	constructor(base, cookie, token) {
+		this.base = base;
+		this.cookie = cookie;
+		this.token = token;
+	}
+
+	headers(hasBody) {
+		const h = { "user-agent": `dbd/${VERSION}` };
+		if (hasBody) h["content-type"] = "application/json";
+		if (this.token) h["authorization"] = `Bearer ${this.token}`;
+		else if (this.cookie) h["cookie"] = this.cookie;
+		return h;
+	}
+
+	async req(method, path, body) {
+		const res = await fetch(this.base + path, {
+			method,
+			headers: this.headers(body !== undefined),
+			body: body === undefined ? undefined : JSON.stringify(body)
+		});
+		const text = await res.text();
+		let val = null;
+		try {
+			val = text ? JSON.parse(text) : null;
+		} catch {
+			val = null;
+		}
+		if (!res.ok) throw new Error(`${(val && val.error) || text || res.statusText} (${res.status})`);
+		return val;
+	}
+
+	get(p) {
+		return this.req("GET", p);
+	}
+	post(p, b) {
+		return this.req("POST", p, b ?? {});
+	}
+	del(p) {
+		return this.req("DELETE", p);
+	}
+}
+
+function apiFor(cfg) {
+	return new Api(cfg.api_url, cfg.cookie, tokenOf(cfg));
+}
+
+async function login(base, username, password) {
+	const res = await fetch(`${base.replace(/\/$/, "")}/api/auth/login`, {
+		method: "POST",
+		headers: { "content-type": "application/json", "user-agent": `dbd/${VERSION}` },
+		body: JSON.stringify({ username, password })
+	});
+	const text = await res.text();
+	if (!res.ok) {
+		let msg = text;
+		try {
+			msg = JSON.parse(text).error ?? text;
+		} catch {
+			/* ignore */
+		}
+		throw new Error(`login failed: ${msg} (${res.status})`);
+	}
+	const cookie = res.headers.get("set-cookie")?.split(";")[0];
+	if (!cookie) throw new Error("login succeeded but no session cookie was returned");
+	return cookie;
+}
+
+async function resolveWorkspace(cfg, api) {
+	if (cfg.workspace_id) return cfg.workspace_id;
+	const v = await api.get("/api/workspaces");
+	const id = v?.workspaces?.[0]?.id;
+	if (!id) throw new Error("no workspace found; run `dbd workspace ls`");
+	return id;
+}
+
+async function workspaceDetail(api, ws) {
+	return api.get(`/api/workspaces/${ws}`);
+}
+
+async function findSourceDb(api, ws, name) {
+	const v = await workspaceDetail(api, ws);
+	const found = (v?.source_dbs ?? []).find((s) => s.name === name);
+	if (!found) throw new Error(`source DB "${name}" not found`);
+	return found;
+}
+
+/** Resolve which source_db a bare `branch`/`use` refers to. */
+async function resolveSourceDb(cfg, api, ws, explicit) {
+	if (explicit) return explicit;
+	if (cfg.source_db) return cfg.source_db;
+	const v = await workspaceDetail(api, ws);
+	const names = (v?.source_dbs ?? []).map((s) => s.name);
+	if (names.length === 1) return names[0];
+	if (names.length === 0) throw new Error("no source DB yet; run `dbd add-source-db <name> <url>`");
+	const sds = v.source_dbs;
+	const picked = await chooseRadio("Select a source DB:", sds, (s) => s.name);
+	if (picked) {
+		cfg.source_db = picked.name;
+		saveConfig(cfg);
+		return picked.name;
+	}
+	throw new Error(`which source DB? pass --source-db <name> (available: ${names.join(", ")})`);
+}
+
+async function connFor(api, ws, sourceDb, branch) {
+	const sd = await findSourceDb(api, ws, sourceDb);
+	if (!branch) return sd.conn;
+	const b = (sd.branches ?? []).find((x) => x.name === branch);
+	if (!b) throw new Error(`branch "${branch}" not found on "${sourceDb}"`);
+	return b.conn;
+}
+
+const enc = (s) => encodeURIComponent(s);
+
+/** The source DB flag: `--source-db` (with `--source` accepted for back-compat). */
+const sourceFlag = (args) => str(args.flags["source-db"]) ?? sourceFlag(args);
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+	const out = { pos: [], flags: {} };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a.startsWith("--")) {
+			const eq = a.indexOf("=");
+			if (eq > -1) out.flags[a.slice(2, eq)] = a.slice(eq + 1);
+			else {
+				const key = a.slice(2);
+				const next = argv[i + 1];
+				if (next !== undefined && !next.startsWith("--")) {
+					out.flags[key] = next;
+					i++;
+				} else out.flags[key] = true;
+			}
+		} else out.pos.push(a);
+	}
+	return out;
+}
+
+const str = (v) => (typeof v === "string" ? v : undefined);
+const num = (v) => {
+	const s = str(v);
+	if (s === undefined) return undefined;
+	const n = Number(s);
+	return Number.isFinite(n) ? n : undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Hidden password prompt
+// ---------------------------------------------------------------------------
+
+async function promptPassword(prompt) {
+	process.stdout.write(prompt);
+	const input = process.stdin;
+	const canRaw = typeof input.setRawMode === "function";
+	if (canRaw) input.setRawMode(true);
+	input.resume();
+	return await new Promise((resolve) => {
+		let buf = "";
+		const onData = (chunk) => {
+			for (const ch of chunk.toString("utf8")) {
+				if (ch === "\r" || ch === "\n") {
+					input.off("data", onData);
+					if (canRaw) input.setRawMode(false);
+					input.pause();
+					process.stdout.write("\n");
+					resolve(buf);
+					return;
+				}
+				if (ch === "\u0003") process.exit(130);
+				if (ch === "\u007f") buf = buf.slice(0, -1);
+				else buf += ch;
+			}
+		};
+		input.on("data", onData);
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Interactive selection
+// ---------------------------------------------------------------------------
+
+const isTTY = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+/**
+ * Radio-style selector: ↑/↓ (or j/k, or a number) then Enter. Returns the
+ * chosen item, or null when there is no TTY to prompt on.
+ */
+async function chooseRadio(question, items, label) {
+	if (!isTTY() || items.length === 0) return null;
+	let idx = 0;
+	const draw = (first) => {
+		if (!first) process.stdout.write(`\x1b[${items.length}A`);
+		for (let i = 0; i < items.length; i++) {
+			const mark = i === idx ? "❯" : " ";
+			process.stdout.write(`\x1b[K ${mark} ${label(items[i], i)}\n`);
+		}
+	};
+	process.stdout.write(`${question}\n`);
+	draw(true);
+	const input = process.stdin;
+	const wasRaw = input.isRaw;
+	input.setRawMode(true);
+	input.resume();
+	return await new Promise((resolve) => {
+		const done = (value) => {
+			input.off("data", onData);
+			input.setRawMode(wasRaw ?? false);
+			input.pause();
+			process.stdout.write("\n");
+			resolve(value);
+		};
+		const onData = (chunk) => {
+			const s = chunk.toString("utf8");
+			if (s === "\u0003") {
+				input.setRawMode(wasRaw ?? false);
+				process.exit(130);
+			}
+			if (s === "\r" || s === "\n") return done(items[idx]);
+			if (s === "\x1b[A" || s === "k") {
+				idx = (idx - 1 + items.length) % items.length;
+				return draw(false);
+			}
+			if (s === "\x1b[B" || s === "j") {
+				idx = (idx + 1) % items.length;
+				return draw(false);
+			}
+			const n = Number(s);
+			if (Number.isInteger(n) && n >= 1 && n <= items.length) {
+				idx = n - 1;
+				draw(false);
+			}
+		};
+		input.on("data", onData);
+	});
+}
+
+/**
+ * After login, pick a workspace (auto if there is only one, otherwise prompt)
+ * and remember a single source DB when the workspace has exactly one.
+ */
+async function settleContext(cfg, api) {
+	try {
+		const v = await api.get("/api/workspaces");
+		const list = v?.workspaces ?? [];
+		let ws = cfg.workspace_id;
+		if (!ws) {
+			if (list.length === 1) {
+				ws = list[0].id;
+				console.log(`using workspace ${ws} (${list[0].name})`);
+			} else if (list.length > 1) {
+				const picked = await chooseRadio("Select a workspace:", list, (w) => `${w.name}  (${w.role})`);
+				if (picked) {
+					ws = picked.id;
+					console.log(`using workspace ${ws} (${picked.name})`);
+				}
+			}
+			if (ws) {
+				cfg.workspace_id = ws;
+				saveConfig(cfg);
+			}
+		}
+		if (!ws || cfg.source_db) return;
+		const sds = (await workspaceDetail(api, ws))?.source_dbs ?? [];
+		if (sds.length === 1) {
+			cfg.source_db = sds[0].name;
+			saveConfig(cfg);
+			console.log(`using source DB "${sds[0].name}"`);
+		}
+	} catch {
+		/* best effort — never fail a login over this */
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function cmdAuth(cfg, args) {
+	const base = cfg.api_url;
+	const token = str(args.flags.token);
+	if (token) {
+		cfg.token = token;
+		cfg.cookie = null;
+		saveConfig(cfg);
+		console.log(`stored API token for ${base}`);
+		await settleContext(cfg, apiFor(cfg));
+		return;
+	}
+	const password = str(args.flags.password);
+	if (password === undefined) {
+		// Browser device flow.
+		const anon = new Api(base);
+		const start = await anon.post("/api/auth/device/start");
+		const device = start?.device_code ?? "";
+		const code = start?.user_code ?? "";
+		const uri = start?.verification_uri ?? base;
+		if (!device) throw new Error("device flow unavailable on this server");
+		console.log(`Open ${uri} and enter the code:  ${code}`);
+		for (let i = 0; i < 100; i++) {
+			await sleep(3000);
+			const r = await anon.post("/api/auth/device/poll", { device_code: device });
+			if (r?.status === "approved") {
+				cfg.token = r.secret;
+				cfg.cookie = null;
+				saveConfig(cfg);
+				console.log("logged in — token stored");
+				await settleContext(cfg, apiFor(cfg));
+				return;
+			}
+			if (r?.status !== "pending") throw new Error(`device login failed: ${JSON.stringify(r)}`);
+		}
+		throw new Error("device code expired — run `dbd auth` again");
+	}
+	const username = str(args.flags.username) ?? cfg.username;
+	if (!username) throw new Error("--username is required for password login");
+	const cookie = await login(base, username, password);
+	cfg.cookie = cookie;
+	cfg.token = null;
+	cfg.username = username;
+	cfg.password = password;
+	saveConfig(cfg);
+	console.log(`logged in as ${username} (${base})`);
+	await settleContext(cfg, apiFor(cfg));
+}
+
+async function cmdWhoami(cfg) {
+	const v = await apiFor(cfg).get("/api/me");
+	const u = v?.user ?? {};
+	console.log(
+		`${u.username ?? "?"} <${u.email ?? "?"}> plan=${u.plan ?? "?"} super=${u.is_super ?? false}`
+	);
+}
+
+async function cmdWorkspace(cfg, args) {
+	const api = apiFor(cfg);
+	const sub = args.pos[0];
+	if (sub === "ls" || sub === undefined) {
+		const v = await api.get("/api/workspaces");
+		for (const w of v?.workspaces ?? []) {
+			const mark = w.id === cfg.workspace_id ? "*" : " ";
+			console.log(`${mark} ${String(w.id).padStart(3)}  ${(w.name ?? "").padEnd(28)} ${w.role ?? ""}`);
+		}
+		return;
+	}
+	if (sub === "use") {
+		const id = Number(args.pos[1]);
+		if (!Number.isFinite(id)) throw new Error("usage: dbd workspace use <id>");
+		cfg.workspace_id = id;
+		saveConfig(cfg);
+		console.log(`current workspace: ${id}`);
+		return;
+	}
+	throw new Error("usage: dbd workspace ls | use <id>");
+}
+
+/** `dbd source-db …` and the `dbd add-source-db` / `dbd use` aliases. */
+async function cmdSourceDb(cfg, args, verb) {
+	const api = apiFor(cfg);
+	const ws = await resolveWorkspace(cfg, api);
+	const sub = verb ?? args.pos[0];
+
+	if (sub === "ls" || sub === undefined) {
+		const v = await workspaceDetail(api, ws);
+		for (const s of v?.source_dbs ?? []) {
+			const n = (s.branches ?? []).length;
+			console.log(`${(s.name ?? "").padEnd(28)} ${n} branch(es)  ${s.conn ?? ""}`);
+		}
+		return;
+	}
+	if (sub === "add") {
+		// `dbd add-source-db <name> <url>` or `dbd source-db add <name> <url>`
+		const name = verb ? args.pos[0] : args.pos[1];
+		const url = verb ? args.pos[1] : args.pos[2];
+		await api.post(`/api/workspaces/${ws}/source-dbs`, { name, url });
+		cfg.source_db = name;
+		saveConfig(cfg);
+		console.log(`source DB "${name}" added (with a \`main\` branch)`);
+		return;
+	}
+	if (sub === "rm") {
+		const name = verb ? args.pos[0] : args.pos[1];
+		await api.del(`/api/workspaces/${ws}/source-dbs/${enc(name)}`);
+		console.log(`source DB "${name}" deleted`);
+		return;
+	}
+	if (sub === "reset") {
+		const name = verb ? args.pos[0] : args.pos[1];
+		await api.post(`/api/workspaces/${ws}/source-dbs/${enc(name)}/reset`);
+		console.log(`reset the \`main\` overlay of "${name}"`);
+		return;
+	}
+	throw new Error("usage: dbd source-db ls | add <name> <url> | rm <name> | reset <name>");
+}
+
+/** `dbd use <source-db>` — set the default source DB. */
+async function cmdUse(cfg, args) {
+	const api = apiFor(cfg);
+	const ws = await resolveWorkspace(cfg, api);
+	let name = args.pos[0];
+	if (!name) {
+		const sds = (await workspaceDetail(api, ws))?.source_dbs ?? [];
+		if (sds.length === 1) name = sds[0].name;
+		else if (sds.length > 1) {
+			name = (await chooseRadio("Select a source DB:", sds, (s) => s.name))?.name;
+		}
+	}
+	if (!name) throw new Error("usage: dbd use <source-db>");
+	await findSourceDb(api, ws, name); // validate
+	cfg.source_db = name;
+	saveConfig(cfg);
+	console.log(`current source DB: ${name}`);
+}
+
+async function cmdBranch(cfg, args) {
+	const api = apiFor(cfg);
+	const ws = await resolveWorkspace(cfg, api);
+	const sub = args.pos[0];
+
+	// `dbd branch ls`
+	if (sub === "ls") {
+		const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
+		const sd = await findSourceDb(api, ws, src);
+		for (const b of sd.branches ?? []) {
+			console.log(
+				`${(b.name ?? "").padEnd(28)} ${(b.protected ? "default" : "branch").padEnd(8)} ${b.conn ?? ""}`
+			);
+		}
+		return;
+	}
+	// `dbd branch rm <name>`
+	if (sub === "rm") {
+		const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
+		await api.del(`/api/workspaces/${ws}/source-dbs/${enc(src)}/branches/${enc(args.pos[1])}`);
+		console.log(`branch "${args.pos[1]}" deleted`);
+		return;
+	}
+	// `dbd branch create <name>` or simply `dbd branch <name>` → print the DSN.
+	const explicitCreate = sub === "create";
+	const name = explicitCreate ? args.pos[1] : args.pos[0];
+	if (!name) throw new Error("usage: dbd branch <name>  (or: dbd branch ls | rm <name>)");
+	const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
+	const body = { name };
+	const ttl = num(args.flags["ttl-days"]);
+	if (ttl !== undefined) body.ttl_days = ttl;
+	await api.post(`/api/workspaces/${ws}/source-dbs/${enc(src)}/branches`, body);
+	console.log(await connFor(api, ws, src, name));
+}
+
+async function cmdToken(cfg, args) {
+	const api = apiFor(cfg);
+	const sub = args.pos[0];
+	if (sub === "ls" || sub === undefined) {
+		const v = await api.get("/api/tokens");
+		for (const t of v?.tokens ?? []) {
+			console.log(
+				`${String(t.id).padStart(3)}  ${(t.name ?? "").padEnd(24)} [${(t.scopes ?? []).join(",")}]  ws=${t.workspace_id ?? "-"}  expires=${t.expires_at ?? "never"}`
+			);
+		}
+		return;
+	}
+	if (sub === "create") {
+		const scopes = (str(args.flags.scopes) ?? "read").split(",").map((s) => s.trim());
+		const body = { name: args.pos[1], scopes };
+		const wsId = num(args.flags["workspace-id"]);
+		if (wsId !== undefined) body.workspace_id = wsId;
+		const days = num(args.flags["expires-in-days"]);
+		if (days !== undefined) body.expires_in_days = days;
+		const v = await api.post("/api/tokens", body);
+		console.log(v?.secret ?? ""); // only the secret, so it can be piped
+		return;
+	}
+	if (sub === "rm") {
+		await api.del(`/api/tokens/${Number(args.pos[1])}`);
+		console.log(`token ${args.pos[1]} revoked`);
+		return;
+	}
+	throw new Error("usage: dbd token ls | create <name> [--scopes a,b] | rm <id>");
+}
+
+/** Run SQL over the wire (lazily loads the `postgres` driver). */
+async function runSql(dsn, username, password, query) {
+	const url = dsn.replace(`://${username}@`, `://${username}:${encodeURIComponent(password)}@`);
+	const { default: postgres } = await import("postgres");
+	const sql = postgres(url, { ssl: "require", max: 1, idle_timeout: 2, connect_timeout: 15 });
+	try {
+		const rows = await sql.unsafe(query);
+		if (Array.isArray(rows)) {
+			for (const row of rows) console.log(Object.values(row).map(String).join("\t"));
+		}
+	} finally {
+		await sql.end({ timeout: 2 });
+	}
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+function usage() {
+	console.log(`dbd ${VERSION} — db_drifter CLI
+
+Usage: dbd [--api-url <url>] <command> [args]
+
+  auth [--username U] [--password P] [--token T]   log in (device flow by default)
+  whoami
+  use <source-db>                                  set the default source DB
+
+  add-source-db <name> <url>                       connect a source DB (admin)
+  source-db ls | add <name> <url> | rm <name> | reset <name>
+
+  branch <name> [--source-db S] [--ttl-days N]     create a branch, print its DSN
+  branch ls | rm <name>
+
+  conn <source-db> [--branch <name>]               print a connection string
+  sql  <source-db> [--branch <name>] <query>       run SQL over the wire
+  workspace ls | use <id>
+  token ls | create <name> [--scopes a,b] | rm <id>
+
+Environment: DBDRIFTER_API_URL, DBDRIFTER_TOKEN
+Config:      ~/.config/db_drifter/config.json (0600)`);
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const cfg = loadConfig();
+	const apiUrl = str(args.flags["api-url"]) ?? process.env.DBDRIFTER_API_URL ?? cfg.api_url;
+	cfg.api_url = apiUrl.replace(/\/$/, "");
+
+	if (args.pos.length === 0 || args.flags.help || args.flags.h) {
+		usage();
+		return;
+	}
+
+	const [cmd] = args.pos;
+	const rest = { pos: args.pos.slice(1), flags: args.flags };
+	const api = apiFor(cfg);
+
+	switch (cmd) {
+		case "auth":
+		case "login":
+			await cmdAuth(cfg, args);
+			break;
+		case "logout":
+			cfg.cookie = null;
+			cfg.token = null;
+			cfg.password = null;
+			saveConfig(cfg);
+			console.log("logged out");
+			break;
+		case "whoami":
+			await cmdWhoami(cfg);
+			break;
+		case "use":
+			await cmdUse(cfg, rest);
+			break;
+		case "workspace":
+			await cmdWorkspace(cfg, rest);
+			break;
+		case "add-source-db":
+		case "add-source":
+			await cmdSourceDb(cfg, rest, "add");
+			break;
+		case "source-db":
+			await cmdSourceDb(cfg, rest);
+			break;
+		case "branch":
+			await cmdBranch(cfg, rest);
+			break;
+		case "token":
+			await cmdToken(cfg, rest);
+			break;
+		case "conn": {
+			const ws = await resolveWorkspace(cfg, api);
+			console.log(await connFor(api, ws, rest.pos[0], str(args.flags.branch)));
+			break;
+		}
+		case "sql": {
+			const ws = await resolveWorkspace(cfg, api);
+			const dsn = await connFor(api, ws, rest.pos[0], str(args.flags.branch));
+			if (!cfg.username || !cfg.password) throw new Error("not logged in; run `dbd auth`");
+			const query = rest.pos.slice(1).join(" ");
+			if (!query.trim()) throw new Error("no SQL provided");
+			await runSql(dsn, cfg.username, cfg.password, query);
+			break;
+		}
+		default:
+			usage();
+			process.exitCode = 2;
+	}
+}
+
+main().catch((err) => {
+	console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+	process.exitCode = 1;
+});