@canner-ca/cli 0.4.0 → 0.5.0

package/src/cli.mjs

@@ -1,1257 +1,2543 @@
-#!/usr/bin/env node
-// @canner-ca/cli — canner deploy CLI.
-//
-// Single-file ESM. Zero transitive deps beyond `tar` (one MIT package).
-// Works in any terminal (macOS / Linux / Windows / Cursor). Authenticates
-// with a `cnr_*` API token from the dashboard; deploys by tarring the
-// current directory and POSTing to the same /projects/:slug/upload
-// endpoint the dashboard's drag-drop uses.
-//
-// Commands:
-//   canner login                        store an API token
-//   canner logout                       remove the stored token from this machine
-//   canner whoami                       show the account this CLI is signed in as
-//   canner init [--slug X]              create a project, write canner.json
-//   canner deploy [path] [--slug X] [--follow]
-//                                       tar + upload + optionally stream the build log
-//
-// Exit codes: 0 on success, 1 on user/network/auth error, 2 on bad CLI
-// invocation. `canner deploy --follow` exits with the build's success
-// (0 = live, 1 = failed) so it composes with CI pipelines.
-
-import { existsSync, openAsBlob } from 'node:fs';
-import { mkdir, readFile, writeFile, stat, chmod, unlink } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
-import { join, resolve, basename } from 'node:path';
-import { createInterface } from 'node:readline/promises';
-import { randomUUID } from 'node:crypto';
-import { stdin as input, stdout as output } from 'node:process';
-import { create as tarCreate } from 'tar';
-
-const VERSION = '0.4.0';
-const DEFAULT_API_BASE = 'https://api.canner.ca';
-const CONFIG_DIR = join(homedir(), '.canner');
-const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
-const PROJECT_CONFIG_FILE = 'canner.json';
-
-// Stuff we never ship even if the user doesn't have a .cannerignore. These
-// are "build noise" — heavy directories that the server-side build pipeline
-// rebuilds, plus OS / IDE droppings.
-const HARD_EXCLUDES = new Set([
-  'node_modules',
-  '.git',
-  '.next',
-  '.nuxt',
-  '.turbo',
-  '.vercel',
-  '.svelte-kit',
-  '.DS_Store',
-  'Thumbs.db',
-]);
-
-// ---------------------------------------------------------------------------
-// Tiny ANSI styling. No chalk dep — eight inlined escape codes cover us.
-// Disabled when stdout isn't a TTY (CI, redirected to file).
-// ---------------------------------------------------------------------------
-const isTTY = output.isTTY === true;
-const c = (code) => (s) => isTTY ? `\x1b[${code}m${s}\x1b[0m` : String(s);
-const bold = c('1');
-const dim = c('2');
-const red = c('31');
-const green = c('32');
-const yellow = c('33');
-const cyan = c('36');
-
-// Machine-readable output mode (`--json`). Set once in main from argv. In JSON
-// mode every command prints a single JSON value to stdout and nothing else, so
-// the output pipes straight into `jq` or an agent; errors become
-// {"error":"..."} on stderr with a non-zero exit. Human-facing helpers
-// (info/muted) go silent so they can't corrupt the JSON stream.
-let JSON_MODE = false;
-
-function emitJSON(value) {
-  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
-}
-
-function die(msg, code = 1) {
-  if (JSON_MODE) {
-    process.stderr.write(JSON.stringify({ error: String(msg) }) + '\n');
-  } else {
-    process.stderr.write(`${red('error:')} ${msg}\n`);
-  }
-  process.exit(code);
-}
-
-function info(msg) {
-  if (JSON_MODE) return;
-  process.stdout.write(`${msg}\n`);
-}
-
-function muted(msg) {
-  if (JSON_MODE) return;
-  process.stdout.write(`${dim(msg)}\n`);
-}
-
-// ---------------------------------------------------------------------------
-// Credential storage (~/.canner/credentials)
-//
-// JSON with shape: { api_base: string, token: string }. Mode 0600 on
-// platforms that respect it. We default api_base to https://api.canner.ca
-// but allow override via CANNER_API_BASE env var (handy for self-host
-// later, and for local dev pointing at localhost:4001 via tunnel).
-// ---------------------------------------------------------------------------
-async function loadCredentials() {
-  try {
-    const raw = await readFile(CREDENTIALS_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    return {
-      apiBase: process.env.CANNER_API_BASE || parsed.api_base || DEFAULT_API_BASE,
-      token: parsed.token,
-    };
-  } catch {
-    return {
-      apiBase: process.env.CANNER_API_BASE || DEFAULT_API_BASE,
-      token: process.env.CANNER_TOKEN || null,
-    };
-  }
-}
-
-async function saveCredentials({ apiBase, token }) {
-  await mkdir(CONFIG_DIR, { recursive: true });
-  await writeFile(
-    CREDENTIALS_PATH,
-    JSON.stringify({ api_base: apiBase, token }, null, 2),
-    { mode: 0o600 }
-  );
-  try {
-    await chmod(CREDENTIALS_PATH, 0o600);
-  } catch {
-    // Windows doesn't honor Unix mode; fine.
-  }
-}
-
-// ---------------------------------------------------------------------------
-// HTTP helpers. fetch is built-in on Node 20+.
-// ---------------------------------------------------------------------------
-async function apiRequest(creds, method, path, options = {}) {
-  if (!creds.token) {
-    die("not signed in. Run `canner login` first.");
-  }
-  const url = `${creds.apiBase}${path}`;
-  const headers = {
-    Authorization: `Bearer ${creds.token}`,
-    Accept: 'application/json',
-    ...(options.headers ?? {}),
-  };
-  const init = {
-    method,
-    headers,
-    body: options.body,
-    // Long-lived ops (deploy upload, SSE) shouldn't time out at the
-    // fetch level. Per-call options.signal can still abort.
-  };
-  if (options.signal) init.signal = options.signal;
-  const res = await fetch(url, init).catch((err) => {
-    die(`network: ${err.message}`);
-  });
-  if (!res.ok) {
-    let body = null;
-    try { body = await res.json(); } catch { /* not JSON */ }
-    if (res.status === 401) {
-      die("authentication failed. Your token may be revoked. Run `canner login` again.");
-    }
-    if (res.status === 403) {
-      die("forbidden. The API token doesn't have access to this resource.");
-    }
-    const msg = body?.message || body?.error || `${res.status} ${res.statusText}`;
-    die(`${method} ${path}: ${msg}`);
-  }
-  return res;
-}
-
-async function apiJSON(creds, method, path, body) {
-  const init = {};
-  if (body !== undefined) {
-    init.headers = { 'Content-Type': 'application/json' };
-    init.body = JSON.stringify(body);
-  }
-  const res = await apiRequest(creds, method, path, init);
-  if (res.status === 204) return null;
-  return res.json();
-}
-
-// ---------------------------------------------------------------------------
-// .cannerignore parsing — simple line-based excludes.
-// One pattern per line. '#' comments, blank lines ignored. Supports:
-//   - exact-basename match anywhere ('build', 'coverage')
-//   - trailing-slash directory match ('logs/' matches only directories)
-//   - leading '/' anchors to project root ('/dist' = only the root dist/)
-//   - basic glob: '*' inside a single path segment
-// No negation ('!') support — keep the surface tight.
-// ---------------------------------------------------------------------------
-function parseIgnoreFile(text) {
-  const patterns = [];
-  for (const lineRaw of text.split('\n')) {
-    const line = lineRaw.trim();
-    if (!line || line.startsWith('#')) continue;
-    const dirOnly = line.endsWith('/');
-    const anchored = line.startsWith('/');
-    const body = line.replace(/^\/+/, '').replace(/\/+$/, '');
-    const glob = body.includes('*');
-    patterns.push({ pattern: body, dirOnly, anchored, glob });
-  }
-  return patterns;
-}
-
-function matchesIgnore(relPath, isDir, patterns) {
-  // relPath is POSIX-normalized, no leading slash, no './'.
-  const parts = relPath.split('/');
-  for (const p of patterns) {
-    if (p.dirOnly && !isDir) continue;
-    if (p.anchored) {
-      if (matchSegment(p, parts.join('/'))) return true;
-    } else {
-      // Unanchored: match the pattern against any segment (basename match)
-      // OR against any suffix of the path.
-      for (let i = 0; i < parts.length; i++) {
-        if (matchSegment(p, parts.slice(i).join('/'))) return true;
-      }
-    }
-  }
-  return false;
-}
-
-function matchSegment(p, candidate) {
-  if (!p.glob) return p.pattern === candidate;
-  // Compile glob to regex on first use. Cache on the pattern object.
-  if (!p._re) {
-    const escaped = p.pattern
-      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-      .replace(/\*/g, '[^/]*');
-    p._re = new RegExp(`^${escaped}$`);
-  }
-  return p._re.test(candidate);
-}
-
-async function loadIgnorePatterns(cwd) {
-  const path = join(cwd, '.cannerignore');
-  if (!existsSync(path)) return [];
-  const text = await readFile(path, 'utf8');
-  return parseIgnoreFile(text);
-}
-
-// ---------------------------------------------------------------------------
-// Project config (canner.json) — what `canner init` writes and `canner
-// deploy` reads. Currently just {slug}. Future fields: a `path` override
-// for monorepos pointing at a subdir, an optional `before_upload` hook.
-// ---------------------------------------------------------------------------
-async function loadProjectConfig(cwd) {
-  const path = join(cwd, PROJECT_CONFIG_FILE);
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(await readFile(path, 'utf8'));
-  } catch (err) {
-    die(`could not parse ${PROJECT_CONFIG_FILE}: ${err.message}`);
-  }
-}
-
-async function writeProjectConfig(cwd, cfg) {
-  await writeFile(join(cwd, PROJECT_CONFIG_FILE), JSON.stringify(cfg, null, 2) + '\n');
-}
-
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-
-async function cmdLogin(_args) {
-  const rl = createInterface({ input, output });
-  const existing = await loadCredentials();
-  const apiBase = process.env.CANNER_API_BASE || existing.apiBase || DEFAULT_API_BASE;
-  info(bold('Sign in to Canner'));
-  info(`Create an API token at ${cyan(apiBase.replace('api.', '') + '/dashboard/account')}`);
-  info(`Then paste it below. It starts with ${dim('cnr_')}`);
-  const token = (await rl.question('token: ')).trim();
-  rl.close();
-  if (!token.startsWith('cnr_')) {
-    die("that doesn't look like a Canner API token (expected prefix 'cnr_').");
-  }
-  await saveCredentials({ apiBase, token });
-  // Verify by hitting /auth/me.
-  const me = await apiJSON({ apiBase, token }, 'GET', '/auth/me');
-  if (!me?.account) {
-    die("token didn't authenticate. Check it was copied correctly.");
-  }
-  info(`${green('Signed in as')} ${bold(me.account.email)}`);
-}
-
-async function cmdWhoami() {
-  const creds = await loadCredentials();
-  if (!creds.token) {
-    die("not signed in. Run `canner login`.");
-  }
-  const me = await apiJSON(creds, 'GET', '/auth/me');
-  if (!me?.account) {
-    die('authenticated but /auth/me returned no account.');
-  }
-  // Projects count from /me/plan (cheap call we already have).
-  let plan = null;
-  try {
-    plan = await apiJSON(creds, 'GET', '/me/plan');
-  } catch {
-    // /me/plan is optional context; not fatal if it fails.
-  }
-  if (JSON_MODE) {
-    return emitJSON({ account: me.account, api_base: creds.apiBase, plan: plan ?? null });
-  }
-  info(`${bold(me.account.email)}`);
-  muted(`api: ${creds.apiBase}`);
-  if (plan?.plan) {
-    muted(
-      `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
-    );
-  }
-}
-
-// Remove the stored credential from this machine.
-//
-// `npm uninstall -g @canner-ca/cli` leaves ~/.canner/credentials behind — a
-// live bearer token sitting in the user's home directory with no obvious way
-// to clear it. That's the gap this closes: uninstalling should not leave a
-// working credential on disk.
-//
-// Deliberately local-only. We delete the file we wrote; we do NOT revoke the
-// token server-side, because the same token may be in use by CI, the MCP
-// server, or another machine, and silently killing those from a `logout` on
-// one laptop would be a surprising side effect. The output says so plainly and
-// points at `canner token revoke` for people who do want it gone everywhere.
-async function cmdLogout() {
-  const creds = await loadCredentials();
-  let removed = false;
-  try {
-    await unlink(CREDENTIALS_PATH);
-    removed = true;
-  } catch (err) {
-    // ENOENT just means there was nothing stored — that's a success, not an
-    // error. Anything else (EACCES, EPERM) the user needs to know about.
-    if (err?.code !== 'ENOENT') {
-      die(`could not remove ${CREDENTIALS_PATH}: ${err.message}`);
-    }
-  }
-  if (JSON_MODE) {
-    return emitJSON({ removed, path: CREDENTIALS_PATH });
-  }
-  if (!removed) {
-    info('Nothing to remove — no stored credential on this machine.');
-    // A token in the environment survives logout, and a user who doesn't know
-    // that will think they've signed out when they haven't.
-    if (process.env.CANNER_TOKEN) {
-      muted('Note: CANNER_TOKEN is set in your environment and still applies.');
-    }
-    return;
-  }
-  info(`${green('Signed out.')} Removed ${CREDENTIALS_PATH}`);
-  if (creds.token) {
-    muted('The token itself is still valid. To revoke it everywhere, run');
-    muted(`  canner token revoke <name>   ${dim('(or use the dashboard)')}`);
-  }
-  if (process.env.CANNER_TOKEN) {
-    muted('Note: CANNER_TOKEN is set in your environment and still applies.');
-  }
-}
-
-async function cmdInit(args) {
-  const cwd = process.cwd();
-  const existing = await loadProjectConfig(cwd);
-  if (existing?.slug) {
-    die(`already initialized — ${PROJECT_CONFIG_FILE} has slug=${existing.slug}`);
-  }
-
-  const creds = await loadCredentials();
-  if (!creds.token) {
-    die("not signed in. Run `canner login` first.");
-  }
-
-  const rl = createInterface({ input, output });
-  const defaultName = basename(cwd);
-  const name = (await rl.question(`Project name [${defaultName}]: `)).trim() || defaultName;
-  const defaultSlug = sluggify(name);
-  const slug =
-    args.slug ||
-    (await rl.question(`Slug [${defaultSlug}]: `)).trim() ||
-    defaultSlug;
-  rl.close();
-
-  if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
-    die(`invalid slug "${slug}" — must be 3–50 lowercase letters/digits/hyphens, no leading or trailing hyphen.`);
-  }
-
-  // Server validates uniqueness + reserved-slug rules; we just surface them.
-  const body = await apiJSON(creds, 'POST', '/projects', { name, slug });
-  if (!body) die('project creation returned no body.');
-  await writeProjectConfig(cwd, { slug });
-  info(`${green('Created')} ${bold(slug)}`);
-  muted(`Will be served at https://${slug}.canner.app after the first deploy.`);
-  muted(`Wrote ${PROJECT_CONFIG_FILE}. Run \`canner deploy\` to ship.`);
-}
-
-// Resolve a project slug from --slug flag → canner.json → error. Used by
-// every command that needs one. Returns the slug string (never null).
-async function resolveSlug(args) {
-  if (args.slug) return args.slug;
-  const cfg = await loadProjectConfig(process.cwd());
-  if (cfg?.slug) return cfg.slug;
-  die(`no project slug. Pass --slug=X or run \`canner init\` to create ${PROJECT_CONFIG_FILE}.`);
-}
-
-// Format an ISO timestamp as a short relative-time string (e.g. "2m ago",
-// "3h ago", "5d ago"). Falls back to absolute YYYY-MM-DD for dates > 30d.
-function relTime(iso) {
-  if (!iso) return dim('—');
-  const ms = Date.now() - new Date(iso).getTime();
-  const s = Math.floor(ms / 1000);
-  if (s < 60) return `${s}s ago`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m ago`;
-  const h = Math.floor(m / 60);
-  if (h < 24) return `${h}h ago`;
-  const d = Math.floor(h / 24);
-  if (d < 30) return `${d}d ago`;
-  return iso.slice(0, 10);
-}
-
-// Right-pad a string to width N, ANSI-stripped for length math.
-function pad(s, n) {
-  const visible = String(s).replace(/\x1b\[[0-9;]*m/g, '');
-  return String(s) + ' '.repeat(Math.max(0, n - visible.length));
-}
-
-// Color a deployment status string for table output.
-function colorStatus(s) {
-  if (s === 'live') return green(s);
-  if (s === 'failed') return red(s);
-  if (s === 'queued' || s === 'building' || s === 'deploying') return yellow(s);
-  return dim(s);
-}
-
-// ---------------------------------------------------------------------------
-// canner projects — list owned + team projects
-// ---------------------------------------------------------------------------
-async function cmdProjects() {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const body = await apiJSON(creds, 'GET', '/projects');
-  const rows = body?.projects ?? body ?? [];
-  if (JSON_MODE) return emitJSON(rows);
-  if (!Array.isArray(rows) || rows.length === 0) {
-    muted('no projects yet. Run `canner init` to create one.');
-    return;
-  }
-  info(`${pad(bold('SLUG'), 24)}${pad(bold('STATUS'), 14)}${pad(bold('URL'), 40)}${bold('LAST REQUEST')}`);
-  for (const p of rows) {
-    const url = `https://${p.slug}.canner.app`;
-    const lastReq = relTime(p.last_request_at);
-    info(`${pad(p.slug, 24)}${pad(colorStatus(p.status), 14)}${pad(dim(url), 40)}${dim(lastReq)}`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// canner status [--slug X] — single project detail
-// ---------------------------------------------------------------------------
-async function cmdStatus(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}`);
-  const p = body?.project ?? body;
-  if (!p?.slug) die('unexpected response from /projects/:slug');
-  if (JSON_MODE) return emitJSON(p);
-  info(`${bold(p.slug)} ${dim(`(${p.name ?? ''})`)}`);
-  info(`  status:        ${colorStatus(p.status)}${p.is_cold ? dim(' (cold)') : ''}`);
-  info(`  url:           ${cyan(`https://${p.slug}.canner.app`)}`);
-  info(`  source:        ${p.is_connected ? `${dim('github')} ${p.repo_url ?? ''} (branch ${p.repo_branch})` : dim('upload-only')}`);
-  info(`  memory:        ${p.memory_limit_mb}M${p.always_warm ? ` ${dim('(always-warm)')}` : ''}`);
-  info(`  last request:  ${relTime(p.last_request_at)}`);
-  info(`  updated:       ${relTime(p.updated_at)}`);
-}
-
-// ---------------------------------------------------------------------------
-// canner deployments [--slug X]                  — list
-// canner deployments <id> [--slug X] [--follow]  — view one (optionally tail)
-// ---------------------------------------------------------------------------
-async function cmdDeployments(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const id = args._[0];
-  if (id) return viewDeployment(creds, slug, id, args.follow === true);
-  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
-  const rows = body?.deployments ?? [];
-  if (JSON_MODE) return emitJSON(rows);
-  if (rows.length === 0) {
-    muted('no deployments yet.');
-    return;
-  }
-  info(`${pad(bold('ID'), 12)}${pad(bold('STATUS'), 14)}${pad(bold('WHEN'), 14)}${pad(bold('DURATION'), 12)}${bold('COMMIT')}`);
-  for (const d of rows.slice(0, 20)) {
-    const sha = (d.commit_sha || '').slice(0, 7) || dim('—');
-    const msg = (d.commit_message || '').split('\n')[0].slice(0, 60);
-    const dur = d.build_duration_ms != null ? `${Math.round(d.build_duration_ms / 1000)}s` : dim('—');
-    const star = d.is_current ? green('●') : ' ';
-    info(`${star} ${pad(dim(d.id.slice(0, 8)), 10)}${pad(colorStatus(d.status), 14)}${pad(dim(relTime(d.created_at)), 14)}${pad(dur, 12)}${sha} ${dim(msg)}`);
-  }
-}
-
-async function viewDeployment(creds, slug, idPrefix, follow) {
-  // Allow the user to pass an 8-char prefix — disambiguate against the list.
-  let fullId = idPrefix;
-  if (idPrefix.length < 36) {
-    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
-    const matches = (body?.deployments ?? []).filter((d) => d.id.startsWith(idPrefix));
-    if (matches.length === 0) die(`no deployment matching "${idPrefix}"`);
-    if (matches.length > 1) die(`ambiguous "${idPrefix}" — matches ${matches.length} deployments`);
-    fullId = matches[0].id;
-  }
-  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments/${fullId}`);
-  const d = body?.deployment;
-  if (!d) die('deployment not found');
-  if (JSON_MODE) return emitJSON(d);
-  info(`${bold(d.id.slice(0, 8))}${dim(d.id.slice(8))}  ${colorStatus(d.status)}`);
-  if (d.commit_sha) info(`  ${dim('commit')}  ${d.commit_sha.slice(0, 12)} ${dim((d.commit_message || '').split('\n')[0])}`);
-  if (d.commit_author) info(`  ${dim('author')}  ${d.commit_author}`);
-  info(`  ${dim('queued')}  ${relTime(d.created_at)}`);
-  if (d.deployed_at) info(`  ${dim('done')}    ${relTime(d.deployed_at)}`);
-  if (d.error_message) info(`  ${dim('error')}   ${red(d.error_message)}`);
-  if (d.build_log) {
-    info(dim('─── build log ───────────────────────────────────'));
-    process.stdout.write(d.build_log);
-    if (!d.build_log.endsWith('\n')) process.stdout.write('\n');
-  }
-  if (follow && !['live', 'failed', 'superseded'].includes(d.status)) {
-    info(dim('─── streaming (still in progress) ────────────────'));
-    const code = await tailDeploymentLogs(creds, slug, fullId);
-    process.exit(code);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// canner logs [--slug X] [--lines N] [--follow]
-//   Stream the live tenant runtime logs via SSE. Without --follow, exits
-//   after the initial history burst settles (~1s quiet window).
-// ---------------------------------------------------------------------------
-async function cmdLogs(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const lines = Number(args.lines) || 200;
-  const url = `${creds.apiBase}/projects/${encodeURIComponent(slug)}/runtime-logs?lines=${lines}`;
-  const res = await fetch(url, {
-    headers: { Authorization: `Bearer ${creds.token}`, Accept: 'text/event-stream' },
-  }).catch((err) => die(`could not open log stream: ${err.message}`));
-  if (!res.ok || !res.body) die(`log stream returned ${res.status} ${res.statusText}`);
-
-  const decoder = new TextDecoder('utf-8');
-  let buffer = '';
-  let quietTimer = null;
-  const armQuiet = () => {
-    if (!args.follow) {
-      clearTimeout(quietTimer);
-      // 1.5s with no new data after the history burst → assume we're caught up.
-      quietTimer = setTimeout(() => process.exit(0), 1500);
-    }
-  };
-  armQuiet();
-
-  for await (const chunk of res.body) {
-    buffer += decoder.decode(chunk, { stream: true });
-    let idx;
-    while ((idx = buffer.indexOf('\n\n')) !== -1) {
-      const raw = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 2);
-      if (raw.startsWith(':')) continue; // heartbeat
-      let event = 'message';
-      let data = '';
-      for (const line of raw.split('\n')) {
-        if (line.startsWith('event:')) event = line.slice(6).trim();
-        else if (line.startsWith('data:')) data += line.slice(5).trim();
-      }
-      if (!data) continue;
-      let parsed;
-      try { parsed = JSON.parse(data); } catch { continue; }
-      if (event === 'log') {
-        // runtime-logs uses {line:...}, build-logs uses {log:...} — handle both.
-        const text = parsed.line ?? parsed.log;
-        if (text) process.stdout.write(text + (text.endsWith('\n') ? '' : '\n'));
-        armQuiet();
-      } else if (event === 'done') {
-        process.exit(0);
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// canner cancel [<id>] [--slug X]
-//   Cancel an in-flight build. With no id, finds the latest non-terminal
-//   deployment for the project and cancels it.
-// ---------------------------------------------------------------------------
-async function cmdCancel(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  let id = args._[0];
-  if (!id) {
-    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
-    const inflight = (body?.deployments ?? []).find((d) =>
-      ['queued', 'building', 'deploying'].includes(d.status)
-    );
-    if (!inflight) die('no in-flight deployment to cancel. Pass an id to cancel a specific one.');
-    id = inflight.id;
-  } else if (id.length < 36) {
-    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
-    const matches = (body?.deployments ?? []).filter((d) => d.id.startsWith(id));
-    if (matches.length === 0) die(`no deployment matching "${id}"`);
-    if (matches.length > 1) die(`ambiguous "${id}" — matches ${matches.length} deployments`);
-    id = matches[0].id;
-  }
-  await apiJSON(creds, 'POST', `/projects/${encodeURIComponent(slug)}/deployments/${id}/cancel`);
-  if (JSON_MODE) return emitJSON({ ok: true, cancelled: id });
-  info(`${green('cancelled')} ${dim(id.slice(0, 8))}`);
-}
-
-// ---------------------------------------------------------------------------
-// canner token                       — list API tokens
-// canner token create <name>         — mint a token (plaintext printed once)
-// canner token revoke <id|prefix>    — revoke a token
-// ---------------------------------------------------------------------------
-async function cmdToken(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const sub = args._[0] ?? 'list';
-
-  if (sub === 'list') {
-    const body = await apiJSON(creds, 'GET', '/tokens');
-    const rows = body?.tokens ?? [];
-    if (JSON_MODE) return emitJSON(rows);
-    if (rows.length === 0) { muted('no API tokens. Create one with `canner token create <name>`.'); return; }
-    info(`${pad(bold('ID'), 12)}${pad(bold('NAME'), 28)}${pad(bold('PREFIX'), 18)}${bold('LAST USED')}`);
-    for (const t of rows) {
-      info(`${pad(dim(t.id.slice(0, 8)), 12)}${pad(t.name ?? dim('—'), 28)}${pad(dim(`${t.prefix}…`), 18)}${dim(relTime(t.last_used_at))}`);
-    }
-    return;
-  }
-
-  if (sub === 'create') {
-    const name = args._[1] || (typeof args.name === 'string' ? args.name : null);
-    if (!name) die('usage: canner token create <name>', 2);
-    const tok = await apiJSON(creds, 'POST', '/tokens', { name });
-    if (!tok?.token) die('token creation returned no secret.');
-    if (JSON_MODE) return emitJSON(tok);
-    info(`${green('created')} ${bold(tok.name)}`);
-    info(tok.token);
-    muted('Copy this now — the secret is not shown again.');
-    return;
-  }
-
-  if (sub === 'revoke') {
-    const ref = args._[1];
-    if (!ref) die('usage: canner token revoke <id|prefix|name>', 2);
-    const id = await resolveTokenId(creds, ref);
-    await apiJSON(creds, 'DELETE', `/tokens/${encodeURIComponent(id)}`);
-    if (JSON_MODE) return emitJSON({ ok: true, revoked: id });
-    info(`${green('revoked')} ${dim(id.slice(0, 8))}`);
-    return;
-  }
-
-  die(`unknown token subcommand "${sub}". Use: list | create | revoke.`, 2);
-}
-
-async function resolveTokenId(creds, ref) {
-  if (ref.length >= 36) return ref; // full UUID
-  const body = await apiJSON(creds, 'GET', '/tokens');
-  const rows = body?.tokens ?? [];
-  const matches = rows.filter(
-    (t) => t.id.startsWith(ref) || t.name === ref || (t.prefix && t.prefix.startsWith(ref))
-  );
-  if (matches.length === 0) die(`no token matching "${ref}"`);
-  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} tokens`);
-  return matches[0].id;
-}
-
-// ---------------------------------------------------------------------------
-// canner env [--slug X]                                 — list env vars
-// canner env set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
-// canner env rm <KEY|id> [--env ...] [--slug X]         — delete an env var
-// ---------------------------------------------------------------------------
-async function cmdEnv(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const sub = args._[0] ?? 'list';
-  const base = `/projects/${encodeURIComponent(slug)}/env-vars`;
-
-  if (sub === 'list') {
-    const body = await apiJSON(creds, 'GET', base);
-    const rows = body?.env_vars ?? [];
-    if (JSON_MODE) return emitJSON(rows);
-    if (rows.length === 0) { muted('no environment variables.'); return; }
-    info(`${pad(bold('KEY'), 28)}${pad(bold('ENV'), 14)}${pad(bold('SENSITIVE'), 12)}${bold('VALUE')}`);
-    for (const v of rows) {
-      const val = v.is_sensitive ? dim('••••••') : (v.value ?? '').split('\n')[0].slice(0, 48);
-      info(`${pad(v.key, 28)}${pad(dim(v.environment ?? 'all'), 14)}${pad(v.is_sensitive ? yellow('yes') : dim('no'), 12)}${dim(val)}`);
-    }
-    return;
-  }
-
-  if (sub === 'set') {
-    const kv = args._[1];
-    if (!kv || !kv.includes('=')) die('usage: canner env set KEY=VALUE', 2);
-    const eq = kv.indexOf('=');
-    const key = kv.slice(0, eq);
-    const value = kv.slice(eq + 1);
-    const environment = normalizeEnvScope(args.env);
-    const isSensitive = args.sensitive === true;
-    const result = await apiJSON(creds, 'POST', base, {
-      key, value, environment, is_sensitive: isSensitive,
-    });
-    if (JSON_MODE) return emitJSON(result);
-    if ((result?.created ?? []).length > 0) {
-      info(`${green('set')} ${bold(key)}${environment ? dim(` (${environment})`) : ''}`);
-    } else {
-      // A duplicate (same key+scope) is skipped, not overwritten — surface that
-      // so the user isn't surprised the value didn't change.
-      die(`${key} already exists for that environment. Delete it first (canner env rm ${key}), then set again.`);
-    }
-    return;
-  }
-
-  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
-    const ref = args._[1];
-    if (!ref) die('usage: canner env rm <KEY|id>', 2);
-    const id = await resolveEnvVarId(creds, base, ref, normalizeEnvScope(args.env));
-    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
-    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
-    info(`${green('deleted')} ${bold(ref)}`);
-    return;
-  }
-
-  die(`unknown env subcommand "${sub}". Use: list | set | rm.`, 2);
-}
-
-// Map a --env flag to the API's environment field. Accepts production/preview;
-// anything else (or absent) means "all environments" (null).
-function normalizeEnvScope(flag) {
-  if (flag === 'production' || flag === 'preview') return flag;
-  return null;
-}
-
-async function resolveEnvVarId(creds, base, ref, environment) {
-  if (ref.length >= 36 && ref.includes('-')) return ref; // looks like a UUID
-  const body = await apiJSON(creds, 'GET', base);
-  const rows = body?.env_vars ?? [];
-  const matches = rows.filter((v) => {
-    if (v.id.startsWith(ref)) return true;
-    if (v.key !== ref) return false;
-    // If a scope was given, narrow to it; otherwise match any scope.
-    return environment === null ? true : v.environment === environment;
-  });
-  if (matches.length === 0) die(`no env var matching "${ref}"`);
-  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} vars (pass --env to disambiguate)`);
-  return matches[0].id;
-}
-
-// ---------------------------------------------------------------------------
-// canner domains [--slug X]                  — list custom domains
-// canner domains add <hostname> [--slug X]   — attach a domain (pending)
-// canner domains verify <host|id> [--slug X] — re-check DNS + provision TLS
-// canner domains rm <host|id> [--slug X]     — detach a domain
-// ---------------------------------------------------------------------------
-async function cmdDomains(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const sub = args._[0] ?? 'list';
-  const base = `/projects/${encodeURIComponent(slug)}/domains`;
-
-  if (sub === 'list') {
-    const body = await apiJSON(creds, 'GET', base);
-    const rows = body?.domains ?? [];
-    if (JSON_MODE) return emitJSON(rows);
-    if (rows.length === 0) {
-      muted(`no custom domains. Add one with \`canner domains add <hostname>\`.`);
-      if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify\`.`);
-      return;
-    }
-    info(`${pad(bold('HOSTNAME'), 36)}${pad(bold('STATUS'), 16)}${bold('VERIFIED')}`);
-    for (const d of rows) {
-      info(`${pad(d.hostname, 36)}${pad(colorDomainStatus(d.status), 16)}${dim(relTime(d.verified_at))}`);
-    }
-    if (body?.platform_ip) muted(`A record target: ${body.platform_ip}`);
-    return;
-  }
-
-  if (sub === 'add') {
-    const hostname = args._[1];
-    if (!hostname) die('usage: canner domains add <hostname>', 2);
-    const body = await apiJSON(creds, 'POST', base, { hostname });
-    if (JSON_MODE) return emitJSON(body);
-    const d = body?.domain ?? {};
-    info(`${green('added')} ${bold(d.hostname ?? hostname)} ${dim(`(${d.status ?? 'pending'})`)}`);
-    if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify ${hostname}\`.`);
-    return;
-  }
-
-  if (sub === 'verify') {
-    const ref = args._[1];
-    if (!ref) die('usage: canner domains verify <hostname|id>', 2);
-    const id = await resolveDomainId(creds, base, ref);
-    const body = await apiJSON(creds, 'POST', `${base}/${encodeURIComponent(id)}/verify`);
-    if (JSON_MODE) return emitJSON(body);
-    const d = body?.domain ?? {};
-    info(`${green('verified')} ${bold(d.hostname ?? ref)} ${dim(`(${d.status ?? 'verified'})`)}`);
-    return;
-  }
-
-  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
-    const ref = args._[1];
-    if (!ref) die('usage: canner domains rm <hostname|id>', 2);
-    const id = await resolveDomainId(creds, base, ref);
-    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
-    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
-    info(`${green('removed')} ${bold(ref)}`);
-    return;
-  }
-
-  die(`unknown domains subcommand "${sub}". Use: list | add | verify | rm.`, 2);
-}
-
-function colorDomainStatus(s) {
-  if (s === 'verified') return green(s);
-  if (s === 'failed') return red(s);
-  if (s === 'pending') return yellow(s);
-  return dim(s);
-}
-
-async function resolveDomainId(creds, base, ref) {
-  if (ref.length >= 36 && ref.includes('-')) return ref; // UUID
-  const body = await apiJSON(creds, 'GET', base);
-  const rows = body?.domains ?? [];
-  const matches = rows.filter((d) => d.id.startsWith(ref) || d.hostname === ref);
-  if (matches.length === 0) die(`no domain matching "${ref}"`);
-  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} domains`);
-  return matches[0].id;
-}
-
-// ---------------------------------------------------------------------------
-// canner open [--slug X] [--dashboard]
-//   Open the tenant URL (default) or the dashboard project page in the
-//   user's default browser.
-// ---------------------------------------------------------------------------
-async function cmdOpen(args) {
-  const slug = await resolveSlug(args);
-  // Strict slug validation — never trust user input as part of a shell arg
-  // even though the runner below uses argv (not bash -c). Belt and braces.
-  if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
-    die(`invalid slug "${slug}"`);
-  }
-  const creds = await loadCredentials();
-  const dashboardOrigin = (creds.apiBase || DEFAULT_API_BASE).replace(/^https?:\/\/api\./, 'https://');
-  const url = args.dashboard
-    ? `${dashboardOrigin}/dashboard/projects/${slug}`
-    : `https://${slug}.canner.app`;
-  info(`opening ${dim(url)}`);
-  const { spawn } = await import('node:child_process');
-  const platform = process.platform;
-  let cmd, cmdArgs;
-  if (platform === 'win32') { cmd = 'cmd'; cmdArgs = ['/c', 'start', '""', url]; }
-  else if (platform === 'darwin') { cmd = 'open'; cmdArgs = [url]; }
-  else { cmd = 'xdg-open'; cmdArgs = [url]; }
-  const child = spawn(cmd, cmdArgs, { stdio: 'ignore', detached: true });
-  child.on('error', () => die(`could not launch browser (${cmd} not found)`));
-  child.unref();
-}
-
-// ---------------------------------------------------------------------------
-// canner redeploy [--slug X] [--follow]
-//   Trigger a rebuild from the GitHub repo's current HEAD — no local upload.
-//   Only works for projects that are GitHub-connected via the Canner Deploy
-//   GitHub App. For upload-only projects, use `canner deploy` instead.
-// ---------------------------------------------------------------------------
-async function cmdRedeploy(args) {
-  const creds = await loadCredentials();
-  if (!creds.token) die("not signed in. Run `canner login`.");
-  const slug = await resolveSlug(args);
-  const res = await apiRequest(creds, 'POST', `/projects/${encodeURIComponent(slug)}/deploy`);
-  const body = await res.json();
-  const deploymentId = body.deployment_id;
-  if (!deploymentId) die('redeploy returned no deployment_id.');
-  if (JSON_MODE) return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug });
-  info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}  ${dim('(rebuild from GitHub HEAD)')}`);
-  if (!args.follow) {
-    muted(`Tail with: canner deployments ${deploymentId.slice(0, 8)} --follow`);
-    return;
-  }
-  const exitCode = await tailDeploymentLogs(creds, slug, deploymentId);
-  process.exit(exitCode);
-}
-
-async function cmdDeploy(args) {
-  const projectPath = resolve(args._[0] || '.');
-  if (!existsSync(projectPath)) {
-    die(`path not found: ${projectPath}`);
-  }
-  const cwdStat = await stat(projectPath);
-  if (!cwdStat.isDirectory()) {
-    die(`path is not a directory: ${projectPath}`);
-  }
-
-  const cfg = await loadProjectConfig(projectPath);
-  const slug = args.slug || cfg?.slug;
-  if (!slug) {
-    die(`no project slug. Pass --slug=X or run \`canner init\` to create ${PROJECT_CONFIG_FILE}.`);
-  }
-
-  const creds = await loadCredentials();
-  if (!creds.token) {
-    die("not signed in. Run `canner login`.");
-  }
-
-  // Build the ignore patterns: hard excludes + user .cannerignore.
-  const userPatterns = await loadIgnorePatterns(projectPath);
-
-  // Build the tarball as a temp file. We use a temp file (not piping directly
-  // into the upload) so we know the final size before POST + so a tar error
-  // surfaces cleanly before we touch the network.
-  const tarPath = join(tmpdir(), `canner-${randomUUID()}.tar.gz`);
-  let fileCount = 0;
-  info(`${dim('packaging')} ${projectPath}`);
-  try {
-    await tarCreate(
-      {
-        gzip: true,
-        file: tarPath,
-        cwd: projectPath,
-        // Strict portable-file-only — refuse symlinks pointing outside the
-        // project, etc. Matches what the server-side safe-extractor enforces.
-        portable: true,
-        filter: (path) => {
-          // path is relative to cwd, POSIX-normalized by tar.
-          const rel = path.replace(/^\.\//, '').replace(/^\/+/, '');
-          if (!rel) return true; // root
-          const parts = rel.split('/');
-          // Hard excludes match by basename anywhere in the tree.
-          for (const part of parts) {
-            if (HARD_EXCLUDES.has(part)) return false;
-          }
-          // User .cannerignore.
-          const isDir = path.endsWith('/');
-          if (matchesIgnore(rel, isDir, userPatterns)) return false;
-          fileCount++;
-          return true;
-        },
-      },
-      ['./']
-    );
-  } catch (err) {
-    await unlink(tarPath).catch(() => undefined);
-    die(`tar failed: ${err.message}`);
-  }
-
-  const tarStat = await stat(tarPath);
-  const sizeMb = (tarStat.size / 1024 / 1024).toFixed(2);
-  info(`${dim('packaged')} ${fileCount} files (${sizeMb} MB compressed)`);
-
-  // Upload. fs.openAsBlob() backs the Blob by the on-disk file lazily —
-  // bytes only flow when fetch consumes them, so a 500 MB Live upload
-  // doesn't buffer into RAM on the user's machine. Node fetch has no
-  // upload-progress hook as of 2026, so we just print the size we're
-  // sending; the dashboard shows real-time progress for browser uploads.
-  info(`${dim('uploading')} to ${slug}…`);
-  const form = new FormData();
-  const blob = await openAsBlob(tarPath, { type: 'application/gzip' });
-  form.append('archive', blob, `${slug}.tar.gz`);
-
-  let response;
-  try {
-    response = await apiRequest(creds, 'POST', `/projects/${slug}/upload`, { body: form });
-  } finally {
-    await unlink(tarPath).catch(() => undefined);
-  }
-
-  const body = await response.json();
-  const deploymentId = body.deployment_id;
-  if (!deploymentId) {
-    die('upload succeeded but the response had no deployment_id.');
-  }
-  if (JSON_MODE) {
-    // JSON mode never streams the SSE build log (it would corrupt the
-    // single-value contract). Emit the queued result; the caller can poll
-    // `canner deployments <id> --json` for terminal status.
-    return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug, files: fileCount, size_mb: Number(sizeMb) });
-  }
-  info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}`);
-
-  if (!args.follow) {
-    muted(`Tail with: canner deploy --follow --slug=${slug}  (or visit the dashboard)`);
-    return;
-  }
-
-  // SSE tail until terminal.
-  const exitCode = await tailDeploymentLogs(creds, slug, deploymentId);
-  process.exit(exitCode);
-}
-
-// ---------------------------------------------------------------------------
-// SSE consumer for /projects/:slug/deployments/:id/logs.
-// Parses the wire format manually (no eventsource dep). Returns exit code:
-// 0 if status ended at 'live', 1 if 'failed', 2 if connection died early.
-// ---------------------------------------------------------------------------
-async function tailDeploymentLogs(creds, slug, deploymentId) {
-  info(dim(`streaming build log…`));
-  const url = `${creds.apiBase}/projects/${slug}/deployments/${deploymentId}/logs`;
-  const res = await fetch(url, {
-    headers: {
-      Authorization: `Bearer ${creds.token}`,
-      Accept: 'text/event-stream',
-    },
-  }).catch((err) => {
-    die(`could not open log stream: ${err.message}`);
-  });
-  if (!res.ok || !res.body) {
-    die(`log stream returned ${res.status} ${res.statusText}`);
-  }
-
-  const decoder = new TextDecoder('utf-8');
-  let buffer = '';
-  let lastStatus = 'queued';
-  let printedHistory = false;
-
-  for await (const chunk of res.body) {
-    buffer += decoder.decode(chunk, { stream: true });
-    let idx;
-    while ((idx = buffer.indexOf('\n\n')) !== -1) {
-      const raw = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 2);
-      // Skip heartbeat comments (": ping").
-      if (raw.startsWith(':')) continue;
-      let event = 'message';
-      let data = '';
-      for (const line of raw.split('\n')) {
-        if (line.startsWith('event:')) event = line.slice(6).trim();
-        else if (line.startsWith('data:')) data += line.slice(5).trim();
-      }
-      if (!data) continue;
-      let parsed;
-      try { parsed = JSON.parse(data); } catch { continue; }
-      if (event === 'history') {
-        if (!printedHistory && parsed.log) {
-          process.stdout.write(parsed.log);
-        }
-        printedHistory = true;
-      } else if (event === 'log') {
-        if (parsed.log) process.stdout.write(parsed.log);
-      } else if (event === 'status') {
-        lastStatus = parsed.status ?? lastStatus;
-      } else if (event === 'done') {
-        lastStatus = parsed.status ?? lastStatus;
-        break;
-      }
-    }
-  }
-
-  if (lastStatus === 'live') {
-    info(`\n${green('live')} at https://${slug}.canner.app`);
-    return 0;
-  }
-  if (lastStatus === 'failed') {
-    info(`\n${red('failed')} (status=${lastStatus})`);
-    return 1;
-  }
-  info(`\n${yellow('stream ended')} (status=${lastStatus})`);
-  return 2;
-}
-
-// ---------------------------------------------------------------------------
-// Slug derivation mirrors the server's regex: ^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$
-// ---------------------------------------------------------------------------
-function sluggify(s) {
-  return s
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .replace(/-+/g, '-')
-    .slice(0, 50);
-}
-
-// ---------------------------------------------------------------------------
-// Argv parser. Tiny, no dep. Supports:
-//   canner cmd                    → { _: [], cmd }
-//   canner cmd value              → { _: ['value'] }
-//   canner cmd --flag             → { flag: true }
-//   canner cmd --key value        → { key: 'value' }
-//   canner cmd --key=value        → { key: 'value' }
-//   canner cmd -v                 → { v: true }
-// ---------------------------------------------------------------------------
-function parseArgs(argv) {
-  const out = { _: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith('--')) {
-      const eq = a.indexOf('=');
-      if (eq !== -1) {
-        out[a.slice(2, eq)] = a.slice(eq + 1);
-      } else {
-        const key = a.slice(2);
-        const next = argv[i + 1];
-        if (next && !next.startsWith('-')) {
-          out[key] = next;
-          i++;
-        } else {
-          out[key] = true;
-        }
-      }
-    } else if (a.startsWith('-') && a.length === 2) {
-      out[a.slice(1)] = true;
-    } else {
-      out._.push(a);
-    }
-  }
-  return out;
-}
-
-function printHelp() {
-  process.stdout.write(`${bold('canner')} ${dim('— deploy to Canner from any terminal')}
-
-${bold('Usage:')}
-  canner <command> [options]
-
-${bold('Setup:')}
-  ${bold('login')}                Store your Canner API token (one-time).
-  ${bold('logout')}               Remove the stored token from this machine.
-  ${bold('whoami')}               Show the account this CLI is signed in as.
-
-${bold('Projects:')}
-  ${bold('projects')}             List your projects.
-  ${bold('init')} [--slug X]      Create a project and write ${cyan(PROJECT_CONFIG_FILE)}.
-  ${bold('status')} [--slug X]    Show project state (URL, status, source, last request).
-  ${bold('open')} [--slug X] [--dashboard]
-                       Open the tenant URL (or dashboard page) in your browser.
-
-${bold('Deploys:')}
-  ${bold('deploy')} [path] [--slug X] [--follow]
-                       Tar the current directory and upload. Works for any
-                       project (GitHub-connected or upload-only).
-  ${bold('redeploy')} [--slug X] [--follow]
-                       Trigger a rebuild from the GitHub repo's HEAD without
-                       uploading. GitHub-connected projects only.
-  ${bold('deployments')} [--slug X]
-                       List the project's recent deployments.
-  ${bold('deployments')} <id> [--slug X] [--follow]
-                       Show one deployment's build log (--follow streams if
-                       it's still in progress).
-  ${bold('cancel')} [<id>] [--slug X]
-                       Abort the in-flight build (or a specific one by id).
-  ${bold('logs')} [--slug X] [--lines N] [--follow]
-                       Stream the running tenant's runtime logs (last 200
-                       lines by default, --follow to keep streaming).
-
-${bold('Resources:')}
-  ${bold('token')} list | create <name> | revoke <id|name>
-                       Manage the cnr_ API tokens that authenticate this CLI.
-  ${bold('env')} [list] [--slug X]
-  ${bold('env')} set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
-  ${bold('env')} rm <KEY|id> [--env ...] [--slug X]
-                       Manage a project's environment variables.
-  ${bold('domains')} [list] [--slug X]
-  ${bold('domains')} add <hostname> [--slug X]
-  ${bold('domains')} verify <hostname|id> [--slug X]
-  ${bold('domains')} rm <hostname|id> [--slug X]
-                       Manage a project's custom domains.
-
-${bold('Global:')}
-  ${bold('--json')}               Emit machine-readable JSON (for scripts, CI, agents).
-                       Suppresses tables + progress; --follow log streaming is
-                       skipped. Errors go to stderr as {"error":"..."}.
-
-${bold('Examples:')}
-  canner login
-  cd my-site && canner init
-  canner deploy --follow                 ${dim('# build to live, streaming logs')}
-  canner redeploy --follow                ${dim('# rebuild from GitHub HEAD')}
-  canner deployments                      ${dim('# list recent deploys')}
-  canner deployments 7bf4862e --follow    ${dim('# inspect a specific one')}
-  canner logs --follow                    ${dim('# tail tenant runtime logs')}
-  canner cancel                            ${dim('# abort the current build')}
-  canner open --dashboard                 ${dim('# open dashboard project page')}
-  canner token create ci                  ${dim('# mint a token named "ci"')}
-  canner env set API_KEY=secret --sensitive  ${dim('# add a hidden env var')}
-  canner domains add www.example.com      ${dim('# attach a custom domain')}
-  canner projects --json | jq '.[].slug'  ${dim('# machine-readable output')}
-
-${bold('Environment:')}
-  CANNER_TOKEN         Override stored token (handy for CI).
-  CANNER_API_BASE      Override API endpoint (default ${DEFAULT_API_BASE}).
-
-${bold('Files:')}
-  ~/.canner/credentials   Stored token (mode 0600).
-  canner.json             Per-project slug (committed alongside source).
-  .cannerignore           Optional excludes (in addition to node_modules,
-                          .git, .next, .nuxt, .turbo, .vercel, .svelte-kit,
-                          .DS_Store, Thumbs.db which are always excluded).
-
-Docs: https://canner.ca/cli
-Version: ${VERSION}
-`);
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-const args = parseArgs(process.argv.slice(2));
-const command = args._.shift();
-
-// Global --json: machine-readable output for scripts, CI, and agents. Set
-// before dispatch so every helper (info/muted/die) honors it.
-JSON_MODE = args.json === true;
-
-if (args.version || args.v || command === 'version') {
-  process.stdout.write(`canner ${VERSION}\n`);
-  process.exit(0);
-}
-if (!command || args.help || args.h || command === 'help') {
-  printHelp();
-  process.exit(0);
-}
-
-const dispatch = {
-  login: cmdLogin,
-  logout: cmdLogout,
-  whoami: cmdWhoami,
-  init: cmdInit,
-  deploy: cmdDeploy,
-  redeploy: cmdRedeploy,
-  projects: cmdProjects,
-  status: cmdStatus,
-  logs: cmdLogs,
-  deployments: cmdDeployments,
-  cancel: cmdCancel,
-  open: cmdOpen,
-  token: cmdToken,
-  tokens: cmdToken,
-  env: cmdEnv,
-  domains: cmdDomains,
-};
-const handler = dispatch[command];
-if (!handler) {
-  process.stderr.write(`${red('error:')} unknown command "${command}"\n\n`);
-  printHelp();
-  process.exit(2);
-}
-
-try {
-  await handler(args);
-} catch (err) {
-  if (err && err.code === 'ERR_UNHANDLED_ERROR') {
-    die(err.message);
-  }
-  die(err?.message ?? String(err));
-}
+#!/usr/bin/env node
+// @canner-ca/cli — canner deploy CLI.
+//
+// Single-file ESM. Zero transitive deps beyond `tar` (one MIT package).
+// Works in any terminal (macOS / Linux / Windows / Cursor). Authenticates
+// with a `cnr_*` API token from the dashboard; deploys by tarring the
+// current directory and POSTing to the same /projects/:slug/upload
+// endpoint the dashboard's drag-drop uses.
+//
+// Commands:
+//   canner login                        store an API token
+//   canner logout                       remove the stored token from this machine
+//   canner whoami                       show the account this CLI is signed in as
+//   canner init [--slug X]              create a project, write canner.json
+//   canner deploy [path] [--slug X] [--follow]
+//                                       tar + upload + optionally stream the build log
+//
+// Exit codes: 0 on success, 1 on user/network/auth error, 2 on bad CLI
+// invocation. `canner deploy --follow` exits with the build's success
+// (0 = live, 1 = failed) so it composes with CI pipelines.
+
+import { existsSync, openAsBlob } from 'node:fs';
+import { mkdir, readFile, writeFile, stat, chmod, unlink } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve, basename } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { randomUUID } from 'node:crypto';
+import { stdin as input, stdout as output } from 'node:process';
+import { create as tarCreate } from 'tar';
+
+const VERSION = '0.5.0';
+const DEFAULT_API_BASE = 'https://api.canner.ca';
+const CONFIG_DIR = join(homedir(), '.canner');
+const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
+const PROJECT_CONFIG_FILE = 'canner.json';
+
+// Stuff we never ship even if the user doesn't have a .cannerignore. These
+// are "build noise" — heavy directories that the server-side build pipeline
+// rebuilds, plus OS / IDE droppings.
+const HARD_EXCLUDES = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.vercel',
+  '.svelte-kit',
+  '.DS_Store',
+  'Thumbs.db',
+]);
+
+// ---------------------------------------------------------------------------
+// Tiny ANSI styling. No chalk dep — eight inlined escape codes cover us.
+// Disabled when stdout isn't a TTY (CI, redirected to file).
+// ---------------------------------------------------------------------------
+const isTTY = output.isTTY === true;
+const c = (code) => (s) => isTTY ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+const bold = c('1');
+const dim = c('2');
+const red = c('31');
+const green = c('32');
+const yellow = c('33');
+const cyan = c('36');
+
+// Machine-readable output mode (`--json`). Set once in main from argv. In JSON
+// mode every command prints a single JSON value to stdout and nothing else, so
+// the output pipes straight into `jq` or an agent; errors become
+// {"error":"..."} on stderr with a non-zero exit. Human-facing helpers
+// (info/muted) go silent so they can't corrupt the JSON stream.
+let JSON_MODE = false;
+
+function emitJSON(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+
+function die(msg, code = 1) {
+  if (JSON_MODE) {
+    process.stderr.write(JSON.stringify({ error: String(msg) }) + '\n');
+  } else {
+    process.stderr.write(`${red('error:')} ${msg}\n`);
+  }
+  process.exit(code);
+}
+
+function info(msg) {
+  if (JSON_MODE) return;
+  process.stdout.write(`${msg}\n`);
+}
+
+function muted(msg) {
+  if (JSON_MODE) return;
+  process.stdout.write(`${dim(msg)}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Credential storage (~/.canner/credentials)
+//
+// JSON with shape: { api_base: string, token: string }. Mode 0600 on
+// platforms that respect it. We default api_base to https://api.canner.ca
+// but allow override via CANNER_API_BASE env var (handy for self-host
+// later, and for local dev pointing at localhost:4001 via tunnel).
+// ---------------------------------------------------------------------------
+async function loadCredentials() {
+  try {
+    const raw = await readFile(CREDENTIALS_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      apiBase: process.env.CANNER_API_BASE || parsed.api_base || DEFAULT_API_BASE,
+      token: parsed.token,
+    };
+  } catch {
+    return {
+      apiBase: process.env.CANNER_API_BASE || DEFAULT_API_BASE,
+      token: process.env.CANNER_TOKEN || null,
+    };
+  }
+}
+
+async function saveCredentials({ apiBase, token }) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(
+    CREDENTIALS_PATH,
+    JSON.stringify({ api_base: apiBase, token }, null, 2),
+    { mode: 0o600 }
+  );
+  try {
+    await chmod(CREDENTIALS_PATH, 0o600);
+  } catch {
+    // Windows doesn't honor Unix mode; fine.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers. fetch is built-in on Node 20+.
+// ---------------------------------------------------------------------------
+async function apiRequest(creds, method, path, options = {}) {
+  if (!creds.token) {
+    die("not signed in. Run `canner login` first.");
+  }
+  const url = `${creds.apiBase}${path}`;
+  const headers = {
+    Authorization: `Bearer ${creds.token}`,
+    Accept: 'application/json',
+    ...(options.headers ?? {}),
+  };
+  const init = {
+    method,
+    headers,
+    body: options.body,
+    // Long-lived ops (deploy upload, SSE) shouldn't time out at the
+    // fetch level. Per-call options.signal can still abort.
+  };
+  if (options.signal) init.signal = options.signal;
+  // A streamed request body (database imports) needs duplex: 'half' in Node's fetch.
+  if (options.duplex) init.duplex = options.duplex;
+  const res = await fetch(url, init).catch((err) => {
+    die(`network: ${err.message}`);
+  });
+  if (!res.ok) {
+    let body = null;
+    try { body = await res.json(); } catch { /* not JSON */ }
+    if (res.status === 401) {
+      die("authentication failed. Your token may be revoked. Run `canner login` again.");
+    }
+    if (res.status === 403) {
+      // Surface the server's specific reason: a token missing a scope
+      // (insufficient_scope) or the member's role/permission in the org
+      // (insufficient_permission) both send a human `message`.
+      const detail =
+        body?.message ||
+        (body?.error === 'insufficient_scope'
+          ? 'the API token is missing a required scope'
+          : body?.error === 'insufficient_permission'
+            ? "your role in this organization doesn't permit this action"
+            : "the API token doesn't have access to this resource");
+      die(`forbidden: ${detail}`);
+    }
+    const msg = body?.message || body?.error || `${res.status} ${res.statusText}`;
+    die(`${method} ${path}: ${msg}`);
+  }
+  return res;
+}
+
+async function apiJSON(creds, method, path, body) {
+  const init = {};
+  if (body !== undefined) {
+    init.headers = { 'Content-Type': 'application/json' };
+    init.body = JSON.stringify(body);
+  }
+  const res = await apiRequest(creds, method, path, init);
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+// ---------------------------------------------------------------------------
+// .cannerignore parsing — simple line-based excludes.
+// One pattern per line. '#' comments, blank lines ignored. Supports:
+//   - exact-basename match anywhere ('build', 'coverage')
+//   - trailing-slash directory match ('logs/' matches only directories)
+//   - leading '/' anchors to project root ('/dist' = only the root dist/)
+//   - basic glob: '*' inside a single path segment
+// No negation ('!') support — keep the surface tight.
+// ---------------------------------------------------------------------------
+function parseIgnoreFile(text) {
+  const patterns = [];
+  for (const lineRaw of text.split('\n')) {
+    const line = lineRaw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const dirOnly = line.endsWith('/');
+    const anchored = line.startsWith('/');
+    const body = line.replace(/^\/+/, '').replace(/\/+$/, '');
+    const glob = body.includes('*');
+    patterns.push({ pattern: body, dirOnly, anchored, glob });
+  }
+  return patterns;
+}
+
+function matchesIgnore(relPath, isDir, patterns) {
+  // relPath is POSIX-normalized, no leading slash, no './'.
+  const parts = relPath.split('/');
+  for (const p of patterns) {
+    if (p.dirOnly && !isDir) continue;
+    if (p.anchored) {
+      if (matchSegment(p, parts.join('/'))) return true;
+    } else {
+      // Unanchored: match the pattern against any segment (basename match)
+      // OR against any suffix of the path.
+      for (let i = 0; i < parts.length; i++) {
+        if (matchSegment(p, parts.slice(i).join('/'))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function matchSegment(p, candidate) {
+  if (!p.glob) return p.pattern === candidate;
+  // Compile glob to regex on first use. Cache on the pattern object.
+  if (!p._re) {
+    const escaped = p.pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '[^/]*');
+    p._re = new RegExp(`^${escaped}$`);
+  }
+  return p._re.test(candidate);
+}
+
+async function loadIgnorePatterns(cwd) {
+  const path = join(cwd, '.cannerignore');
+  if (!existsSync(path)) return [];
+  const text = await readFile(path, 'utf8');
+  return parseIgnoreFile(text);
+}
+
+// ---------------------------------------------------------------------------
+// Project config (canner.json) — what `canner init` writes and `canner
+// deploy` reads. Currently just {slug}. Future fields: a `path` override
+// for monorepos pointing at a subdir, an optional `before_upload` hook.
+// ---------------------------------------------------------------------------
+async function loadProjectConfig(cwd) {
+  const path = join(cwd, PROJECT_CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (err) {
+    die(`could not parse ${PROJECT_CONFIG_FILE}: ${err.message}`);
+  }
+}
+
+async function writeProjectConfig(cwd, cfg) {
+  await writeFile(join(cwd, PROJECT_CONFIG_FILE), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function cmdLogin(_args) {
+  const rl = createInterface({ input, output });
+  const existing = await loadCredentials();
+  const apiBase = process.env.CANNER_API_BASE || existing.apiBase || DEFAULT_API_BASE;
+  info(bold('Sign in to Canner'));
+  info(`Create an API token at ${cyan(apiBase.replace('api.', '') + '/dashboard/account')}`);
+  info(`Then paste it below. It starts with ${dim('cnr_')}`);
+  const token = (await rl.question('token: ')).trim();
+  rl.close();
+  if (!token.startsWith('cnr_')) {
+    die("that doesn't look like a Canner API token (expected prefix 'cnr_').");
+  }
+  await saveCredentials({ apiBase, token });
+  // Verify by hitting /auth/me.
+  const me = await apiJSON({ apiBase, token }, 'GET', '/auth/me');
+  if (!me?.account) {
+    die("token didn't authenticate. Check it was copied correctly.");
+  }
+  info(`${green('Signed in as')} ${bold(me.account.email)}`);
+}
+
+async function cmdWhoami() {
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login`.");
+  }
+  const me = await apiJSON(creds, 'GET', '/auth/me');
+  if (!me?.account) {
+    die('authenticated but /auth/me returned no account.');
+  }
+  // Projects count from /me/plan (cheap call we already have).
+  let plan = null;
+  try {
+    plan = await apiJSON(creds, 'GET', '/me/plan');
+  } catch {
+    // /me/plan is optional context; not fatal if it fails.
+  }
+  if (JSON_MODE) {
+    return emitJSON({ account: me.account, api_base: creds.apiBase, plan: plan ?? null });
+  }
+  info(`${bold(me.account.email)}`);
+  muted(`api: ${creds.apiBase}`);
+  if (plan?.plan) {
+    muted(
+      `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
+    );
+  }
+}
+
+// Remove the stored credential from this machine.
+//
+// `npm uninstall -g @canner-ca/cli` leaves ~/.canner/credentials behind — a
+// live bearer token sitting in the user's home directory with no obvious way
+// to clear it. That's the gap this closes: uninstalling should not leave a
+// working credential on disk.
+//
+// Deliberately local-only. We delete the file we wrote; we do NOT revoke the
+// token server-side, because the same token may be in use by CI, the MCP
+// server, or another machine, and silently killing those from a `logout` on
+// one laptop would be a surprising side effect. The output says so plainly and
+// points at `canner token revoke` for people who do want it gone everywhere.
+async function cmdLogout() {
+  const creds = await loadCredentials();
+  let removed = false;
+  try {
+    await unlink(CREDENTIALS_PATH);
+    removed = true;
+  } catch (err) {
+    // ENOENT just means there was nothing stored — that's a success, not an
+    // error. Anything else (EACCES, EPERM) the user needs to know about.
+    if (err?.code !== 'ENOENT') {
+      die(`could not remove ${CREDENTIALS_PATH}: ${err.message}`);
+    }
+  }
+  if (JSON_MODE) {
+    return emitJSON({ removed, path: CREDENTIALS_PATH });
+  }
+  if (!removed) {
+    info('Nothing to remove — no stored credential on this machine.');
+    // A token in the environment survives logout, and a user who doesn't know
+    // that will think they've signed out when they haven't.
+    if (process.env.CANNER_TOKEN) {
+      muted('Note: CANNER_TOKEN is set in your environment and still applies.');
+    }
+    return;
+  }
+  info(`${green('Signed out.')} Removed ${CREDENTIALS_PATH}`);
+  if (creds.token) {
+    muted('The token itself is still valid. To revoke it everywhere, run');
+    muted(`  canner token revoke <name>   ${dim('(or use the dashboard)')}`);
+  }
+  if (process.env.CANNER_TOKEN) {
+    muted('Note: CANNER_TOKEN is set in your environment and still applies.');
+  }
+}
+
+async function cmdInit(args) {
+  const cwd = process.cwd();
+  const existing = await loadProjectConfig(cwd);
+  if (existing?.slug) {
+    die(`already initialized — ${PROJECT_CONFIG_FILE} has slug=${existing.slug}`);
+  }
+
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login` first.");
+  }
+
+  const rl = createInterface({ input, output });
+  const defaultName = basename(cwd);
+  const name = (await rl.question(`Project name [${defaultName}]: `)).trim() || defaultName;
+  const defaultSlug = sluggify(name);
+  const slug =
+    args.slug ||
+    (await rl.question(`Slug [${defaultSlug}]: `)).trim() ||
+    defaultSlug;
+  rl.close();
+
+  if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
+    die(`invalid slug "${slug}" — must be 3–50 lowercase letters/digits/hyphens, no leading or trailing hyphen.`);
+  }
+
+  // Server validates uniqueness + reserved-slug rules; we just surface them.
+  const body = await apiJSON(creds, 'POST', '/projects', { name, slug });
+  if (!body) die('project creation returned no body.');
+  await writeProjectConfig(cwd, { slug });
+  info(`${green('Created')} ${bold(slug)}`);
+  muted(`Will be served at https://${slug}.canner.app after the first deploy.`);
+  muted(`Wrote ${PROJECT_CONFIG_FILE}. Run \`canner deploy\` to ship.`);
+}
+
+// Resolve a project slug from --slug flag → canner.json → error. Used by
+// every command that needs one. Returns the slug string (never null).
+async function resolveSlug(args) {
+  if (args.slug) return args.slug;
+  const cfg = await loadProjectConfig(process.cwd());
+  if (cfg?.slug) return cfg.slug;
+  die(`no project slug. Pass --slug=X or run \`canner init\` to create ${PROJECT_CONFIG_FILE}.`);
+}
+
+// Format an ISO timestamp as a short relative-time string (e.g. "2m ago",
+// "3h ago", "5d ago"). Falls back to absolute YYYY-MM-DD for dates > 30d.
+function relTime(iso) {
+  if (!iso) return dim('—');
+  const ms = Date.now() - new Date(iso).getTime();
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  return iso.slice(0, 10);
+}
+
+// Right-pad a string to width N, ANSI-stripped for length math.
+function pad(s, n) {
+  const visible = String(s).replace(/\x1b\[[0-9;]*m/g, '');
+  return String(s) + ' '.repeat(Math.max(0, n - visible.length));
+}
+
+// Color a deployment status string for table output.
+function colorStatus(s) {
+  if (s === 'live') return green(s);
+  if (s === 'failed') return red(s);
+  if (s === 'queued' || s === 'building' || s === 'deploying') return yellow(s);
+  return dim(s);
+}
+
+// ---------------------------------------------------------------------------
+// canner projects — list owned + team projects
+// ---------------------------------------------------------------------------
+async function cmdProjects() {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const body = await apiJSON(creds, 'GET', '/projects');
+  const rows = body?.projects ?? body ?? [];
+  if (JSON_MODE) return emitJSON(rows);
+  if (!Array.isArray(rows) || rows.length === 0) {
+    muted('no projects yet. Run `canner init` to create one.');
+    return;
+  }
+  info(`${pad(bold('SLUG'), 24)}${pad(bold('STATUS'), 14)}${pad(bold('URL'), 40)}${bold('LAST REQUEST')}`);
+  for (const p of rows) {
+    const url = `https://${p.slug}.canner.app`;
+    const lastReq = relTime(p.last_request_at);
+    info(`${pad(p.slug, 24)}${pad(colorStatus(p.status), 14)}${pad(dim(url), 40)}${dim(lastReq)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// canner status [--slug X] — single project detail
+// ---------------------------------------------------------------------------
+async function cmdStatus(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}`);
+  const p = body?.project ?? body;
+  if (!p?.slug) die('unexpected response from /projects/:slug');
+  if (JSON_MODE) return emitJSON(p);
+  info(`${bold(p.slug)} ${dim(`(${p.name ?? ''})`)}`);
+  info(`  status:        ${colorStatus(p.status)}${p.is_cold ? dim(' (cold)') : ''}`);
+  info(`  url:           ${cyan(`https://${p.slug}.canner.app`)}`);
+  info(`  source:        ${p.is_connected ? `${dim('github')} ${p.repo_url ?? ''} (branch ${p.repo_branch})` : dim('upload-only')}`);
+  info(`  memory:        ${p.memory_limit_mb}M${p.always_warm ? ` ${dim('(always-warm)')}` : ''}`);
+  info(`  last request:  ${relTime(p.last_request_at)}`);
+  info(`  updated:       ${relTime(p.updated_at)}`);
+}
+
+// ---------------------------------------------------------------------------
+// canner deployments [--slug X]                  — list
+// canner deployments <id> [--slug X] [--follow]  — view one (optionally tail)
+// ---------------------------------------------------------------------------
+async function cmdDeployments(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const id = args._[0];
+  if (id) return viewDeployment(creds, slug, id, args.follow === true);
+  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
+  const rows = body?.deployments ?? [];
+  if (JSON_MODE) return emitJSON(rows);
+  if (rows.length === 0) {
+    muted('no deployments yet.');
+    return;
+  }
+  info(`${pad(bold('ID'), 12)}${pad(bold('STATUS'), 14)}${pad(bold('WHEN'), 14)}${pad(bold('DURATION'), 12)}${bold('COMMIT')}`);
+  for (const d of rows.slice(0, 20)) {
+    const sha = (d.commit_sha || '').slice(0, 7) || dim('—');
+    const msg = (d.commit_message || '').split('\n')[0].slice(0, 60);
+    const dur = d.build_duration_ms != null ? `${Math.round(d.build_duration_ms / 1000)}s` : dim('—');
+    const star = d.is_current ? green('●') : ' ';
+    info(`${star} ${pad(dim(d.id.slice(0, 8)), 10)}${pad(colorStatus(d.status), 14)}${pad(dim(relTime(d.created_at)), 14)}${pad(dur, 12)}${sha} ${dim(msg)}`);
+  }
+}
+
+async function viewDeployment(creds, slug, idPrefix, follow) {
+  // Allow the user to pass an 8-char prefix — disambiguate against the list.
+  let fullId = idPrefix;
+  if (idPrefix.length < 36) {
+    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
+    const matches = (body?.deployments ?? []).filter((d) => d.id.startsWith(idPrefix));
+    if (matches.length === 0) die(`no deployment matching "${idPrefix}"`);
+    if (matches.length > 1) die(`ambiguous "${idPrefix}" — matches ${matches.length} deployments`);
+    fullId = matches[0].id;
+  }
+  const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments/${fullId}`);
+  const d = body?.deployment;
+  if (!d) die('deployment not found');
+  if (JSON_MODE) return emitJSON(d);
+  info(`${bold(d.id.slice(0, 8))}${dim(d.id.slice(8))}  ${colorStatus(d.status)}`);
+  if (d.commit_sha) info(`  ${dim('commit')}  ${d.commit_sha.slice(0, 12)} ${dim((d.commit_message || '').split('\n')[0])}`);
+  if (d.commit_author) info(`  ${dim('author')}  ${d.commit_author}`);
+  info(`  ${dim('queued')}  ${relTime(d.created_at)}`);
+  if (d.deployed_at) info(`  ${dim('done')}    ${relTime(d.deployed_at)}`);
+  if (d.error_message) info(`  ${dim('error')}   ${red(d.error_message)}`);
+  if (d.build_log) {
+    info(dim('─── build log ───────────────────────────────────'));
+    process.stdout.write(d.build_log);
+    if (!d.build_log.endsWith('\n')) process.stdout.write('\n');
+  }
+  if (follow && !['live', 'failed', 'superseded'].includes(d.status)) {
+    info(dim('─── streaming (still in progress) ────────────────'));
+    const code = await tailDeploymentLogs(creds, slug, fullId);
+    process.exit(code);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// canner logs [--slug X] [--lines N] [--follow]
+//   Stream the live tenant runtime logs via SSE. Without --follow, exits
+//   after the initial history burst settles (~1s quiet window).
+// ---------------------------------------------------------------------------
+async function cmdLogs(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const lines = Number(args.lines) || 200;
+  const url = `${creds.apiBase}/projects/${encodeURIComponent(slug)}/runtime-logs?lines=${lines}`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${creds.token}`, Accept: 'text/event-stream' },
+  }).catch((err) => die(`could not open log stream: ${err.message}`));
+  if (!res.ok || !res.body) die(`log stream returned ${res.status} ${res.statusText}`);
+
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let quietTimer = null;
+  const armQuiet = () => {
+    if (!args.follow) {
+      clearTimeout(quietTimer);
+      // 1.5s with no new data after the history burst → assume we're caught up.
+      quietTimer = setTimeout(() => process.exit(0), 1500);
+    }
+  };
+  armQuiet();
+
+  for await (const chunk of res.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const raw = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      if (raw.startsWith(':')) continue; // heartbeat
+      let event = 'message';
+      let data = '';
+      for (const line of raw.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data += line.slice(5).trim();
+      }
+      if (!data) continue;
+      let parsed;
+      try { parsed = JSON.parse(data); } catch { continue; }
+      if (event === 'log') {
+        // runtime-logs uses {line:...}, build-logs uses {log:...} — handle both.
+        const text = parsed.line ?? parsed.log;
+        if (text) process.stdout.write(text + (text.endsWith('\n') ? '' : '\n'));
+        armQuiet();
+      } else if (event === 'done') {
+        process.exit(0);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// canner cancel [<id>] [--slug X]
+//   Cancel an in-flight build. With no id, finds the latest non-terminal
+//   deployment for the project and cancels it.
+// ---------------------------------------------------------------------------
+async function cmdCancel(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  let id = args._[0];
+  if (!id) {
+    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
+    const inflight = (body?.deployments ?? []).find((d) =>
+      ['queued', 'building', 'deploying'].includes(d.status)
+    );
+    if (!inflight) die('no in-flight deployment to cancel. Pass an id to cancel a specific one.');
+    id = inflight.id;
+  } else if (id.length < 36) {
+    const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
+    const matches = (body?.deployments ?? []).filter((d) => d.id.startsWith(id));
+    if (matches.length === 0) die(`no deployment matching "${id}"`);
+    if (matches.length > 1) die(`ambiguous "${id}" — matches ${matches.length} deployments`);
+    id = matches[0].id;
+  }
+  await apiJSON(creds, 'POST', `/projects/${encodeURIComponent(slug)}/deployments/${id}/cancel`);
+  if (JSON_MODE) return emitJSON({ ok: true, cancelled: id });
+  info(`${green('cancelled')} ${dim(id.slice(0, 8))}`);
+}
+
+// ---------------------------------------------------------------------------
+// canner token                       — list API tokens
+// canner token create <name>         — mint a token (plaintext printed once)
+// canner token revoke <id|prefix>    — revoke a token
+// ---------------------------------------------------------------------------
+async function cmdToken(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const sub = args._[0] ?? 'list';
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', '/tokens');
+    const rows = body?.tokens ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) { muted('no API tokens. Create one with `canner token create <name>`.'); return; }
+    info(`${pad(bold('ID'), 12)}${pad(bold('NAME'), 28)}${pad(bold('PREFIX'), 18)}${bold('LAST USED')}`);
+    for (const t of rows) {
+      info(`${pad(dim(t.id.slice(0, 8)), 12)}${pad(t.name ?? dim('—'), 28)}${pad(dim(`${t.prefix}…`), 18)}${dim(relTime(t.last_used_at))}`);
+    }
+    return;
+  }
+
+  if (sub === 'create') {
+    const name = args._[1] || (typeof args.name === 'string' ? args.name : null);
+    if (!name) die('usage: canner token create <name>', 2);
+    const tok = await apiJSON(creds, 'POST', '/tokens', { name });
+    if (!tok?.token) die('token creation returned no secret.');
+    if (JSON_MODE) return emitJSON(tok);
+    info(`${green('created')} ${bold(tok.name)}`);
+    info(tok.token);
+    muted('Copy this now — the secret is not shown again.');
+    return;
+  }
+
+  if (sub === 'revoke') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner token revoke <id|prefix|name>', 2);
+    const id = await resolveTokenId(creds, ref);
+    await apiJSON(creds, 'DELETE', `/tokens/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, revoked: id });
+    info(`${green('revoked')} ${dim(id.slice(0, 8))}`);
+    return;
+  }
+
+  die(`unknown token subcommand "${sub}". Use: list | create | revoke.`, 2);
+}
+
+async function resolveTokenId(creds, ref) {
+  if (ref.length >= 36) return ref; // full UUID
+  const body = await apiJSON(creds, 'GET', '/tokens');
+  const rows = body?.tokens ?? [];
+  const matches = rows.filter(
+    (t) => t.id.startsWith(ref) || t.name === ref || (t.prefix && t.prefix.startsWith(ref))
+  );
+  if (matches.length === 0) die(`no token matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} tokens`);
+  return matches[0].id;
+}
+
+// ---------------------------------------------------------------------------
+// canner env [--reveal] [--slug X]                      — list env vars
+//   (sensitive values redacted by default, in text AND --json; --reveal opts out)
+// canner env set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
+// canner env rm <KEY|id> [--env ...] [--slug X]         — delete an env var
+// ---------------------------------------------------------------------------
+async function cmdEnv(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const sub = args._[0] ?? 'list';
+  const base = `/projects/${encodeURIComponent(slug)}/env-vars`;
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', base);
+    const rows = body?.env_vars ?? [];
+    // Sensitive values are redacted by default in BOTH output modes — the API
+    // returns them decrypted (the owner can read their own secrets back), but
+    // a plain `env list` (human or --json) is a read-only config check, not a
+    // secret-reveal action. --reveal is the explicit opt-in for scripts that
+    // actually need the value (e.g. syncing it elsewhere).
+    const reveal = args.reveal === true;
+    if (JSON_MODE) {
+      return emitJSON(
+        reveal ? rows : rows.map((v) => (v.is_sensitive ? { ...v, value: null } : v))
+      );
+    }
+    if (rows.length === 0) { muted('no environment variables.'); return; }
+    info(`${pad(bold('KEY'), 28)}${pad(bold('ENV'), 14)}${pad(bold('SENSITIVE'), 12)}${bold('VALUE')}`);
+    for (const v of rows) {
+      const val = v.is_sensitive && !reveal ? dim('••••••') : (v.value ?? '').split('\n')[0].slice(0, 48);
+      info(`${pad(v.key, 28)}${pad(dim(v.environment ?? 'all'), 14)}${pad(v.is_sensitive ? yellow('yes') : dim('no'), 12)}${dim(val)}`);
+    }
+    return;
+  }
+
+  if (sub === 'set') {
+    const kv = args._[1];
+    if (!kv || !kv.includes('=')) die('usage: canner env set KEY=VALUE', 2);
+    const eq = kv.indexOf('=');
+    const key = kv.slice(0, eq);
+    const value = kv.slice(eq + 1);
+    const environment = normalizeEnvScope(args.env);
+    const isSensitive = args.sensitive === true;
+    const result = await apiJSON(creds, 'POST', base, {
+      key, value, environment, is_sensitive: isSensitive,
+    });
+    if (JSON_MODE) return emitJSON(result);
+    if ((result?.created ?? []).length > 0) {
+      info(`${green('set')} ${bold(key)}${environment ? dim(` (${environment})`) : ''}`);
+    } else {
+      // A duplicate (same key+scope) is skipped, not overwritten — surface that
+      // so the user isn't surprised the value didn't change.
+      die(`${key} already exists for that environment. Delete it first (canner env rm ${key}), then set again.`);
+    }
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner env rm <KEY|id>', 2);
+    const id = await resolveEnvVarId(creds, base, ref, normalizeEnvScope(args.env));
+    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+    info(`${green('deleted')} ${bold(ref)}`);
+    return;
+  }
+
+  die(`unknown env subcommand "${sub}". Use: list | set | rm.`, 2);
+}
+
+// Map a --env flag to the API's environment field. Accepts production/preview;
+// anything else (or absent) means "all environments" (null).
+function normalizeEnvScope(flag) {
+  if (flag === 'production' || flag === 'preview') return flag;
+  return null;
+}
+
+async function resolveEnvVarId(creds, base, ref, environment) {
+  if (ref.length >= 36 && ref.includes('-')) return ref; // looks like a UUID
+  const body = await apiJSON(creds, 'GET', base);
+  const rows = body?.env_vars ?? [];
+  const matches = rows.filter((v) => {
+    if (v.id.startsWith(ref)) return true;
+    if (v.key !== ref) return false;
+    // If a scope was given, narrow to it; otherwise match any scope.
+    return environment === null ? true : v.environment === environment;
+  });
+  if (matches.length === 0) die(`no env var matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} vars (pass --env to disambiguate)`);
+  return matches[0].id;
+}
+
+// ---------------------------------------------------------------------------
+// canner domains [--slug X]                  — list custom domains
+// canner domains add <hostname> [--slug X]   — attach a domain (pending)
+// canner domains verify <host|id> [--slug X] — re-check DNS + provision TLS
+// canner domains rm <host|id> [--slug X]     — detach a domain
+// ---------------------------------------------------------------------------
+async function cmdDomains(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const sub = args._[0] ?? 'list';
+  const base = `/projects/${encodeURIComponent(slug)}/domains`;
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', base);
+    const rows = body?.domains ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) {
+      muted(`no custom domains. Add one with \`canner domains add <hostname>\`.`);
+      if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify\`.`);
+      return;
+    }
+    info(`${pad(bold('HOSTNAME'), 36)}${pad(bold('STATUS'), 16)}${bold('VERIFIED')}`);
+    for (const d of rows) {
+      info(`${pad(d.hostname, 36)}${pad(colorDomainStatus(d.status), 16)}${dim(relTime(d.verified_at))}`);
+    }
+    if (body?.platform_ip) muted(`A record target: ${body.platform_ip}`);
+    return;
+  }
+
+  if (sub === 'add') {
+    const hostname = args._[1];
+    if (!hostname) die('usage: canner domains add <hostname>', 2);
+    const body = await apiJSON(creds, 'POST', base, { hostname });
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.domain ?? {};
+    info(`${green('added')} ${bold(d.hostname ?? hostname)} ${dim(`(${d.status ?? 'pending'})`)}`);
+    if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify ${hostname}\`.`);
+    return;
+  }
+
+  if (sub === 'verify') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner domains verify <hostname|id>', 2);
+    const id = await resolveDomainId(creds, base, ref);
+    const body = await apiJSON(creds, 'POST', `${base}/${encodeURIComponent(id)}/verify`);
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.domain ?? {};
+    info(`${green('verified')} ${bold(d.hostname ?? ref)} ${dim(`(${d.status ?? 'verified'})`)}`);
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner domains rm <hostname|id>', 2);
+    const id = await resolveDomainId(creds, base, ref);
+    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+    info(`${green('removed')} ${bold(ref)}`);
+    return;
+  }
+
+  die(`unknown domains subcommand "${sub}". Use: list | add | verify | rm.`, 2);
+}
+
+function colorDomainStatus(s) {
+  if (s === 'verified') return green(s);
+  if (s === 'failed') return red(s);
+  if (s === 'pending') return yellow(s);
+  return dim(s);
+}
+
+async function resolveDomainId(creds, base, ref) {
+  if (ref.length >= 36 && ref.includes('-')) return ref; // UUID
+  const body = await apiJSON(creds, 'GET', base);
+  const rows = body?.domains ?? [];
+  const matches = rows.filter((d) => d.id.startsWith(ref) || d.hostname === ref);
+  if (matches.length === 0) die(`no domain matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} domains`);
+  return matches[0].id;
+}
+
+// ---------------------------------------------------------------------------
+// canner open [--slug X] [--dashboard]
+//   Open the tenant URL (default) or the dashboard project page in the
+//   user's default browser.
+// ---------------------------------------------------------------------------
+async function cmdOpen(args) {
+  const slug = await resolveSlug(args);
+  // Strict slug validation — never trust user input as part of a shell arg
+  // even though the runner below uses argv (not bash -c). Belt and braces.
+  if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
+    die(`invalid slug "${slug}"`);
+  }
+  const creds = await loadCredentials();
+  const dashboardOrigin = (creds.apiBase || DEFAULT_API_BASE).replace(/^https?:\/\/api\./, 'https://');
+  const url = args.dashboard
+    ? `${dashboardOrigin}/dashboard/projects/${slug}`
+    : `https://${slug}.canner.app`;
+  info(`opening ${dim(url)}`);
+  const { spawn } = await import('node:child_process');
+  const platform = process.platform;
+  let cmd, cmdArgs;
+  if (platform === 'win32') { cmd = 'cmd'; cmdArgs = ['/c', 'start', '""', url]; }
+  else if (platform === 'darwin') { cmd = 'open'; cmdArgs = [url]; }
+  else { cmd = 'xdg-open'; cmdArgs = [url]; }
+  const child = spawn(cmd, cmdArgs, { stdio: 'ignore', detached: true });
+  child.on('error', () => die(`could not launch browser (${cmd} not found)`));
+  child.unref();
+}
+
+// ---------------------------------------------------------------------------
+// canner redeploy [--slug X] [--follow]
+//   Trigger a rebuild from the GitHub repo's current HEAD — no local upload.
+//   Only works for projects that are GitHub-connected via the Canner Deploy
+//   GitHub App. For upload-only projects, use `canner deploy` instead.
+// ---------------------------------------------------------------------------
+async function cmdRedeploy(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const res = await apiRequest(creds, 'POST', `/projects/${encodeURIComponent(slug)}/deploy`);
+  const body = await res.json();
+  const deploymentId = body.deployment_id;
+  if (!deploymentId) die('redeploy returned no deployment_id.');
+  if (JSON_MODE) return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug });
+  info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}  ${dim('(rebuild from GitHub HEAD)')}`);
+  if (!args.follow) {
+    muted(`Tail with: canner deployments ${deploymentId.slice(0, 8)} --follow`);
+    return;
+  }
+  const exitCode = await tailDeploymentLogs(creds, slug, deploymentId);
+  process.exit(exitCode);
+}
+
+async function cmdDeploy(args) {
+  const projectPath = resolve(args._[0] || '.');
+  if (!existsSync(projectPath)) {
+    die(`path not found: ${projectPath}`);
+  }
+  const cwdStat = await stat(projectPath);
+  if (!cwdStat.isDirectory()) {
+    die(`path is not a directory: ${projectPath}`);
+  }
+
+  const cfg = await loadProjectConfig(projectPath);
+  const slug = args.slug || cfg?.slug;
+  if (!slug) {
+    die(`no project slug. Pass --slug=X or run \`canner init\` to create ${PROJECT_CONFIG_FILE}.`);
+  }
+
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login`.");
+  }
+
+  // Build the ignore patterns: hard excludes + user .cannerignore.
+  const userPatterns = await loadIgnorePatterns(projectPath);
+
+  // Build the tarball as a temp file. We use a temp file (not piping directly
+  // into the upload) so we know the final size before POST + so a tar error
+  // surfaces cleanly before we touch the network.
+  const tarPath = join(tmpdir(), `canner-${randomUUID()}.tar.gz`);
+  let fileCount = 0;
+  info(`${dim('packaging')} ${projectPath}`);
+  try {
+    await tarCreate(
+      {
+        gzip: true,
+        file: tarPath,
+        cwd: projectPath,
+        // Strict portable-file-only — refuse symlinks pointing outside the
+        // project, etc. Matches what the server-side safe-extractor enforces.
+        portable: true,
+        filter: (path) => {
+          // path is relative to cwd, POSIX-normalized by tar.
+          const rel = path.replace(/^\.\//, '').replace(/^\/+/, '');
+          if (!rel) return true; // root
+          const parts = rel.split('/');
+          // Hard excludes match by basename anywhere in the tree.
+          for (const part of parts) {
+            if (HARD_EXCLUDES.has(part)) return false;
+          }
+          // User .cannerignore.
+          const isDir = path.endsWith('/');
+          if (matchesIgnore(rel, isDir, userPatterns)) return false;
+          fileCount++;
+          return true;
+        },
+      },
+      ['./']
+    );
+  } catch (err) {
+    await unlink(tarPath).catch(() => undefined);
+    die(`tar failed: ${err.message}`);
+  }
+
+  const tarStat = await stat(tarPath);
+  const sizeMb = (tarStat.size / 1024 / 1024).toFixed(2);
+  info(`${dim('packaged')} ${fileCount} files (${sizeMb} MB compressed)`);
+
+  // Upload. fs.openAsBlob() backs the Blob by the on-disk file lazily —
+  // bytes only flow when fetch consumes them, so a 500 MB Live upload
+  // doesn't buffer into RAM on the user's machine. Node fetch has no
+  // upload-progress hook as of 2026, so we just print the size we're
+  // sending; the dashboard shows real-time progress for browser uploads.
+  info(`${dim('uploading')} to ${slug}…`);
+  const form = new FormData();
+  const blob = await openAsBlob(tarPath, { type: 'application/gzip' });
+  form.append('archive', blob, `${slug}.tar.gz`);
+
+  let response;
+  try {
+    response = await apiRequest(creds, 'POST', `/projects/${slug}/upload`, { body: form });
+  } finally {
+    await unlink(tarPath).catch(() => undefined);
+  }
+
+  const body = await response.json();
+  const deploymentId = body.deployment_id;
+  if (!deploymentId) {
+    die('upload succeeded but the response had no deployment_id.');
+  }
+  if (JSON_MODE) {
+    // JSON mode never streams the SSE build log (it would corrupt the
+    // single-value contract). Emit the queued result; the caller can poll
+    // `canner deployments <id> --json` for terminal status.
+    return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug, files: fileCount, size_mb: Number(sizeMb) });
+  }
+  info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}`);
+
+  if (!args.follow) {
+    muted(`Tail with: canner deploy --follow --slug=${slug}  (or visit the dashboard)`);
+    return;
+  }
+
+  // SSE tail until terminal.
+  const exitCode = await tailDeploymentLogs(creds, slug, deploymentId);
+  process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// SSE consumer for /projects/:slug/deployments/:id/logs.
+// Parses the wire format manually (no eventsource dep). Returns exit code:
+// 0 if status ended at 'live', 1 if 'failed', 2 if connection died early.
+// ---------------------------------------------------------------------------
+async function tailDeploymentLogs(creds, slug, deploymentId) {
+  info(dim(`streaming build log…`));
+  const url = `${creds.apiBase}/projects/${slug}/deployments/${deploymentId}/logs`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${creds.token}`,
+      Accept: 'text/event-stream',
+    },
+  }).catch((err) => {
+    die(`could not open log stream: ${err.message}`);
+  });
+  if (!res.ok || !res.body) {
+    die(`log stream returned ${res.status} ${res.statusText}`);
+  }
+
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let lastStatus = 'queued';
+  let printedHistory = false;
+
+  for await (const chunk of res.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const raw = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      // Skip heartbeat comments (": ping").
+      if (raw.startsWith(':')) continue;
+      let event = 'message';
+      let data = '';
+      for (const line of raw.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data += line.slice(5).trim();
+      }
+      if (!data) continue;
+      let parsed;
+      try { parsed = JSON.parse(data); } catch { continue; }
+      if (event === 'history') {
+        if (!printedHistory && parsed.log) {
+          process.stdout.write(parsed.log);
+        }
+        printedHistory = true;
+      } else if (event === 'log') {
+        if (parsed.log) process.stdout.write(parsed.log);
+      } else if (event === 'status') {
+        lastStatus = parsed.status ?? lastStatus;
+      } else if (event === 'done') {
+        lastStatus = parsed.status ?? lastStatus;
+        break;
+      }
+    }
+  }
+
+  if (lastStatus === 'live') {
+    info(`\n${green('live')} at https://${slug}.canner.app`);
+    return 0;
+  }
+  if (lastStatus === 'failed') {
+    info(`\n${red('failed')} (status=${lastStatus})`);
+    return 1;
+  }
+  info(`\n${yellow('stream ended')} (status=${lastStatus})`);
+  return 2;
+}
+
+// ---------------------------------------------------------------------------
+// Slug derivation mirrors the server's regex: ^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$
+// ---------------------------------------------------------------------------
+function sluggify(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-')
+    .slice(0, 50);
+}
+
+// ---------------------------------------------------------------------------
+// Argv parser. Tiny, no dep. Supports:
+//   canner cmd                    → { _: [], cmd }
+//   canner cmd value              → { _: ['value'] }
+//   canner cmd --flag             → { flag: true }
+//   canner cmd --key value        → { key: 'value' }
+//   canner cmd --key=value        → { key: 'value' }
+//   canner cmd -v                 → { v: true }
+// ---------------------------------------------------------------------------
+// Flags that never take a value, so `canner db import --replace dump.dump` keeps
+// dump.dump as the positional argument instead of reading it as --replace's value.
+const BOOLEAN_FLAGS = new Set([
+  'json', 'reveal', 'sensitive', 'follow', 'dashboard', 'version', 'help',
+  'replace', 'yes', 'no-wait', 'enable', 'disable', 'restore', 'download', 'rm', 'delete', 'instance', 'pitr',
+]);
+
+// A flag repeated on the command line (e.g. `--allow a --allow b`) accumulates
+// into an array instead of the last one silently winning.
+function setArg(out, key, value) {
+  if (key in out) {
+    out[key] = Array.isArray(out[key]) ? [...out[key], value] : [out[key], value];
+  } else {
+    out[key] = value;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        setArg(out, a.slice(2, eq), a.slice(eq + 1));
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-') && !BOOLEAN_FLAGS.has(key)) {
+          setArg(out, key, next);
+          i++;
+        } else {
+          setArg(out, key, true);
+        }
+      }
+    } else if (a.startsWith('-') && a.length === 2) {
+      out[a.slice(1)] = true;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// canner db …                                            — project databases
+//
+//   canner db [list] [--slug X]                          list the project's databases
+//   canner db init [--pg 17|18] [--slug X]               provision the primary database
+//   canner db create <name> [--pg 17|18]                 add another database (paid plans)
+//   canner db info [<name>] [--reveal]                   connection details (password hidden by default)
+//   canner db url [<name>]                               print just the connection string
+//   canner db rm <name> --yes                            delete an additional database
+//   canner db pg-version <name> <17|18> --yes            move a database to another Postgres version
+//   canner db export [<name>] [--format custom|plain] [--out FILE]
+//   canner db import <file> [--to <name>] [--replace]    restore a pg_dump custom-format file
+//   canner db migrate-in [--to <name>] --from <url>|--from-env VAR|--from - [--replace]
+//   canner db migrate-out [--from <name>] --to-url <url>|--to-env VAR|--to-url - --yes
+//   canner db copy <from> <to> [--to-project SLUG] [--replace]
+//   canner db ops [<id>]                                 recent operations / one operation
+//
+// Long operations (export, import, migrate, copy) run on the platform: the CLI
+// starts one, then waits and shows progress. Pass --no-wait to return the
+// operation id immediately (poll with `canner db ops <id>`).
+// ---------------------------------------------------------------------------
+const DB_OP_POLL_MS = 2000;
+
+function dbBase(slug) {
+  return `/projects/${encodeURIComponent(slug)}`;
+}
+
+function fmtBytes(n) {
+  if (n == null) return '—';
+  const u = ['B', 'KB', 'MB', 'GB'];
+  let i = 0;
+  let v = Number(n);
+  while (v >= 1024 && i < u.length - 1) { v /= 1024; i++; }
+  return `${v >= 10 || i === 0 ? Math.round(v) : v.toFixed(1)} ${u[i]}`;
+}
+
+// A connection URL is a secret: never take it from a positional argument that
+// ends up in shell history unless the user insists. --from/--to-url take a URL,
+// --from-env/--to-env read an environment variable, and "-" reads one line from stdin.
+async function readSecretArg(args, urlFlag, envFlag, what) {
+  if (args[envFlag]) {
+    const v = process.env[String(args[envFlag])];
+    if (!v) die(`environment variable ${args[envFlag]} is not set.`, 2);
+    return v.trim();
+  }
+  const v = args[urlFlag];
+  if (v === '-' || v === true) {
+    const rl = createInterface({ input, output: process.stderr, terminal: false });
+    const line = await rl.question(`${what} (postgres://user:password@host:port/db): `);
+    rl.close();
+    if (!line.trim()) die(`no ${what} given.`, 2);
+    return line.trim();
+  }
+  if (typeof v === 'string' && v) return v;
+  die(`give the ${what} with --${urlFlag} <url>, --${envFlag} <VAR>, or --${urlFlag} - to type it.`, 2);
+}
+
+function requireYes(args, message) {
+  if (args.yes === true || args.y === true) return;
+  die(`${message} Re-run with --yes to confirm.`, 2);
+}
+
+async function waitForOperation(creds, base, id, args) {
+  if (args['no-wait'] === true) return null;
+  const path = `${base}/database-operations/${encodeURIComponent(id)}`;
+  let last = '';
+  for (;;) {
+    const body = await apiJSON(creds, 'GET', path);
+    const op = body?.operation;
+    if (!op) die('lost track of the operation.');
+    if (op.state === 'succeeded') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      return op;
+    }
+    if (op.state === 'failed' || op.state === 'cancelled') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      die(op.error || `the operation ${op.state}.`);
+    }
+    if (!JSON_MODE) {
+      const p = op.progress ?? {};
+      const bit = p.bytes != null ? ` ${fmtBytes(p.bytes)}` : p.size_mb != null ? ` ${p.size_mb} MB` : '';
+      last = `  ${op.state}…${bit}`;
+      process.stderr.write('\r' + last);
+    }
+    await new Promise((r) => setTimeout(r, DB_OP_POLL_MS));
+  }
+}
+
+async function waitForBackup(creds, base, label, id, args) {
+  if (args['no-wait'] === true) return null;
+  const path = `${base}/databases/${encodeURIComponent(label)}/backups/${encodeURIComponent(id)}`;
+  let last = '';
+  for (;;) {
+    const body = await apiJSON(creds, 'GET', path);
+    const b = body?.backup;
+    if (!b) die('lost track of the backup.');
+    if (b.state === 'succeeded') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      return b;
+    }
+    if (b.state === 'failed') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      die(b.error || 'the backup failed.');
+    }
+    if (!JSON_MODE) {
+      last = '  running…';
+      process.stderr.write('\r' + last);
+    }
+    await new Promise((r) => setTimeout(r, DB_OP_POLL_MS));
+  }
+}
+
+async function startAndWait(creds, base, args, method, path, body, verb) {
+  const started = await apiJSON(creds, method, path, body);
+  const op = started?.operation;
+  if (!op) die('the platform did not return an operation.');
+  if (args['no-wait'] === true) {
+    if (JSON_MODE) emitJSON(op);
+    else { info(`${green('started')} ${verb} ${dim(op.id)}`); muted(`Check it with: canner db ops ${op.id}`); }
+    return null;
+  }
+  if (!JSON_MODE) info(`${verb}…`);
+  return waitForOperation(creds, base, op.id, args);
+}
+
+async function cmdDb(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const base = dbBase(slug);
+  const sub = args._[0] ?? 'list';
+  const name = (i = 1) => args._[i] ?? 'primary';
+
+  if (sub === 'list' || sub === 'ls') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases`);
+    if (JSON_MODE) return emitJSON(body);
+    const rows = body?.databases ?? [];
+    if (rows.length === 0) { muted('no database yet. Create one with `canner db init`.'); return; }
+    info(`${pad(bold('NAME'), 22)}${pad(bold('POSTGRES'), 11)}${pad(bold('SIZE'), 11)}${bold('STATUS')}`);
+    for (const d of rows) {
+      const status = d.over_quota_at ? red('write-locked (over quota)') : green('ok');
+      info(`${pad(d.is_primary ? `${d.name} ${dim('(DATABASE_URL)')}` : d.name, 22)}${pad(d.pg_version, 11)}${pad(`${d.size_mb} MB`, 11)}${status}`);
+    }
+    const l = body?.limits;
+    if (l && !l.advanced_enabled) muted('Additional databases, import and migration are available on paid plans.');
+    return;
+  }
+
+  if (sub === 'init' || sub === 'provision') {
+    const body = await apiJSON(creds, 'POST', `${base}/database`, args.pg ? { pg_version: String(args.pg) } : {});
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.database;
+    info(`${green('provisioned')} ${bold('primary')} ${dim(`(Postgres ${d?.pg_version_full ?? d?.pg_version})`)}`);
+    muted('The connection string is injected as DATABASE_URL on your next deploy.');
+    return;
+  }
+
+  if (sub === 'create' || sub === 'add') {
+    const label = args._[1];
+    if (!label) die('usage: canner db create <name> [--pg 17|18]', 2);
+    const body = await apiJSON(creds, 'POST', `${base}/databases`, {
+      name: label,
+      ...(args.pg ? { pg_version: String(args.pg) } : {}),
+      ...(args.instance === true ? { instance: true } : {}),
+    });
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.database;
+    info(`${green('created')} ${bold(label)} ${dim(`(Postgres ${d?.pg_version_full ?? d?.pg_version})`)}`);
+    muted(`Injected into your app as DATABASE_URL_${label.toUpperCase()} on your next deploy.`);
+    return;
+  }
+
+  if (sub === 'info' || sub === 'show') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(name())}`);
+    const d = body?.database;
+    if (JSON_MODE) return emitJSON(args.reveal === true ? d : { ...d, password: null, connection_string: null });
+    info(`${bold(d.name)} ${dim(`Postgres ${d.pg_version_full ?? d.pg_version} · ${d.size_mb} MB`)}`);
+    info(`  user      ${d.db_user}`);
+    info(`  database  ${d.db_name}`);
+    info(`  password  ${args.reveal === true ? d.password : dim('•••••• (--reveal to show)')}`);
+    if (args.reveal === true) info(`  url       ${d.connection_string}`);
+    return;
+  }
+
+  if (sub === 'url') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(name())}`);
+    const d = body?.database;
+    if (JSON_MODE) return emitJSON({ url: d.connection_string });
+    process.stdout.write(`${d.connection_string}\n`);
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'delete') {
+    const label = args._[1];
+    if (!label) die('usage: canner db rm <name> --yes', 2);
+    requireYes(args, `This permanently deletes the database "${label}" and everything in it.`);
+    await apiJSON(creds, 'DELETE', `${base}/databases/${encodeURIComponent(label)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: label });
+    info(`${green('deleted')} ${bold(label)}`);
+    return;
+  }
+
+  if (sub === 'pg-version') {
+    const label = args._[1];
+    const target = args._[2];
+    if (!label || !target) die('usage: canner db pg-version <name> <17|18> --yes', 2);
+    requireYes(args, 'Changing the Postgres version dumps and restores the database, with downtime while it runs.');
+    const body = await apiJSON(creds, 'PATCH', `${base}/databases/${encodeURIComponent(label)}/pg-version`, { target_version: String(target), confirm: true });
+    if (JSON_MODE) return emitJSON(body);
+    info(`${green('moved')} ${bold(label)} from Postgres ${body.from_version} to ${body.to_version}. The connection string is unchanged.`);
+    return;
+  }
+
+  if (sub === 'export') {
+    const label = name();
+    const format = args.format === 'plain' ? 'plain' : 'custom';
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(label)}/exports`, { format }, 'exporting');
+    if (!done) return;
+    const out = resolve(typeof args.out === 'string' ? args.out : done.result.file_name);
+    const res = await apiRequest(creds, 'GET', `${base}/database-operations/${encodeURIComponent(done.id)}/download`);
+    const { Readable } = await import('node:stream');
+    const { pipeline } = await import('node:stream/promises');
+    const { createWriteStream } = await import('node:fs');
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(out, { mode: 0o600 }));
+    if (JSON_MODE) return emitJSON({ file: out, bytes: done.result.bytes, sha256: done.result.sha256, format });
+    info(`${green('exported')} ${bold(label)} → ${cyan(out)} ${dim(`(${fmtBytes(done.result.bytes)}, sha256 ${done.result.sha256.slice(0, 12)}…)`)}`);
+    muted(`Restore with: ${done.result.restore_hint}`);
+    return;
+  }
+
+  if (sub === 'import') {
+    const file = args._[1];
+    if (!file) die('usage: canner db import <file.dump> [--to <name>] [--replace]', 2);
+    const to = typeof args.to === 'string' ? args.to : 'primary';
+    const size = (await stat(resolve(file))).size;
+    const { createReadStream } = await import('node:fs');
+    if (!JSON_MODE) info(`uploading ${basename(file)} (${fmtBytes(size)})…`);
+    const res = await apiRequest(creds, 'POST',
+      `${base}/databases/${encodeURIComponent(to)}/imports${args.replace === true ? '?replace=true' : ''}`,
+      { headers: { 'Content-Type': 'application/octet-stream', 'Content-Length': String(size) }, body: createReadStream(resolve(file)), duplex: 'half' });
+    const started = await res.json();
+    const opId = started?.operation?.id;
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(started.operation);
+      info(`${green('started')} import ${dim(opId)}`);
+      return;
+    }
+    if (!JSON_MODE) info('restoring…');
+    const done = await waitForOperation(creds, base, opId, args);
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('imported')} into ${bold(to)}`);
+    if (done.result?.snapshot) muted(`A snapshot of the previous contents was kept for 7 days (${fmtBytes(done.result.snapshot.bytes)}).`);
+    return;
+  }
+
+  if (sub === 'migrate-in') {
+    const to = typeof args.to === 'string' ? args.to : 'primary';
+    const url = await readSecretArg(args, 'from', 'from-env', 'source connection URL');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(to)}/migrate-in`,
+      { url, replace: args.replace === true }, 'migrating in');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('migrated')} ${dim(done.result?.source_host ?? '')} → ${bold(to)}`);
+    return;
+  }
+
+  if (sub === 'migrate-out') {
+    const from = typeof args.from === 'string' ? args.from : 'primary';
+    requireYes(args, 'This writes this database into the server you name.');
+    const url = await readSecretArg(args, 'to-url', 'to-env', 'target connection URL');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(from)}/migrate-out`,
+      { url, replace: args.replace === true, confirm: true }, 'migrating out');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('migrated')} ${bold(from)} → ${dim(done.result?.target_host ?? '')}`);
+    return;
+  }
+
+  if (sub === 'copy') {
+    const from = args._[1];
+    const to = args._[2];
+    if (!from || !to) die('usage: canner db copy <from> <to> [--to-project SLUG] [--replace]', 2);
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(from)}/copy`,
+      { target_name: to, ...(args['to-project'] ? { target_project: String(args['to-project']) } : {}), replace: args.replace === true }, 'copying');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('copied')} ${bold(from)} → ${bold(to)}`);
+    return;
+  }
+
+  if (sub === 'ops' || sub === 'operations') {
+    const id = args._[1];
+    if (id) {
+      const body = await apiJSON(creds, 'GET', `${base}/database-operations/${encodeURIComponent(id)}`);
+      if (JSON_MODE) return emitJSON(body.operation);
+      const o = body.operation;
+      info(`${bold(o.kind)} ${dim(o.id)}  ${o.state === 'succeeded' ? green(o.state) : o.state === 'failed' ? red(o.state) : yellow(o.state)}`);
+      if (o.error) info(`  ${red(o.error)}`);
+      if (o.progress?.bytes != null) info(`  ${fmtBytes(o.progress.bytes)} written`);
+      if (o.progress?.size_mb != null) info(`  target is ${o.progress.size_mb} MB`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', `${base}/database-operations`);
+    const rows = body?.operations ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) { muted('no database operations yet.'); return; }
+    info(`${pad(bold('ID'), 12)}${pad(bold('KIND'), 14)}${pad(bold('STATE'), 12)}${bold('WHEN')}`);
+    for (const o of rows) {
+      info(`${pad(o.id.slice(0, 8), 12)}${pad(o.kind, 14)}${pad(o.state === 'succeeded' ? green(o.state) : o.state === 'failed' ? red(o.state) : yellow(o.state), 12)}${dim(relTime(o.created_at))}`);
+    }
+    return;
+  }
+
+  if (sub === 'external' || sub === 'external-access') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/external-access`;
+
+    if (args.disable === true) {
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: false });
+      if (JSON_MODE) return emitJSON(body.external_access);
+      info(`${green('disabled')} external access on ${bold(label)}`);
+      return;
+    }
+    if (args.enable === true || args.allow !== undefined || args['allow-all'] === true) {
+      const allowlist = args.allow === undefined ? [] : (Array.isArray(args.allow) ? args.allow : [args.allow]).map(String);
+      if (args['allow-all'] === true) {
+        requireYes(args, 'This allows connections to this database from anywhere on the internet.');
+        allowlist.push('0.0.0.0/0', '::/0');
+      }
+      if (allowlist.length === 0) die('give at least one --allow <cidr>, or --allow-all --yes.', 2);
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: true, allowlist, allow_open: args['allow-all'] === true });
+      if (JSON_MODE) return emitJSON(body.external_access);
+      const ea = body.external_access;
+      info(`${green('enabled')} external access on ${bold(label)}`);
+      info(`  ${ea.host}:${ea.port}`);
+      info(`  allowed: ${ea.allowlist.join(', ')}`);
+      return;
+    }
+    // No mutating flag: show current status.
+    const body = await apiJSON(creds, 'GET', path);
+    const ea = body.external_access;
+    if (JSON_MODE) return emitJSON(ea);
+    info(`${bold(label)}  ${ea.enabled ? green('enabled') : dim('disabled')}`);
+    info(`  ${ea.host}:${ea.port}${!ea.configured ? dim('  (not available on this platform instance yet)') : ''}`);
+    if (ea.enabled) info(`  allowed: ${ea.allowlist.length ? ea.allowlist.join(', ') : dim('(none)')}`);
+    return;
+  }
+
+  if (sub === 'rotate' || sub === 'rotate-credentials') {
+    const label = args._[1] ?? 'primary';
+    requireYes(args, 'This changes the password — your app needs the new DATABASE_URL from the next deploy.');
+    const body = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/rotate-credentials`);
+    if (JSON_MODE) return emitJSON(body.database);
+    info(`${green('rotated')} the password for ${bold(label)}.`);
+    muted('Redeploy to pick up the new DATABASE_URL.');
+    return;
+  }
+
+  if (sub === 'backup-policy') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/backup-policy`;
+
+    if (args.disable === true) {
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: false });
+      if (JSON_MODE) return emitJSON(body.policy);
+      info(`${green('disabled')} scheduled backups on ${bold(label)}`);
+      return;
+    }
+    const setting = args.enable === true || args.every !== undefined || args.keep !== undefined || args['keep-count'] !== undefined || args.offsite !== undefined;
+    if (setting) {
+      const patch = {};
+      if (args.enable === true) patch.enabled = true;
+      if (args.every !== undefined) patch.interval_hours = Number(args.every);
+      if (args.keep !== undefined) patch.retention_days = Number(args.keep);
+      if (args['keep-count'] !== undefined) patch.retention_count = args['keep-count'] === 'none' ? null : Number(args['keep-count']);
+      if (args.offsite !== undefined) {
+        if (args.offsite === 'off' || args.offsite === 'none') patch.offsite_destination_id = null;
+        else if (typeof args.offsite === 'string' && args.offsite !== 'on') {
+          const all = (await apiJSON(creds, 'GET', `${base}/backup-destinations`)).destinations;
+          const hit = all.find((d) => d.id === args.offsite || d.name.toLowerCase() === args.offsite.toLowerCase());
+          if (!hit) die(`no destination "${args.offsite}". List them with: canner db offsite`, 1);
+          patch.offsite_destination_id = hit.id;
+        } else die('--offsite takes a destination name (see: canner db offsite) or off.', 2);
+      }
+      const body = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(body.policy);
+      const p = body.policy;
+      info(`${green('set')} backup policy for ${bold(label)}: every ${p.interval_hours}h, keep ${p.retention_days}d${p.retention_count ? ` (max ${p.retention_count})` : ''}`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', path);
+    const p = body.policy;
+    if (JSON_MODE) return emitJSON(p);
+    info(`${bold(label)}  ${p.enabled ? green('enabled') : dim('disabled')}`);
+    info(`  every ${p.interval_hours}h, keep ${p.retention_days}d${p.retention_count ? `, max ${p.retention_count} backups` : ''}`);
+    info(`  off-site copy ${p.offsite ? green('on') : dim('off')}`);
+    if (p.enabled && p.next_run_at) info(`  next run ${dim(relTime(p.next_run_at))}`);
+    return;
+  }
+
+  if (sub === 'backup') {
+    const label = name();
+    const started = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/backups`);
+    const b = started?.backup;
+    if (!b) die('the platform did not return a backup.');
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(b);
+      info(`${green('started')} backup ${dim(b.id)}`);
+      muted(`Check it with: canner db backups ${label} ${b.id}`);
+      return;
+    }
+    if (!JSON_MODE) info('backing up…');
+    const done = await waitForBackup(creds, base, label, b.id, args);
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('backed up')} ${bold(label)} ${dim(`(${fmtBytes(done.bytes)}, sha256 ${done.sha256.slice(0, 12)}…)`)}`);
+    return;
+  }
+
+  if (sub === 'backups') {
+    const label = args._[1] ?? 'primary';
+    const id = args._[2];
+    const listPath = `${base}/databases/${encodeURIComponent(label)}/backups`;
+
+    if (!id) {
+      const body = await apiJSON(creds, 'GET', listPath);
+      const rows = body?.backups ?? [];
+      if (JSON_MODE) return emitJSON(rows);
+      if (rows.length === 0) { muted(`no backups yet for ${label}. Create one with \`canner db backup ${label}\`.`); return; }
+      info(`${pad(bold('ID'), 12)}${pad(bold('KIND'), 11)}${pad(bold('STATE'), 12)}${pad(bold('SIZE'), 11)}${bold('WHEN')}`);
+      for (const b of rows) {
+        const state = b.state === 'succeeded' ? green(b.state) : b.state === 'failed' ? red(b.state) : yellow(b.state);
+        info(`${pad(b.id.slice(0, 8), 12)}${pad(b.kind, 11)}${pad(state, 12)}${pad(b.bytes != null ? fmtBytes(b.bytes) : '—', 11)}${dim(relTime(b.created_at))}`);
+      }
+      return;
+    }
+
+    const itemPath = `${listPath}/${encodeURIComponent(id)}`;
+
+    if (args.rm === true || args.delete === true) {
+      requireYes(args, 'This permanently deletes the backup — its encryption key is destroyed immediately, so this cannot be undone.');
+      await apiJSON(creds, 'DELETE', itemPath);
+      if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+      info(`${green('deleted')} backup ${dim(id.slice(0, 8))}`);
+      return;
+    }
+
+    if (args.restore === true) {
+      const to = typeof args.to === 'string' ? args.to : undefined;
+      if (to) requireYes(args, `This replaces the contents of "${to}" with this backup (Canner takes a snapshot first).`);
+      const inspect = args.inspect === true;
+      if (inspect && to) die('--inspect restores into a new temporary database; it cannot be combined with --to.', 2);
+      const body = await apiJSON(creds, 'POST', `${itemPath}/restore`, to ? { target_name: to, confirm: true } : inspect ? { inspect: true } : {});
+      const opId = body?.operation_id;
+      if (args['no-wait'] === true) {
+        if (JSON_MODE) return emitJSON(body);
+        info(`${green('started')} restore ${dim(opId)} → ${bold(body.database.name)}`);
+        muted(`Check it with: canner db ops ${opId}`);
+        return;
+      }
+      if (!JSON_MODE) info('restoring…');
+      const done = await waitForOperation(creds, base, opId, args);
+      if (JSON_MODE) return emitJSON({ ...done, database: body.database });
+      info(`${green('restored')} into ${bold(body.database.name)}`);
+      if (inspect) muted(`Temporary inspect database (deleted ${dim(relTime(body.inspect_expires_at))}). Compare it: canner db diff ${body.database.name}. Keep it: canner db inspect ${body.database.name} --keep`);
+      return;
+    }
+
+    if (args.offsite !== undefined) {
+      const body = {};
+      if (typeof args.offsite === 'string') {
+        const all = (await apiJSON(creds, 'GET', `${base}/backup-destinations`)).destinations;
+        const hit = all.find((d) => d.id === args.offsite || d.name.toLowerCase() === args.offsite.toLowerCase());
+        if (!hit) die(`no destination "${args.offsite}". List them with: canner db offsite`, 1);
+        body.destination_id = hit.id;
+      }
+      await apiJSON(creds, 'POST', `${itemPath}/offsite`, body);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('copied')} backup ${dim(id.slice(0, 8))} to your off-site bucket`);
+      return;
+    }
+
+    if (args.verify === true) {
+      const body = await apiJSON(creds, 'POST', `${itemPath}/verify`);
+      const opId = body?.operation_id;
+      if (args['no-wait'] === true) {
+        if (JSON_MODE) return emitJSON(body);
+        info(`${green('started')} test restore ${dim(opId)}`);
+        return;
+      }
+      if (!JSON_MODE) info('test-restoring…');
+      const done = await waitForOperation(creds, base, opId, args);
+      if (JSON_MODE) return emitJSON(done);
+      info(`${green('verified')} backup ${dim(id.slice(0, 8))}: ${done?.result?.tables ?? '?'} tables restored and readable`);
+      return;
+    }
+
+    if (args.download === true) {
+      const out = resolve(typeof args.out === 'string' ? args.out : `${label}-${id.slice(0, 8)}.dump`);
+      const res = await apiRequest(creds, 'GET', `${itemPath}/download`);
+      const { Readable } = await import('node:stream');
+      const { pipeline } = await import('node:stream/promises');
+      const { createWriteStream } = await import('node:fs');
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(out, { mode: 0o600 }));
+      if (JSON_MODE) return emitJSON({ file: out });
+      info(`${green('downloaded')} → ${cyan(out)}`);
+      return;
+    }
+
+    const body = await apiJSON(creds, 'GET', itemPath);
+    const b = body?.backup;
+    if (JSON_MODE) return emitJSON(b);
+    info(`${bold(b.id)} ${dim(b.kind)}  ${b.state === 'succeeded' ? green(b.state) : b.state === 'failed' ? red(b.state) : yellow(b.state)}`);
+    if (b.error) info(`  ${red(b.error)}`);
+    if (b.bytes != null) info(`  ${fmtBytes(b.bytes)}`);
+    if (b.expires_at) info(`  expires ${dim(relTime(b.expires_at))}`);
+    return;
+  }
+
+  if (sub === 'diff') {
+    const label = args._[1];
+    if (!label) die('usage: canner db diff <name> [--against <name>]', 2);
+    const q = typeof args.against === 'string' ? `?against=${encodeURIComponent(args.against)}` : '';
+    const d = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/diff${q}`);
+    if (JSON_MODE) return emitJSON(d);
+    info(`${bold(d.to)} compared with ${bold(d.from)}: ${d.summary.added} only in ${d.to}, ${d.summary.removed} missing, ${d.summary.changed} different, ${d.summary.same} same`);
+    for (const t of d.tables.filter((x) => x.status !== 'same')) {
+      const tag = t.status === 'added' ? green('added  ') : t.status === 'removed' ? red('missing') : yellow('changed');
+      info(`  ${tag} ${pad(t.table, 32)} ${dim(`${t.rows_from ?? '?'} → ${t.rows_to ?? '?'} rows`)}`);
+    }
+    return;
+  }
+
+  if (sub === 'inspect') {
+    const label = args._[1];
+    if (!label) die('usage: canner db inspect <name> --keep | --extend HOURS', 2);
+    const body = args.keep === true ? { keep: true } : args.extend !== undefined ? { hours: Number(args.extend) } : null;
+    if (!body) die('use --keep to make it permanent, or --extend HOURS to push the expiry out.', 2);
+    await apiJSON(creds, 'PATCH', `${base}/databases/${encodeURIComponent(label)}/inspect`, body);
+    if (JSON_MODE) return emitJSON({ ok: true });
+    info(`${green('updated')} ${bold(label)}`);
+    return;
+  }
+
+  if (sub === 'resources') {
+    const path = `${base}/instance/resources`;
+    const action = args._[1];
+    const mb = (n) => (n >= 1024 ? `${(n / 1024).toFixed(n % 1024 === 0 ? 0 : 1)} GB` : `${n} MB`);
+    if (action === 'apply') {
+      requireYes(args, 'Applying restarts your dedicated instance; connections drop for a few seconds.');
+      const r = await apiJSON(creds, 'POST', `${path}/apply`, { confirm: true });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('applied')} the memory budget${r.limits_applied ? '' : yellow(' (hard limit pending on the host)')}`);
+      if (r.redeploy_recommended) muted('Your app memory limit was lowered to its new ceiling. Redeploy the app to use it.');
+      return;
+    }
+    if (action === 'set') {
+      const patch = {};
+      if (args.share !== undefined) patch.pg_share_pct = Number(args.share);
+      if (args['app-reserved'] !== undefined) {
+        const cur = (await apiJSON(creds, 'GET', path)).resources.budget;
+        patch.reserved_to_pg_mb = cur.reserved_purchased_mb - Math.round(Number(args['app-reserved']) * 1024);
+      }
+      if (Object.keys(patch).length === 0) die('nothing to change. Use --share PCT (10-90) or --app-reserved GB.', 2);
+      const r = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(r.resources);
+      info(`${green('saved')} the split. It takes effect with: canner db resources apply --yes`);
+      return;
+    }
+    const r = (await apiJSON(creds, 'GET', path)).resources;
+    if (JSON_MODE) return emitJSON(r);
+    const b = r.budget;
+    info(`${bold('postgres')}  ${mb(b.pg.total_mb)}  (${mb(b.pg.reserved_mb)} guaranteed, ${mb(b.pg.pooled_mb)} shared)`);
+    info(`${bold('app')}       ${mb(b.app.ceiling_mb)}  (${mb(b.app.reserved_mb)} guaranteed, ${mb(b.app.pooled_mb)} shared)`);
+    info(`  Postgres takes ${b.pg_share_pct}% of the shared memory; reserved RAM bought: ${mb(b.reserved_purchased_mb)} (+ ${mb(b.reserved_included_mb)} included)`);
+    info(`  ${r.applied ? `in force: ${mb(r.applied.max_mb)} limit, ${dim(relTime(r.applied.at))}` : 'not applied yet'}${r.pending ? yellow('  (changes pending: canner db resources apply --yes)') : ''}`);
+    if (r.applied?.error) info(`  ${yellow(r.applied.error)}`);
+    return;
+  }
+
+  if (sub === 'extensions') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/extensions`;
+    if (action === 'install') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> install <extension> [--window] [--yes]', 2);
+      const needsRestart = name === 'pg_cron';
+      if (needsRestart) requireYes(args, `${name} loads a library at startup: installing it restarts your instance${args.window === true ? ' in the next maintenance window' : ' now; connections drop for a few seconds'}.`);
+      const r = await apiJSON(creds, 'POST', path, { extension: name, when: args.window === true ? 'window' : 'now', confirm: needsRestart ? true : undefined });
+      if (JSON_MODE) return emitJSON(r);
+      if (r.restart && !r.restart.restarted) info(`${yellow('scheduled')} ${bold(name)}: the instance restarts at the next maintenance window (${r.restart.scheduled_for ?? 'unknown'}) and installs it then.`);
+      else info(`${green('installed')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'update') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> update <extension>', 2);
+      const r = await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/update`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('updated')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'rm') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> rm <extension> --yes', 2);
+      requireYes(args, `This removes ${name} from the database. Nothing is removed if objects still use it.`);
+      const r = await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('removed')} ${bold(name)}${r.restart_pending ? dim('  (the library stops loading at the next restart)') : ''}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    for (const e of r.extensions) {
+      const state = e.installed_version ? green(`installed ${e.installed_version}`) : e.available ? dim('available') : red('unavailable');
+      info(`${pad(bold(e.id), 24)}${pad(state, 24)}${e.update_available ? yellow(`update to ${e.default_version}  `) : ''}${dim(e.description)}${e.preload ? dim('  (restarts the instance)') : ''}`);
+    }
+    if (r.pg_cron_database) muted(`pg_cron runs in the database "${r.pg_cron_database}".`);
+    return;
+  }
+
+  if (sub === 'tuning') {
+    const path = `${base}/instance/config`;
+    const patch = {};
+    if (typeof args.preset === 'string') patch.preset = args.preset.replace(/-/g, '_');
+    const ov = {};
+    if (args['statement-timeout'] !== undefined) ov.statement_timeout_ms = Math.round(Number(args['statement-timeout']) * 1000);
+    if (args['idle-timeout'] !== undefined) ov.idle_in_transaction_timeout_ms = Math.round(Number(args['idle-timeout']) * 1000);
+    if (args['lock-timeout'] !== undefined) ov.lock_timeout_ms = Math.round(Number(args['lock-timeout']) * 1000);
+    if (Object.keys(ov).length > 0) {
+      const cur = (await apiJSON(creds, 'GET', path)).config.overrides;
+      patch.overrides = { ...cur, ...ov };
+    }
+    if (args['window-day'] !== undefined || args['window-hour'] !== undefined || args['window-tz'] !== undefined) {
+      const cur = (await apiJSON(creds, 'GET', path)).config.window;
+      patch.window = {
+        day: args['window-day'] === undefined ? cur.day : args['window-day'] === 'all' ? null : Number(args['window-day']),
+        hour: args['window-hour'] === undefined ? cur.hour : Number(args['window-hour']),
+        tz: typeof args['window-tz'] === 'string' ? args['window-tz'] : cur.tz,
+      };
+    }
+    const r = Object.keys(patch).length > 0 ? await apiJSON(creds, 'PATCH', path, patch) : await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.config);
+    const c = r.config;
+    if (Object.keys(patch).length > 0) info(`${green('saved')}. No restart needed.`);
+    const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+    const secs = (ms) => (ms ? `${ms / 1000} s` : 'none');
+    info(`${bold('preset')}   ${c.preset}  ${dim(`(${c.presets.join(' | ')})`)}`);
+    info(`${bold('timeouts')} statement ${secs(c.overrides.statement_timeout_ms)}, idle in transaction ${secs(c.overrides.idle_in_transaction_timeout_ms)}, lock wait ${secs(c.overrides.lock_timeout_ms)}`);
+    info(`${bold('window')}   ${c.window.day === null ? 'every day' : days[c.window.day]} ${String(c.window.hour).padStart(2, '0')}:00 for two hours, ${c.window.tz}${c.window_open ? green('  (open now)') : c.next_window ? dim(`  (next ${relTime(c.next_window)})`) : ''}`);
+    if (c.restart.waiting_for_window) info(yellow(`  a restart is waiting for the window; do it now with: canner db restart --yes`));
+    if (c.restart.settings.length > 0) info(yellow(`  waiting for a restart: ${c.restart.settings.join(', ')}`));
+    return;
+  }
+
+  if (sub === 'restart') {
+    requireYes(args, 'Restarting your dedicated instance drops connections for a few seconds.');
+    const r = await apiJSON(creds, 'POST', `${base}/instance/restart`, { confirm: true });
+    if (JSON_MODE) return emitJSON(r);
+    info(`${green('restarted')} the instance${r.failed_actions ? yellow(` (${r.failed_actions} queued action(s) failed)`) : ''}`);
+    return;
+  }
+
+  if (sub === 'replication') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/replication`;
+    const inst = `${base}/instance/replication`;
+    if (action === 'on') {
+      requireYes(args, `Turning logical replication on restarts your instance${args.window === true ? ' in the next maintenance window' : ' now; connections drop for a few seconds'}.`);
+      const body = { enabled: true, when: args.window === true ? 'window' : 'now', confirm: true };
+      if (args.cap !== undefined) body.cap_mb = Number(args.cap);
+      const r = await apiJSON(creds, 'POST', inst, body);
+      if (JSON_MODE) return emitJSON(r);
+      info(r.restart && !r.restart.restarted ? `${yellow('scheduled')}: the instance restarts at the next maintenance window (${r.restart.scheduled_for ?? 'unknown'}).` : `${green('on')} logical replication`);
+      muted(`Next: create a login with \`canner db roles ${label} create <name> --replication\` and a publication with \`canner db replication ${label} pub <name> --all\`.`);
+      return;
+    }
+    if (action === 'off') {
+      requireYes(args, 'Turning logical replication off restarts your instance for a few seconds. Remove every slot and replication role first.');
+      const r = await apiJSON(creds, 'POST', inst, { enabled: false, when: args.window === true ? 'window' : 'now', confirm: true });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('off')} logical replication`);
+      return;
+    }
+    if (action === 'cap') {
+      const mb = Number(args._[3]);
+      if (!Number.isFinite(mb)) die('usage: canner db replication <db> cap <MB>', 2);
+      const r = await apiJSON(creds, 'PATCH', inst, { cap_mb: mb });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('set')} the limit on WAL held back per slot to ${mb} MB (no restart)`);
+      return;
+    }
+    if (action === 'pub') {
+      const name = args._[3];
+      if (!name) die('usage: canner db replication <db> pub <name> --all | --tables schema.table,schema.table', 2);
+      const body = args.all === true ? { name, all_tables: true } : { name, tables: String(args.tables ?? '').split(',').map((x) => x.trim()).filter(Boolean) };
+      if (args.all !== true && body.tables.length === 0) die('give --all or --tables schema.table,schema.table.', 2);
+      const r = await apiJSON(creds, 'POST', `${path}/publications`, body);
+      if (JSON_MODE) return emitJSON(r.replication);
+      info(`${green('created')} publication ${bold(name)}`);
+      return;
+    }
+    if (action === 'unpub' || action === 'drop-slot') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db replication <db> ${action} <name> --yes`, 2);
+      requireYes(args, action === 'unpub' ? `This drops the publication "${name}"; subscribers that use it stop receiving changes.` : `This drops the slot "${name}" and disconnects its subscriber, which cannot resume.`);
+      const r = await apiJSON(creds, 'DELETE', `${path}/${action === 'unpub' ? 'publications' : 'slots'}/${encodeURIComponent(name)}`);
+      if (JSON_MODE) return emitJSON(r.replication);
+      info(`${green('dropped')} ${action === 'unpub' ? 'publication' : 'slot'} ${bold(name)}`);
+      return;
+    }
+    const r = (await apiJSON(creds, 'GET', path)).replication;
+    if (JSON_MODE) return emitJSON(r);
+    info(`logical replication ${r.active ? green('on') : r.enabled ? yellow('saved, waiting for a restart') : dim('off')}  ${dim(`(limit ${r.cap_mb} MB of WAL per slot)`)}`);
+    for (const p of r.publications) info(`  publication ${bold(p.name)}  ${dim(p.all_tables ? 'all tables' : p.tables.join(', '))}`);
+    for (const x of r.slots) {
+      const tone = x.health === 'ok' ? green : x.health === 'lost' || x.health === 'critical' ? red : yellow;
+      info(`  slot ${bold(x.slot_name)}  ${tone(x.health)}  ${dim(`${x.retained_mb} MB held back (${x.percent_of_cap}% of the limit)`)}`);
+    }
+    return;
+  }
+
+  if (sub === 'subscriptions') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/subscriptions`;
+    if (action === 'add') {
+      const name = args._[3];
+      if (!name || typeof args.publication !== 'string') die('usage: canner db subscriptions <db> add <name> --from <url>|--from-env VAR|--from - --publication p1,p2 [--no-copy]', 2);
+      const url = await readSecretArg(args, 'from', 'from-env', 'connection URL of the server to follow');
+      const body = { name, url, publications: args.publication.split(',').map((x) => x.trim()).filter(Boolean), copy_data: args['no-copy'] !== true };
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.subscription);
+      info(`${green('following')} ${bold(r.subscription.publications.join(', '))} on ${r.subscription.host}:${r.subscription.port}/${r.subscription.remote_db} as ${bold(name)}`);
+      muted(`The existing rows are copied first. Watch it with: canner db subscriptions ${label}`);
+      return;
+    }
+    if (action === 'refresh' || action === 'pause' || action === 'resume') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db subscriptions <db> ${action} <name>`, 2);
+      const r = action === 'refresh'
+        ? await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/refresh`)
+        : await apiJSON(creds, 'PATCH', `${path}/${encodeURIComponent(name)}`, { enabled: action === 'resume' });
+      if (JSON_MODE) return emitJSON(r.subscriptions);
+      info(`${green(action === 'refresh' ? 'refreshed' : action === 'pause' ? 'paused' : 'resumed')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'rm') {
+      const name = args._[3];
+      if (!name) die('usage: canner db subscriptions <db> rm <name> [--force] --yes', 2);
+      requireYes(args, `This stops following with "${name}" and removes its replication slot on the other server. Rows already copied stay.`);
+      await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}${args.force === true ? '?force=true' : ''}`);
+      if (JSON_MODE) return emitJSON({ ok: true, removed: name });
+      info(`${green('stopped')} following with ${bold(name)}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    if (r.subscriptions.length === 0) { muted(`not following any server. Start with: canner db subscriptions ${label} add <name> --from-env URL_VAR --publication <name>`); return; }
+    for (const x of r.subscriptions) {
+      const tone = x.health === 'streaming' ? green : x.health === 'error' ? red : x.health === 'disabled' ? yellow : cyan;
+      info(`${pad(bold(x.name), 22)}${tone(x.health)}  ${dim(`${x.remote_user}@${x.host}:${x.port}/${x.remote_db}  ${x.publications.join(',')}`)}`);
+      info(`  ${x.tables_ready}/${x.tables_total} tables in step${x.last_message_at ? `, last change ${relTime(x.last_message_at)}` : ''}${x.apply_errors ? red(`, ${x.apply_errors} error(s)`) : ''}`);
+    }
+    return;
+  }
+
+  if (sub === 'metrics') {
+    const label = args._[1] ?? 'primary';
+    const range = typeof args.range === 'string' ? args.range : '24h';
+    const m = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/metrics?range=${encodeURIComponent(range)}`);
+    if (JSON_MODE) return emitJSON(m);
+    const pts = m.database.points;
+    if (m.database.samples === 0) { muted('no samples yet: metrics appear a few minutes after a database is created.'); return; }
+    const tx = pts.reduce((n, p) => n + p.transactions, 0);
+    const conns = pts.map((p) => p.connections).filter((v) => v !== null);
+    const hits = pts.map((p) => p.cache_hit).filter((v) => v !== null);
+    info(`${bold(label)}  last ${range}`);
+    info(`  transactions   ${tx.toLocaleString()}  (${pts.reduce((n, p) => n + p.rollbacks, 0).toLocaleString()} rolled back)`);
+    info(`  connections    peak ${conns.length ? Math.max(...conns) : '—'}`);
+    info(`  cache hit      ${hits.length ? (100 * hits.reduce((a, b) => a + b, 0) / hits.length).toFixed(1) + '%' : '—'}`);
+    const last = [...pts].reverse().find((p) => p.size_bytes !== null);
+    if (last) info(`  size           ${fmtBytes(last.size_bytes)}`);
+    if (m.instance) {
+      const ip = m.instance.points;
+      const mem = ip.map((p) => p.mem_current).filter((v) => v !== null);
+      const cpu = ip.map((p) => p.cpu_cores).filter((v) => v !== null);
+      info(`  instance       memory peak ${mem.length ? fmtBytes(Math.max(...mem)) : '—'}, cpu peak ${cpu.length ? Math.max(...cpu).toFixed(2) + ' cores' : '—'}`);
+    }
+    return;
+  }
+
+  if (sub === 'monitoring') {
+    const path = `${base}/instance/monitoring`;
+    const action = args._[1];
+    if (action === 'on' || action === 'off') {
+      const on = action === 'on';
+      requireYes(args, on ? 'Turning monitoring on restarts your instance; connections drop for a few seconds.' : 'Turning monitoring off removes query statistics and logs and restarts your instance for a few seconds.');
+      const body = { enabled: on, confirm: true };
+      if (args['slow-ms'] !== undefined) body.slow_ms = Number(args['slow-ms']);
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.monitoring);
+      info(`${green(on ? 'on' : 'off')} query insights and logs${on ? `, logging statements slower than ${r.monitoring.slow_ms} ms` : ''}`);
+      return;
+    }
+    if (args['slow-ms'] !== undefined) {
+      const r = await apiJSON(creds, 'POST', path, { enabled: true, slow_ms: Number(args['slow-ms']) });
+      if (JSON_MODE) return emitJSON(r.monitoring);
+      info(`${green('set')} slow-query threshold to ${r.monitoring.slow_ms} ms`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.monitoring);
+    info(`query insights and logs ${r.monitoring.enabled ? green('on') : dim('off')}  (slow threshold ${r.monitoring.slow_ms} ms)`);
+    return;
+  }
+
+  if (sub === 'insights') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/insights`;
+    if (args.reset === true) {
+      requireYes(args, 'This clears the collected query statistics for this database.');
+      await apiJSON(creds, 'POST', `${path}/reset`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('reset')} query statistics for ${bold(label)}`);
+      return;
+    }
+    const sort = typeof args.sort === 'string' ? args.sort : 'total';
+    const r = await apiJSON(creds, 'GET', `${path}?sort=${encodeURIComponent(sort)}&limit=${Number(args.limit ?? 10)}`);
+    if (JSON_MODE) return emitJSON(r.statements);
+    if (r.statements.length === 0) { muted('no statements yet.'); return; }
+    for (const st of r.statements) {
+      info(`${dim(`${st.calls.toLocaleString()}x  avg ${st.mean_ms} ms  total ${Math.round(st.total_ms).toLocaleString()} ms  max ${st.max_ms} ms`)}`);
+      info(`  ${st.query.replace(/\s+/g, ' ').slice(0, 200)}`);
+    }
+    return;
+  }
+
+  if (sub === 'logs') {
+    const label = args._[1] ?? 'primary';
+    const q = new URLSearchParams();
+    if (typeof args.level === 'string') q.set('level', args.level);
+    if (args['min-ms'] !== undefined) q.set('min_ms', String(args['min-ms']));
+    if (typeof args.search === 'string') q.set('q', args.search);
+    q.set('limit', String(Number(args.limit ?? 50)));
+    const r = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/logs?${q.toString()}`);
+    if (JSON_MODE) return emitJSON(r.entries);
+    if (r.entries.length === 0) { muted('no matching log lines.'); return; }
+    for (const e of r.entries) {
+      const lvl = e.level === 'ERROR' || e.level === 'FATAL' || e.level === 'PANIC' ? red(e.level) : e.level === 'WARNING' ? yellow(e.level) : dim(e.level);
+      info(`${dim(e.ts)} ${lvl} ${e.message.replace(/\s+/g, ' ')}`);
+      if (e.detail) info(`  ${dim(e.detail.replace(/\s+/g, ' '))}`);
+    }
+    return;
+  }
+
+  if (sub === 'roles') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/roles`;
+    if (action === 'create') {
+      const name = args._[3];
+      if (!name) die('usage: canner db roles <db> create <name> --read-only | --read-write | --replication', 2);
+      const picked = ['read-only', 'read-write', 'replication'].filter((k) => args[k] === true);
+      if (picked.length !== 1) die('choose exactly one of --read-only, --read-write or --replication.', 2);
+      const r = await apiJSON(creds, 'POST', path, { label: name, kind: picked[0].replace('-', '_') });
+      if (JSON_MODE) return emitJSON(r.role);
+      info(`${green('created')} ${r.role.kind === 'read_write' ? 'read-write' : r.role.kind === 'replication' ? 'replication' : 'read-only'} role ${bold(r.role.label)}`);
+      info(`  ${cyan(r.role.connection_string)}`);
+      return;
+    }
+    if (action === 'rotate' || action === 'rm') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db roles <db> ${action} <name> --yes`, 2);
+      requireYes(args, action === 'rm' ? `This drops the role "${name}"; anything using its connection string stops working.` : `This gives "${name}" a new password; anything using the old one stops working.`);
+      if (action === 'rm') {
+        await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}`);
+        if (JSON_MODE) return emitJSON({ ok: true, deleted: name });
+        info(`${green('deleted')} role ${bold(name)}`);
+      } else {
+        const r = await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/rotate`);
+        if (JSON_MODE) return emitJSON(r.role);
+        info(`${green('rotated')} ${bold(name)}: ${cyan(r.role.connection_string)}`);
+      }
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.roles);
+    if (r.roles.length === 0) { muted(`no roles on ${label}. Create one with \`canner db roles ${label} create <name> --read-only\`.`); return; }
+    for (const x of r.roles) {
+      info(`${pad(bold(x.label), 22)}${x.kind === 'read_write' ? yellow('read-write') : x.kind === 'replication' ? cyan('replication') : green('read-only')}  ${dim(relTime(x.created_at))}`);
+      info(`  ${cyan(x.connection_string)}`);
+      if (x.external_connection_string) info(`  ${cyan(x.external_connection_string)}`);
+    }
+    return;
+  }
+
+  if (sub === 'offsite') {
+    const action = args._[1];
+    const path = `${base}/backup-destinations`;
+    const listAll = async () => (await apiJSON(creds, 'GET', path)).destinations;
+    const find = async (ref) => {
+      const all = await listAll();
+      const hit = all.find((d) => d.id === ref || d.name.toLowerCase() === String(ref).toLowerCase());
+      if (!hit) die(`no destination "${ref}". List them with: canner db offsite`, 1);
+      return hit;
+    };
+    const fields = (body) => {
+      if (typeof args.endpoint === 'string') body.endpoint = args.endpoint;
+      if (typeof args.bucket === 'string') body.bucket = args.bucket;
+      if (typeof args.region === 'string') body.region = args.region;
+      if (typeof args.folder === 'string') body.prefix = args.folder;
+      if (typeof args['access-key'] === 'string') body.access_key = args['access-key'];
+      if (typeof args['secret-key'] === 'string') body.secret_key = args['secret-key'];
+      return body;
+    };
+    if (action === 'add') {
+      const name = args._[2];
+      const body = fields({ name });
+      if (!name || !body.endpoint || !body.bucket || !body.access_key || !body.secret_key) {
+        die('usage: canner db offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET [--region R] [--folder F]', 2);
+      }
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.destination);
+      info(`${green('added')} off-site destination ${bold(r.destination.name)} (${r.destination.bucket} at ${r.destination.endpoint}). Test it: canner db offsite test ${r.destination.name}`);
+      return;
+    }
+    if (action === 'edit') {
+      if (!args._[2]) die('usage: canner db offsite edit <name> [--new-name N] [--endpoint HOST] [--bucket NAME] [--access-key KEY] [--secret-key SECRET] [--region R] [--folder F]', 2);
+      const cur = await find(args._[2]);
+      const body = fields({ name: typeof args['new-name'] === 'string' ? args['new-name'] : cur.name });
+      body.endpoint ??= cur.endpoint; body.bucket ??= cur.bucket; body.access_key ??= cur.access_key; body.region ??= cur.region; body.prefix ??= cur.prefix;
+      const r = await apiJSON(creds, 'PUT', `${path}/${cur.id}`, body);
+      if (JSON_MODE) return emitJSON(r.destination);
+      info(`${green('saved')} ${bold(r.destination.name)}. Test it: canner db offsite test ${r.destination.name}`);
+      return;
+    }
+    if (action === 'test') {
+      if (!args._[2]) die('usage: canner db offsite test <name>', 2);
+      const cur = await find(args._[2]);
+      const r = await apiJSON(creds, 'POST', `${path}/${cur.id}/test`);
+      if (JSON_MODE) return emitJSON(r);
+      if (r.ok) info(green(`${cur.name}: the bucket accepted a test file.`));
+      else die(`${cur.name}: the test failed: ${r.error}`);
+      return;
+    }
+    if (action === 'rm') {
+      if (!args._[2]) die('usage: canner db offsite rm <name> --yes', 2);
+      const cur = await find(args._[2]);
+      requireYes(args, `This removes "${cur.name}"${cur.databases ? `; ${cur.databases} database(s) stop copying backups off-site` : ''}. Files already in your bucket stay there but can no longer be used to restore.`);
+      await apiJSON(creds, 'DELETE', `${path}/${cur.id}`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('removed')} ${bold(cur.name)}`);
+      return;
+    }
+    const all = await listAll();
+    if (JSON_MODE) return emitJSON(all);
+    if (all.length === 0) { muted('no off-site destinations. Add one with `canner db offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET`.'); return; }
+    for (const d of all) {
+      info(`${bold(d.name)}  ${d.bucket} at ${cyan(d.endpoint)}  region ${d.region}  folder ${d.prefix || dim('(root)')}`);
+      info(`  access key ${d.access_key}  ${d.last_test_at ? (d.last_test_ok ? green('test ok') : red('test failed')) + ' ' + dim(relTime(d.last_test_at)) : dim('not tested')}  ${d.databases ? dim(`${d.databases} database(s)`) : ''}`);
+    }
+    return;
+  }
+
+  if (sub === 'alerts') {
+    const action = args._[1];
+    const path = `${base}/database-alerts`;
+    if (action === 'test') {
+      const r = await apiJSON(creds, 'POST', `${path}/test`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('sent')} ${r.emails} email${r.emails === 1 ? '' : 's'}${r.webhook === 'sent' ? ' and the webhook' : r.webhook === 'failed' ? `; the webhook ${red('failed')}: ${r.error}` : ''}`);
+      return;
+    }
+    if (action === 'set') {
+      const patch = {};
+      const onOff = (v, name) => { if (v !== 'on' && v !== 'off') die(`--${name} takes on or off.`, 2); return v === 'on'; };
+      if (args.email !== undefined) patch.email_enabled = onOff(args.email, 'email');
+      if (args.verify !== undefined) patch.verify_backups = onOff(args.verify, 'verify');
+      if (args.recipients !== undefined) patch.recipients = args.recipients === 'all' ? [] : String(args.recipients).split(',').map((x) => x.trim()).filter(Boolean);
+      if (args.webhook !== undefined) patch.webhook_url = args.webhook === 'none' ? null : String(args.webhook);
+      if (args['rotate-secret'] === true) patch.rotate_webhook_secret = true;
+      if (Object.keys(patch).length === 0) die('nothing to change. Use --email, --recipients, --webhook, --rotate-secret or --verify.', 2);
+      const r = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('saved')} alert settings`);
+      if (r.webhook_secret) info(`  webhook signing secret (shown once): ${cyan(r.webhook_secret)}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    const c = r.settings;
+    info(`${bold('email')}      ${c.email_enabled ? green('on') : dim('off')} → ${r.effective_recipients.join(', ') || dim('(nobody)')}${c.recipients.length ? '' : dim('  (all org admins)')}`);
+    info(`${bold('webhook')}    ${c.webhook_url ? cyan(c.webhook_url) : dim('none')}`);
+    info(`${bold('verify')}     ${c.verify_backups ? green('on') : dim('off')}  ${dim('(test-restore backups overnight)')}`);
+    const open = r.incidents.filter((i) => i.state === 'open');
+    if (open.length === 0) muted('no open problems.');
+    for (const i of open) info(`  ${i.severity === 'critical' ? red(i.kind) : yellow(i.kind)} ${i.database ?? ''} ${dim(relTime(i.first_seen_at))}${i.detail?.error ? ' ' + dim(i.detail.error) : ''}`);
+    return;
+  }
+
+  if (sub === 'instance') {
+    const action = args._[1];
+    const path = `${base}/instance`;
+
+    if (!action || action === 'show') {
+      const body = await apiJSON(creds, 'GET', path);
+      if (JSON_MODE) return emitJSON(body);
+      const i = body?.instance;
+      if (!i) {
+        muted(body?.allowed ? 'no dedicated instance yet. Create one with `canner db instance create`.' : 'A dedicated Postgres instance is a paid add-on for this project.');
+        return;
+      }
+      info(`${bold('dedicated instance')}  ${i.state === 'running' ? green(i.state) : yellow(i.state)}  ${dim(`Postgres ${i.pg_version} · ${i.databases} database${i.databases === 1 ? '' : 's'}`)}`);
+      info(`  point-in-time recovery  ${i.pitr_enabled ? green(`on (${i.pitr_window_days}-day window)`) : dim('off')}${i.pitr_enabled ? dim(`  archive ${i.archive_mb} MB`) : ''}`);
+      if (i.error) info(`  ${red(i.error)}`);
+      return;
+    }
+
+    if (action === 'create') {
+      const body = await apiJSON(creds, 'POST', path, {
+        ...(args.pg ? { pg_version: String(args.pg) } : {}),
+        ...(args.pitr === true ? { pitr: true } : {}),
+        ...(args.window ? { window_days: Number(args.window) } : {}),
+      });
+      if (JSON_MODE) return emitJSON(body);
+      const i = body?.instance;
+      info(`${green('created')} a dedicated Postgres ${i.pg_version} instance${i.pitr_enabled ? ` with point-in-time recovery (${i.pitr_window_days}-day window)` : ''}`);
+      muted('Add databases to it with `canner db create <name> --instance`, or move one with `canner db move <name> --to instance --yes`.');
+      return;
+    }
+
+    if (action === 'stop' || action === 'start') {
+      if (action === 'stop') requireYes(args, 'Stopping takes every database on the instance offline (data is kept).');
+      const body = await apiJSON(creds, 'POST', `${path}/power`, { action, ...(action === 'stop' ? { confirm: true } : {}) });
+      if (JSON_MODE) return emitJSON(body);
+      info(`${green(action === 'stop' ? 'stopped' : 'started')} the dedicated instance`);
+      return;
+    }
+
+    if (action === 'destroy') {
+      requireYes(args, 'This permanently destroys the instance and its point-in-time-recovery archive. Every database on it must be moved or deleted first.');
+      await apiJSON(creds, 'DELETE', `${path}?confirm=true`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('destroyed')} the dedicated instance`);
+      return;
+    }
+
+    die('usage: canner db instance [show] | create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | destroy --yes', 2);
+  }
+
+  if (sub === 'pitr') {
+    const path = `${base}/instance/pitr`;
+    if (args.now === true) {
+      const started = await apiJSON(creds, 'POST', `${base}/instance/base-backups`);
+      const op = started?.operation;
+      if (!op) die('the platform did not return an operation.');
+      if (args['no-wait'] === true) { if (JSON_MODE) return emitJSON(op); info(`${green('started')} base backup ${dim(op.id)}`); return; }
+      if (!JSON_MODE) info('taking a base backup…');
+      const done = await waitForOperation(creds, base, op.id, args);
+      if (JSON_MODE) return emitJSON(done);
+      info(`${green('done')} ${done.result?.bytes != null ? dim(`(${fmtBytes(done.result.bytes)})`) : ''}`);
+      return;
+    }
+    if (args.offsite !== undefined) {
+      // --offsite <destination name|id>  |  --offsite none
+      let destination_id = null;
+      if (args.offsite !== 'none') {
+        const dl = await apiJSON(creds, 'GET', `${base}/backup-destinations`);
+        const want = String(args.offsite);
+        const hit = dl.destinations.find((d) => d.id === want || d.name.toLowerCase() === want.toLowerCase());
+        if (!hit) die(`no off-site destination named "${want}". Add one first: canner db offsite add ...`, 2);
+        destination_id = hit.id;
+      }
+      const body = await apiJSON(creds, 'PATCH', `${base}/instance/archive-offsite`, { destination_id });
+      if (JSON_MODE) return emitJSON(body);
+      const o = body.archive_offsite;
+      info(o.destination_id ? `${green('set')} the recovery archive is copied off-site to ${bold(o.destination_name)}` : `${green('set')} the recovery archive is no longer copied off-site`);
+      return;
+    }
+    const setting = args.enable === true || args.disable === true || args.window !== undefined || args.every !== undefined;
+    if (setting) {
+      if (args.disable === true) requireYes(args, 'Turning off point-in-time recovery permanently deletes the recovery archive.');
+      const patch = {};
+      if (args.enable === true) patch.enabled = true;
+      if (args.disable === true) { patch.enabled = false; patch.confirm = true; }
+      if (args.window !== undefined) patch.window_days = Number(args.window);
+      if (args.every !== undefined) patch.base_backup_interval_hours = Number(args.every);
+      const body = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(body);
+      const i = body.instance;
+      info(`${green('set')} point-in-time recovery: ${i.pitr_enabled ? `on, ${i.pitr_window_days}-day window, base backup every ${i.base_backup_interval_hours}h` : 'off'}`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(body);
+    const p = body.pitr;
+    info(`${bold('point-in-time recovery')}  ${p.enabled ? green('on') : dim('off')}`);
+    if (p.enabled) {
+      info(`  restorable from ${p.earliest ? cyan(p.earliest) : dim('(first base backup pending)')} to ${p.latest_archived ? cyan(p.latest_archived) : dim('now')}`);
+      info(`  ${p.window_days}-day window · base backup every ${p.base_backup_interval_hours}h · ${p.base_backups} base backup${p.base_backups === 1 ? '' : 's'} · archive ${p.archive_mb} MB`);
+      if (p.archive_failures > 0) info(`  ${red(`${p.archive_failures} WAL archive failure(s) — contact support`)}`);
+      const o = body.archive_offsite;
+      if (o?.destination_id) {
+        info(`  off-site copy: ${bold(o.destination_name)} · ${o.files} file${o.files === 1 ? '' : 's'} (${fmtBytes(o.bytes)})${o.pending ? ` · ${o.pending} waiting` : ''}${o.last_at ? ` · last ${relTime(o.last_at)}` : ''}`);
+        if (o.error) info(`  ${red(`last copy failed: ${o.error}`)}`);
+      } else if (p.archive_encrypted) {
+        info(`  off-site copy: ${dim('off (canner db pitr --offsite <destination>)')}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === 'pitr-restore') {
+    const label = args._[1];
+    const to = typeof args.to === 'string' ? args.to : null;
+    if (!label || !to) die('usage: canner db pitr-restore <name> --to <ISO-8601 time | latest>', 2);
+    const started = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/pitr-restore`, { target: to });
+    const op = started?.operation;
+    const into = started?.database?.name;
+    if (!op) die('the platform did not return an operation.');
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(started);
+      info(`${green('started')} recovery ${dim(op.id)} → ${bold(into)}`);
+      return;
+    }
+    if (!JSON_MODE) info(`recovering ${label} as of ${to} into ${into}…`);
+    const done = await waitForOperation(creds, base, op.id, args);
+    if (JSON_MODE) return emitJSON({ ...done, database: started.database });
+    info(`${green('recovered')} ${bold(label)} as of ${to} → new database ${bold(into)}`);
+    muted(`Nothing existing was touched. To swap it in: canner db copy ${into} ${label} --replace`);
+    return;
+  }
+
+  if (sub === 'move') {
+    const label = args._[1];
+    const to = typeof args.to === 'string' ? args.to : null;
+    if (!label || (to !== 'instance' && to !== 'shared')) die('usage: canner db move <name> --to instance|shared --yes', 2);
+    requireYes(args, 'Moving a database has real downtime while it runs (the connection string does not change; a failed move leaves it untouched).');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(label)}/move`, { to, confirm: true }, 'moving');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('moved')} ${bold(label)} to ${to === 'instance' ? 'the dedicated instance' : 'shared hosting'}`);
+    return;
+  }
+
+  die(`unknown db subcommand "${sub}". Use: list | init | create | info | url | rm | pg-version | export | import | migrate-in | migrate-out | copy | ops | external | rotate | backup-policy | backup | backups | diff | inspect | alerts | roles | offsite | metrics | monitoring | insights | logs | resources | extensions | tuning | restart | replication | subscriptions | instance | pitr | pitr-restore | move.`, 2);
+}
+
+function printHelp() {
+  process.stdout.write(`${bold('canner')} ${dim('— deploy to Canner from any terminal')}
+
+${bold('Usage:')}
+  canner <command> [options]
+
+${bold('Setup:')}
+  ${bold('login')}                Store your Canner API token (one-time).
+  ${bold('logout')}               Remove the stored token from this machine.
+  ${bold('whoami')}               Show the account this CLI is signed in as.
+
+${bold('Projects:')}
+  ${bold('projects')}             List your projects.
+  ${bold('init')} [--slug X]      Create a project and write ${cyan(PROJECT_CONFIG_FILE)}.
+  ${bold('status')} [--slug X]    Show project state (URL, status, source, last request).
+  ${bold('open')} [--slug X] [--dashboard]
+                       Open the tenant URL (or dashboard page) in your browser.
+
+${bold('Deploys:')}
+  ${bold('deploy')} [path] [--slug X] [--follow]
+                       Tar the current directory and upload. Works for any
+                       project (GitHub-connected or upload-only).
+  ${bold('redeploy')} [--slug X] [--follow]
+                       Trigger a rebuild from the GitHub repo's HEAD without
+                       uploading. GitHub-connected projects only.
+  ${bold('deployments')} [--slug X]
+                       List the project's recent deployments.
+  ${bold('deployments')} <id> [--slug X] [--follow]
+                       Show one deployment's build log (--follow streams if
+                       it's still in progress).
+  ${bold('cancel')} [<id>] [--slug X]
+                       Abort the in-flight build (or a specific one by id).
+  ${bold('logs')} [--slug X] [--lines N] [--follow]
+                       Stream the running tenant's runtime logs (last 200
+                       lines by default, --follow to keep streaming).
+
+${bold('Resources:')}
+  ${bold('token')} list | create <name> | revoke <id|name>
+                       Manage the cnr_ API tokens that authenticate this CLI.
+  ${bold('env')} [list] [--reveal] [--slug X]
+  ${bold('env')} set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
+  ${bold('env')} rm <KEY|id> [--env ...] [--slug X]
+                       Manage a project's environment variables. Sensitive
+                       values are redacted as •••••• (or null in --json) on
+                       list; pass --reveal to see them in cleartext.
+  ${bold('domains')} [list] [--slug X]
+  ${bold('domains')} add <hostname> [--slug X]
+  ${bold('domains')} verify <hostname|id> [--slug X]
+  ${bold('domains')} rm <hostname|id> [--slug X]
+                       Manage a project's custom domains.
+
+${bold('Databases:')}
+  ${bold('db')} [list] [--slug X]           List the project's databases.
+  ${bold('db')} init | create <name> [--pg 17|18]
+                       Provision the primary database, or add another (paid).
+  ${bold('db')} info [<name>] [--reveal] | url [<name>]
+                       Connection details (password hidden unless --reveal).
+  ${bold('db')} export [<name>] [--format custom|plain] [--out FILE]
+  ${bold('db')} import <file> [--to <name>] [--replace]
+  ${bold('db')} migrate-in --from <url>|--from-env VAR [--to <name>] [--replace]
+  ${bold('db')} migrate-out --to-url <url>|--to-env VAR [--from <name>] --yes
+  ${bold('db')} copy <from> <to> [--to-project SLUG] [--replace]
+  ${bold('db')} rm <name> --yes | pg-version <name> <17|18> --yes | ops [<id>]
+                       Move data in and out, copy between databases, and
+                       manage them. Long operations run on Canner; the CLI
+                       waits (or use --no-wait).
+  ${bold('db')} external [<name>]           Show external-access status.
+  ${bold('db')} external <name> --enable --allow CIDR [--allow CIDR ...]
+                       Turn on public access, allowed from only these
+                       addresses (repeat --allow; or --allow-all --yes for
+                       0.0.0.0/0 — not recommended).
+  ${bold('db')} external <name> --disable   Turn public access off.
+  ${bold('db')} rotate <name> --yes         Rotate the database password.
+  ${bold('db')} backup-policy [<name>]      Show a database's backup schedule.
+  ${bold('db')} backup-policy <name> --enable --every HOURS --keep DAYS [--keep-count N|none]
+  ${bold('db')} backup-policy <name> --disable
+                       Turn scheduled backups on/off and set how often and how
+                       long they're kept (paid plans).
+  ${bold('db')} backup [<name>]             Take a manual backup now (waits by
+                       default, or use --no-wait).
+  ${bold('db')} backups [<name>]            List backups for a database.
+  ${bold('db')} backups <name> <id>         Show one backup.
+  ${bold('db')} backups <name> <id> --download [--out FILE]
+                       Download the decrypted dump.
+  ${bold('db')} backups <name> <id> --restore --inspect
+                       Restore into a temporary inspect database (own
+                       connection string, never injected, expires).
+  ${bold('db')} backups <name> <id> --verify
+                       Test-restore the backup into a scratch database.
+  ${bold('db')} diff <name> [--against <name>]
+                       Compare tables, columns and row counts (default: the
+                       database an inspect database was restored from).
+  ${bold('db')} inspect <name> --keep | --extend HOURS
+  ${bold('db')} resources                   Show the memory budget shared by the app and the dedicated instance.
+  ${bold('db')} resources set [--share PCT] [--app-reserved GB]   Postgres's share of the shared memory (10-90); reserved RAM kept for the app.
+  ${bold('db')} resources apply --yes       Size Postgres for it and set its memory limit (restarts the instance).
+  ${bold('db')} extensions [<name>] [install|update|rm <ext>] [--window] [--yes]   Extensions on the dedicated instance (pgvector, PostGIS, pg_trgm, pg_cron, ...).
+  ${bold('db')} tuning [--preset balanced|read-heavy|write-heavy|analytics] [--statement-timeout S] [--idle-timeout S] [--lock-timeout S]
+                       [--window-day 0-6|all] [--window-hour 0-23] [--window-tz ZONE]   Workload preset, timeouts and the maintenance window.
+  ${bold('db')} restart --yes               Restart the dedicated instance now (also applies settings waiting for the window).
+  ${bold('db')} replication [<name>] [on [--cap MB] [--window] --yes | off --yes | cap MB | pub <n> --all|--tables a.b,c.d | unpub <n> --yes | drop-slot <n> --yes]
+                       Logical replication: turn on (restarts), the WAL cap per slot, publications, slots. Subscribers sign in with \`db roles <name> create <n> --replication\`.
+  ${bold('db')} subscriptions [<name>] [add <n> --from <url>|--from-env VAR --publication p1,p2 [--no-copy] | refresh|pause|resume <n> | rm <n> [--force] --yes]
+                       Follow publications on an external server (live copy / no-downtime migration).
+  ${bold('db')} metrics [<name>] [--range 1h|24h|7d|30d]   Transactions, connections, cache hit, size (and instance memory/CPU).
+  ${bold('db')} monitoring [on|off --yes] [--slow-ms N]     Query insights + logs on the dedicated instance (restarts it).
+  ${bold('db')} insights [<name>] [--sort total|mean|calls|max] [--limit N] | --reset --yes
+  ${bold('db')} logs [<name>] [--level ERROR,WARNING] [--min-ms N] [--search TEXT] [--limit N]
+  ${bold('db')} roles [<name>]              List a database's roles (read-only / read-write logins).
+  ${bold('db')} roles <name> create <role> --read-only | --read-write
+  ${bold('db')} roles <name> rotate <role> --yes
+  ${bold('db')} roles <name> rm <role> --yes
+  ${bold('db')} offsite                     List the off-site backup destinations (S3-compatible buckets).
+  ${bold('db')} offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET [--region R] [--folder F]
+  ${bold('db')} offsite edit <name> [--new-name N] [--endpoint HOST] [--bucket NAME] [--access-key KEY] [--secret-key SECRET] [--region R] [--folder F]
+  ${bold('db')} offsite test <name> | rm <name> --yes
+  ${bold('db')} backup-policy <name> --offsite <destination>|off   Copy this database's backups off-site to that destination.
+  ${bold('db')} backups <name> <id> --offsite [destination]        Copy one backup off-site now (default: the policy's destination).
+  ${bold('db')} alerts                      Show alert settings and open problems.
+  ${bold('db')} alerts set [--email on|off] [--recipients a@x.com,b@y.com|all]
+                       [--webhook URL|none] [--rotate-secret] [--verify on|off]
+  ${bold('db')} alerts test                 Send a test alert.
+  ${bold('db')} backups <name> <id> --restore [--no-wait]
+                       Restore into a brand-new database (safe default).
+  ${bold('db')} backups <name> <id> --restore --to <name> --yes
+                       Restore IN PLACE into an existing database, replacing
+                       its contents (Canner snapshots it first).
+  ${bold('db')} backups <name> <id> --rm --yes
+                       Delete a backup (destroys its key immediately).
+  ${bold('db')} instance [create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | destroy --yes]
+                       A dedicated Postgres server for this project (paid add-on).
+  ${bold('db')} create <name> --instance      Create a database on the dedicated instance.
+  ${bold('db')} move <name> --to instance|shared --yes
+                       Move a database onto/off the instance (same connection string).
+  ${bold('db')} pitr [--enable | --disable --yes] [--window DAYS] [--every HOURS] [--now] [--offsite <destination>|none]
+                       Point-in-time recovery: status, settings, or a base backup now.
+  ${bold('db')} pitr-restore <name> --to <ISO time | latest>
+                       Recover a database as of a moment into a NEW database.
+
+${bold('Global:')}
+  ${bold('--json')}               Emit machine-readable JSON (for scripts, CI, agents).
+                       Suppresses tables + progress; --follow log streaming is
+                       skipped. Errors go to stderr as {"error":"..."}.
+
+${bold('Examples:')}
+  canner login
+  cd my-site && canner init
+  canner deploy --follow                 ${dim('# build to live, streaming logs')}
+  canner redeploy --follow                ${dim('# rebuild from GitHub HEAD')}
+  canner deployments                      ${dim('# list recent deploys')}
+  canner deployments 7bf4862e --follow    ${dim('# inspect a specific one')}
+  canner logs --follow                    ${dim('# tail tenant runtime logs')}
+  canner cancel                            ${dim('# abort the current build')}
+  canner open --dashboard                 ${dim('# open dashboard project page')}
+  canner token create ci                  ${dim('# mint a token named "ci"')}
+  canner env set API_KEY=secret --sensitive  ${dim('# add a hidden env var')}
+  canner env list --reveal                ${dim('# show sensitive values in cleartext')}
+  canner domains add www.example.com      ${dim('# attach a custom domain')}
+  canner db export --out backup.dump      ${dim('# download a pg_dump of the primary database')}
+  canner db import backup.dump --to analytics  ${dim('# restore a dump into another database')}
+  canner projects --json | jq '.[].slug'  ${dim('# machine-readable output')}
+
+${bold('Environment:')}
+  CANNER_TOKEN         Override stored token (handy for CI).
+  CANNER_API_BASE      Override API endpoint (default ${DEFAULT_API_BASE}).
+
+${bold('Files:')}
+  ~/.canner/credentials   Stored token (mode 0600).
+  canner.json             Per-project slug (committed alongside source).
+  .cannerignore           Optional excludes (in addition to node_modules,
+                          .git, .next, .nuxt, .turbo, .vercel, .svelte-kit,
+                          .DS_Store, Thumbs.db which are always excluded).
+
+Docs: https://canner.ca/cli
+Version: ${VERSION}
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+const args = parseArgs(process.argv.slice(2));
+const command = args._.shift();
+
+// Global --json: machine-readable output for scripts, CI, and agents. Set
+// before dispatch so every helper (info/muted/die) honors it.
+JSON_MODE = args.json === true;
+
+if (args.version || args.v || command === 'version') {
+  process.stdout.write(`canner ${VERSION}\n`);
+  process.exit(0);
+}
+if (!command || args.help || args.h || command === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+const dispatch = {
+  login: cmdLogin,
+  logout: cmdLogout,
+  whoami: cmdWhoami,
+  init: cmdInit,
+  deploy: cmdDeploy,
+  redeploy: cmdRedeploy,
+  projects: cmdProjects,
+  status: cmdStatus,
+  logs: cmdLogs,
+  deployments: cmdDeployments,
+  cancel: cmdCancel,
+  open: cmdOpen,
+  token: cmdToken,
+  tokens: cmdToken,
+  env: cmdEnv,
+  domains: cmdDomains,
+  db: cmdDb,
+  database: cmdDb,
+  databases: cmdDb,
+};
+const handler = dispatch[command];
+if (!handler) {
+  process.stderr.write(`${red('error:')} unknown command "${command}"\n\n`);
+  printHelp();
+  process.exit(2);
+}
+
+try {
+  await handler(args);
+} catch (err) {
+  if (err && err.code === 'ERR_UNHANDLED_ERROR') {
+    die(err.message);
+  }
+  die(err?.message ?? String(err));
+}