@tryarcanist/cli 0.1.342 → 0.1.344

package/README.md

@@ -18,7 +18,7 @@ arcanist sessions list --json
 ```
 
 ```bash
-export ARCANIST_TOKEN=arc_...       # write-scoped for session mutations
+export ARCANIST_TOKEN=arc_...       # write-scoped for prepare, review, and stop
 SESSION_ID=$(arcanist sessions list --json | jq -r '.sessions[0].id')
 arcanist sessions events "$SESSION_ID" --follow --json
 ```
@@ -34,7 +34,7 @@ arcanist auth login
 
 Token config is stored at `~/.arcanist/config.json`. Existing automation can still provide a token through `ARCANIST_TOKEN` or `--token-stdin`. Multiple active tokens per user are supported; revoke tokens independently when a device or workflow no longer needs access.
 
-Use a read-scoped token for inspection and debugging; use a write-scoped token only to create sessions, send prompts, or stop runs.
+Use a read-scoped token for inspection and debugging; use a write-scoped token to prepare or retry environments, trigger a Zeus review, stop a session, or manage tokens.
 
 You can also pipe the token via stdin:
 
@@ -95,14 +95,13 @@ With `--json`, successful command output is machine-readable and newline-termina
   "error": {
     "code": "auth",
     "message": "Not logged in.",
-    "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`.",
-    "data": { "serverCode": "token_revoked" }
+    "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`."
   }
 }
 ```
 
 `error.data` is omitted when there is no structured recovery data.
-Stable fields are `serverCode` for server-provided error codes and `sessionId` when the server started a session before the request failed.
+Stable fields are `serverCode` for server-provided error codes, `repository`, and `environmentsUrl`.
 
 Exit codes:
 
@@ -116,21 +115,40 @@ Exit codes:
 130 interrupted
 ```
 
-Mutation commands send an `Idempotency-Key` header. The CLI does not auto-retry mutation endpoints; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. `--idempotency-key` is available on `tokens create` and `sandbox build`. Both use auto-random keys by default, so only an explicit key makes cross-invocation retries safe.
+`tokens create` and `sandbox build` send an `Idempotency-Key` header. The CLI does not auto-retry those endpoints; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. Both use auto-random keys by default, so only an explicit key makes cross-invocation retries safe.
 
 ## Commands
 
-### `arcanist environments prepare|status`
+### `arcanist environments prepare`
 
-Prepare the current repository for Zeus, or inspect its machine-readable setup state. Pass `owner/repo` outside a checkout. A write-scoped token is required to prepare; read-scoped tokens can inspect status.
+Prepare the current repository for Zeus. Pass `owner/repo` outside a checkout. A write-scoped token is required.
 
 ```bash
 arcanist environments prepare --wait --json
+arcanist environments prepare owner/repo --wait --poll-interval 5000 --json
+```
+
+Agents should follow `repository.nextAction` and `repository.command`. Request a Zeus review only when `nextAction` is `review`. When `command` is `null`, do not invent an API call; surface `question` / `secretRequest` to a human. `--wait` waits through internal handoffs until setup is ready or there is a real action for the user or Arcanist.
+
+### `arcanist environments status`
+
+Inspect machine-readable setup state. Read-scoped tokens can inspect status. Pass `owner/repo` outside a checkout.
+
+```bash
 arcanist environments status owner/repo --json
-arcanist environments retry owner/repo --wait --json
+arcanist environments status owner/repo --wait --poll-interval 5000 --json
 ```
 
-Agents should follow `repository.nextAction` and request a Zeus review only when it is `review`. The command waits through internal handoffs until setup is ready or there is a real action for the user or Arcanist.
+Agents should follow `repository.nextAction` and `repository.command`. Request a Zeus review only when `nextAction` is `review`. When `command` is `null`, do not invent an API call; surface `question` / `secretRequest` to a human. `--wait` waits through internal handoffs until setup is ready or there is a real action for the user or Arcanist.
+
+### `arcanist environments retry`
+
+Retry a failed repository environment setup. A write-scoped token is required. Pass `owner/repo` outside a checkout.
+
+```bash
+arcanist environments retry owner/repo --wait --json
+arcanist environments retry owner/repo --wait --poll-interval 5000 --json
+```
 
 ### `arcanist setup`
 
