voroa-cli 0.0.0-stage → 0.2.0

package/src/commands/logs.js

@@ -0,0 +1,285 @@
+// `voroa logs <service>` - the running container's output, and with --build the build log.
+//
+// Every line printed here is printed AS THE SERVER SENT IT. Voroa redacts build output server-side
+// before it is ever returned (golden rules 3 and 6). Re-parsing or re-filtering it here would be a
+// second, weaker filter that drifts from the real one - so we do not touch the text.
+import { runtimeLogs, buildLog, deployHistory, streamBuildLog, ApiError, SESSION_EXPIRED } from '../api.js';
+import { isBuildFinished, isBuildRunning } from '../status.js';
+import { resolveService } from '../resolve.js';
+import { numberFlag } from '../flags.js';
+import { out, err } from '../output.js';
+import { CliError } from '../errors.js';
+
+const DEFAULT_LINES = 100;
+const MAX_LINES = 1000; // the server's own clamp - asking for more cannot return more
+// A build that never reaches a terminal state would otherwise hold the poll loop open forever. The
+// cap is generous (a Voroa build timeout is far below it) so it only ever catches the pathological
+// case, and it says what happened rather than exiting as if the log had ended.
+const BUILD_WAIT_MAX_MS = 60 * 60_000;
+const FOLLOW_BASE_MS = 2000;
+const FOLLOW_IDLE_AFTER_MS = 60_000;
+const FOLLOW_SLOW_MS = 10_000;
+const FOLLOW_MAX_MS = 60_000;
+const BUILD_POLL_MS = 2000;
+
+function splitLines(blob) {
+  if (!blob) return [];
+  return String(blob).replace(/\r\n/g, '\n').split('\n');
+}
+
+// The runtime endpoint returns a fixed-size TAIL, so successive polls overlap and the window
+// slides. Find the longest suffix of what we already printed that is a prefix of the new tail, and
+// print only what follows it.
+//
+// No overlap at all means the service produced more than a whole window between two polls: we have
+// genuinely lost track of where we were, so we print the new window rather than guess. Duplicated
+// output is a visible, self-explaining failure; silently skipped output is not.
+// keepFollowingEmptyBuild(d) -> boolean. An empty build log is not the same answer twice: for the first
+// seconds of every off-box build there are no lines yet while the build is perfectly healthy, and saying
+// "No build log is available for this deploy." there tells a customer their log does not exist seconds
+// before it arrives. `/log` carries the deployments row's status even on an empty read, so the two are
+// distinguishable - and the test is EXPLICITLY 'building', not `!isBuildFinished(...)`: a null status is
+// the feature-off answer and must reach the honest message instead of waiting out the caller's deadline.
+export function keepFollowingEmptyBuild(d) {
+  return !!d && d.available === false && d.reason !== 'retention' && isBuildRunning(d.buildStatus);
+}
+
+export function newTailLines(prev, next) {
+  if (!prev.length) return next;
+  const max = Math.min(prev.length, next.length);
+  for (let k = max; k > 0; k--) {
+    let same = true;
+    for (let i = 0; i < k; i++) {
+      if (prev[prev.length - k + i] !== next[i]) {
+        same = false;
+        break;
+      }
+    }
+    if (same) return next.slice(k);
+  }
+  return next;
+}
+
+// One place decides which failures end a follow. A 401 is worth its own sentence because "expired"
+// is actionable and "forbidden" is not the same thing.
+function fatalFor(e) {
+  if (!(e instanceof ApiError)) return e;
+  if (e.httpStatus === 401) return new CliError(SESSION_EXPIRED);
+  if (e.httpStatus === 403) return new CliError('You do not have access to this service\'s logs.');
+  if (e.httpStatus === 404) return new CliError('That service no longer exists.');
+  return new CliError(e.message);
+}
+
+// Ctrl-C on a watch command is how you STOP watching - a normal, successful end, not a failure. It
+// sets a flag and wakes the sleep, so the command returns through the ordinary path with exit 0
+// rather than calling process.exit() (see the note in index.js about why that call is avoided).
+function interruptible() {
+  const state = { stopped: false };
+  let wake = () => {};
+  state.onSigint = () => {
+    state.stopped = true;
+    wake();
+  };
+  state.wait = (ms) =>
+    new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      wake = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+    });
+  return state;
+}
+
+async function followRuntime(ctx, app, lines, search) {
+  const ctl = interruptible();
+  process.on('SIGINT', ctl.onSigint);
+
+  let interval = FOLLOW_BASE_MS;
+  let prev = [];
+  let lastOutputAt = Date.now();
+  let saidRateLimited = false;
+  let first = true;
+
+  try {
+    while (!ctl.stopped) {
+      try {
+        const next = splitLines(await runtimeLogs(ctx, app.uuid, lines, search));
+        const fresh = first ? next : newTailLines(prev, next);
+        first = false;
+        prev = next;
+        if (fresh.length && fresh.some((l) => l !== '')) {
+          for (const line of fresh) out(line);
+          lastOutputAt = Date.now();
+          interval = FOLLOW_BASE_MS; // new output -> back to a tight poll
+        }
+      } catch (e) {
+        if (e instanceof ApiError && e.httpStatus === 429) {
+          interval = Math.min(interval * 2, FOLLOW_MAX_MS);
+          if (!saidRateLimited) {
+            err('Rate limited - slowing down.'); // said once, not once per poll
+            saidRateLimited = true;
+          }
+        } else {
+          throw fatalFor(e);
+        }
+      }
+
+      // Nothing for a minute: this service is idle, so stop asking every two seconds.
+      if (Date.now() - lastOutputAt > FOLLOW_IDLE_AFTER_MS && interval < FOLLOW_SLOW_MS) {
+        interval = FOLLOW_SLOW_MS;
+      }
+      await ctl.wait(interval);
+    }
+  } finally {
+    process.off('SIGINT', ctl.onSigint);
+  }
+}
+
+function printBuildLines(lines) {
+  for (const l of lines) {
+    if (!l) continue;
+    out(typeof l === 'string' ? l : String(l.text ?? ''));
+  }
+}
+
+// Snapshot loop. This is the CORRECTNESS path: the stream is only a speed-up, and every way the
+// stream can decline or drop lands here.
+async function pollBuildLog(ctx, app, deploymentUuid, { alreadyPrinted = 0, deadline: callerDeadline = null }, ctl) {
+  let printed = alreadyPrinted;
+  const deadline = callerDeadline ?? Date.now() + BUILD_WAIT_MAX_MS;
+  while (!ctl.stopped) {
+    if (Date.now() >= deadline) {
+      // A caller's own deadline (deploy --follow --timeout) reports its timeout itself.
+      if (callerDeadline === null) out('Stopped following this build log after an hour - the build has still not reported an end.');
+      return;
+    }
+    const d = await buildLog(ctx, app.uuid, deploymentUuid);
+    if (!d.available) {
+      if (d.reason === 'retention') {
+        out('This build log is past its retention window and is no longer available.');
+        return;
+      }
+      // A BUILD THAT HAS NOT PRINTED YET IS NOT A BUILD WITH NO LOG - the same defect the deploy page had.
+      // `available` is "are there lines", and for the first seconds of every off-box build the answer is no
+      // while the build is perfectly healthy. Giving up there told the customer their log did not exist,
+      // seconds before it arrived. The route now carries the row's status on an empty read, so we can tell
+      // the two apart: keep following while it explicitly says 'building', and the loop's own deadline above
+      // still bounds the wait. Explicitly 'building', not `!isBuildFinished(...)` - a null status (the
+      // feature-off answer) must fall through to the honest message rather than wait out the deadline.
+      if (keepFollowingEmptyBuild(d)) {
+        await ctl.wait(Math.max(0, Math.min(BUILD_POLL_MS, deadline - Date.now())));
+        continue;
+      }
+      if (printed === 0) out('No build log is available for this deploy.');
+      return;
+    }
+    printBuildLines(d.lines.slice(printed));
+    printed = d.lines.length;
+    if (isBuildFinished(d.buildStatus)) return;
+    // Never sleep past the deadline - same rule as deploy --wait.
+    await ctl.wait(Math.max(0, Math.min(BUILD_POLL_MS, deadline - Date.now())));
+  }
+}
+
+// Returns true when the user pressed Ctrl-C, so a caller can stop too instead of carrying on.
+// `deadline` (epoch ms) bounds the whole thing - stream and poll - for a caller with its own timeout.
+export async function showBuildLog(ctx, app, wanted, { deadline = null } = {}) {
+  let deploymentUuid = typeof wanted === 'string' ? wanted : null;
+  if (!deploymentUuid) {
+    const history = await deployHistory(ctx, app.uuid);
+    if (!history.length) throw new CliError(`${app.name} has not been deployed yet.`);
+    deploymentUuid = history[0].deploymentUuid;
+  }
+
+  const ctl = interruptible();
+  let abortStream = () => {};
+  const onSigint = () => {
+    ctl.onSigint();
+    abortStream();
+  };
+  process.on('SIGINT', onSigint);
+  let deadlineTimer = null;
+
+  try {
+    let printed = 0;
+    const finished = await new Promise((resolve) => {
+      abortStream = streamBuildLog(ctx, app.uuid, deploymentUuid, {
+        onLog: (data) => {
+          const lines = Array.isArray(data && data.lines) ? data.lines : [];
+          printBuildLines(lines);
+          printed += lines.length;
+        },
+        onDone: () => {
+          abortStream();
+          resolve(true);
+        },
+        onUnavailable: () => {
+          abortStream();
+          resolve(false);
+        },
+        onError: () => {
+          abortStream();
+          resolve(false);
+        },
+      });
+      if (ctl.stopped) resolve(false); // Ctrl-C landed before the stream even opened
+      if (deadline !== null) {
+        deadlineTimer = setTimeout(() => {
+          abortStream();
+          resolve(false);
+        }, Math.max(0, deadline - Date.now()));
+      }
+    });
+    clearTimeout(deadlineTimer);
+
+    // Not finished over the stream -> the snapshot endpoint, skipping what we already printed. This
+    // is the correctness path; the stream only makes it feel live.
+    if (!finished && !ctl.stopped) await pollBuildLog(ctx, app, deploymentUuid, { alreadyPrinted: printed, deadline }, ctl);
+    return ctl.stopped;
+  } finally {
+    process.off('SIGINT', onSigint);
+  }
+}
+
+export async function logs(ctx, { positionals, flags }) {
+  const app = await resolveService(ctx, positionals[0]);
+
+  if (flags.build !== undefined) {
+    if (flags.search !== undefined) throw new CliError('--search works on the running service\'s output, not a build log.');
+    await showBuildLog(ctx, app, flags.build);
+    return 0;
+  }
+
+  // `--lines abc` used to become 100 without a word. A number over the server's own maximum is
+  // clamped (that ceiling is published, so clamping is what it means); anything unparseable is
+  // refused, because there is no defensible value to substitute - see cli/src/flags.js.
+  const lines = numberFlag('--lines', flags.lines, {
+    fallback: DEFAULT_LINES,
+    min: 0,
+    max: MAX_LINES,
+    clampToMax: true,
+    integer: true, // a fractional line count was being rounded downstream without a word
+  });
+
+  // --search: the dashboard's search, run by the server. Same rule as the server, refused here before any request.
+  const search = typeof flags.search === 'string' ? flags.search.trim() : '';
+  if (search.length > 200 || /[`\r\n]/.test(search)) {
+    throw new CliError('--search takes one line of up to 200 characters, without backticks.');
+  }
+
+  if (flags.follow) {
+    // Returns when Ctrl-C stops the watch, which is a successful end - see interruptible() above.
+    // Any other way out of that loop is a throw.
+    await followRuntime(ctx, app, lines, search);
+    return 0;
+  }
+
+  const blob = await runtimeLogs(ctx, app.uuid, lines, search);
+  if (!blob.trim()) {
+    out(search ? `No lines from ${app.name} in the last 24 hours contain "${search}".` : `${app.name} has not printed anything yet.`);
+    return 0;
+  }
+  process.stdout.write(blob.endsWith('\n') ? blob : `${blob}\n`);
+  return 0;
+}

package/src/commands/services.js

@@ -0,0 +1,72 @@
+// `voroa services` - the services in the active workspace.
+//
+// The status column comes from the BATCH endpoint, which dedupes its uuid list and then slices it
+// at a cap, dropping anything past it without a word. So we chunk (api.js owns the cap) and we
+// track which uuids came back: a service missing from the merged answer renders "Status
+// unavailable", never a blank cell. A blank would read as "this service has no status", which is a
+// different and false claim - the same silent-degrade shape as known bug #26.
+import { listApps, batchStatus, deployHistory } from '../api.js';
+import { classify } from '../status.js';
+import { REGION_LABEL } from '../region.js';
+import { renderTable, timeAgo, out, json } from '../output.js';
+
+const STATUS_UNAVAILABLE = 'Status unavailable';
+
+// How many "last deploy" reads run at once. The list endpoint carries no updated-at, so the column
+// is the newest deploy's time - one small read per service, the same source the dashboard uses.
+const HISTORY_CONCURRENCY = 6;
+
+async function mapWithLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (;;) {
+      const i = cursor++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+export async function services(ctx, { flags }) {
+  const apps = await listApps(ctx);
+
+  if (flags.json) {
+    // Raw rows, exactly as the API sent them - the point of --json is that a script sees the
+    // server's shape, not our rendering of it.
+    json({ services: apps.map((a) => a.raw) });
+    return 0;
+  }
+
+  if (apps.length === 0) {
+    out('No services in this workspace.');
+    out('Create one at https://app.getvoroa.com, then run this again.');
+    return 0;
+  }
+
+  const statuses = await batchStatus(ctx, apps.map((a) => a.uuid));
+
+  // Last deploy per service. Best-effort: one failed read shows an em dash in that row, it does not
+  // fail the listing.
+  const updated = await mapWithLimit(apps, HISTORY_CONCURRENCY, async (app) => {
+    try {
+      const rows = await deployHistory(ctx, app.uuid);
+      return rows.length ? timeAgo(rows[0].createdAt) : null;
+    } catch {
+      return null;
+    }
+  });
+
+  const rows = apps.map((app, i) => {
+    const st = statuses.get(app.uuid);
+    const label = st ? classify(st.containerStatus, st.deploymentStatus, st.verdict).label : STATUS_UNAVAILABLE;
+    return [app.name, label, REGION_LABEL, updated[i]];
+  });
+
+  out(renderTable(['NAME', 'STATUS', 'REGION', 'UPDATED'], rows));
+  return 0;
+}
+
+export { STATUS_UNAVAILABLE };

package/src/commands/ssh.js

@@ -0,0 +1,46 @@
+// `voroa ssh [service]` - a shell in the running service, through Voroa's SSH gateway.
+//
+// No new authentication: the gateway accepts the SSH keys already on the account (added in the
+// dashboard, behind a step-up), and there is no password login. This command only asks the server
+// where to connect and as whom, then hands the terminal to the system `ssh`.
+import { sshAccess, isApiToken } from '../api.js';
+import { runInteractive } from '../interactive.js';
+import { resolveService } from '../resolve.js';
+import { out, err, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+export async function ssh(ctx, { positionals, flags }) {
+  if (isApiToken(ctx.token)) throw new CliError('SSH needs a signed-in session, not an API token. Run `voroa login`.');
+  const app = await resolveService(ctx, positionals[0]);
+  const a = await sshAccess(ctx, app.uuid);
+
+  if (!a || a.entitled === false) {
+    const plans = Array.isArray(a && a.requiredPlans) && a.requiredPlans.length ? ` It is included in: ${a.requiredPlans.join(', ')}.` : '';
+    throw new CliError(`SSH is not included in this workspace's plan.${plans}`);
+  }
+  // The server's values go to ssh as arguments, so they are checked like input: a username beginning
+  // with "-" would be read as an ssh OPTION (-oProxyCommand runs a command locally). No shell is used,
+  // and `--` ends option parsing on top of the checks.
+  const port = Number(a.port);
+  if (
+    typeof a.username !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/i.test(a.username) ||
+    typeof a.host !== 'string' || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i.test(a.host) ||
+    !Number.isInteger(port) || port < 1 || port > 65535
+  ) {
+    throw new CliError('SSH details are not available for this service right now.');
+  }
+
+  const args = ['-p', String(port), '--', `${a.username}@${a.host}`];
+  if (flags.json || flags.print) {
+    if (flags.json) json({ host: a.host, port: a.port, username: a.username, hostKeyFingerprint: a.hostKeyFingerprint || null, keys: Array.isArray(a.keys) ? a.keys.length : 0 });
+    else out(`ssh ${a.username}@${a.host} -p ${port}`);
+    return 0;
+  }
+  if (Array.isArray(a.keys) && a.keys.length === 0) {
+    throw new CliError('Add an SSH public key to your account in the dashboard first - there is no password login.');
+  }
+  if (a.running === false) throw new CliError(`${app.name} is not running, so there is nothing to connect to. Start it with \`voroa start\`.`);
+  if (a.hostKeyFingerprint) err(`Gateway host key: ${a.hostKeyFingerprint} - compare it if ssh asks you to confirm.`);
+
+  return runInteractive('ssh', args, { notFound: 'ssh was not found. Install an OpenSSH client.' });
+}

package/src/commands/status.js

@@ -0,0 +1,36 @@
+// `voroa status <service>` - one service's live state.
+//
+// The label comes from the pinned `classify` in ../status.js and nowhere else. This file never
+// inspects a raw state token itself: that is what put a green "Running" badge on a container that
+// had been crash-looping for the better part of an hour (known bug #30).
+import { appStatus } from '../api.js';
+import { classify } from '../status.js';
+import { REGION_LABEL } from '../region.js';
+import { resolveService } from '../resolve.js';
+import { renderFields, out, json } from '../output.js';
+
+export async function status(ctx, { positionals, flags }) {
+  const app = await resolveService(ctx, positionals[0]);
+  const st = await appStatus(ctx, app.uuid);
+
+  if (flags.json) {
+    json(st ? st.raw : null);
+    return 0;
+  }
+
+  const label = st ? classify(st.containerStatus, st.deploymentStatus, st.verdict).label : 'Status unavailable';
+  // fqdn arrives comma-separated ("https://a,https://b"); the first entry is the primary.
+  const url = st && st.fqdn ? String(st.fqdn).split(',')[0].trim() : null;
+
+  out(
+    renderFields([
+      ['Service', app.name],
+      ['Id', app.uuid],
+      ['Status', label],
+      ['Region', REGION_LABEL],
+      ['Branch', (st && st.branch) || app.branch],
+      ['URL', url],
+    ])
+  );
+  return 0;
+}

package/src/commands/tokens.js

@@ -0,0 +1,81 @@
+// `voroa tokens list|create|revoke` - API tokens for CI and AI clients.
+//
+// A token is created from a signed-in SESSION only (the mint route needs a fresh step-up, so a stolen
+// session cannot quietly turn itself into a long-lived credential - ADR-0200 D7). The raw value is shown
+// ONCE, on stdout, because that is the whole point of the command; it is never written anywhere by us -
+// unless `--save` asks for it, in which case it goes into the CLI's own 0600 config for the tool commands
+// (mcpTools.js) and is NOT printed at all: a value that is stored has no reason to cross a screen.
+import { listApiTokens, mintApiToken, revokeApiToken, isApiToken } from '../api.js';
+import { withStepUp } from '../stepup.js';
+import { renderTable, out, err, json } from '../output.js';
+import { CliError } from '../errors.js';
+import { saveSettings } from '../config.js';
+
+function when(epochSec) {
+  return epochSec ? new Date(epochSec * 1000).toISOString().slice(0, 10) : '';
+}
+
+export async function tokens(ctx, { positionals, flags }) {
+  if (isApiToken(ctx.token)) throw new CliError('Tokens are managed from a signed-in session, not with an API token. Run `voroa login`.');
+  const sub = positionals[0];
+
+  if (!sub || sub === 'list') {
+    const d = await listApiTokens(ctx);
+    const rows = Array.isArray(d.tokens) ? d.tokens : [];
+    if (flags.json) {
+      // Metadata only - the list route never returns a value or a hash.
+      json({ tokens: rows, scopes: d.grantedScopes || d.scopes || [] });
+      return 0;
+    }
+    if (!rows.length) out('No API tokens in this workspace.');
+    else {
+      out(
+        renderTable(
+          ['NAME', 'SCOPES', 'EXPIRES', 'STATE', 'ID'],
+          rows.map((r) => [r.name, r.scopes, when(r.expiresAt), r.revokedAt ? 'revoked' : 'active', r.id])
+        )
+      );
+    }
+    const scopes = d.grantedScopes || d.scopes;
+    if (Array.isArray(scopes) && scopes.length) out(`\nScopes you can grant: ${scopes.join(', ')}`);
+    return 0;
+  }
+
+  if (sub === 'create') {
+    const name = typeof flags.name === 'string' ? flags.name.trim() : '';
+    if (!name) throw new CliError('Give the token a name: `voroa tokens create --name ci --scope services:read,services:act`.');
+    const scopes = typeof flags.scope === 'string' ? flags.scope.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    if (!scopes.length) throw new CliError('Choose at least one scope with --scope. `voroa tokens list` shows the ones you can grant.');
+    const d = await withStepUp(ctx, () => mintApiToken(ctx, name, scopes), { recovery: !!flags.recovery });
+    const t = d && d.token;
+    if (!t || !t.value) throw new CliError('The token was not created. Try again.');
+    if (flags.save) {
+      saveSettings({ apiToken: t.value, apiTokenUrl: ctx.apiUrl });
+      if (flags.json) json({ id: t.id, name: t.name, scopes: t.scopes, expiresAt: t.expiresAt, saved: true });
+      else out(`Token "${t.name}" saved for this machine. It expires ${when(t.expiresAt)}. ` + 'Run `voroa tools` to see what it unlocks.');
+      return 0;
+    }
+    if (flags.json) {
+      json({ id: t.id, name: t.name, scopes: t.scopes, expiresAt: t.expiresAt, value: t.value });
+      return 0;
+    }
+    // The scopes that were actually granted can be fewer than asked - an unknown scope is dropped.
+    out(renderTable(['NAME', 'SCOPES', 'EXPIRES', 'ID'], [[t.name, t.scopes, when(t.expiresAt), t.id]]));
+    out('');
+    out(t.value);
+    out('');
+    err('Copy this value now. It is shown once and cannot be retrieved again. Use it as VOROA_TOKEN.');
+    return 0;
+  }
+
+  if (sub === 'revoke') {
+    const id = positionals[1];
+    if (!id) throw new CliError('Which token? `voroa tokens revoke <id>` - see `voroa tokens list`.');
+    const d = await revokeApiToken(ctx, id);
+    if (flags.json) json({ id, revoked: !!(d && d.revoked) });
+    else out(d && d.revoked ? 'Token revoked. It stops working immediately.' : 'That token was already revoked, or does not exist.');
+    return 0;
+  }
+
+  throw new CliError(`Unknown tokens command "${sub}". Try \`voroa tokens list\`, \`create\` or \`revoke <id>\`.`);
+}

package/src/commands/workspace.js

@@ -0,0 +1,63 @@
+// `voroa workspace list` / `voroa workspace set <id>`
+//
+// The stored id is sent as the `X-Workspace-Id` header. It is a CLIENT-SUPPLIED value and the
+// server treats it as one: `middleware/workspaceScope.js` validates it against the caller's own
+// workspaces on every single request, and a foreign or forged id is a 403. So the check below is a
+// courtesy - it turns a typo into a sentence instead of a 403 on the next command - and it is not,
+// and must never become, the thing that decides access.
+//
+// Nothing stored means no header, which means the server uses the caller's default workspace. That
+// is deliberately not the same as the CLI picking one: an id we guessed is an ownership claim we
+// are not entitled to make.
+import { listWorkspaces, isApiToken } from '../api.js';
+import { saveSettings, readConfig } from '../config.js';
+import { renderTable, out, json } from '../output.js';
+import { CliError } from '../errors.js';
+
+export async function workspace(ctx, { positionals, flags }) {
+  const sub = positionals[0];
+  // An API token is pinned to one workspace on the server; there is nothing here for it to list or pick.
+  if (isApiToken(ctx.token)) {
+    throw new CliError('An API token is pinned to one workspace, so workspace commands do not apply to it.');
+  }
+
+  if (!sub || sub === 'list') {
+    const rows = await listWorkspaces(ctx);
+    if (flags.json) {
+      json({ workspaces: rows });
+      return 0;
+    }
+    if (!rows.length) {
+      out('No workspaces.');
+      return 0;
+    }
+    const chosen = readConfig().workspaceId || null;
+    out(
+      renderTable(
+        ['', 'NAME', 'ID'],
+        rows.map((w) => [
+          // With nothing chosen the server's default is what commands actually hit, so mark that
+          // one - showing no marker at all would imply no workspace is in effect.
+          (chosen ? w.id === chosen : !!w.isDefault) ? '*' : '',
+          w.name,
+          w.id,
+        ])
+      )
+    );
+    if (!chosen) out('\n* your default workspace. Use `voroa workspace set <id>` to pick another.');
+    return 0;
+  }
+
+  if (sub === 'set') {
+    const id = positionals[1];
+    if (!id) throw new CliError('Which workspace? `voroa workspace set <id>` - run `voroa workspace list` for the ids.');
+    const rows = await listWorkspaces(ctx);
+    const match = rows.find((w) => w.id === id);
+    if (!match) throw new CliError(`No workspace with the id "${id}". Run \`voroa workspace list\` to see yours.`);
+    saveSettings({ workspaceId: id });
+    out(`Commands now act on ${match.name}.`);
+    return 0;
+  }
+
+  throw new CliError(`Unknown workspace command "${sub}". Try \`voroa workspace list\` or \`voroa workspace set <id>\`.`);
+}