@tryarcanist/cli 0.1.11 → 0.1.13

package/dist/index.js

@@ -1,30 +1,131 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
 
+// src/api.ts
+import { createRequire } from "module";
+
 // ../../shared/utils/url.ts
 function normalizeBaseUrl(url) {
   return url.replace(/\/+$/, "");
 }
 
-// src/api.ts
-async function apiRequest(config, path, init) {
-  const res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
-    ...init,
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${config.token}`,
-      ...init?.headers
+// src/errors.ts
+var CliError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  requestId;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = options.exitCode ?? exitCodeForErrorCode(code);
+    this.hint = options.hint;
+    this.requestId = options.requestId;
+  }
+};
+var ApiError = class extends CliError {
+  status;
+  body;
+  constructor(status, body, requestId) {
+    const code = codeForHttpStatus(status);
+    super(code, messageForApiError(status, body), {
+      exitCode: exitCodeForHttpStatus(status),
+      hint: hintForHttpStatus(status),
+      requestId
+    });
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+function exitCodeForErrorCode(code) {
+  switch (code) {
+    case "auth":
+      return 2;
+    case "not_found":
+      return 3;
+    case "conflict":
+      return 4;
+    case "server":
+      return 10;
+    case "user":
+    default:
+      return 1;
+  }
+}
+function codeForHttpStatus(status) {
+  if (status === 401 || status === 403) return "auth";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status >= 500) return "server";
+  return "user";
+}
+function exitCodeForHttpStatus(status) {
+  return exitCodeForErrorCode(codeForHttpStatus(status));
+}
+function messageForApiError(status, body) {
+  const parsed = parseApiErrorBody(body);
+  if (parsed) return parsed;
+  return body ? `API error ${status}: ${body}` : `API error ${status}`;
+}
+function parseApiErrorBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (!parsed || typeof parsed !== "object") return null;
+    const error = parsed.error;
+    return typeof error === "string" && error.length > 0 ? error : null;
+  } catch {
+    return null;
+  }
+}
+function hintForHttpStatus(status) {
+  if (status === 401 || status === 403) return "Run `arcanist login` or set `ARCANIST_TOKEN`.";
+  if (status === 404) return "List sessions with `arcanist sessions list`.";
+  if (status === 409) return "Check the current resource state and retry the command when it is ready.";
+  if (status >= 500) return "Retry later or check the control-plane logs.";
+  return void 0;
+}
+function toCliError(err) {
+  if (err instanceof CliError) return err;
+  if (err instanceof Error) return new CliError("user", err.message);
+  return new CliError("user", String(err));
+}
+function formatJsonError(err) {
+  return JSON.stringify({
+    error: {
+      code: err.code,
+      message: err.message,
+      ...err.hint ? { hint: err.hint } : {},
+      ...err.requestId ? { requestId: err.requestId } : {}
     }
   });
-  if (res.status === 401) {
-    throw new Error("Token is invalid or expired. Run `arcanist login` to re-authenticate.");
+}
+
+// src/api.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var CLI_USER_AGENT = `arcanist-cli/${version}`;
+async function apiRequest(config, path, init) {
+  let res;
+  try {
+    const headers = new Headers(init?.headers);
+    headers.set("Content-Type", "application/json");
+    headers.set("User-Agent", CLI_USER_AGENT);
+    headers.set("Authorization", `Bearer ${config.token}`);
+    res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
+      ...init,
+      headers
+    });
+  } catch (err) {
+    throw new CliError("server", `Network error: ${err instanceof Error ? err.message : String(err)}`);
   }
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    throw new Error(`API error ${res.status}: ${body}`);
+    throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0);
   }
   return res;
 }
@@ -43,26 +144,42 @@ import { homedir } from "os";
 import { join } from "path";
 var CONFIG_DIR = join(homedir(), ".arcanist");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
-function loadConfig() {
+var DEFAULT_API_URL = "https://app.tryarcanist.com";
+function loadFileConfig() {
   try {
-    const config = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
-    return { ...config, apiUrl: normalizeBaseUrl(config.apiUrl) };
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
   } catch {
     return null;
   }
 }
+function loadConfig(overrides = {}) {
+  const fileConfig = loadFileConfig();
+  const apiUrl = overrides.apiUrl ?? process.env.ARCANIST_API_URL ?? fileConfig?.apiUrl;
+  const token = overrides.token ?? process.env.ARCANIST_TOKEN ?? fileConfig?.token;
+  if (!apiUrl || !token) return null;
+  const urlError = validateApiUrl(apiUrl);
+  if (urlError) throw new CliError("user", urlError);
+  return { apiUrl: normalizeBaseUrl(apiUrl), token };
+}
 function saveConfig(config) {
+  const urlError = validateApiUrl(config.apiUrl);
+  if (urlError) throw new CliError("user", urlError);
   mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
   writeFileSync(CONFIG_FILE, JSON.stringify({ ...config, apiUrl: normalizeBaseUrl(config.apiUrl) }, null, 2) + "\n", { mode: 384 });
 }
-function requireConfig() {
-  const config = loadConfig();
+function requireConfig(overrides = {}) {
+  const config = loadConfig(overrides);
   if (!config) {
-    console.error("Error: Not logged in. Run `arcanist login` first.");
-    process.exit(1);
+    throw new CliError("auth", "Not logged in.", { hint: "Run `arcanist login` or set `ARCANIST_TOKEN`." });
   }
   return config;
 }
+function resolveLoginApiUrl(apiUrl) {
+  const raw = apiUrl ?? process.env.ARCANIST_API_URL ?? loadFileConfig()?.apiUrl ?? DEFAULT_API_URL;
+  const urlError = validateApiUrl(raw);
+  if (urlError) throw new CliError("user", urlError);
+  return normalizeBaseUrl(raw);
+}
 function validateApiUrl(url) {
   let parsed;
   try {
@@ -78,6 +195,83 @@ function validateApiUrl(url) {
   return null;
 }
 
+// src/runtime.ts
+import { randomUUID } from "crypto";
+import { createInterface } from "readline/promises";
+function getRuntimeOptions(command, options = {}) {
+  const globals = command?.optsWithGlobals?.();
+  const merged = { ...globals, ...options };
+  return { ...merged, noColor: merged.noColor === true || merged.color === false };
+}
+function isJson(command, options = {}) {
+  return getRuntimeOptions(command, options).json === true;
+}
+function isQuiet(command, options = {}) {
+  return getRuntimeOptions(command, options).quiet === true;
+}
+function writeJson(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString();
+}
+async function readStdinTrimmed() {
+  return (await readStdin()).trim();
+}
+async function resolvePromptInput(promptArg, options) {
+  const shouldReadStdin = options.promptStdin === true || promptArg === "-";
+  const prompt = shouldReadStdin ? await readStdin() : promptArg;
+  if (!prompt || prompt.trim().length === 0) {
+    throw new CliError("user", "Missing prompt. Pass a prompt argument, use '-' to read stdin, or pass --prompt-stdin.");
+  }
+  return prompt;
+}
+async function confirmOrThrow(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new CliError("user", "Confirmation required. Re-run with --yes in non-interactive environments.");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`${message} [y/N] `)).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      throw new CliError("user", "Aborted.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+function printDeprecatedAlias(alias, replacement, command, options = {}) {
+  if (isQuiet(command, options)) return;
+  process.stderr.write(`Warning: \`arcanist ${alias}\` is deprecated; use \`arcanist ${replacement}\`.
+`);
+}
+function applyColorEnvironment(options) {
+  if (options.noColor === true || !process.stdout.isTTY) {
+    process.env.NO_COLOR = "1";
+  }
+}
+function randomIdempotencyKey() {
+  return randomUUID();
+}
+
+// src/commands/auth.ts
+async function whoamiCommand(options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const payload = await apiFetch(config, "/api/auth/whoami");
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  console.log(`User: ${String(payload.email ?? payload.userId ?? "unknown")}`);
+  if (payload.tokenScope) console.log(`Token scope: ${String(payload.tokenScope)}`);
+}
+
 // src/commands/create.ts
 var REPO_URL_PATTERNS = [
   /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/,
@@ -88,89 +282,104 @@ function validateRepoUrl(url) {
   if (REPO_URL_PATTERNS.some((pattern) => pattern.test(url))) return null;
   return `Invalid repo URL: "${url}". Expected a GitHub URL (https://github.com/owner/repo) or owner/repo shorthand.`;
 }
-async function createCommand(repoUrl, prompt, options) {
-  const config = requireConfig();
+async function createCommand(repoUrl, promptArg, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const prompt = await resolvePromptInput(promptArg, options);
   const repoError = validateRepoUrl(repoUrl);
   if (repoError) {
-    console.error(`Error: ${repoError}`);
-    process.exit(1);
-  }
-  let sessionId;
-  try {
-    const sessionData = await apiFetch(config, "/api/sessions", {
-      method: "POST",
-      body: JSON.stringify({
-        context: { repoUrl },
-        ...options.model ? { model: options.model } : {}
-      })
-    });
-    sessionId = sessionData.sessionId;
-  } catch (err) {
-    console.error(`Error creating session: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+    throw new CliError("user", repoError);
   }
+  const idempotencyKey = options.idempotencyKey ?? randomIdempotencyKey();
+  const sessionIdempotencyKey = `${idempotencyKey}:session`;
+  const promptIdempotencyKey = `${idempotencyKey}:prompt`;
+  const sessionData = await apiFetch(config, "/api/sessions", {
+    method: "POST",
+    headers: { "Idempotency-Key": sessionIdempotencyKey },
+    body: JSON.stringify({
+      context: { repoUrl },
+      ...options.model ? { model: options.model } : {}
+    })
+  });
+  const sessionId = sessionData.sessionId;
   try {
-    await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
+    const promptData = await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
       method: "POST",
+      headers: { "Idempotency-Key": promptIdempotencyKey },
       body: JSON.stringify({ prompt })
     });
+    const promptId = promptData.prompt?.promptId ?? promptData.prompt?.id;
+    if (isJson(command, options)) {
+      writeJson({
+        sessionId,
+        ...sessionData.sessionUrl ? { sessionUrl: sessionData.sessionUrl } : {},
+        repoUrl,
+        ...options.model ? { model: options.model } : {},
+        ...promptId ? { promptId } : {}
+      });
+      return;
+    }
   } catch (err) {
-    console.error(`Session created (${sessionId}) but prompt failed: ${err instanceof Error ? err.message : String(err)}`);
-    console.error(`Retry with: arcanist message ${sessionId} "${prompt}"`);
-    process.exit(1);
+    throw new CliError(err instanceof CliError ? err.code : "server", `Session created (${sessionId}) but prompt failed: ${err instanceof Error ? err.message : String(err)}`, {
+      exitCode: err instanceof CliError ? err.exitCode : void 0,
+      hint: `Retry with: arcanist sessions send ${sessionId} --prompt-stdin`,
+      requestId: err instanceof CliError ? err.requestId : void 0
+    });
   }
-  const uiUrl = config.apiUrl.replace(/:\d+$/, ":5173");
   console.log(`Session: ${sessionId}`);
-  console.log(`URL: ${uiUrl}/sessions/${sessionId}`);
+  if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
 }
 
 // src/commands/login.ts
-import { createInterface } from "readline";
-async function loginCommand(options) {
+import { createInterface as createInterface2 } from "readline";
+async function loginCommand(options, command) {
+  const runtime = getRuntimeOptions(command, options);
   let token;
   if (options.tokenStdin) {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
-    }
-    token = Buffer.concat(chunks).toString().trim();
+    token = await readStdinTrimmed();
+  } else if (runtime.token) {
+    token = runtime.token;
   } else {
     token = await promptHidden("Enter your CLI token: ");
   }
   if (!token) {
-    console.error("Error: No token provided.");
-    process.exit(1);
+    throw new CliError("user", "No token provided.");
   }
   if (!token.startsWith("arc_")) {
-    console.error("Error: Invalid token format. Token must start with 'arc_'.");
-    process.exit(1);
+    throw new CliError("user", "Invalid token format. Token must start with 'arc_'.");
   }
-  if (options.apiUrl) {
-    const urlError = validateApiUrl(options.apiUrl);
+  if (runtime.apiUrl) {
+    const urlError = validateApiUrl(runtime.apiUrl);
     if (urlError) {
-      console.error(`Error: ${urlError}`);
-      process.exit(1);
+      throw new CliError("user", urlError);
     }
   }
-  const apiUrl = normalizeBaseUrl(options.apiUrl ?? loadConfig()?.apiUrl ?? "https://app.tryarcanist.com");
+  const apiUrl = normalizeBaseUrl(resolveLoginApiUrl(runtime.apiUrl));
   saveConfig({ apiUrl, token });
-  console.log(`Logged in. API: ${apiUrl}`);
+  if (runtime.json) {
+    writeJson({ ok: true, apiUrl });
+  } else if (!runtime.quiet) {
+    console.log(`Logged in. API: ${apiUrl}`);
+  }
   try {
     const res = await fetch(`${apiUrl}/api/cli-tokens`, {
-      headers: { Authorization: `Bearer ${token}` }
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": CLI_USER_AGENT }
     });
-    if (res.ok) {
+    if (res.ok && !runtime.json && !runtime.quiet) {
       console.log("Token verified.");
-    } else if (res.status === 401) {
+    } else if (res.status === 401 && !runtime.json && !runtime.quiet) {
       console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
     }
   } catch {
-    console.warn("Warning: Could not reach API to verify token.");
+    if (!runtime.json && !runtime.quiet) console.warn("Warning: Could not reach API to verify token.");
   }
 }
 function promptHidden(prompt) {
-  return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return Promise.reject(new CliError("user", "No interactive terminal available. Re-run with --token-stdin or set ARCANIST_TOKEN."));
+  }
+  return new Promise((resolve, reject) => {
+    const rl = createInterface2({ input: process.stdin, output: process.stdout });
     process.stdout.write(prompt);
     const stdin = process.stdin;
     if (stdin.isTTY) stdin.setRawMode(true);
@@ -185,7 +394,9 @@ function promptHidden(prompt) {
         resolve(input);
       } else if (c === "") {
         if (stdin.isTTY) stdin.setRawMode(false);
-        process.exit(1);
+        stdin.removeListener("data", onData);
+        rl.close();
+        reject(new CliError("user", "Interrupted.", { exitCode: 130 }));
       } else if (c === "\x7F" || c === "\b") {
         input = input.slice(0, -1);
       } else {
@@ -197,32 +408,21 @@ function promptHidden(prompt) {
 }
 
 // src/commands/message.ts
-async function messageCommand(sessionId, prompt) {
-  const config = requireConfig();
-  try {
-    await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
-      method: "POST",
-      body: JSON.stringify({ prompt })
-    });
-    console.log(`Message sent to session ${sessionId}.`);
-  } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-}
-
-// src/commands/stop.ts
-async function stopCommand(sessionId) {
-  const config = requireConfig();
-  try {
-    await apiFetch(config, `/api/sessions/${sessionId}/stop`, {
-      method: "POST"
-    });
-    console.log(`Stop requested for session ${sessionId}.`);
-  } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+async function messageCommand(sessionId, promptArg, options = {}, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const prompt = await resolvePromptInput(promptArg, options);
+  const response = await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
+    method: "POST",
+    headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
+    body: JSON.stringify({ prompt })
+  });
+  const promptId = response.prompt?.promptId ?? response.prompt?.id;
+  if (isJson(command, options)) {
+    writeJson({ sessionId, ...promptId ? { promptId } : {} });
+    return;
   }
+  console.log(`Message sent to session ${sessionId}.`);
 }
 
 // ../../shared/transcript/projector.ts
@@ -794,22 +994,6 @@ function renderWatchEvent(event, state) {
   }
 }
 
-// src/commands/transcript.ts
-async function transcriptCommand(sessionId, options) {
-  const config = requireConfig();
-  try {
-    const exportData = await apiFetch(config, `/api/sessions/${sessionId}/export`);
-    if (options.json) {
-      console.log(JSON.stringify(exportData, null, 2));
-      return;
-    }
-    console.log(renderSessionTranscript(exportData));
-  } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-}
-
 // src/constants/watch.ts
 var DEFAULT_WATCH_POLL_INTERVAL_MS = 1e3;
 var WATCH_REPLAY_PAGE_SIZE = 200;
@@ -821,11 +1005,17 @@ function sleep(ms) {
 }
 function parsePollInterval(raw) {
   if (!raw) return DEFAULT_WATCH_POLL_INTERVAL_MS;
-  const parsed = Number.parseInt(raw, 10);
-  if (!Number.isFinite(parsed) || parsed < 0) {
-    throw new Error("Polling interval must be a non-negative integer.");
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("user", "Polling interval must be a non-negative integer.");
   }
-  return parsed;
+  return Number(raw);
+}
+function parseNonNegativeInteger(raw, name, defaultValue) {
+  if (!raw) return defaultValue;
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("user", `${name} must be a non-negative integer.`);
+  }
+  return Number(raw);
 }
 function formatStatusLine(status) {
   const details = [];
@@ -837,33 +1027,42 @@ async function fetchPromptLabels(config, sessionId) {
   const data = await apiFetch(config, `/api/sessions/${sessionId}/prompts`);
   return buildPromptLabelMap(data.prompts);
 }
-async function watchCommand(sessionId, options) {
-  const config = requireConfig();
+async function watchCommand(sessionId, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
   const pollIntervalMs = parsePollInterval(options.pollInterval);
+  const initialAfterSequence = parseNonNegativeInteger(options.afterSequence, "--after-sequence", 0);
+  const pageSize = parseNonNegativeInteger(options.limit, "--limit", WATCH_REPLAY_PAGE_SIZE);
+  if (pageSize === 0) {
+    throw new CliError("user", "--limit must be greater than 0.");
+  }
+  const json = isJson(command, options);
   let promptLabels = /* @__PURE__ */ new Map();
-  try {
-    promptLabels = await fetchPromptLabels(config, sessionId);
-  } catch (err) {
-    console.error(`Warning: failed to fetch prompt labels for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+  if (!json) {
+    try {
+      promptLabels = await fetchPromptLabels(config, sessionId);
+    } catch (err) {
+      console.error(`Warning: failed to fetch prompt labels for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
   const renderState = {
     promptLabels,
     toolCalls: /* @__PURE__ */ new Map()
   };
-  let afterSequence = 0;
+  let afterSequence = initialAfterSequence;
   let lastStatusLine = null;
   let textOpen = false;
-  console.log(`Watching session ${sessionId}...`);
+  if (!json) console.log(`Watching session ${sessionId}...`);
   try {
     while (true) {
       const query = new URLSearchParams({
         afterSequence: String(afterSequence),
-        limit: String(WATCH_REPLAY_PAGE_SIZE)
+        limit: String(pageSize)
       });
       const payload = await apiFetchText(config, `/api/sessions/${sessionId}/events?${query}`);
       const parsed = parseSsePayload(payload);
-      const receivedFullPage = parsed.events.length >= WATCH_REPLAY_PAGE_SIZE;
-      if (parsed.status) {
+      const receivedFullPage = parsed.events.length >= pageSize;
+      if (!json && parsed.status) {
         const nextStatusLine = formatStatusLine(parsed.status);
         if (nextStatusLine !== lastStatusLine) {
           if (textOpen) {
@@ -876,6 +1075,11 @@ async function watchCommand(sessionId, options) {
       }
       for (const event of parsed.events) {
         if (typeof event.id === "number" && event.id > afterSequence) afterSequence = event.id;
+        if (json) {
+          process.stdout.write(`${JSON.stringify({ sequence: event.id, type: event.type, data: event.data })}
+`);
+          continue;
+        }
         const rendered = renderWatchEvent(event, renderState);
         if (!rendered) continue;
         if (rendered.kind === "text") {
@@ -899,30 +1103,347 @@ async function watchCommand(sessionId, options) {
         await sleep(pollIntervalMs);
       }
     }
-  } catch (err) {
+  } finally {
     if (textOpen) process.stdout.write("\n");
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+  }
+}
+
+// src/commands/sessions.ts
+async function listSessionsCommand(options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const query = new URLSearchParams();
+  if (options.status) query.set("status", options.status);
+  if (options.scope) query.set("scope", options.scope);
+  if (options.limit) query.set("limit", options.limit);
+  if (options.cursor) query.set("cursor", options.cursor);
+  const payload = await apiFetch(
+    config,
+    `/api/sessions${query.size ? `?${query.toString()}` : ""}`
+  );
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  if (payload.sessions.length === 0) {
+    console.log("No sessions found.");
+    return;
+  }
+  for (const session of payload.sessions) {
+    const id = String(session.id ?? session.sessionId ?? "");
+    const status = String(session.status ?? "");
+    const title = typeof session.title === "string" ? ` ${session.title}` : "";
+    console.log(`${id}	${status}${title}`);
+  }
+  if (payload.nextCursor) console.log(`Next cursor: ${payload.nextCursor}`);
+}
+async function getSessionCommand(sessionId, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const payload = await apiFetch(config, `/api/sessions/${sessionId}`);
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  const session = payload.session && typeof payload.session === "object" ? payload.session : payload;
+  console.log(`Session: ${String(session.sessionId ?? session.id ?? sessionId)}`);
+  console.log(`Status: ${String(session.status ?? "unknown")}`);
+  if (session.repoUrl) console.log(`Repo: ${String(session.repoUrl)}`);
+  if (session.title) console.log(`Title: ${String(session.title)}`);
+}
+async function sessionEventsCommand(sessionId, options, command) {
+  if (options.follow) {
+    if (options.beforeSequence) {
+      throw new CliError("user", "--before-sequence cannot be used with --follow.");
+    }
+    if (options.promptId) {
+      throw new CliError("user", "--prompt-id cannot be used with --follow because the follow endpoint does not support prompt filtering.");
+    }
+    await watchCommand(sessionId, { ...options, pollInterval: options.pollInterval, afterSequence: options.afterSequence, limit: options.limit }, command);
+    return;
+  }
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const query = new URLSearchParams();
+  if (options.afterSequence) query.set("after_sequence", options.afterSequence);
+  if (options.beforeSequence) query.set("before_sequence", options.beforeSequence);
+  if (options.promptId) query.set("prompt_id", options.promptId);
+  if (options.limit) query.set("limit", options.limit);
+  const payload = await apiFetch(config, `/api/sessions/${sessionId}/events/history${query.size ? `?${query.toString()}` : ""}`);
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  const promptLabels = await fetchPromptLabels(config, sessionId).catch(() => /* @__PURE__ */ new Map());
+  const state = { promptLabels, toolCalls: /* @__PURE__ */ new Map() };
+  let textOpen = false;
+  for (const event of payload.events) {
+    const rendered = renderWatchEvent(event, state);
+    if (rendered?.kind === "line") {
+      if (textOpen) {
+        process.stdout.write("\n");
+        textOpen = false;
+      }
+      console.log(rendered.line);
+    }
+    if (rendered?.kind === "text" && rendered.text) {
+      process.stdout.write(rendered.text);
+      textOpen = true;
+    }
   }
   if (textOpen) process.stdout.write("\n");
 }
+async function usageCommand(sessionId, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const payload = await apiFetch(config, `/api/sessions/${sessionId}/usage`);
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  const usage = payload.usage && typeof payload.usage === "object" ? payload.usage : payload;
+  console.log(`Input tokens: ${String(usage.inputTokens ?? 0)}`);
+  console.log(`Output tokens: ${String(usage.outputTokens ?? 0)}`);
+  console.log(`Total tokens: ${String(usage.totalTokens ?? 0)}`);
+  if (usage.totalCostUsd !== void 0) console.log(`Cost: ${String(usage.totalCostUsd)}`);
+}
+
+// src/commands/stop.ts
+async function stopCommand(sessionId, options = {}, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const response = await apiFetch(config, `/api/sessions/${sessionId}/stop`, {
+    method: "POST"
+  });
+  const status = response.status ?? "stopping";
+  if (isJson(command, options)) {
+    writeJson({ sessionId, status });
+    return;
+  }
+  console.log(status === "already_stopped" ? `Session ${sessionId} is already stopped.` : `Stop requested for session ${sessionId}.`);
+}
+
+// src/commands/tokens.ts
+async function listTokensCommand(options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const query = new URLSearchParams();
+  if (options.limit) query.set("limit", options.limit);
+  if (options.cursor) query.set("cursor", options.cursor);
+  const payload = await apiFetch(config, `/api/cli-tokens${query.size ? `?${query.toString()}` : ""}`);
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  if (payload.data.length === 0) {
+    console.log("No CLI tokens found.");
+    return;
+  }
+  for (const token of payload.data) {
+    console.log(`${String(token.id)}	${String(token.scope)}	${String(token.tokenPrefix)}	${String(token.revokedAt ? "revoked" : "active")}`);
+  }
+  if (payload.nextCursor) console.log(`Next cursor: ${payload.nextCursor}`);
+}
+async function createTokenCommand(options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const expiresInDays = options.expiresInDays === void 0 ? void 0 : Number(options.expiresInDays);
+  if (expiresInDays !== void 0 && (!Number.isInteger(expiresInDays) || expiresInDays <= 0)) {
+    throw new CliError("user", "expiresInDays must be a positive integer.");
+  }
+  const payload = await apiFetch(config, "/api/cli-tokens", {
+    method: "POST",
+    body: JSON.stringify({
+      scope: options.scope ?? "read",
+      ...expiresInDays !== void 0 ? { expiresInDays } : {}
+    })
+  });
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  console.log(`Token: ${String(payload.token)}`);
+  console.log(`ID: ${String(payload.id)}`);
+  console.log(`Scope: ${String(payload.scope)}`);
+}
+async function revokeTokenCommand(tokenId, options, command) {
+  if (isJson(command, options) && options.yes !== true) {
+    throw new CliError("user", "`tokens revoke --json` requires --yes.");
+  }
+  if (options.yes !== true) {
+    await confirmOrThrow(`Revoke CLI token ${tokenId}?`);
+  }
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const payload = await apiFetch(config, `/api/cli-tokens/${tokenId}/revoke`, { method: "POST" });
+  if (isJson(command, options)) {
+    writeJson(payload);
+    return;
+  }
+  console.log(`Revoked token ${tokenId}.`);
+}
+
+// src/commands/transcript.ts
+async function transcriptCommand(sessionId, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  const config = requireConfig(runtime);
+  const exportData = await apiFetch(config, `/api/sessions/${sessionId}/export`);
+  if (isJson(command, options)) {
+    writeJson(exportData);
+    return;
+  }
+  console.log(renderSessionTranscript(exportData));
+}
 
 // src/index.ts
-var require2 = createRequire(import.meta.url);
-var { version } = require2("../package.json");
-var program = new Command().name("arcanist").description("Arcanist CLI").version(version);
-program.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").action(loginCommand);
-program.command("create").description("Create a session and send a prompt").argument("<repo-url>", "Repository URL").argument("<prompt>", "Prompt to send").option("--model <model>", "Model to use").action(createCommand);
-program.command("message").description("Send a message to an existing session").argument("<session-id>", "Session ID").argument("<prompt>", "Message to send").action(messageCommand);
-program.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").action(stopCommand);
-program.command("transcript").description("Render a session transcript").argument("<session-id>", "Session ID").option("--json", "Output raw session export JSON").action(transcriptCommand);
-program.command("watch").description("Watch session activity until it becomes idle").argument("<session-id>", "Session ID").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).action(watchCommand);
+var require3 = createRequire2(import.meta.url);
+var { version: version2 } = require3("../package.json");
+var program = new Command().name("arcanist").description("Arcanist CLI").version(version2).option("--json", "Output machine-readable JSON").option("--quiet", "Suppress non-essential stderr output").option("--api-url <url>", "Override API URL. Prefer ARCANIST_API_URL for persistent use").option("--token <token>", "Override API token. Prefer ARCANIST_TOKEN because flags can be visible in shell history and process lists").option("--no-color", "Disable color output").exitOverride().addHelpText("after", `
+Examples:
+  arcanist auth login --token-stdin
+  arcanist sessions create https://github.com/org/repo "fix bug" --json | jq -r .sessionId
+  printf "fix bug" | arcanist sessions create https://github.com/org/repo --prompt-stdin --json
+  arcanist sessions events <session-id> --follow --json
+
+Exit codes:
+  0 ok, 1 user/input, 2 auth, 3 not found, 4 conflict, 10 server/network, 130 interrupted
+`);
+program.configureOutput({
+  writeErr: (str) => process.stderr.write(str)
+});
+program.hook("preAction", (_thisCommand, actionCommand) => {
+  applyColorEnvironment(getRuntimeOptions(actionCommand));
+});
+function addCreateOptions(cmd) {
+  return cmd.argument("<repo-url>", "Repository URL").argument("[prompt]", "Prompt to send, or '-' to read stdin").option("--model <model>", "Model to use").option("--prompt-stdin", "Read prompt from stdin").option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").addHelpText("after", `
+Examples:
+  arcanist sessions create https://github.com/org/repo "fix bug"
+  printf "fix bug" | arcanist sessions create https://github.com/org/repo --prompt-stdin --json
+  arcanist sessions create https://github.com/org/repo - --json | jq -r .sessionId | xargs -I{} arcanist sessions events {} --follow --json
+`);
+}
+function addSendOptions(cmd) {
+  return cmd.argument("<session-id>", "Session ID").argument("[prompt]", "Prompt to send, or '-' to read stdin").option("--prompt-stdin", "Read prompt from stdin").option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").addHelpText("after", `
+Examples:
+  arcanist sessions send <session-id> "also update tests"
+  printf "also update tests" | arcanist sessions send <session-id> --prompt-stdin --json
+`);
+}
+var auth = program.command("auth").description("Authentication commands");
+auth.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText("after", `
+Examples:
+  arcanist auth login
+  printf "arc_..." | arcanist auth login --token-stdin
+  ARCANIST_TOKEN=arc_... arcanist auth whoami --json
+`).action((options, command) => loginCommand(options, command));
+auth.command("whoami").description("Print the authenticated user and token scope").addHelpText("after", `
+Examples:
+  arcanist auth whoami
+  ARCANIST_TOKEN=arc_... arcanist auth whoami --json
+`).action((options, command) => whoamiCommand(options, command));
+var sessions = program.command("sessions").description("Session commands");
+addCreateOptions(sessions.command("create").description("Create a session and send a prompt")).action((repoUrl, prompt, options, command) => createCommand(repoUrl, prompt, options, command));
+addSendOptions(sessions.command("send").description("Send a message to an existing session")).action((sessionId, prompt, options, command) => messageCommand(sessionId, prompt, options, command));
+sessions.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").addHelpText("after", `
+Examples:
+  arcanist sessions stop <session-id>
+  arcanist sessions stop <session-id> --json
+`).action((sessionId, options, command) => stopCommand(sessionId, options, command));
+sessions.command("get").description("Get session details").argument("<session-id>", "Session ID").addHelpText("after", `
+Examples:
+  arcanist sessions get <session-id>
+  arcanist sessions get <session-id> --json
+`).action((sessionId, options, command) => getSessionCommand(sessionId, options, command));
+sessions.command("list").description("List sessions").option("--status <status>", "Filter by session status").option("--scope <scope>", "Session scope: mine or business").option("--limit <n>", "Maximum sessions to return").option("--cursor <cursor>", "Pagination cursor").addHelpText("after", `
+Examples:
+  arcanist sessions list
+  arcanist sessions list --status idle --json
+`).action((options, command) => listSessionsCommand(options, command));
+sessions.command("events").description("Read or follow session replay events").argument("<session-id>", "Session ID").option("--after-sequence <n>", "Return events after this sequence").option("--before-sequence <n>", "Return events before this sequence").option("--prompt-id <id>", "Filter events by prompt ID").option("--limit <n>", "Maximum events to return").option("--follow", "Follow events until the session is idle").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).addHelpText("after", `
+Examples:
+  arcanist sessions events <session-id> --json
+  arcanist sessions events <session-id> --follow --json
+`).action((sessionId, options, command) => sessionEventsCommand(sessionId, options, command));
+sessions.command("transcript").description("Render a session transcript").argument("<session-id>", "Session ID").addHelpText("after", `
+Examples:
+  arcanist sessions transcript <session-id>
+  arcanist sessions transcript <session-id> --json
+`).action((sessionId, options, command) => transcriptCommand(sessionId, options, command));
+sessions.command("watch").description("Watch session activity until it becomes idle").argument("<session-id>", "Session ID").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).addHelpText("after", `
+Examples:
+  arcanist sessions watch <session-id>
+  arcanist sessions watch <session-id> --json
+`).action((sessionId, options, command) => watchCommand(sessionId, options, command));
+sessions.command("usage").description("Get token usage for a session").argument("<session-id>", "Session ID").addHelpText("after", `
+Examples:
+  arcanist sessions usage <session-id>
+  arcanist sessions usage <session-id> --json
+`).action((sessionId, options, command) => usageCommand(sessionId, options, command));
+var tokens = program.command("tokens").description("CLI token commands");
+tokens.command("list").description("List CLI tokens").option("--limit <n>", "Maximum tokens to return").option("--cursor <cursor>", "Pagination cursor").action((options, command) => listTokensCommand(options, command));
+tokens.command("create").description("Create a CLI token and print it once").option("--scope <scope>", "Token scope: read or write", "read").option("--expires-in-days <days>", "Token expiry in days").addHelpText("after", `
+Examples:
+  arcanist tokens create --scope read
+  arcanist tokens create --scope read --json
+`).action((options, command) => createTokenCommand(options, command));
+tokens.command("revoke").description("Revoke a CLI token").argument("<id>", "Token ID").option("--yes", "Confirm revocation without prompting").addHelpText("after", `
+Examples:
+  arcanist tokens revoke 42
+  arcanist tokens revoke 42 --yes --json
+`).action((id, options, command) => revokeTokenCommand(id, options, command));
+program.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").action((options, command) => {
+  printDeprecatedAlias("login", "auth login", command);
+  return loginCommand(options, command);
+});
+addCreateOptions(program.command("create").description("Create a session and send a prompt")).action((repoUrl, prompt, options, command) => {
+  printDeprecatedAlias("create", "sessions create", command);
+  return createCommand(repoUrl, prompt, options, command);
+});
+addSendOptions(program.command("message").description("Send a message to an existing session")).action((sessionId, prompt, options, command) => {
+  printDeprecatedAlias("message", "sessions send", command);
+  return messageCommand(sessionId, prompt, options, command);
+});
+program.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").action((sessionId, options, command) => {
+  printDeprecatedAlias("stop", "sessions stop", command);
+  return stopCommand(sessionId, options, command);
+});
+program.command("transcript").description("Render a session transcript").argument("<session-id>", "Session ID").action((sessionId, options, command) => {
+  printDeprecatedAlias("transcript", "sessions transcript", command);
+  return transcriptCommand(sessionId, options, command);
+});
+program.command("watch").description("Watch session activity until it becomes idle").argument("<session-id>", "Session ID").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).action((sessionId, options, command) => {
+  printDeprecatedAlias("watch", "sessions events --follow", command);
+  return watchCommand(sessionId, options, command);
+});
 async function main() {
   try {
     await program.parseAsync(process.argv);
   } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : "An unexpected error occurred."}`);
-    process.exit(1);
+    if (isCommanderHelpOrVersion(err)) {
+      process.exit(0);
+    }
+    if (err instanceof CliError && err.exitCode === 130) restoreTerminal();
+    const cliError = toCliError(err);
+    const options = program.opts();
+    if (options.json) {
+      process.stderr.write(`${formatJsonError(cliError)}
+`);
+    } else {
+      process.stderr.write(`Error: ${cliError.message}
+`);
+      if (cliError.hint) process.stderr.write(`Hint: ${cliError.hint}
+`);
+    }
+    process.exit(cliError.exitCode);
   }
 }
+function isCommanderHelpOrVersion(err) {
+  if (!err || typeof err !== "object") return false;
+  const code = err.code;
+  return code === "commander.helpDisplayed" || code === "commander.version";
+}
+function restoreTerminal() {
+  if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  process.stdout.write("\x1B[?25h");
+}
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {