voroa-cli 0.2.0 → 0.3.0

package/README.md

@@ -109,6 +109,60 @@ to commit). In that folder and any subfolder, `<service>` becomes optional. The
 against your workspace on every command, so a link copied from someone else's repository does
 nothing. An explicit `--workspace` still wins over the one the link remembers.
 
+## Interactive session
+
+Run `voroa` with nothing after it and you get a session instead of a single command:
+
+```
+$ voroa
+
+  | ^ voroa  CLI 0.3.0
+  |
+  | Account   you@example.com
+  | Services  * 2 running   o 1 idle   x 0 failed
+
+  /help commands  -  Tab complete  -  Ctrl+C stop  -  /exit
+
+voroa > services
+voroa > logs web --follow
+voroa > deploy web --wait
+voroa > /exit
+```
+
+Every command on this page works there, with or without the leading `/`. **Tab** completes a command
+name, then a service name. **Up arrow** recalls earlier commands - only commands: what you type into a
+password, code or value prompt is never kept. **Ctrl+C** stops a running log tail and returns to the
+prompt; at an empty prompt, pressing it twice leaves, as does `/exit` or Ctrl+D. A command that fails
+prints its message and the session carries on.
+
+It is not a shell: quotes group words (`--command "node job.js"`), and nothing else on the line is
+expanded or executed. In a pipe or in CI, `voroa` with no arguments prints the usage text exactly as
+before; `voroa session` opens a session by name.
+
+On a real terminal the header, the status marks (green running, grey idle, amber changing, red failed)
+and the last line of a deploy are coloured. That is decoration on top of the words: set `NO_COLOR`, or
+pipe the output anywhere, and you get the same text with no colour and no escape codes.
+
+## For scripts and AI agents
+
+```
+voroa agent            the rules, written for a model to read
+voroa agent --json     the same as data
+```
+
+- `--json` on any command: the result is JSON on stdout, and a failure is one object on stderr,
+  `{"error": "...", "code": "NOT_FOUND"}`. The codes are a short fixed list - `voroa agent` prints them.
+- `--no-input` or `VOROA_NO_INPUT=1`: a step that would ask a question (a sign-in code, a password)
+  fails at once with `NEEDS_HUMAN` instead of waiting for an answer nobody will type.
+- `deploy --wait --json` prints one object when it ends, with `outcome` (`live`, `failed`,
+  `failed_to_start`, `timeout`, ...) and the same `exitCode` the process returns.
+- `logs --json` prints `{"service", "lines"}`; with `--follow`, one `{"line"}` object per line.
+- `status --all --json` gives every service with its `verdict` in one call.
+- `voroa tools <word>` narrows the list (`voroa tools bucket`); each command is marked as changing
+  something or not.
+- A flag a command does not have is refused (`BAD_INPUT`), never ignored.
+- Authenticate an agent with `VOROA_TOKEN`, never with a sign-in.
+
 ## Everything else: `voroa tools`
 
 The commands above are the everyday ones. Everything else the platform lets a token do is a command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voroa-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Voroa command line interface - deploy, inspect and manage your services, databases, cron jobs and storage from the terminal.",
   "type": "module",
   "license": "MIT",

package/src/agent.js

@@ -0,0 +1,95 @@
+// `voroa agent` - how to drive this CLI, written for an AI agent to read.
+//
+// A customer's coding agent (Claude Code, Cursor, anything that can run a shell command) does not need
+// a plugin to use Voroa: it needs to know five rules and where to look things up. This prints them.
+// The exit codes and error codes are READ from the modules that own them, not retyped, so the guide
+// cannot describe a contract the binary does not keep (test/agent.test.js).
+import { ERROR_CODES } from './errors.js';
+import { EXIT_OK, EXIT_FAILED, EXIT_TIMEOUT, VERDICT_MEANINGS } from './status.js';
+import { out, json } from './output.js';
+
+const EXIT_CODES = {
+  [EXIT_OK]: 'Succeeded. With deploy --wait: the service is live.',
+  [EXIT_FAILED]: 'Failed. The error says why.',
+  [EXIT_TIMEOUT]: 'Still going when the wait ended (deploy --wait), or not live yet (domains verify). Not a failure and not a success - check again.',
+};
+
+const RULES = [
+  'Authenticate with the VOROA_TOKEN environment variable: an API token that starts with voroa_cat_. A person creates it (dashboard: Settings -> API tokens, or `voroa tokens create`). You cannot sign in yourself - `voroa login` sends a code to a person\'s email.',
+  'Add --json to every command. The result is JSON on stdout. A failure is one JSON object on stderr: {"error": "...", "code": "..."}.',
+  'Set VOROA_NO_INPUT=1 (or pass --no-input). A step that needs a person then fails at once with code NEEDS_HUMAN instead of waiting for an answer that will not come.',
+  'Read the exit code, not the text. It says whether the COMMAND worked - not whether a service is healthy: `voroa status` exits 0 for a stopped service too. For health, read the "verdict" field (table below), never the raw "status" field.',
+  'Prefer the everyday commands (services, status, logs, deploy, restart, rollback, env, domains). The `voroa tools` commands cover everything else; a few overlap (services and list-services are the same list).',
+  'To stay read-only, run only commands that `voroa tools` marks "changes: no", plus services, status and logs.',
+  'A service is named by its name or its id. Every other resource (database, bucket, task) takes an id - get it from the matching list command.',
+  'Creating or deleting a resource is a PROPOSAL: `voroa propose` returns a request a person approves in the dashboard. Tell the person; do not retry, and do not look for another way.',
+  'Never put a secret value in a command line. Pipe it: `printf %s "$VALUE" | voroa env set KEY <service>`, or pass arguments with --args-file.',
+];
+
+const DISCOVER = [
+  ['voroa tools <word> --json', 'platform commands matching a word (bucket, backup, task...), each with its argument schema and whether it changes anything'],
+  ['voroa tools --json', 'all of them (large)'],
+  ['voroa <tools-command> --help', 'one of those: what it does and what it takes'],
+  ['voroa --help', 'the everyday commands and their flags'],
+  ['voroa agent --json', 'this guide as data'],
+];
+
+const EXAMPLES = [
+  ['voroa services --json', 'the services (names, ids, repository, branch)'],
+  ['voroa status --all --json', 'how every service is doing: its verdict'],
+  ['voroa status <service> --json', 'one service in full'],
+  ['voroa deploy <service> --wait --json', 'deploy and wait; exit 0 only when live'],
+  ['voroa logs <service> --lines 100 --json', 'recent output'],
+  ['voroa get-deploy-history <service> --json', 'what was deployed, and how it went'],
+  ['voroa rollback <service> --json', 'serve the previous version again'],
+];
+
+export function agentGuide(version) {
+  return {
+    cli: 'voroa',
+    version,
+    rules: RULES,
+    exitCodes: EXIT_CODES,
+    errorCodes: ERROR_CODES,
+    verdicts: VERDICT_MEANINGS,
+    discover: DISCOVER.map(([command, what]) => ({ command, what })),
+    examples: EXAMPLES.map(([command, what]) => ({ command, what })),
+  };
+}
+
+const table = (rows) => {
+  const width = Math.max(...rows.map(([a]) => String(a).length));
+  return rows.map(([a, b]) => `  ${String(a).padEnd(width)}  ${b}`).join('\n');
+};
+
+export function agent({ flags, version }) {
+  const guide = agentGuide(version);
+  if (flags.json) {
+    json(guide);
+    return 0;
+  }
+  out(
+    [
+      `Voroa CLI ${version} - guide for an AI agent`,
+      '',
+      'Rules',
+      ...RULES.map((r, i) => `  ${i + 1}. ${r}`),
+      '',
+      'Exit codes',
+      table(Object.entries(EXIT_CODES)),
+      '',
+      'Error codes (the "code" field of a --json failure)',
+      table(Object.entries(ERROR_CODES)),
+      '',
+      'A service\'s "verdict"',
+      table(Object.entries(VERDICT_MEANINGS)),
+      '',
+      'Look things up',
+      table(DISCOVER),
+      '',
+      'Examples',
+      table(EXAMPLES),
+    ].join('\n')
+  );
+  return 0;
+}

