@canner-ca/cli 0.1.0 → 0.3.0

package/README.md

@@ -33,12 +33,59 @@ canner deploy --follow
 
 ## Commands
 
+### Setup
+
 | Command | What it does |
 |---|---|
 | `canner login` | Prompt for an API token, store it at `~/.canner/credentials` (mode 0600). |
 | `canner whoami` | Show the email + plan this CLI is signed in as. |
+
+### Projects
+
+| Command | What it does |
+|---|---|
+| `canner projects` | List your projects. |
 | `canner init [--slug X]` | Create a new Canner project and write `canner.json` in the current directory. |
-| `canner deploy [path] [--slug X] [--follow]` | Tar the directory and upload it. `--follow` streams the build log and exits with the build's success code. |
+| `canner status [--slug X]` | Show one project's state — URL, status, source, last request. |
+| `canner open [--slug X] [--dashboard]` | Open the tenant URL (or the dashboard project page) in your browser. |
+
+### Deploys
+
+| Command | What it does |
+|---|---|
+| `canner deploy [path] [--slug X] [--follow]` | Tar the directory and upload. Works for any project — GitHub-connected or upload-only. `--follow` streams the build log and exits with the build's success code. |
+| `canner redeploy [--slug X] [--follow]` | Trigger a rebuild from the GitHub repo's `HEAD` without uploading. GitHub-connected projects only. |
+| `canner deployments [--slug X]` | List the project's recent deployments. |
+| `canner deployments <id> [--slug X] [--follow]` | Show one deployment's build log; `--follow` streams if it's still in progress. |
+| `canner cancel [<id>] [--slug X]` | Abort the in-flight build (or a specific one by id). |
+| `canner logs [--slug X] [--lines N] [--follow]` | Stream the running tenant's runtime logs (last 200 lines by default). |
+
+### Resources
+
+| Command | What it does |
+|---|---|
+| `canner token list` | List your `cnr_` API tokens. |
+| `canner token create <name>` | Mint a new token. The secret is printed once — copy it immediately. |
+| `canner token revoke <id\|name>` | Revoke a token. |
+| `canner env [list] [--slug X]` | List a project's environment variables. |
+| `canner env set KEY=VALUE [--env production\|preview] [--sensitive] [--slug X]` | Add an environment variable. |
+| `canner env rm <KEY\|id> [--env ...] [--slug X]` | Delete an environment variable. |
+| `canner domains [list] [--slug X]` | List a project's custom domains. |
+| `canner domains add <hostname> [--slug X]` | Attach a custom domain (starts `pending`). |
+| `canner domains verify <hostname\|id> [--slug X]` | Re-check DNS and provision TLS. |
+| `canner domains rm <hostname\|id> [--slug X]` | Detach a custom domain. |
+
+## JSON output
+
+Add `--json` to any command for machine-readable output — tables and progress lines are suppressed and a single JSON value is printed to stdout, so the result pipes straight into `jq` or an agent. Errors are written to stderr as `{"error":"..."}` with a non-zero exit code. With `--json`, `deploy --follow` does **not** stream the build log (it would corrupt the JSON); poll `canner deployments <id> --json` for the terminal status instead.
+
+```bash
+canner projects --json | jq -r '.[].slug'
+canner deploy --json                      # → {"deployment_id":"…","status":"queued",…}
+canner env list --slug my-app --json
+```
+
+This pairs with the REST API directly: every command wraps an endpoint documented in the [API reference](https://canner.ca/developers) (interactive explorer at <https://api.canner.ca/docs>, OpenAPI spec at <https://api.canner.ca/openapi.json>).
 
 ## What gets uploaded
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canner-ca/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Canner deploy CLI — git push from any terminal, no GitHub required",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -27,7 +27,7 @@ import { randomUUID } from 'node:crypto';
 import { stdin as input, stdout as output } from 'node:process';
 import { create as tarCreate } from 'tar';
 
-const VERSION = '0.1.0';
+const VERSION = '0.3.0';
 const DEFAULT_API_BASE = 'https://api.canner.ca';
 const CONFIG_DIR = join(homedir(), '.canner');
 const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
@@ -61,16 +61,33 @@ 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) {
-  process.stderr.write(`${red('error:')} ${msg}\n`);
+  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`);
 }
 
@@ -275,19 +292,23 @@ async function cmdWhoami() {
   if (!me?.account) {
     die('authenticated but /auth/me returned no account.');
   }
-  info(`${bold(me.account.email)}`);
-  muted(`api: ${creds.apiBase}`);
   // Projects count from /me/plan (cheap call we already have).
+  let plan = null;
   try {
-    const plan = await apiJSON(creds, 'GET', '/me/plan');
-    if (plan?.plan) {
-      muted(
-        `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
-      );
-    }
+    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)`
+    );
+  }
 }
 
 async function cmdInit(args) {
@@ -325,6 +346,506 @@ async function cmdInit(args) {
   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}.app.canner.ca`;
+    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}.app.canner.ca`)}`);
+  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}.app.canner.ca`;
+  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)) {
@@ -413,6 +934,12 @@ async function cmdDeploy(args) {
   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) {
@@ -549,18 +1076,67 @@ function printHelp() {
 ${bold('Usage:')}
   canner <command> [options]
 
-${bold('Commands:')}
+${bold('Setup:')}
   ${bold('login')}                Store your Canner API token (one-time).
   ${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 ship it.
+                       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 deploy ./web --slug my-app  ${dim('# deploy a sibling directory')}
+  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).
@@ -584,6 +1160,10 @@ Version: ${VERSION}
 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);
@@ -598,6 +1178,17 @@ const dispatch = {
   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) {