@@ -140,9 +158,10 @@ Connect Arcanist and prepare one or more repository environments. The command st
 arcanist setup
 arcanist setup acme/web
 arcanist setup acme/web acme/api --json
+arcanist setup acme/web acme/api --workspace
 ```
 
-With no repository arguments, the command returns the eligible repositories and `selection_required`. Rerun with the repositories to prepare. Builds continue after the command exits. The command prints an `arcanist environments status owner/repo --wait` command for each build so agents can track progress or leave it running.
+With no repository arguments, the command returns the eligible repositories and `selection_required`. Rerun with the repositories to prepare. `--workspace` prepares them as one multi-repository workspace. Builds continue after the command exits. The command prints an `arcanist environments status owner/repo --wait` command for each build so agents can track progress or leave it running.
 
 ### `arcanist auth login`
 
@@ -152,7 +171,7 @@ printf "arc_..." | arcanist auth login --token-stdin
 arcanist auth login --api-url https://api.tryarcanist.com
 ```
 
-The default flow prints a browser authorization URL and waits for approval. `--json` writes the action immediately as JSONL on stderr and writes one final result to stdout. `--token-stdin` and `ARCANIST_TOKEN` remain available for automation that already has a token.
+The default flow prints a browser authorization URL and waits for human approval. `--json` writes the action immediately as JSONL on stderr and writes one final result to stdout. `ARCANIST_TOKEN` authenticates later commands through the same config loader as `~/.arcanist/config.json`. `arcanist auth login --token-stdin`, `--token`, or `ARCANIST_TOKEN` persists a token for later use.
 
 ### `arcanist auth whoami`
 
@@ -253,11 +272,11 @@ arcanist sessions events abc123 --follow --json
 
 JSON mode without `--follow` returns one JSON object from `/events/history`: `{events: [...], ...}`. Canonical events carry `phase`.
 
-Follow mode emits NDJSON, one `{sequence, type, data}` object per line, until the session becomes idle. Actionable follow-mode signals:
+Follow mode emits NDJSON, one `{sequence, type, data}` object per line, until the session reaches a terminal phase: `completed`, `superseded`, `needs_you`, `blocked`, `failed`, `stopped`, or `archived`. JSON follow still suppresses lifecycle `status` frames. Actionable follow-mode signals:
 
 - PR opened or updated: `pr_created` / `pr_updated`; URL at `data.prUrl`.
 - Waiting for human input: `question`; question text at `data.question`.
-- Terminal: `prompt_completed`, `prompt_failed`, and `session_idle`. Follow JSON mode suppresses lifecycle `status` frames, so key on these event names rather than `waiting_for_input`.
+- Prompt or idle signals: `prompt_completed`, `prompt_failed`, and `session_idle`. Key on these event names rather than `waiting_for_input`. `session_idle` does not exit the process.
 
 ### `arcanist sessions transcript <session-id>`
 
@@ -371,7 +390,7 @@ Chain commands with `--json` and `jq`:
 
 ```bash
 SESSION_ID=$(arcanist sessions list --json | jq -r '.sessions[0].id')
-arcanist sessions events "$SESSION_ID" --follow --json | jq -r 'select(.type == "assistant_message")'
+arcanist sessions events "$SESSION_ID" --follow --json | jq -r 'select(.type == "text")'
 ```
 
 For cron, prefer `ARCANIST_TOKEN` or a logged-in `~/.arcanist/config.json` over passing `--token` on the command line.

package/dist/index.js

