@uic-coe-connect/cli 0.12.0 → 0.13.1

package/dist/client.js

@@ -25,8 +25,44 @@ async function fail(res, server) {
     }
     if (res.status === 404)
         throw new CliError(`Not found: ${message}`, 4);
+    // A refusal the caller can act on: bad input (400), something that can't be
+    // done in the current state (409, e.g. "this COEConnect doesn't manage that
+    // VM" or "nothing is deploying"), or input the server understood and
+    // rejected (422). These used to fall through to the generic 1, which is not
+    // in the documented table at all — so a script told to branch on exit codes
+    // got an undocumented one for the most common recoverable failures.
+    if ([400, 409, 422].includes(res.status))
+        throw new CliError(message, 6);
     throw new CliError(message, 1);
 }
+/**
+ * How long a plain request may take before the CLI gives up.
+ *
+ * Generous — some reads go out to a VM agent and back — but finite. Without a
+ * limit a server that accepts the connection and then never answers leaves the
+ * CLI waiting for ever, printing nothing: no spinner, no error, no exit. That
+ * is what `coe auth list` did in production on 2026-09-22, and the silence
+ * made it look like the CLI itself was broken rather than one route on the
+ * server.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+/** Uploads and downloads move real files, so they get longer. */
+const TRANSFER_TIMEOUT_MS = 120_000;
+/**
+ * A deploy stream has no overall limit — a pipeline legitimately runs for
+ * minutes — so it is policed on *silence* instead. The server heartbeats every
+ * ten seconds precisely so a quiet build still looks alive, which makes a long
+ * gap a real failure rather than a slow step.
+ */
+const STREAM_IDLE_TIMEOUT_MS = 120_000;
+/** Turns a timeout into something that says what to do next. */
+function timeoutError(server, seconds) {
+    return new CliError(`${server} did not respond within ${seconds}s.`, 5, "The server accepted the connection but never answered. Try again, and if it persists " +
+        "check the server's logs — a route that throws can stop responding without closing.");
+}
+function isAbort(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
 /**
  * Spread into a fetch init. Omits `body` entirely rather than passing
  * `undefined` — fetch rejects a body on GET even when it's undefined.
@@ -49,9 +85,16 @@ export function createClient(options = {}) {
         async request(method, path, body) {
             let res;
             try {
-                res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
+                res = await fetch(`${server}${path}`, {
+                    method,
+                    headers,
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    ...bodyInit(body),
+                });
             }
             catch (error) {
+                if (isAbort(error))
+                    throw timeoutError(server, REQUEST_TIMEOUT_MS / 1000);
                 throw new CliError(`Could not reach ${server}: ${error instanceof Error ? error.message : String(error)}`, 5, "Check the server URL, and that you're on the campus network or VPN.");
             }
             if (!res.ok)
@@ -72,40 +115,82 @@ export function createClient(options = {}) {
                     "X-File-Name": encodeURIComponent(filename),
                 },
                 body: bytes,
+                signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+            }).catch((error) => {
+                if (isAbort(error))
+                    throw timeoutError(server, TRANSFER_TIMEOUT_MS / 1000);
+                throw error;
             });
             if (!res.ok)
                 await fail(res, server);
             return (await res.json());
         },
         async download(path) {
-            const res = await fetch(`${server}${path}`, { headers });
+            const res = await fetch(`${server}${path}`, {
+                headers,
+                signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+            }).catch((error) => {
+                if (isAbort(error))
+                    throw timeoutError(server, TRANSFER_TIMEOUT_MS / 1000);
+                throw error;
+            });
             if (!res.ok)
                 await fail(res, server);
             return new Uint8Array(await res.arrayBuffer());
         },
         async stream(method, path, body, onLine) {
-            const res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
-            if (!res.ok)
-                await fail(res, server);
-            if (!res.body)
-                throw new CliError("The server sent no output stream.");
-            // The deploy endpoint writes plain newline-delimited text, not SSE, so
-            // buffer across chunk boundaries rather than assuming whole lines.
-            const reader = res.body.getReader();
-            const decoder = new TextDecoder();
-            let buffer = "";
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split("\n");
-                buffer = lines.pop() ?? "";
-                for (const line of lines)
-                    onLine(line);
+            // No overall deadline here, only an idle one: the whole point of this
+            // call is to sit open while a deploy runs.
+            const idle = new AbortController();
+            let watchdog;
+            const resetWatchdog = () => {
+                if (watchdog)
+                    clearTimeout(watchdog);
+                watchdog = setTimeout(() => idle.abort(), STREAM_IDLE_TIMEOUT_MS);
+                watchdog.unref?.();
+            };
+            resetWatchdog();
+            try {
+                const res = await fetch(`${server}${path}`, {
+                    method,
+                    headers,
+                    signal: idle.signal,
+                    ...bodyInit(body),
+                });
+                if (!res.ok)
+                    await fail(res, server);
+                if (!res.body)
+                    throw new CliError("The server sent no output stream.");
+                // The deploy endpoint writes plain newline-delimited text, not SSE, so
+                // buffer across chunk boundaries rather than assuming whole lines.
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    resetWatchdog();
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    for (const line of lines)
+                        onLine(line);
+                }
+                if (buffer)
+                    onLine(buffer);
+            }
+            catch (error) {
+                if (isAbort(error)) {
+                    throw new CliError(`${server} sent nothing for ${STREAM_IDLE_TIMEOUT_MS / 1000}s.`, 5, "A running deploy heartbeats every 10s, so this means the connection died — " +
+                        "the deploy itself may still be going. Check: coe builds <app>");
+                }
+                throw error;
+            }
+            finally {
+                if (watchdog)
+                    clearTimeout(watchdog);
             }
-            if (buffer)
-                onLine(buffer);
         },
     };
 }

package/dist/commands/access.js

@@ -1,5 +1,5 @@
 import { CliError } from "../client.js";
-import { details, emit, info } from "../output.js";
+import { details, emit, info, success } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 function currentAccess(app) {
@@ -42,7 +42,7 @@ export function registerAccessCommands() {
             const access = currentAccess(app);
             const devTeam = [...new Set([...access.devTeam, ...toAdd])];
             await saveAccess(c, app.id, { ...access, devTeam });
-            emit({ appId: app.id, devTeam, added: toAdd }, () => info(`✓ Dev team for ${app.id}: ${devTeam.join(", ")}`));
+            emit({ appId: app.id, devTeam, added: toAdd }, () => success(`Dev team for ${app.id}: ${devTeam.join(", ")}`));
         },
     }, {
         name: "access remove-dev",
@@ -60,7 +60,7 @@ export function registerAccessCommands() {
                 throw new CliError(`That removes everyone from ${app.id}'s dev team, leaving it webadmin-only.`, 6, "Re-run with --yes if that's intended.");
             }
             await saveAccess(c, app.id, { ...access, devTeam });
-            emit({ appId: app.id, devTeam, removed: [...toRemove] }, () => info(`✓ Dev team for ${app.id}: ${devTeam.join(", ") || "(none)"}`));
+            emit({ appId: app.id, devTeam, removed: [...toRemove] }, () => success(`Dev team for ${app.id}: ${devTeam.join(", ") || "(none)"}`));
         },
     }, {
         name: "access set-staff",
@@ -79,7 +79,7 @@ export function registerAccessCommands() {
                 staff: { ...access.staff, everyone: mode === "everyone" },
             };
             await saveAccess(c, app.id, next);
-            emit({ appId: app.id, staffAccess: mode }, () => info(`✓ Staff access for ${app.id}: ${mode}`));
+            emit({ appId: app.id, staffAccess: mode }, () => success(`Staff access for ${app.id}: ${mode}`));
         },
     }, {
         name: "access add-staff",
@@ -93,7 +93,7 @@ export function registerAccessCommands() {
             const members = [...new Set([...access.staff.members, ...toAdd])];
             await saveAccess(c, app.id, { ...access, staff: { ...access.staff, members } });
             emit({ appId: app.id, members, added: toAdd }, () => {
-                info(`✓ Staff members for ${app.id}: ${members.join(", ")}`);
+                success(`Staff members for ${app.id}: ${members.join(", ")}`);
                 if (access.staff.everyone) {
                     info("  note: staff access is still 'everyone', so this list isn't enforced yet.");
                 }
@@ -110,7 +110,7 @@ export function registerAccessCommands() {
             const access = currentAccess(app);
             const members = access.staff.members.filter((n) => !toRemove.has(n));
             await saveAccess(c, app.id, { ...access, staff: { ...access.staff, members } });
-            emit({ appId: app.id, members, removed: [...toRemove] }, () => info(`✓ Staff members for ${app.id}: ${members.join(", ") || "(none)"}`));
+            emit({ appId: app.id, members, removed: [...toRemove] }, () => success(`Staff members for ${app.id}: ${members.join(", ") || "(none)"}`));
         },
     }, {
         name: "access block",
@@ -123,7 +123,7 @@ export function registerAccessCommands() {
             const access = currentAccess(app);
             const exceptions = [...new Set([...access.staff.exceptions, ...toAdd])];
             await saveAccess(c, app.id, { ...access, staff: { ...access.staff, exceptions } });
-            emit({ appId: app.id, blacklist: exceptions, added: toAdd }, () => info(`✓ Blacklist for ${app.id}: ${exceptions.join(", ")}`));
+            emit({ appId: app.id, blacklist: exceptions, added: toAdd }, () => success(`Blacklist for ${app.id}: ${exceptions.join(", ")}`));
         },
     }, {
         name: "access unblock",
@@ -136,7 +136,7 @@ export function registerAccessCommands() {
             const access = currentAccess(app);
             const exceptions = access.staff.exceptions.filter((n) => !toRemove.has(n));
             await saveAccess(c, app.id, { ...access, staff: { ...access.staff, exceptions } });
-            emit({ appId: app.id, blacklist: exceptions, removed: [...toRemove] }, () => info(`✓ Blacklist for ${app.id}: ${exceptions.join(", ") || "(none)"}`));
+            emit({ appId: app.id, blacklist: exceptions, removed: [...toRemove] }, () => success(`Blacklist for ${app.id}: ${exceptions.join(", ") || "(none)"}`));
         },
     });
 }

package/dist/commands/auth.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { CliError, createClient } from "../client.js";
 import { clearCredentials, credentialsPath, readCredentials, resolveServer, saveCredentials, saveServer, sessionLabel, } from "../config.js";
-import { details, emit, info, isJsonMode } from "../output.js";
+import { details, emit, info, isJsonMode, style, success } from "../output.js";
 import { register } from "../registry.js";
 /** Best-effort browser open. Never fatal — the URL is always printed too. */
 function openBrowser(url) {
@@ -80,7 +80,7 @@ export function registerAuthCommands() {
             const all = args.bool("all");
             const result = await client.request("DELETE", `/cli/sessions${all ? "?all=true" : ""}`);
             clearCredentials();
-            emit({ loggedOut: true, revoked: result.revoked }, () => info(`✓ Signed out (${result.revoked} session${result.revoked === 1 ? "" : "s"} revoked)`));
+            emit({ loggedOut: true, revoked: result.revoked }, () => success(`Signed out (${result.revoked} session${result.revoked === 1 ? "" : "s"} revoked)`));
         },
     }, {
         name: "whoami",
@@ -112,10 +112,19 @@ export function registerAuthCommands() {
                 }
                 for (const s of sessions) {
                     details([
-                        ["Label", s.label],
+                        ["Label", s.current ? `${s.label} ${style.ok("(this terminal)")}` : s.label],
                         ["Created", new Date(s.createdAt).toLocaleString()],
                         ["Expires", new Date(s.expiresAt).toLocaleString()],
-                        ["Last used", s.lastUsedAt ? new Date(s.lastUsedAt).toLocaleString() : "never"],
+                        [
+                            "Last used",
+                            // Your own row reads "never" because authenticating stamps the
+                            // timestamp after this read — say so rather than look wrong.
+                            s.current
+                                ? "now"
+                                : s.lastUsedAt
+                                    ? new Date(s.lastUsedAt).toLocaleString()
+                                    : "never",
+                        ],
                     ]);
                     info("");
                 }
@@ -131,7 +140,7 @@ export function registerAuthCommands() {
             }
             const result = await client().request("DELETE", "/cli/sessions?all=true");
             clearCredentials();
-            emit(result, () => info(`✓ Revoked ${result.revoked} session(s)`));
+            emit(result, () => success(`Revoked ${result.revoked} session(s)`));
         },
     }, {
         name: "auth status",

package/dist/commands/deploy.js

@@ -1,5 +1,5 @@
 import { CliError } from "../client.js";
-import { emit, info, isJsonMode, table } from "../output.js";
+import { emit, info, isJsonMode, table, style } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 /** Sentinels the deploy stream ends with — the server's own success signal. */
@@ -11,7 +11,7 @@ const CANCELLED = "__DEPLOY_CANCELLED__";
  * They're meaningless here and read as debug noise, so they never reach the
  * console or the JSON log — the stream already carries a human line for each.
  */
-const MARKER = /^__(NODE|COMMIT|PREV)__:/;
+const MARKER = /^__(NODE|STEPS|COMMIT|PREV)__:/;
 /**
  * The engine's marker for a line worth remembering after the run.
  *
@@ -173,14 +173,13 @@ export function registerDeployCommands() {
         async run({ args, client }) {
             const c = client();
             const app = await resolveApp(c, args.arg(0, "app"));
-            const limit = Number(args.flag("limit") ?? 20);
-            const offset = Number(args.flag("offset") ?? 0);
-            const { builds, total } = await c.request("GET", `/registered-apps/${app.id}/builds?limit=${Number.isFinite(limit) ? limit : 20}` +
-                `&offset=${Number.isFinite(offset) ? offset : 0}`);
+            const limit = args.num("limit", 20);
+            const offset = args.num("offset", 0);
+            const { builds, total } = await c.request("GET", `/registered-apps/${app.id}/builds?limit=${limit}&offset=${offset}`);
             emit({ appId: app.id, builds, total, offset }, () => {
                 table(builds.map((b) => ({
                     started: new Date(b.startedAt).toLocaleString(),
-                    status: b.status,
+                    status: style.state(b.status),
                     version: b.version ?? "—",
                     pipeline: b.pipelineName ?? "—",
                     source: b.source,
@@ -240,9 +239,8 @@ export function registerDeployCommands() {
             if (!branch) {
                 throw new CliError(`${app.id} has no default branch set.`, 4, "Name one with --branch, or set it on the app.");
             }
-            const limit = Number(args.flag("limit") ?? 25);
-            const { commits } = await c.request("GET", `/registered-apps/${app.id}/commits?branch=${encodeURIComponent(branch)}` +
-                `&limit=${Number.isFinite(limit) ? limit : 25}`);
+            const limit = args.num("limit", 25);
+            const { commits } = await c.request("GET", `/registered-apps/${app.id}/commits?branch=${encodeURIComponent(branch)}&limit=${limit}`);
             emit({ appId: app.id, branch, commits }, () => {
                 table(commits.map((x) => ({
                     commit: x.sha,

package/dist/commands/env.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.js";
-import { emit, info, table } from "../output.js";
+import { emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 /**
@@ -95,7 +95,7 @@ export function registerEnvCommands() {
             // clobbers the app's name/url/icon the way a full record PUT would.
             const next = { ...env, ...updates };
             await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
-            emit({ appId: app.id, set: Object.keys(updates), count: Object.keys(next).length }, () => info(`✓ Set ${Object.keys(updates).join(", ")} on ${app.id}`));
+            emit({ appId: app.id, set: Object.keys(updates), count: Object.keys(next).length }, () => success(`Set ${Object.keys(updates).join(", ")} on ${app.id}`));
         },
     }, {
         name: "env unset",
@@ -116,7 +116,7 @@ export function registerEnvCommands() {
             for (const key of keys)
                 delete next[key];
             await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
-            emit({ appId: app.id, removed: keys, count: Object.keys(next).length }, () => info(`✓ Removed ${keys.join(", ")} from ${app.id}`));
+            emit({ appId: app.id, removed: keys, count: Object.keys(next).length }, () => success(`Removed ${keys.join(", ")} from ${app.id}`));
         },
     });
 }

package/dist/commands/logs.js

@@ -22,7 +22,7 @@ export function registerLogCommands() {
             const c = client();
             const app = await resolveApp(c, args.arg(0, "app"));
             const stream = args.bool("out") ? "out" : "err";
-            const tail = Number(args.flag("tail") ?? 100);
+            const tail = args.num("tail", 100);
             if (!Number.isFinite(tail) || tail < 1) {
                 throw new CliError(`--tail must be a positive number, got "${args.flag("tail")}".`, 6);
             }

package/dist/commands/pipelines.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.js";
-import { emit, info, table } from "../output.js";
+import { emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 /**
@@ -202,7 +202,7 @@ export function registerPipelineCommands() {
             pipelines.push({ id: "", name, config: { steps } });
             const updated = await savePipelines(c, app.id, pipelines);
             const created = (updated.pipelines ?? []).find((p) => p.name === name);
-            emit({ appId: app.id, pipeline: created }, () => info(`✓ Created pipeline "${name}" on ${app.id} (${steps.length} steps)`));
+            emit({ appId: app.id, pipeline: created }, () => success(`Created pipeline "${name}" on ${app.id} (${steps.length} steps)`));
         },
     }, {
         name: "pipelines set-steps",
@@ -217,7 +217,7 @@ export function registerPipelineCommands() {
                 throw new CliError("A pipeline needs at least one step.", 6);
             const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, config: { steps } } : p);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, pipelineId: pipeline.id, steps }, () => info(`✓ Updated "${pipeline.name}" on ${app.id} (${steps.length} steps)`));
+            emit({ appId: app.id, pipelineId: pipeline.id, steps }, () => success(`Updated "${pipeline.name}" on ${app.id} (${steps.length} steps)`));
         },
     }, {
         name: "pipelines rename",
@@ -230,7 +230,7 @@ export function registerPipelineCommands() {
             const newName = args.arg(2, "new-name");
             const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, name: newName } : p);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, pipelineId: pipeline.id, name: newName }, () => info(`✓ Renamed "${pipeline.name}" → "${newName}"`));
+            emit({ appId: app.id, pipelineId: pipeline.id, name: newName }, () => success(`Renamed "${pipeline.name}" → "${newName}"`));
         },
     }, {
         name: "pipelines delete",
@@ -245,7 +245,7 @@ export function registerPipelineCommands() {
             }
             const pipelines = (app.pipelines ?? []).filter((p) => p.id !== pipeline.id);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, deleted: pipeline.id }, () => info(`✓ Deleted pipeline "${pipeline.name}" from ${app.id}`));
+            emit({ appId: app.id, deleted: pipeline.id }, () => success(`Deleted pipeline "${pipeline.name}" from ${app.id}`));
         },
     });
 }

package/dist/commands/reports.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { CliError } from "../client.js";
-import { details, emit, info, table } from "../output.js";
+import { details, emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 /**
  * Bug reports and feature requests from the terminal.
@@ -184,7 +184,7 @@ export function registerReportCommands() {
             const message = args.arg(1, "message");
             const status = args.flag("status") ? assertStatus(args.flag("status")) : undefined;
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: message, status });
-            emit({ report }, () => info(`✓ Replied on ${report.id}${status ? ` — now ${report.status}` : ""}`));
+            emit({ report }, () => success(`Replied on ${report.id}${status ? ` — now ${report.status}` : ""}`));
         },
     }, {
         name: "reports status",
@@ -198,7 +198,7 @@ export function registerReportCommands() {
             const id = args.arg(0, "id");
             const status = assertStatus(args.arg(1, "status"));
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
-            emit({ report }, () => info(`✓ ${report.id} is now ${report.status}`));
+            emit({ report }, () => success(`${report.id} is now ${report.status}`));
         },
     }, {
         name: "reports close",
@@ -213,7 +213,7 @@ export function registerReportCommands() {
             const id = args.arg(0, "id");
             const status = args.bool("wont-do") ? "declined" : "done";
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
-            emit({ report }, () => info(`✓ Closed ${report.id} as ${report.status}`));
+            emit({ report }, () => success(`Closed ${report.id} as ${report.status}`));
         },
     }, {
         name: "reports reopen",
@@ -222,7 +222,7 @@ export function registerReportCommands() {
         async run({ args, client }) {
             const id = args.arg(0, "id");
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status: "open" });
-            emit({ report }, () => info(`✓ Reopened ${report.id}`));
+            emit({ report }, () => success(`Reopened ${report.id}`));
         },
     }, {
         name: "reports attach",
@@ -244,7 +244,7 @@ export function registerReportCommands() {
                 throw new CliError(`Can't read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, 4);
             }
             const file = await client().upload(`/reports/${id}/attachments`, basename(filePath), bytes);
-            emit({ attachment: file }, () => info(`✓ Attached ${file.name} (${humanSize(file.size)}) to ${id}`));
+            emit({ attachment: file }, () => success(`Attached ${file.name} (${humanSize(file.size)}) to ${id}`));
         },
     }, {
         name: "reports download",
@@ -258,7 +258,7 @@ export function registerReportCommands() {
             const bytes = await c.download(`/reports/${id}/attachments/${file.id}`);
             const out = args.flag("out") ?? file.name;
             writeFileSync(out, bytes);
-            emit({ reportId: id, attachment: file.name, out, bytes: bytes.length }, () => info(`✓ Wrote ${out} (${humanSize(bytes.length)})`));
+            emit({ reportId: id, attachment: file.name, out, bytes: bytes.length }, () => success(`Wrote ${out} (${humanSize(bytes.length)})`));
         },
     }, {
         name: "reports file",
@@ -290,7 +290,7 @@ export function registerReportCommands() {
                     attachment = await c.upload(`/reports/${report.id}/attachments`, basename(attach), readFileSync(attach));
                 }
                 catch (error) {
-                    info(`✓ Filed ${report.id} — ${report.title}`);
+                    success(`Filed ${report.id} — ${report.title}`);
                     throw new CliError(`The report was filed, but ${attach} did not attach: ` +
                         (error instanceof Error ? error.message : String(error)), 1, `Try again with: coe reports attach ${report.id} ${attach}`);
                 }

package/dist/commands/resources.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { CliError } from "../client.js";
-import { details, emit, info, table } from "../output.js";
+import { details, emit, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 function humanSize(bytes) {
@@ -70,7 +70,7 @@ export function registerResourceCommands() {
             if (description) {
                 await c.request("PATCH", `/registered-apps/${app.id}/files/${file.id}`, { description });
             }
-            emit({ appId: app.id, file }, () => info(`✓ Uploaded ${file.name} (${humanSize(file.size)}) to ${app.id}`));
+            emit({ appId: app.id, file }, () => success(`Uploaded ${file.name} (${humanSize(file.size)}) to ${app.id}`));
         },
     }, {
         name: "files download",
@@ -87,7 +87,7 @@ export function registerResourceCommands() {
             const bytes = await c.download(`/registered-apps/${app.id}/files/${file.id}`);
             const out = args.flag("out") ?? file.name;
             writeFileSync(out, bytes);
-            emit({ appId: app.id, file: file.name, out, bytes: bytes.length }, () => info(`✓ Wrote ${out} (${humanSize(bytes.length)})`));
+            emit({ appId: app.id, file: file.name, out, bytes: bytes.length }, () => success(`Wrote ${out} (${humanSize(bytes.length)})`));
         },
     }, {
         name: "files delete",
@@ -102,7 +102,7 @@ export function registerResourceCommands() {
                 throw new CliError(`This deletes "${file.name}" from ${app.id}.`, 6, "Re-run with --yes to confirm.");
             }
             await c.request("DELETE", `/registered-apps/${app.id}/files/${file.id}`);
-            emit({ appId: app.id, deleted: file.name }, () => info(`✓ Deleted ${file.name} from ${app.id}`));
+            emit({ appId: app.id, deleted: file.name }, () => success(`Deleted ${file.name} from ${app.id}`));
         },
     }, {
         name: "files link",
@@ -118,7 +118,7 @@ export function registerResourceCommands() {
                 name: args.flag("name"),
                 description: args.flag("description"),
             });
-            emit({ appId: app.id, link }, () => info(`✓ Linked "${link.name}" → ${link.url}`));
+            emit({ appId: app.id, link }, () => success(`Linked "${link.name}" → ${link.url}`));
         },
     }, {
         name: "files show",

package/dist/commands/tips.js

@@ -1,5 +1,5 @@
 import { CliError } from "../client.js";
-import { emit, info, table } from "../output.js";
+import { emit, info, style, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 export function registerTipCommands() {
@@ -47,7 +47,7 @@ export function registerTipCommands() {
                     return;
                 }
                 if (result.alreadyReviewed === "accepted") {
-                    info("✓ This trigger already has accepted advice. Counted, not queued again.");
+                    success("This trigger already has accepted advice. Counted, not queued again.");
                     return;
                 }
                 info(result.created
@@ -76,7 +76,7 @@ export function registerTipCommands() {
                 }
                 table(tips.map((t) => ({
                     id: t.id,
-                    status: t.status,
+                    status: style.state(t.status),
                     kind: t.kind,
                     seen: String(t.occurrences),
                     apps: t.appIds.join(", "),
@@ -107,7 +107,7 @@ export function registerTipCommands() {
                 status,
                 note: args.flag("note"),
             });
-            emit({ tip }, () => info(`✓ ${tip.id} marked ${tip.status}.`));
+            emit({ tip }, () => success(`${tip.id} marked ${tip.status}.`));
         },
     });
 }

package/dist/index.js

@@ -14,7 +14,7 @@ import { registerReportCommands } from "./commands/reports.js";
 import { registerResourceCommands } from "./commands/resources.js";
 import { registerTipCommands } from "./commands/tips.js";
 import { registerVmCommands } from "./commands/vms.js";
-import { info, setJsonMode } from "./output.js";
+import { failure, setJsonMode } from "./output.js";
 import { allCommands, findCommand, register } from "./registry.js";
 registerAuthCommands();
 registerAppCommands();
@@ -71,6 +71,19 @@ function parseArgs(argv) {
         bool(name) {
             return flags[name] !== undefined;
         },
+        num(name, fallback) {
+            const raw = flags[name];
+            if (raw === undefined)
+                return fallback;
+            if (raw === true) {
+                throw new CliError(`--${name} needs a number.`, 6, `e.g. --${name} ${fallback}`);
+            }
+            const value = Number(raw);
+            if (!Number.isFinite(value)) {
+                throw new CliError(`--${name} must be a number, not "${raw}".`, 6);
+            }
+            return value;
+        },
     };
 }
 function printHelp() {
@@ -125,11 +138,9 @@ async function main() {
 }
 main().catch((error) => {
     if (error instanceof CliError) {
-        info(`error: ${error.message}`);
-        if (error.hint)
-            info(`  ${error.hint}`);
+        failure(error.message, error.hint);
         process.exit(error.exitCode);
     }
-    info(`error: ${error instanceof Error ? error.message : String(error)}`);
+    failure(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });

package/dist/output.d.ts

@@ -8,12 +8,29 @@
  */
 export declare function setJsonMode(on: boolean): void;
 export declare function isJsonMode(): boolean;
+/** Marks a value for the reader's eye. Safe to pass into `table` or `details`. */
+export declare const style: {
+    ok: (t: string) => string;
+    bad: (t: string) => string;
+    warn: (t: string) => string;
+    muted: (t: string) => string;
+    strong: (t: string) => string;
+    id: (t: string) => string;
+    /** A build/process state, coloured by what it means rather than by name. */
+    state: (t: string) => string;
+};
 /** The command's result. In JSON mode this is the only thing on stdout. */
 export declare function emit(data: unknown, human: () => void): void;
 /** Progress/status chatter. Always stderr, so it never pollutes piped JSON. */
 export declare function info(message: string): void;
 export declare function warn(message: string): void;
+/** A command that did what it was asked. */
+export declare function success(message: string): void;
+/** How a failure is rendered, including the hint that says what to do next. */
+export declare function failure(message: string, hint?: string): void;
 /** Minimal column alignment — no dependency, and stable enough to eyeball. */
 export declare function table(rows: Array<Record<string, string>>, columns: string[]): void;
 /** Key/value block for `show`-style commands. */
 export declare function details(pairs: Array<[string, string]>): void;
+/** A heading above a block, for commands that print more than one. */
+export declare function heading(text: string): void;

package/dist/output.js

@@ -13,6 +13,71 @@ export function setJsonMode(on) {
 export function isJsonMode() {
     return jsonMode;
 }
+// ---- colour ----------------------------------------------------------------
+/**
+ * Colour only when a person is actually looking at that stream.
+ *
+ * Checked per stream, not once: stdout is frequently redirected while stderr
+ * is still a terminal (`coe builds app > builds.txt`), and escape codes in the
+ * redirected half would corrupt a file someone is about to parse. `NO_COLOR`
+ * is honoured because it is the convention, and `FORCE_COLOR` exists so output
+ * can be inspected through a pipe when working on this file.
+ */
+function allowColor(stream) {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return stream.isTTY === true && process.env.TERM !== "dumb";
+}
+const CODES = {
+    reset: "\u001B[0m",
+    bold: "\u001B[1m",
+    dim: "\u001B[2m",
+    red: "\u001B[31m",
+    green: "\u001B[32m",
+    yellow: "\u001B[33m",
+    blue: "\u001B[34m",
+    cyan: "\u001B[36m",
+};
+function paint(text, style, stream) {
+    return allowColor(stream) ? `${CODES[style]}${text}${CODES.reset}` : text;
+}
+/** Style for stdout (data). Never colours in JSON mode. */
+const out = (text, style) => jsonMode ? text : paint(text, style, process.stdout);
+/** Style for stderr (chatter). */
+const err = (text, style) => paint(text, style, process.stderr);
+/**
+ * Length as a terminal renders it.
+ *
+ * Column widths are computed from cell contents, and an escape sequence is
+ * zero columns wide but several characters long — measuring the raw string
+ * makes every coloured cell over-padded and the table ragged.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001B\[[0-9;]*m/g;
+const visibleLength = (text) => text.replace(ANSI, "").length;
+/** Marks a value for the reader's eye. Safe to pass into `table` or `details`. */
+export const style = {
+    ok: (t) => out(t, "green"),
+    bad: (t) => out(t, "red"),
+    warn: (t) => out(t, "yellow"),
+    muted: (t) => out(t, "dim"),
+    strong: (t) => out(t, "bold"),
+    id: (t) => out(t, "cyan"),
+    /** A build/process state, coloured by what it means rather than by name. */
+    state: (t) => {
+        const s = t.toLowerCase();
+        if (["ok", "online", "up", "done", "accepted", "active", "yes"].includes(s))
+            return style.ok(t);
+        if (["failed", "error", "down", "stopped", "rejected", "errored"].includes(s))
+            return style.bad(t);
+        if (["cancelled", "running", "new", "pending", "queued", "unknown"].includes(s))
+            return style.warn(t);
+        return t;
+    },
+};
+// ---- writers ---------------------------------------------------------------
 /** The command's result. In JSON mode this is the only thing on stdout. */
 export function emit(data, human) {
     if (jsonMode) {
@@ -26,18 +91,29 @@ export function info(message) {
     process.stderr.write(`${message}\n`);
 }
 export function warn(message) {
-    process.stderr.write(`warning: ${message}\n`);
+    process.stderr.write(`${err("warning:", "yellow")} ${message}\n`);
+}
+/** A command that did what it was asked. */
+export function success(message) {
+    process.stderr.write(`${err("✓", "green")} ${message}\n`);
+}
+/** How a failure is rendered, including the hint that says what to do next. */
+export function failure(message, hint) {
+    process.stderr.write(`${err("error:", "red")} ${message}\n`);
+    if (hint)
+        process.stderr.write(`${err(`  ${hint}`, "dim")}\n`);
 }
 /** Minimal column alignment — no dependency, and stable enough to eyeball. */
 export function table(rows, columns) {
     if (rows.length === 0) {
-        info("(none)");
+        info(err("(none)", "dim"));
         return;
     }
-    const width = (col) => Math.max(col.length, ...rows.map((r) => (r[col] ?? "").length));
+    const width = (col) => Math.max(col.length, ...rows.map((r) => visibleLength(r[col] ?? "")));
     const widths = columns.map(width);
-    const line = (cells) => cells.map((c, i) => c.padEnd(i === cells.length - 1 ? 0 : widths[i])).join("  ").trimEnd();
-    process.stdout.write(`${line(columns.map((c) => c.toUpperCase()))}\n`);
+    const pad = (cell, i, last) => last ? cell : cell + " ".repeat(Math.max(0, widths[i] - visibleLength(cell)));
+    const line = (cells) => cells.map((c, i) => pad(c, i, i === cells.length - 1)).join("  ").trimEnd();
+    process.stdout.write(`${out(line(columns.map((c) => c.toUpperCase())), "dim")}\n`);
     for (const row of rows) {
         process.stdout.write(`${line(columns.map((c) => row[c] ?? ""))}\n`);
     }
@@ -46,6 +122,10 @@ export function table(rows, columns) {
 export function details(pairs) {
     const width = Math.max(...pairs.map(([k]) => k.length));
     for (const [k, v] of pairs) {
-        process.stdout.write(`${k.padEnd(width)}  ${v}\n`);
+        process.stdout.write(`${out(k.padEnd(width), "dim")}  ${v}\n`);
     }
 }
+/** A heading above a block, for commands that print more than one. */
+export function heading(text) {
+    process.stderr.write(`\n${err(text.toUpperCase(), "bold")}\n`);
+}

package/dist/registry.d.ts

@@ -12,6 +12,14 @@ export interface Args {
     /** A flag's value, or undefined. `--flag` with no value reads as true. */
     flag(name: string): string | undefined;
     bool(name: string): boolean;
+    /**
+     * A numeric flag, or the fallback when it wasn't given.
+     *
+     * Rejects a value that isn't a number instead of quietly falling back:
+     * `--limit abc` used to print the default twenty rows and exit 0, which
+     * reads exactly like a limit that worked.
+     */
+    num(name: string, fallback: number): number;
 }
 export interface CommandContext {
     args: Args;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uic-coe-connect/cli",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "The coe CLI \u2014 manage COEConnect apps (pipelines, deploys, access, env) from a terminal, with browser-approved auth. Designed to be driven by an AI agent.",
   "type": "module",
   "bin": {