package/src/commands/deploy.js

@@ -20,7 +20,7 @@ import { showBuildLog } from './logs.js';
 import { verdictOutcome, EXIT_TIMEOUT } from '../status.js';
 import { resolveService } from '../resolve.js';
 import { numberFlag } from '../flags.js';
-import { out } from '../output.js';
+import { out, json, spinner, style, glyphs, elapsed, fancy } from '../output.js';
 import { CliError } from '../errors.js';
 
 const DEFAULT_TIMEOUT_MIN = 10;
@@ -37,8 +37,16 @@ export async function deploy(ctx, { positionals, flags }) {
 
   const app = await resolveService(ctx, positionals[0]);
 
+  const startedAt = Date.now();
   const triggered = await redeploy(ctx, app.uuid);
-  out(`Deploy triggered for ${app.name}.`);
+  const deploymentUuid = triggeredDeploymentUuid(triggered);
+  // --json: ONE object at the end and nothing before it, so stdout parses. The exit code is unchanged.
+  const say = flags.json ? () => {} : out;
+  const finish = (code, outcome, message) => {
+    if (flags.json) json({ service: app.name, id: app.uuid, deployment: deploymentUuid, outcome, message, exitCode: code });
+    return code;
+  };
+  say(`Deploy triggered for ${app.name}.`);
 
   // --follow = the build log as it happens, then the same verdict wait as --wait (same exit codes).
   // Only the uuid THIS trigger returned is followed: "the latest deploy" could be the previous one for
@@ -46,13 +54,13 @@ export async function deploy(ctx, { positionals, flags }) {
   // The deadline starts at the trigger and covers the log phase too, so --timeout means one thing.
   const deadline = Date.now() + minutes * 60_000;
 
-  if (flags.follow) {
-    const deploymentUuid = triggeredDeploymentUuid(triggered);
+  // A build log is text for a person; with --json, --follow simply waits like --wait.
+  if (flags.follow && !flags.json) {
     if (deploymentUuid) {
       // Ctrl-C while following ends the command - the deploy itself keeps running on the server.
       if (await showBuildLog(ctx, app, deploymentUuid, { deadline })) {
         out(`Stopped following. The deploy is still running - check \`voroa status ${app.name}\`.`);
-        return 0;
+        return finish(0, 'stopped_following', 'Stopped following. The deploy is still running.');
       }
     } else {
       out('The build log is not available yet for this deploy - waiting for the outcome instead.');
@@ -60,12 +68,22 @@ export async function deploy(ctx, { positionals, flags }) {
   }
 
   if (!flags.wait && !flags.follow) {
-    out('Run `voroa status ' + app.name + '` to check on it, or add --wait next time.');
-    return 0;
+    say('Run `voroa status ' + app.name + '` to check on it, or add --wait next time.');
+    return finish(0, 'triggered', 'Deploy triggered. It has not been waited for.');
   }
 
-  out('Waiting for the deploy to finish...');
+  const waiting = flags.json ? { stop() {} } : spinner('Waiting for the deploy to finish...');
+  let url = null;
+  // On a terminal the last line carries a mark, how long it took and where the service answers.
+  const lastLine = (outcome) => {
+    if (!fancy()) return outcome.message;
+    const g = glyphs();
+    const mark = outcome.code === 0 ? style('green', g.ok) : style('red', g.bad);
+    const where = outcome.code === 0 && url ? ` ${style('dim', g.arrow)} ${style('cyan', url)}` : '';
+    return `  ${mark} ${outcome.message} ${style('dim', elapsed(Date.now() - startedAt))}${where}`;
+  };
 
+  try {
   for (;;) {
     // A read failure mid-wait is not a verdict - a network blip must not be reported as a failed
     // deploy. But "we could not ask" and "it has not resolved yet" are DIFFERENT answers, and
@@ -77,6 +95,7 @@ export async function deploy(ctx, { positionals, flags }) {
     try {
       const st = await appStatus(ctx, app.uuid);
       verdict = st ? st.verdict : null;
+      if (st && st.fqdn) url = String(st.fqdn).split(',')[0].trim();
     } catch (e) {
       if (e instanceof ApiError && (e.httpStatus === 401 || e.httpStatus === 403 || e.httpStatus === 404)) {
         throw new CliError(`${e.message} The deploy was triggered and is still running - check it from the dashboard.`);
@@ -86,19 +105,26 @@ export async function deploy(ctx, { positionals, flags }) {
 
     const outcome = verdictOutcome(verdict);
     if (outcome.done) {
-      out(outcome.message);
-      return outcome.code;
+      waiting.stop();
+      say(lastLine(outcome));
+      return finish(outcome.code, verdict, outcome.message);
     }
 
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
-      out(`Timed out after ${minutes} minute${minutes === 1 ? '' : 's'}. The deploy has not finished.`);
-      out(`This is not a failure and not a success - check \`voroa status ${app.name}\`.`);
-      return EXIT_TIMEOUT;
+      waiting.stop();
+      const timedOut = `Timed out after ${minutes} minute${minutes === 1 ? '' : 's'}. The deploy has not finished.`;
+      say(timedOut);
+      say(`This is not a failure and not a success - check \`voroa status ${app.name}\`.`);
+      return finish(EXIT_TIMEOUT, 'timeout', timedOut);
     }
 
     // Never sleep past the deadline: a --timeout is a promise about when we stop, and overshooting
     // it by a poll interval makes the number in the flag a lie.
     await sleep(Math.min(POLL_MS, remaining));
   }
+  } finally {
+    // A thrown refusal must not leave the spinner's timer drawing over the error.
+    waiting.stop();
+  }
 }

package/src/commands/logs.js

@@ -7,7 +7,7 @@ import { runtimeLogs, buildLog, deployHistory, streamBuildLog, ApiError, SESSION
 import { isBuildFinished, isBuildRunning } from '../status.js';
 import { resolveService } from '../resolve.js';
 import { numberFlag } from '../flags.js';
-import { out, err } from '../output.js';
+import { out, err, json } from '../output.js';
 import { CliError } from '../errors.js';
 
 const DEFAULT_LINES = 100;
@@ -91,7 +91,7 @@ function interruptible() {
   return state;
 }
 
-async function followRuntime(ctx, app, lines, search) {
+async function followRuntime(ctx, app, lines, search, emit = out) {
   const ctl = interruptible();
   process.on('SIGINT', ctl.onSigint);
 
@@ -109,7 +109,7 @@ async function followRuntime(ctx, app, lines, search) {
         first = false;
         prev = next;
         if (fresh.length && fresh.some((l) => l !== '')) {
-          for (const line of fresh) out(line);
+          for (const line of fresh) emit(line);
           lastOutputAt = Date.now();
           interval = FOLLOW_BASE_MS; // new output -> back to a tight poll
         }
@@ -247,6 +247,19 @@ export async function logs(ctx, { positionals, flags }) {
 
   if (flags.build !== undefined) {
     if (flags.search !== undefined) throw new CliError('--search works on the running service\'s output, not a build log.');
+    if (flags.json) {
+      // A snapshot, not a stream: one object a program can parse. `status` says whether more is coming.
+      let deployment = typeof flags.build === 'string' ? flags.build : null;
+      if (!deployment) {
+        const history = await deployHistory(ctx, app.uuid);
+        if (!history.length) throw new CliError(`${app.name} has not been deployed yet.`, 1, 'NOT_FOUND');
+        deployment = history[0].deploymentUuid;
+      }
+      const d = await buildLog(ctx, app.uuid, deployment);
+      const text = (l) => (typeof l === 'string' ? l : String(l.text ?? ''));
+      json({ service: app.name, deployment, status: d.buildStatus ?? null, available: !!d.available, lines: (d.lines || []).filter(Boolean).map(text) });
+      return 0;
+    }
     await showBuildLog(ctx, app, flags.build);
     return 0;
   }
@@ -271,11 +284,17 @@ export async function logs(ctx, { positionals, flags }) {
   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);
+    // --json while following: one JSON object per line (NDJSON), so a reader can parse as it arrives.
+    const emit = flags.json ? (line) => process.stdout.write(`${JSON.stringify({ line })}\n`) : out;
+    await followRuntime(ctx, app, lines, search, emit);
     return 0;
   }
 
   const blob = await runtimeLogs(ctx, app.uuid, lines, search);
+  if (flags.json) {
+    json({ service: app.name, lines: splitLines(blob).filter((l) => l !== '') });
+    return 0;
+  }
   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;

package/src/commands/services.js

@@ -8,7 +8,7 @@
 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';
+import { renderTable, timeAgo, out, json, statusCell } from '../output.js';
 
 const STATUS_UNAVAILABLE = 'Status unavailable';
 
@@ -61,7 +61,7 @@ export async function services(ctx, { flags }) {
 
   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;
+    const label = st ? statusCell(classify(st.containerStatus, st.deploymentStatus, st.verdict)) : STATUS_UNAVAILABLE;
     return [app.name, label, REGION_LABEL, updated[i]];
   });
 

package/src/commands/status.js

@@ -3,13 +3,27 @@
 // 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 { appStatus, listApps, batchStatus } 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';
+import { renderFields, renderTable, out, json, statusCell } from '../output.js';
 
 export async function status(ctx, { positionals, flags }) {
+  // --all: every service's state at once. `services --json` deliberately makes no status calls, so
+  // without this a program had to ask service by service just to learn which ones are up.
+  if (flags.all) {
+    const apps = await listApps(ctx);
+    const statuses = await batchStatus(ctx, apps.map((a) => a.uuid));
+    const rows = apps.map((a) => {
+      const st = statuses.get(a.uuid);
+      return { name: a.name, id: a.uuid, verdict: st ? (st.verdict ?? null) : null, state: st ? classify(st.containerStatus, st.deploymentStatus, st.verdict) : null };
+    });
+    if (flags.json) json({ services: rows.map((r) => ({ name: r.name, id: r.id, verdict: r.verdict, state: r.state ? r.state.label : null })) });
+    else out(renderTable(['NAME', 'STATUS', 'ID'], rows.map((r) => [r.name, r.state ? statusCell(r.state) : 'Status unavailable', r.id])));
+    return 0;
+  }
+
   const app = await resolveService(ctx, positionals[0]);
   const st = await appStatus(ctx, app.uuid);
 
@@ -18,7 +32,7 @@ export async function status(ctx, { positionals, flags }) {
     return 0;
   }
 
-  const label = st ? classify(st.containerStatus, st.deploymentStatus, st.verdict).label : 'Status unavailable';
+  const label = st ? statusCell(classify(st.containerStatus, st.deploymentStatus, st.verdict)) : '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;
 

package/src/errors.js

@@ -1,10 +1,53 @@
 // A failure the user caused or can act on: a wrong name, a missing argument, an unusable flag.
 // Carries the exit code so `index.js` never has to guess one, and its message is written to be read
 // by a person - never a stack trace, never an internal detail.
+//
+// `code` is for a PROGRAM reading the failure - a script, or a customer's AI agent - so it never has
+// to parse the English. The list is short and fixed on purpose: a caller can switch on it, and
+// `voroa agent` prints exactly this table (test/agent.test.js keeps the two from drifting).
+export const ERROR_CODES = {
+  NOT_SIGNED_IN: 'No usable credential. A person must run voroa login, or set VOROA_TOKEN to an API token.',
+  FORBIDDEN: 'The credential is valid but may not do this (role, token scope, or a protected environment).',
+  NOT_FOUND: 'The service, database or other resource named does not exist in this workspace.',
+  AMBIGUOUS: 'More than one resource matches that name. Use the id.',
+  BAD_INPUT: 'A flag or argument is missing, unknown or malformed. Fix the command; do not retry it unchanged.',
+  NEEDS_HUMAN: 'This step asks a person a question (a sign-in code, a password, a confirmation). Stop and ask them.',
+  TIMEOUT: 'Voroa did not answer in time. Safe to retry once.',
+  UNREACHABLE: 'Voroa could not be reached from this machine (network, proxy or a wrong --api-url).',
+  FAILED: 'Anything else. The message says what happened.',
+};
+
 export class CliError extends Error {
-  constructor(message, exitCode = 1) {
+  constructor(message, exitCode = 1, code = null) {
     super(message);
     this.name = 'CliError';
     this.exitCode = exitCode;
+    this.code = code;
   }
 }
+
+const FROM_HTTP = { 0: 'UNREACHABLE', 401: 'NOT_SIGNED_IN', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 408: 'TIMEOUT', 504: 'TIMEOUT' };
+// What the server, or the tool kernel (customer-mcp/src/lib/http.js), calls the same things.
+const FROM_OTHER = {
+  step_up_required: 'NEEDS_HUMAN',
+  UPSTREAM_TIMEOUT: 'TIMEOUT',
+  UPSTREAM_UNREACHABLE: 'UNREACHABLE',
+  NOT_CONFIGURED: 'NOT_SIGNED_IN',
+  INSECURE_URL: 'BAD_INPUT',
+  UNAUTHORIZED: 'NOT_SIGNED_IN',
+};
+
+// One answer for any thrown thing. Order matters: our own code wins, then a name the server or the
+// kernel used, then the HTTP status, then FAILED - never undefined, so a reader can always switch on it.
+export function errorCode(e) {
+  if (!e) return 'FAILED';
+  for (const c of [e.code, e.cause && e.cause.code]) {
+    if (typeof c !== 'string') continue;
+    if (Object.hasOwn(ERROR_CODES, c)) return c;
+    if (Object.hasOwn(FROM_OTHER, c)) return FROM_OTHER[c];
+  }
+  for (const s of [e.httpStatus, e.cause && e.cause.httpStatus]) {
+    if (Number.isInteger(s) && Object.hasOwn(FROM_HTTP, s)) return FROM_HTTP[s];
+  }
+  return 'FAILED';
+}

package/src/index.js

@@ -13,8 +13,8 @@ import { readFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { readSettings } from './config.js';
 import { contextFrom } from './api.js';
-import { err, out } from './output.js';
-import { closePrompts } from './prompt.js';
+import { out, reportError } from './output.js';
+import { closePrompts, setNoInput } from './prompt.js';
 import { CliError } from './errors.js';
 import { login } from './commands/login.js';
 import { services } from './commands/services.js';
@@ -30,6 +30,8 @@ import { tokens } from './commands/tokens.js';
 import { domains } from './commands/domains.js';
 import { ssh } from './commands/ssh.js';
 import { runTool } from './mcpTools.js';
+import { startSession, wantsSession } from './session.js';
+import { agent } from './agent.js';
 
 // Read from the manifest rather than repeated here. A hardcoded copy goes stale at the first
 // release nobody remembers to edit in two places, and `--version` reporting the wrong number is the
@@ -43,6 +45,7 @@ Usage
   voroa login [--password] [--recovery] sign in (a 6-digit code by email, or a password)
   voroa services                        the services in the active workspace
   voroa status <service>                one service's live state
+  voroa status --all                    every service's state
   voroa logs <service> [--lines N]      the running container's output
   voroa logs <service> --search TEXT    only lines containing TEXT (last 24 hours)
   voroa logs <service> --follow         keep tailing it
@@ -67,13 +70,16 @@ Usage
   voroa ssh [service] [--print]         a shell in the running service
   voroa workspace list                  your workspaces
   voroa workspace set <id>              choose the workspace commands act on
-  voroa tools                           every other command (projects, cron, backups, buckets, ...)
+  voroa tools [word]                    every other command (projects, cron, backups, buckets, ...)
+  voroa                                 with nothing after it: an interactive session (also: voroa session)
+  voroa agent                           how an AI agent should drive this CLI (--json for data)
   voroa <command> --help                what one of those takes
 
 Flags
   --workspace <id>    act on this workspace, for this command only
   --api-url <url>     talk to a different Voroa API
-  --json              machine-readable output
+  --json              machine-readable output; a failure is then {"error","code"} on stderr
+  --no-input          never ask a question - fail with NEEDS_HUMAN instead (also VOROA_NO_INPUT=1)
   --timeout <min>     with deploy --wait, how long to wait (default 10)
   --lines <n>         with logs, how many lines to fetch (default 100, max 1000)
   --search <text>     with logs, only lines containing this text (case-insensitive)
@@ -82,7 +88,7 @@ Flags
 Exit codes
   0  succeeded (with deploy --wait: the service is live)
   1  failed (including a deploy that failed or did not start)
-  2  deploy --wait ran out of time while the deploy was still going
+  2  deploy --wait ran out of time while the deploy was still going; domains verify: not live yet
 
 <service> is a service name or its id, resolved inside the active workspace only.
 
@@ -123,6 +129,12 @@ export function parseArgv(argv) {
   return { flags, positionals };
 }
 
+// Every flag an everyday command reads. A flag outside this list is REFUSED: `--line 5` for `--lines 5`
+// used to be ignored without a word, and the command then did something other than what was asked.
+// (The tool commands check their own flags against their own schema - mcpTools.js.)
+const KNOWN_FLAGS = new Set(['all', 'apiUrl', 'build', 'buildTime', 'fix', 'follow', 'h', 'help', 'json', 'lines', 'name', 'noInput', 'overwrite', 'password', 'print', 'recovery', 'save', 'scope', 'search', 'showUrl', 'timeout', 'to', 'v', 'version', 'wait', 'workspace']);
+const asFlag = (key) => `--${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+
 // Exported for test/mcpTools.test.js, which pins exactly which tool names these shadow.
 export const COMMANDS = { login, services, status, logs, deploy, workspace, link, unlink, open, env, restart, stop, start, rollback, db, tokens, domains, ssh };
 
@@ -136,8 +148,15 @@ export async function run(argv) {
   // Asking for help SUCCEEDED at what was asked, with or without a command - `voroa --help` and
   // `voroa services --help` must not disagree about that. Running the tool with nothing to do is the
   // only usage error here.
+  setNoInput(flags.noInput || process.env.VOROA_NO_INPUT);
   const name = positionals[0];
   const command = COMMANDS[name];
+  if (name === 'agent') return agent({ flags, version: VERSION });
+  // No command at all, in a real terminal: the interactive session (session.js). On a pipe or in CI
+  // nothing changes - the usage text and exit 1 below. `voroa session` asks for it by name.
+  if (name === 'session' || (!name && !flags.help && !flags.h && wantsSession())) {
+    return startSession({ run, version: VERSION, commands: Object.keys(COMMANDS) });
+  }
   // Anything that is not a hand-written command is looked up among the customer-MCP tools
   // (mcpTools.js). Those parse their own flags from their own schema, --help included. `tool <name>`
   // reaches one whose short name a hand-written command already owns (restart, stop, start, rollback).
@@ -158,6 +177,9 @@ export async function run(argv) {
   }
 
 
+  const stray = Object.keys(flags).find((key) => !KNOWN_FLAGS.has(key));
+  if (stray) throw new CliError(`${name} has no ${asFlag(stray)} flag. Run \`voroa --help\`.`, 1, 'BAD_INPUT');
+
   const settings = readSettings({ apiUrl: flags.apiUrl, workspace: flags.workspace });
   const ctx = contextFrom(settings);
   ctx.workspaceExplicit = !!flags.workspace;
@@ -181,7 +203,7 @@ if (invokedDirectly) {
       process.exitCode = code ?? 0;
     })
     .catch((e) => {
-      err(e && e.message ? e.message : 'Something went wrong.');
+      reportError(e, { asJson: process.argv.includes('--json') });
       process.exitCode = e && Number.isInteger(e.exitCode) ? e.exitCode : 1;
     })
     // An open readline interface holds the event loop open. Closed centrally so no command has to

package/src/interactive.js

@@ -8,20 +8,26 @@
 // No shell, ever: `args` are passed straight to the program, so nothing in them is interpreted.
 import { spawn } from 'node:child_process';
 import { CliError } from './errors.js';
+import { suspendPrompts, resumePrompts } from './prompt.js';
 
 export function runInteractive(cmd, args, { env, notFound } = {}) {
   const ignoreSigint = () => {};
   process.on('SIGINT', ignoreSigint);
+  // Inside a session readline holds the terminal; the child gets it for as long as it runs. Outside one
+  // both calls do nothing.
+  suspendPrompts();
   return new Promise((resolve, reject) => {
     // The CLI's own credential never reaches the child (ssh can forward variables with SendEnv).
     const base = env || Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^VOROA_/i.test(k)));
     const child = spawn(cmd, args, { stdio: 'inherit', env: base });
     child.on('error', (e) => {
       process.off('SIGINT', ignoreSigint);
+      resumePrompts();
       reject(new CliError(e && e.code === 'ENOENT' ? notFound || `${cmd} was not found.` : `Could not start ${cmd}.`));
     });
     child.on('exit', (code) => {
       process.off('SIGINT', ignoreSigint);
+      resumePrompts();
       resolve(code ?? 1);
     });
   });

package/src/mcpTools.js

@@ -16,6 +16,7 @@ import { CliError } from './errors.js';
 import { contextFrom, isApiToken } from './api.js';
 import { resolveService } from './resolve.js';
 import { out, json, renderTable } from './output.js';
+import { ownsStdin } from './prompt.js';
 
 const KERNEL_HOMES = [new URL('./mcp/', import.meta.url), new URL('../../customer-mcp/src/', import.meta.url)];
 
@@ -131,11 +132,13 @@ export function parseToolArgv(tool, argv) {
     else if (flag === '--json') result.asJson = true;
     // Already applied by index.js when it built the settings; consumed here so they are not "unknown".
     else if (flag === '--api-url' || flag === '--workspace') takeValue();
+    else if (flag === '--no-input') result.noInput = true;
     else if (flag === '--args') result.args = { ...readJsonObject(takeValue(), '--args'), ...result.args };
     else if (flag === '--args-file') {
       // `-` is stdin. A value on the command line lands in shell history and in `ps`; a secret (an
       // environment variable's value, a secret file's contents) should arrive by pipe or by file.
       const file = takeValue();
+      if (file === '-' && ownsStdin()) throw new CliError('Inside a session, standard input belongs to the session. Give --args-file a real file.');
       let text;
       try {
         text = readFileSync(file === '-' ? 0 : file, 'utf8');
@@ -162,14 +165,37 @@ const firstSentence = (text) => {
   return end === -1 ? s : s.slice(0, end + 1);
 };
 
-export function toolsList(kernel) {
-  return renderTable(['COMMAND', 'WHAT IT DOES'], kernel.listTools().map((t) => [commandName(t.name), firstSentence(t.description)]));
+// Tool descriptions were written for the connector, where a tool is `list_buckets`. Here it is
+// `list-buckets`, and a description that names a command the reader cannot type is a small lie.
+function forCli(text, names) {
+  let said = String(text || '');
+  // Longest first, so `list_bucket_files` is not half-replaced by `list_bucket`.
+  for (const name of [...names].sort((a, b) => b.length - a.length)) {
+    if (name.includes('_')) said = said.split(name).join(commandName(name));
+  }
+  return said;
+}
+
+// What `voroa tools` lists: optionally only those whose name or description contains every word given.
+// `changes` is the tool's own declared kind - a read never changes anything.
+export function listForCli(kernel, words = []) {
+  const wanted = words.map((w) => w.toLowerCase());
+  return kernel
+    .listTools()
+    .map((t) => ({ command: commandName(t.name), changes: kernel.getTool(t.name).kind !== 'read', description: forCli(t.description, kernel.toolNames()), inputSchema: t.inputSchema }))
+    .filter((t) => wanted.every((w) => t.command.includes(w) || t.description.toLowerCase().includes(w)));
+}
+
+export function toolsList(kernel, words = []) {
+  const rows = listForCli(kernel, words);
+  if (!rows.length) return `No command matches "${words.join(' ')}". Run \`voroa tools\` for the full list.`;
+  return renderTable(['COMMAND', 'CHANGES', 'WHAT IT DOES'], rows.map((t) => [t.command, t.changes ? 'yes' : 'no', firstSentence(t.description)]));
 }
 
-export function toolHelp(tool, { explicit = false } = {}) {
+export function toolHelp(tool, { explicit = false, toolNames = [] } = {}) {
   const props = (tool.inputSchema && tool.inputSchema.properties) || {};
   const required = new Set((tool.inputSchema && tool.inputSchema.required) || []);
-  const lines = [`voroa ${explicit ? 'tool ' : ''}${commandName(tool.name)}`, '', String(tool.description || '').replace(/\s+/g, ' ').trim()];
+  const lines = [`voroa ${explicit ? 'tool ' : ''}${commandName(tool.name)}`, '', forCli(tool.description, toolNames).replace(/\s+/g, ' ').trim()];
   const names = Object.keys(props);
   if (names.length) {
     lines.push('', 'Arguments');
@@ -180,7 +206,7 @@ export function toolHelp(tool, { explicit = false } = {}) {
           flagName(p),
           props[p].enum ? 'one of' : typeOf(props[p]),
           required.has(p) ? 'yes' : 'no',
-          props[p].enum ? `${props[p].enum.join(', ')}` : String(props[p].description || '').replace(/\s+/g, ' ').trim(),
+          props[p].enum ? `${props[p].enum.join(', ')}` : forCli(props[p].description, toolNames).replace(/\s+/g, ' ').trim(),
         ])
       )
     );
@@ -219,19 +245,20 @@ export async function runTool(settings, name, argv, { fetchImpl, asJson = false,
   // Listing and help need no credential: both come from the tool definitions. Only a call does.
   const kernel = await loadKernel({ apiUrl: settings.apiUrl, token, fetchImpl });
   if (name === 'tools') {
-    if (asJson || argv.includes('--json')) json(kernel.listTools().map((t) => ({ command: commandName(t.name), description: t.description, inputSchema: t.inputSchema })));
-    else out(toolsList(kernel));
+    const words = argv.filter((a) => !a.startsWith('--'));
+    if (asJson || argv.includes('--json')) json(listForCli(kernel, words));
+    else out(toolsList(kernel, words));
     return 0;
   }
   const tool = findTool(kernel, name);
-  if (!tool) throw new CliError(`Unknown command "${name}". Run \`voroa --help\`, or \`voroa tools\` for the full list.`);
+  if (!tool) throw new CliError(`Unknown command "${name}". Run \`voroa --help\`, or \`voroa tools\` for the full list.`, 1, 'BAD_INPUT');
 
   const parsed = parseToolArgv(tool, argv);
   if (parsed.help) {
-    out(toolHelp(tool, { explicit }));
+    out(toolHelp(tool, { explicit, toolNames: kernel.toolNames() }));
     return 0;
   }
-  if (!token) throw new CliError(NO_API_TOKEN);
+  if (!token) throw new CliError(NO_API_TOKEN, 1, 'NOT_SIGNED_IN');
 
   // A service can be named, or left out in a linked folder - the same resolver the hand-written commands
   // use, so the answer still comes from the server's own workspace-scoped list (resolve.js).

package/src/output.js

@@ -1,6 +1,86 @@
-// Terminal output helpers. Plain text, no colour: a CLI's output gets piped, redirected and pasted
-// into tickets, and ANSI codes survive all three as garbage. The state is carried by the WORD
-// ("Crash looping"), never by a colour a pipe would strip anyway.
+// Terminal output helpers. Plain text: a CLI's output gets piped, redirected and pasted into tickets,
+// and ANSI codes survive all three as garbage. The state is carried by the WORD ("Crash looping"),
+// never by a colour a pipe would strip anyway.
+//
+// The ONE exception is everything gated by `fancy()` below: colour, a status mark, a spinner. All of
+// it is decoration ON TOP of the words and switches itself off unless the stream is a real terminal,
+// NO_COLOR is unset and TERM is not "dumb" - so everything above still holds for every pipe, file and
+// CI log, and an AI agent reading the output never sees an escape code.
+import { errorCode } from './errors.js';
+
+export function fancy(stream = process.stdout) {
+  return !!(stream && stream.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+}
+
+const OFF_COLOUR = '\x1b[39m';
+const STYLES = {
+  bold: ['\x1b[1m', '\x1b[22m'],
+  dim: ['\x1b[2m', '\x1b[22m'],
+  green: ['\x1b[32m', OFF_COLOUR],
+  amber: ['\x1b[33m', OFF_COLOUR],
+  red: ['\x1b[31m', OFF_COLOUR],
+  gray: ['\x1b[90m', OFF_COLOUR],
+  cyan: ['\x1b[36m', OFF_COLOUR],
+  violet: ['\x1b[38;5;141m', OFF_COLOUR], // the brand accent, from the 256-colour table every VT terminal has
+};
+
+export function style(kind, text, stream = process.stdout) {
+  const codes = STYLES[kind];
+  if (!codes || !fancy(stream)) return text;
+  return `${codes[0]}${text}${codes[1]}`;
+}
+
+// Marks. The old Windows console host draws several of these as boxes, so it gets ASCII; Windows
+// Terminal and editor terminals announce themselves and get the real ones.
+const UNICODE = { run: '\u25cf', idle: '\u25cb', busy: '\u25d0', fail: '\u25cf', ok: '\u2714', bad: '\u2716', prompt: '\u203a', bar: '\u258c', arrow: '\u2192', logo: '\u25b2', dot: '\u00b7', spin: ['\u280b', '\u2819', '\u2839', '\u2838', '\u283c', '\u2834', '\u2826', '\u2827', '\u2807', '\u280f'] };
+const ASCII = { run: '*', idle: 'o', busy: '~', fail: 'x', ok: 'ok', bad: 'x', prompt: '>', bar: '|', arrow: '->', logo: '^', dot: '-', spin: ['-', '\\', '|', '/'] };
+
+export function glyphs(env = process.env, platform = process.platform) {
+  return platform !== 'win32' || env.WT_SESSION || env.TERM_PROGRAM ? UNICODE : ASCII;
+}
+
+const TONE = { green: ['green', 'run'], gray: ['gray', 'idle'], amber: ['amber', 'busy'], red: ['red', 'fail'] };
+
+// A status for a table cell. The WORD is always there; on a terminal it gains a mark and a colour.
+// Takes what `classify` returned - this file never looks at a raw status itself.
+export function statusCell(state, stream = process.stdout) {
+  if (!fancy(stream) || !TONE[state.tone]) return state.label;
+  const [colour, mark] = TONE[state.tone];
+  return style(colour, `${glyphs()[mark]} ${state.label}`, stream);
+}
+
+export function elapsed(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+// "Still working" for a wait with nothing to print. Off a terminal it is ONE plain line, exactly what
+// the command printed before spinners existed, so a log file gets a sentence and not 400 frames.
+export function spinner(text, { stream = process.stdout, intervalMs = 90 } = {}) {
+  if (!fancy(stream)) {
+    stream.write(`${text}\n`);
+    return { stop() {} };
+  }
+  const frames = glyphs().spin;
+  const started = Date.now();
+  let i = 0;
+  const draw = () => stream.write(`\r\x1b[2K  ${style('cyan', frames[i++ % frames.length], stream)} ${text} ${style('dim', elapsed(Date.now() - started), stream)}`);
+  draw();
+  const timer = setInterval(draw, intervalMs);
+  return {
+    stop() {
+      clearInterval(timer);
+      stream.write('\r\x1b[2K');
+    },
+  };
+}
+
+// Escape codes take no room on screen, so a column is measured by what is SEEN.
+const ANSI = /\x1b\[[0-9;]*m/g;
+export function visibleLength(text) {
+  return String(text).replace(ANSI, '').length;
+}
+const padTo = (text, width) => text + ' '.repeat(Math.max(0, width - visibleLength(text)));
 
 // Column-aligned table. Values are stringified defensively - a null cell renders as the em dash, so
 // an empty column never reads as an empty VALUE.
@@ -13,8 +93,8 @@ function cell(value) {
 
 export function renderTable(headers, rows) {
   const body = rows.map((r) => r.map(cell));
-  const widths = headers.map((h, i) => Math.max(String(h).length, ...body.map((r) => (r[i] || '').length), 0));
-  const line = (cells) => cells.map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i]))).join('  ').trimEnd();
+  const widths = headers.map((h, i) => Math.max(String(h).length, ...body.map((r) => visibleLength(r[i] || '')), 0));
+  const line = (cells) => cells.map((c, i) => (i === cells.length - 1 ? c : padTo(c, widths[i]))).join('  ').trimEnd();
   return [line(headers.map(String)), ...body.map(line)].join('\n');
 }
 
@@ -51,6 +131,15 @@ export function err(text = '') {
   process.stderr.write(`${text}\n`);
 }
 
+// A failure, for whoever is reading. With --json it is one JSON object on stderr - the same message a
+// person gets, plus a code from the fixed list in errors.js. Never the error object itself: that is the
+// last place a token could surface (golden rule 13).
+export function reportError(e, { asJson = false } = {}) {
+  const message = e && e.message ? e.message : 'Something went wrong.';
+  if (asJson) process.stderr.write(`${JSON.stringify({ error: message, code: errorCode(e) })}\n`);
+  else err(message);
+}
+
 export function json(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

package/src/prompt.js

@@ -13,6 +13,7 @@
 //   * every prompt can carry a timeout. A CLI blocked forever on stdin inside CI is a hung job with
 //     no explanation; timing out with a sentence beats hanging with none.
 import readline from 'node:readline';
+import { CliError } from './errors.js';
 
 class PromptTimeout extends Error {
   constructor() {
@@ -27,6 +28,34 @@ let closed = false;
 const waiting = []; // resolvers for prompts that have been asked but not yet answered
 const buffered = []; // lines that arrived before anything asked for them
 
+// THE INTERACTIVE SESSION (session.js) rides on this same interface - it must, for the reason above -
+// and needs three things a one-shot command does not. They are set here, once, so that an interface
+// RE-created later (a prompt timeout closes it) still has them:
+//   completer  Tab completion.
+//   onSigint   In terminal mode readline SWALLOWS Ctrl+C: the process never receives SIGINT, so the
+//              stop handlers `logs --follow` and `deploy --follow` register on `process` would never
+//              fire and a tail could not be stopped. The session decides where the keypress goes.
+//   history    Kept in this module, so it survives a re-created interface.
+let session = null;
+let history = [];
+
+export function configureSession(options) {
+  session = options || null;
+  if (!session) history = [];
+}
+
+// True while a session owns standard input - `--args-file -` cannot read it then (mcpTools.js).
+export function ownsStdin() {
+  return !!session;
+}
+
+// Readline records EVERY line it reads, and Up arrow replays them. The answer to a prompt is not a
+// command: it can be a password, a one-time code, or an environment variable's value (golden rule 13).
+// Only a line the session asked for as a command stays.
+function forget(line) {
+  if (rl && Array.isArray(rl.history) && rl.history[0] === line) rl.history.shift();
+}
+
 function iface() {
   if (!rl) {
     rl = readline.createInterface({
@@ -35,6 +64,7 @@ function iface() {
       // (`--json`, `db connect --show-url`). A prompt mixed into it corrupts exactly that output.
       output: process.stderr,
       terminal: !!process.stdin.isTTY,
+      ...(session ? { completer: (line) => session.completer(line), history, historySize: 200 } : {}),
     });
     closed = false;
     // We consume 'line' rather than rl.question(), and we QUEUE what nobody has asked for yet. On a
@@ -44,17 +74,77 @@ function iface() {
     // input that had already been read.
     rl.on('line', (line) => {
       const next = waiting.shift();
+      if (!next || !next.isCommand) forget(line);
       if (next) next(line);
       else buffered.push(line);
     });
     rl.on('close', () => {
       closed = true;
+      if (rl && Array.isArray(rl.history)) history = rl.history;
       while (waiting.length) waiting.shift()(''); // EOF - unblock anything still asking
     });
+    // Registered ONLY for a session: with no listener readline keeps its default for one-shot commands.
+    if (session) rl.on('SIGINT', () => session.onSigint());
   }
   return rl;
 }
 
+// Standard input has ended (Ctrl+D, or the end of a pipe) and every line that arrived has been used.
+export function promptsEnded() {
+  return closed && buffered.length === 0;
+}
+
+// What was typed while a command was running is thrown away, not run: a stray `y` typed during a log
+// tail must not become the next command. Terminal only - on a pipe every line "arrives early", and
+// dropping there would discard the script.
+export function dropTypeAhead() {
+  if (process.stdin.isTTY) buffered.length = 0;
+}
+
+// Hand the terminal to another program (psql, ssh) and take it back. Readline holds the terminal in raw
+// mode and reads every key; a child that inherits it would fight for each keystroke.
+export function suspendPrompts() {
+  if (!rl) return;
+  rl.pause();
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') process.stdin.setRawMode(false);
+}
+
+export function resumePrompts() {
+  if (!rl) return;
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') process.stdin.setRawMode(true);
+  rl.resume();
+}
+
+// The session's own prompt. Unlike `ask`, the text is given to readline AS its prompt, so recalling a
+// line with Up arrow redraws it instead of erasing it - and the line it returns is kept in history.
+export function askCommand(text) {
+  const r = iface();
+  if (buffered.length) return Promise.resolve(String(buffered.shift()));
+  if (closed) return Promise.resolve('');
+  r.setPrompt(text);
+  r.prompt();
+  return new Promise((resolve) => {
+    const take = (line) => {
+      r.setPrompt('');
+      resolve(String(line || ''));
+    };
+    take.isCommand = true;
+    waiting.push(take);
+  });
+}
+
+// Draw the session prompt again after something was printed over it.
+export function reprompt() {
+  if (rl) rl.prompt();
+}
+
+// Clear whatever is typed on the current line (Ctrl+C at a prompt, the way a shell does it).
+export function clearTypedLine() {
+  if (!rl || !rl.line) return false;
+  rl.write(null, { ctrl: true, name: 'u' });
+  return true;
+}
+
 // An open readline interface holds the event loop open, so the process would never exit. Every
 // command path closes prompts when it finishes (index.js does it centrally).
 export function closePrompts() {
@@ -84,7 +174,19 @@ function withTimeout(promise, timeoutMs) {
   });
 }
 
+// NO PERSON IS HERE (--no-input, VOROA_NO_INPUT). An agent or a pipeline that reaches a question would
+// otherwise sit on it until something upstream gives up, with nothing to tell it why. It gets a code
+// it can act on instead. The session's own prompt is not a question and is not affected.
+let noInput = false;
+export function setNoInput(value) {
+  noInput = !!value;
+}
+
 function question(text, { hide = false } = {}) {
+  if (noInput) {
+    const asked = String(text).replace(/[:\s]+$/, '');
+    throw new CliError(`This step needs a person - it asks for "${asked}". Run it yourself in a terminal, or set VOROA_TOKEN to an API token.`, 1, 'NEEDS_HUMAN');
+  }
   const r = iface();
   process.stderr.write(text);
 

package/src/resolve.js

@@ -48,17 +48,17 @@ export async function resolveService(ctx, needle, { useLink = true } = {}) {
       err(`Using linked service ${linked.serviceName || linked.serviceId} (${linked.file})`);
     }
   }
-  if (!needle) throw new CliError('Which service? Pass a service name or id, or run `voroa link <service>` in this folder.');
+  if (!needle) throw new CliError('Which service? Pass a service name or id, or run `voroa link <service>` in this folder.', 1, 'BAD_INPUT');
   const apps = await listApps(ctx);
   if (apps.length === 0) {
-    throw new CliError('There are no services in this workspace. Check `voroa workspace list`.');
+    throw new CliError('There are no services in this workspace. Check `voroa workspace list`.', 1, 'NOT_FOUND');
   }
 
   const found = pickByNameOrId(apps, needle, { idOnly: !!linked });
   if (found.match) return found.match;
-  if (found.ambiguous) throw new CliError(`Multiple services match "${needle}", use the id:\n${ambiguityList(found.ambiguous)}`);
+  if (found.ambiguous) throw new CliError(`Multiple services match "${needle}", use the id:\n${ambiguityList(found.ambiguous)}`, 1, 'AMBIGUOUS');
   if (linked) {
     throw new CliError(`This folder is linked to ${linked.serviceName || linked.serviceId}, which is not in this workspace. Run \`voroa link <service>\` again.`);
   }
-  throw new CliError(`No service called "${needle}" in this workspace. Run \`voroa services\` to see them.`);
+  throw new CliError(`No service called "${needle}" in this workspace. Run \`voroa services\` to see them.`, 1, 'NOT_FOUND');
 }

package/src/session.js

@@ -0,0 +1,270 @@
+// `voroa` with nothing after it: an interactive session (plan docs/plans/2026-11-11-cli-interactive-session.md).
+//
+// A session adds NO commands of its own beyond /help, /clear and /exit. Every line is split into words
+// and handed to the same `run()` that `voroa <args>` uses, so a command cannot behave one way typed
+// here and another way typed in a shell (rule #10). What a session does add is the terminal: a welcome
+// box, Tab completion, Up-arrow history, and a Ctrl+C that stops a log tail without ending the session.
+//
+// The terminal itself belongs to prompt.js - ONE readline interface per process, for the reason in its
+// header. This file never creates one.
+import { askCommand, configureSession, promptsEnded, dropTypeAhead, clearTypedLine, reprompt, closePrompts } from './prompt.js';
+import { readSettings, readConfig } from './config.js';
+import { contextFrom, listApps, batchStatus, isApiToken } from './api.js';
+import { classify, TONE_WORDS } from './status.js';
+import { loadKernel, commandName } from './mcpTools.js';
+import { CliError } from './errors.js';
+import { out, err, style, fancy, glyphs } from './output.js';
+
+// The welcome box makes one call. It must never be the reason a session does not open.
+const WELCOME_TIMEOUT_MS = 3000;
+const STATUS_TIMEOUT_MS = 4000;
+const SESSION_WORDS = ['help', 'clear', 'exit'];
+
+// Both ends must be a real terminal. A pipe on either side is a script, and a script gets exactly what
+// it got before sessions existed: the usage text.
+export function wantsSession(stdin = process.stdin, stdout = process.stdout) {
+  return !!(stdin && stdin.isTTY && stdout && stdout.isTTY);
+}
+
+// Words, with quotes: `--command "node job.js"` is one argument. NOT a shell - nothing is expanded or
+// executed, so `$HOME`, backticks, `|` and `>` are ordinary text. A backslash is ordinary text too
+// (Windows paths), except before a quote or another backslash inside double quotes.
+export function tokenize(line) {
+  const words = [];
+  let word = '';
+  let quote = null;
+  let open = false; // a word has begun, even if it is empty so far ("")
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (quote === '"' && c === '\\' && (line[i + 1] === '"' || line[i + 1] === '\\')) word += line[++i];
+      else word += c;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      open = true;
+    } else if (c === ' ' || c === '\t') {
+      if (open) words.push(word);
+      word = '';
+      open = false;
+    } else {
+      word += c;
+      open = true;
+    }
+  }
+  if (quote) throw new CliError(`That line has an unclosed ${quote} quote.`);
+  if (open) words.push(word);
+  return words;
+}
+
+// Tab completion. The first word completes to a command; any later word to a service name.
+export function complete(line, { commands, services }) {
+  const lastSpace = line.lastIndexOf(' ');
+  if (lastSpace === -1) {
+    const slash = line.startsWith('/') ? '/' : '';
+    const typed = line.slice(slash.length);
+    return [commands.filter((c) => c.startsWith(typed)).map((c) => slash + c), line];
+  }
+  const typed = line.slice(lastSpace + 1);
+  if (typed.startsWith('-')) return [[], typed];
+  return [services.filter((s) => s.startsWith(typed)), typed];
+}
+
+export function box(lines) {
+  const width = Math.max(...lines.map((l) => l.length));
+  const edge = `+${'-'.repeat(width + 2)}+`;
+  // Plain ASCII on purpose: box-drawing characters depend on the terminal's code page, and on a
+  // Windows console that is not UTF-8 they arrive as garbage.
+  return [edge, ...lines.map((l) => `| ${l.padEnd(width)} |`), edge].join('\n');
+}
+
+function withDeadline(promise, ms) {
+  let timer;
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new CliError('Voroa did not answer in time.')), ms);
+  });
+  return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+
+export async function startSession({ run, version, commands }) {
+  const state = { running: false, sigints: 0, services: [], commands: [...commands, 'tools', ...SESSION_WORDS] };
+
+  // The service names offered by Tab come from the server's own workspace-scoped list - the same one
+  // the resolver uses - and are thrown away whenever the account or the workspace may have changed.
+  async function loadServices() {
+    const settings = readSettings();
+    if (!settings.token) {
+      state.services = [];
+      return { signedIn: false };
+    }
+    const apps = await withDeadline(listApps(contextFrom(settings)), WELCOME_TIMEOUT_MS);
+    state.services = apps.map((a) => a.name);
+    return { signedIn: true, count: apps.length, viaToken: isApiToken(settings.token), apps, ctx: contextFrom(settings) };
+  }
+
+  // How many are running, idle, failed. One more read, on its own short deadline - and if it does not
+  // answer for EVERY service the line falls back to the plain count, because "7 running" over a partial
+  // answer would be a number we did not measure.
+  async function tally(w) {
+    if (!w.count) return null;
+    const statuses = await withDeadline(batchStatus(w.ctx, w.apps.map((a) => a.uuid)), STATUS_TIMEOUT_MS);
+    if (statuses.size < w.count) return null;
+    const n = { green: 0, gray: 0, amber: 0, red: 0 };
+    for (const st of statuses.values()) n[classify(st.containerStatus, st.deploymentStatus, st.verdict).tone] += 1;
+    return n;
+  }
+
+  function servicesLine(w, n, pretty) {
+    if (!n) return `${w.count} ${w.count === 1 ? 'service' : 'services'} in this workspace`;
+    const g = glyphs();
+    const part = (tone, mark) => (pretty ? `${style(tone, g[mark])} ${n[tone]} ${TONE_WORDS[tone]}` : `${n[tone]} ${TONE_WORDS[tone]}`);
+    const parts = [part('green', 'run'), part('gray', 'idle')];
+    if (n.amber) parts.push(part('amber', 'busy'));
+    parts.push(part('red', 'fail'));
+    return parts.join(pretty ? '   ' : ', ');
+  }
+
+  async function welcome() {
+    const pretty = fancy();
+    const rows = []; // [label, value] - the same facts for both renderings
+    let note = null;
+    try {
+      const w = await loadServices();
+      if (!w.signedIn) note = 'Not signed in - type /login';
+      else {
+        const email = readConfig().email;
+        rows.push(['Account', w.viaToken ? 'the API token in VOROA_TOKEN' : email || 'signed in']);
+        let n = null;
+        try {
+          n = await tally(w);
+        } catch (e) {
+          // The header simply shows the count; a command that needs statuses will report the reason.
+          state.lastTallyError = e;
+        }
+        rows.push(['Services', servicesLine(w, n, pretty)]);
+      }
+    } catch (e) {
+      // Offline, an expired session, a slow answer: say which, and open the prompt anyway.
+      note = e && e.message ? e.message : 'Could not reach Voroa right now.';
+    }
+
+    if (pretty) {
+      const g = glyphs();
+      const bar = style('violet', g.bar);
+      const lines = [`${bar} ${style('violet', style('bold', `${g.logo} voroa`))}  ${style('dim', `CLI ${version}`)}`, bar];
+      for (const [label, value] of rows) lines.push(`${bar} ${style('dim', label.padEnd(9))} ${value}`);
+      if (note) lines.push(`${bar} ${note}`);
+      out('');
+      out(lines.map((l) => `  ${l}`).join('\n'));
+      out('');
+      out(`  ${style('dim', ['/help commands', 'Tab complete', 'Ctrl+C stop', '/exit'].join(`  ${g.dot}  `))}`);
+      out('');
+      return;
+    }
+    // Off a terminal: the plain box, with the same facts as sentences.
+    const plain = [`Voroa CLI ${version}`];
+    for (const [label, value] of rows) {
+      if (label !== 'Account') plain.push(value);
+      else plain.push(value === 'signed in' ? 'Signed in' : value.startsWith('the API token') ? 'Using the API token in VOROA_TOKEN' : `Signed in as ${value}`);
+    }
+    if (note) plain.push(note);
+    plain.push('Type /help for commands, Tab to complete, /exit to leave');
+    out(box(plain));
+    out('');
+  }
+
+  function onSigint() {
+    if (state.running) {
+      // A tail registered its own stop handler on the process; give it the keypress.
+      if (process.listenerCount('SIGINT') > 0) {
+        process.emit('SIGINT');
+        return;
+      }
+      state.sigints += 1;
+      if (state.sigints >= 2) {
+        // The one deliberate hard exit in this CLI (index.js explains why it is avoided elsewhere):
+        // the person has asked twice to leave a command that cannot be interrupted.
+        process.exit(130);
+      }
+      err('This command cannot be stopped midway. Press Ctrl+C again to leave the session.');
+      return;
+    }
+    if (clearTypedLine()) return;
+    state.sigints += 1;
+    if (state.sigints >= 2) {
+      closePrompts(); // ends the loop below, exactly as Ctrl+D does
+      return;
+    }
+    err('\n(Press Ctrl+C again, or type /exit, to leave.)');
+    reprompt();
+  }
+
+  configureSession({ completer: (line) => complete(line, state), onSigint });
+  try {
+    try {
+      const kernel = await loadKernel();
+      state.commands.push(...kernel.listTools().map((t) => commandName(t.name)));
+    } catch (e) {
+      // Completion for the tool commands is a nicety; the commands themselves report this properly
+      // when one is run. Said once here so a broken install is not silent.
+      err(e && e.message ? e.message : 'The tool commands could not be loaded.');
+    }
+    state.commands = [...new Set(state.commands)].sort();
+    await welcome();
+
+    for (;;) {
+      // The prompt is drawn on stderr (prompt.js), so that is the stream that decides how it looks.
+      const prompt = fancy(process.stderr) ? `${style('violet', style('bold', `voroa ${glyphs().prompt}`, process.stderr), process.stderr)} ` : '> ';
+      const line = (await askCommand(prompt)).trim();
+      if (!line) {
+        if (promptsEnded()) break;
+        continue;
+      }
+      state.sigints = 0;
+      let words;
+      try {
+        words = tokenize(line.startsWith('/') ? line.slice(1) : line);
+      } catch (e) {
+        err(e.message);
+        continue;
+      }
+      // Habit from the shell: `voroa services` typed inside the session means `services`.
+      if (words[0] === 'voroa' && words.length > 1) words.shift();
+      const name = words[0];
+      if (!name) continue;
+      if (name === 'exit' || name === 'quit') break;
+      if (name === 'session') {
+        err('You are already in a session.');
+        continue;
+      }
+      if (name === 'clear') {
+        if (process.stdout.isTTY) process.stdout.write('\x1b[2J\x1b[H');
+        continue;
+      }
+      state.running = true;
+      try {
+        await run(name === 'help' ? ['--help'] : words);
+        if (name === 'help') out('\nIn a session: the leading / is optional, Tab completes, Ctrl+C stops a log tail, /clear and /exit.');
+      } catch (e) {
+        // Same rule as the binary: a message, never an error object (the last place a token could surface).
+        err(e && e.message ? e.message : 'Something went wrong.');
+      } finally {
+        state.running = false;
+        state.sigints = 0;
+        dropTypeAhead();
+      }
+      if (name === 'login' || name === 'workspace') {
+        try {
+          await loadServices();
+        } catch (e) {
+          // Only Tab's suggestions depend on this; the next command will report a real problem itself.
+          state.services = [];
+          state.lastRefreshError = e;
+        }
+      }
+    }
+  } finally {
+    configureSession(null);
+  }
+  return 0;
+}

package/src/status.js

@@ -139,6 +139,27 @@ export function statusLabel(status, deploymentStatus) {
 // A verdict we do not recognise is treated as unresolved rather than as success. The failure mode
 // then is "we waited and timed out", which is honest, instead of "we called an unknown state a
 // green deploy".
+// One word per TONE, for a line that counts services by state (the session header). It lives here
+// because this is the only file allowed to hold status vocabulary - a second list elsewhere is how
+// two screens end up calling the same state two things.
+export const TONE_WORDS = { green: 'running', gray: 'idle', amber: 'changing', red: 'failed' };
+
+// What each `verdict` means, for a PROGRAM reading `status --json` or `services --json`. A raw
+// container status can read like a crash for a service that is merely asleep - the verdict is the
+// field that was built to be believed (bug #24), and `voroa agent` prints this table.
+export const VERDICT_MEANINGS = {
+  live: 'Running and serving.',
+  sleeping: 'Idle and asleep. NOT broken - it wakes on the next request.',
+  building: 'A deploy is in progress.',
+  starting: 'Built; waiting for the service to come up.',
+  failed: 'The build failed. Read the build log.',
+  failed_to_start: 'Built, but the service did not come up. Read the logs.',
+  suspended: 'Stopped by Voroa after repeated crashes. A person must start it.',
+  paused_free_hours: 'Paused: the free hours for this month are used.',
+  waiting_for_addon: 'Waiting for its database to be created.',
+  unknown: 'Could not be determined. Not a failure; check again.',
+};
+
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_TIMEOUT = 2;