@@ -7367,11 +7367,50 @@ var require_dist = __commonJS({
 // src/index.ts
 import { Command } from "commander";
 
+// ../../shared/session/phase.ts
+var PHASES = [
+  "idle",
+  "running",
+  "review_starting",
+  "waiting_for_input",
+  "finalizing",
+  "review_listening",
+  "completed",
+  "superseded",
+  "needs_you",
+  "blocked",
+  "failed",
+  "stopped",
+  "archived"
+];
+var TERMINAL_PHASES_ARRAY = [
+  "completed",
+  "superseded",
+  "needs_you",
+  "blocked",
+  "failed",
+  "stopped",
+  "archived"
+];
+var TERMINAL_PHASES = new Set(TERMINAL_PHASES_ARRAY);
+var TERMINAL_FOR_FALLBACK_POLLING_PHASES = new Set(
+  TERMINAL_PHASES_ARRAY.filter((phase) => phase !== "completed")
+);
+var CHILD_SLOT_RELEASE_PHASES = new Set(
+  TERMINAL_PHASES_ARRAY.filter((phase) => phase !== "stopped")
+);
+var ARCHIVABLE_STALE_TERMINAL_PHASES_ARRAY = TERMINAL_PHASES_ARRAY.filter(
+  (phase) => phase !== "archived" && phase !== "needs_you" && phase !== "blocked" && phase !== "stopped"
+);
+function isTerminalPhase(phase, _sessionKind) {
+  return TERMINAL_PHASES.has(phase);
+}
+
 // package.json
 var package_default = {
   name: "@tryarcanist/cli",
-  version: "0.1.342",
-  description: "CLI for Arcanist - create and manage coding agent sessions",
+  version: "0.1.344",
+  description: "Command-line interface for Arcanist: inspect sessions, prepare Zeus environments, and trigger reviews",
   type: "module",
   bin: {
     arcanist: "dist/index.js"
@@ -23070,45 +23109,6 @@ function assertSameAttempt(triggeredSessionId, settledSessionId, label) {
   }
 }
 
-// ../../shared/session/phase.ts
-var PHASES = [
-  "idle",
-  "running",
-  "review_starting",
-  "waiting_for_input",
-  "finalizing",
-  "review_listening",
-  "completed",
-  "superseded",
-  "needs_you",
-  "blocked",
-  "failed",
-  "stopped",
-  "archived"
-];
-var TERMINAL_PHASES_ARRAY = [
-  "completed",
-  "superseded",
-  "needs_you",
-  "blocked",
-  "failed",
-  "stopped",
-  "archived"
-];
-var TERMINAL_PHASES = new Set(TERMINAL_PHASES_ARRAY);
-var TERMINAL_FOR_FALLBACK_POLLING_PHASES = new Set(
-  TERMINAL_PHASES_ARRAY.filter((phase) => phase !== "completed")
-);
-var CHILD_SLOT_RELEASE_PHASES = new Set(
-  TERMINAL_PHASES_ARRAY.filter((phase) => phase !== "stopped")
-);
-var ARCHIVABLE_STALE_TERMINAL_PHASES_ARRAY = TERMINAL_PHASES_ARRAY.filter(
-  (phase) => phase !== "archived" && phase !== "needs_you" && phase !== "blocked" && phase !== "stopped"
-);
-function isTerminalPhase(phase, _sessionKind) {
-  return TERMINAL_PHASES.has(phase);
-}
-
 // src/constants/watch.ts
 var MIN_WATCH_POLL_INTERVAL_MS = 250;
 var DEFAULT_WATCH_POLL_INTERVAL_MS = 1e3;
@@ -23149,11 +23149,33 @@ async function fetchSetupState(config2, fullName) {
     status: "not_started",
     stage: null
   };
-  return { ...state, nextAction: nextAction(state) };
+  const action = nextAction(state);
+  return { ...state, nextAction: action, command: commandForNextAction(action, state.fullName) };
 }
 function isActive(state) {
   return state.nextAction === "wait";
 }
+function commandForNextAction(action, fullName) {
+  switch (action) {
+    case "prepare":
+      return `arcanist environments prepare ${fullName}`;
+    case "wait":
+      return `arcanist environments status ${fullName} --wait`;
+    case "retry":
+      return `arcanist environments retry ${fullName}`;
+    case "review":
+      return null;
+    case "add_credentials":
+    case "answer_question":
+    case "authorize_github":
+    case "wait_for_arcanist":
+      return null;
+    default: {
+      const _exhaustive = action;
+      return _exhaustive;
+    }
+  }
+}
 function nextAction(state) {
   if (state.status === "not_started") return "prepare";
   if (state.status === "ready") return "review";
@@ -23219,11 +23241,13 @@ async function environmentPrepareCommand(repoArg, options = {}, command) {
     emit(command, options, { repository: state2 }, ({ repository }) => printState(repository));
     return;
   }
+  const action = result.status === "already_ready" ? "review" : "wait";
   const state = {
     fullName: result.fullName,
     status: result.status === "already_ready" ? "ready" : "pending",
     stage: null,
-    nextAction: result.status === "already_ready" ? "review" : "wait"
+    nextAction: action,
+    command: commandForNextAction(action, result.fullName)
   };
   emit(command, options, { repository: state }, ({ repository }) => printState(repository));
 }
@@ -23259,11 +23283,12 @@ var DEVICE_AUTH_TOKEN_PATH = "/api/auth/cli/device/token";
 async function loginCommand(options, command) {
   const runtime = getRuntimeOptions(command, options);
   const apiUrl = resolveLoginApiUrl(runtime.apiUrl);
+  const envOrFlag = resolveEnvOrFlagConfig(runtime, false);
   let token = null;
   if (options.tokenStdin) {
     token = await readStdinTrimmed();
-  } else if (runtime.token) {
-    token = runtime.token;
+  } else if (envOrFlag?.token) {
+    token = envOrFlag.token;
   } else {
     token = await loginWithDeviceAuthorization(apiUrl, runtime);
   }
@@ -27021,7 +27046,13 @@ async function setupCommand(repoArgs = [], options = {}, command) {
   }
   const runtime = getRuntimeOptions(command, options);
   let config2 = loadConfig(runtime);
-  if (!config2) config2 = await loginCommand({ ...runtime, emitResult: false }, command);
+  if (!config2) {
+    const envOrFlag = resolveEnvOrFlagConfig(runtime, false);
+    if ((process.stdin.isTTY !== true || process.stdout.isTTY !== true) && !envOrFlag?.token) {
+      throw new CliError("auth", "Not logged in.", { hint: "Run `arcanist auth login` or set `ARCANIST_TOKEN`." });
+    }
+    config2 = await loginCommand({ ...runtime, emitResult: false }, command);
+  }
   const requested = repoArgs.map((value) => {
     const repo = parseRepoArg(value);
     return `${repo.owner}/${repo.repo}`;
@@ -27163,7 +27194,7 @@ function emitSetupAction(runtime, action) {
 `);
 }
 function trackingCommands(repositories) {
-  return repositories.map((repository) => `Track later: arcanist environments status ${repository} --wait`);
+  return repositories.map((repository) => `Track later: ${commandForNextAction("wait", repository)}`);
 }
 
 // src/commands/stop.ts
@@ -27391,7 +27422,7 @@ var { version: version3 } = package_default;
 var program = new Command().name("arcanist").description("Arcanist CLI").version(version3).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(
+).option("--no-color", "Disable color output").configureHelp({ showGlobalOptions: true }).addHelpCommand(false).exitOverride().addHelpText(
   "after",
   `
 Examples:
@@ -27410,7 +27441,7 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
   applyColorEnvironment(getRuntimeOptions(actionCommand));
 });
 var auth = program.command("auth").description("Authentication commands");
-auth.command("login").description("Authenticate through your browser").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText(
+auth.command("login").description("Authenticate through your browser").option("--token-stdin", "Read token from stdin instead of interactive prompt").addHelpText(
   "after",
   `
 Examples:
@@ -27520,7 +27551,7 @@ JSON:
 JSON mode returns {sessions, nextCursor}. --all follows cursors until nextCursor is null.
 `
 ).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("--after <n>", "Alias for --after-sequence").option("--before-sequence <n>", "Return events before this sequence").option("--before <n>", "Alias for --before-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(
+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("--after <n>", "Alias for --after-sequence").option("--before-sequence <n>", "Return events before this sequence").option("--before <n>", "Alias for --before-sequence").option("--prompt-id <id>", "Filter events by prompt ID").option("--limit <n>", "Maximum events to return").option("--follow", "Follow events until a terminal phase").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).addHelpText(
   "after",
   `
 Examples:
@@ -27531,8 +27562,8 @@ Examples:
 
 JSON:
 JSON mode without --follow returns one JSON object from /events/history: {events: [...], ...}; canonical events carry phase.
---follow --json emits NDJSON, one {sequence, type, data} object per line.
-  Actionable follow types: pr_created/pr_updated use data.prUrl; question uses data.question; terminal types are prompt_completed, prompt_failed, and session_idle.
+--follow --json emits NDJSON, one {sequence, type, data} object per line, until a terminal phase: ${formatTerminalPhaseHelpList(TERMINAL_PHASES_ARRAY)}.
+Actionable follow types are NDJSON signals, not process-exit conditions: pr_created/pr_updated use data.prUrl; question uses data.question; prompt_completed, prompt_failed, and session_idle do not exit the process.
 `
 ).action((sessionId, options, command) => sessionEventsCommand(sessionId, options, command));
 sessions.command("transcript").description("Render a session transcript").argument("<session-id>", "Session ID").option("--last <n>", "Render only the last n transcript entries").addHelpText(
@@ -27603,7 +27634,8 @@ environments.command("status").description("Show repository environment setup st
   "after",
   `
 JSON:
-Returns {repository: {fullName, status, stage, nextAction, buildStatus?, failureReason?, secretRequest?, question?}}.
+Returns {repository: {fullName, status, stage, nextAction, command, buildStatus?, failureReason?, secretRequest?, question?}}.
+command is the CLI argv to run, or null when the next step is the web UI or Arcanist.
 The stable status values are not_started, pending, running, escalated, succeeded, failed, and ready.
 `
 ).action((repo, options, command) => environmentStatusCommand(repo, options, command));
@@ -27685,6 +27717,9 @@ Examples:
 `
 ).action((repo, name, options, command) => setTestCredentialCommand(repo, name, options, command));
 testCreds.command("delete").description("Delete a test credential").argument("<repo>", "Repository in 'owner/name' form").argument("<name>", "Credential name").requiredOption("--business <id>", "Business ID that owns the repo").option("--yes", "Confirm deletion without prompting").action((repo, name, options, command) => deleteTestCredentialCommand(repo, name, options, command));
+program.command("help").description("display help for command").argument("[path...]", "Command path to explain").action((path) => {
+  commandForHelpPath(program, path).help({ error: false });
+});
 async function main() {
   try {
     await program.parseAsync(process.argv);
@@ -27708,9 +27743,27 @@ async function main() {
   }
 }
 function isCommanderHelpOrVersion(err) {
-  if (!err || typeof err !== "object") return false;
-  const code = err.code;
-  return code === "commander.helpDisplayed" || code === "commander.version";
+  if (!err || typeof err !== "object" || !("code" in err)) return false;
+  const { code } = err;
+  if (code === "commander.helpDisplayed" || code === "commander.version") return true;
+  return code === "commander.help" && "exitCode" in err && err.exitCode === 0;
+}
+function formatTerminalPhaseHelpList(phases) {
+  const last = phases.at(-1);
+  if (last === void 0) return "";
+  if (phases.length === 1) return last;
+  return `${phases.slice(0, -1).join(", ")}, or ${last}`;
+}
+function commandForHelpPath(root, path) {
+  let current = root;
+  for (const name of path) {
+    const next = current.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
+    if (!next) {
+      throw new CliError("user", `Unknown help topic: ${path.join(" ")}`);
+    }
+    current = next;
+  }
+  return current;
 }
 function restoreTerminal() {
   if (process.stdin.isTTY) process.stdin.setRawMode(false);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.342",
-  "description": "CLI for Arcanist - create and manage coding agent sessions",
+  "version": "0.1.344",
+  "description": "Command-line interface for Arcanist: inspect sessions, prepare Zeus environments, and trigger reviews",
   "type": "module",
   "bin": {
     "arcanist": "dist/index.js"