@tryarcanist/cli 0.1.382 → 0.1.384

package/README.md

@@ -18,7 +18,7 @@ arcanist sessions list --json
 ```
 
 ```bash
-export ARCANIST_TOKEN=arc_...       # write-scoped for prepare, review, and sandbox build
+export ARCANIST_TOKEN=arc_...       # write-scoped for prepare and review
 SESSION_ID=$(arcanist sessions list --json | jq -r '.sessions[0].id')
 arcanist sessions events "$SESSION_ID" --follow --json
 ```
@@ -33,7 +33,7 @@ printf "arc_..." | arcanist auth login --token-stdin
 
 Token config is stored at `~/.arcanist/config.json`. Existing automation can provide a token through `ARCANIST_TOKEN` or `--token`. 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 to prepare or retry environments, trigger an Arcanist review, or build a sandbox layer.
+Use a read-scoped token for inspection and debugging; use a write-scoped token to prepare or retry environments, or trigger an Arcanist review.
 
 Auth and API URL precedence:
 
@@ -93,6 +93,8 @@ With `--json`, successful command output is machine-readable and newline-termina
 }
 ```
 
+A usage error (unknown command, unknown option, missing argument, a command group with no subcommand) uses the same shape, and stderr holds only that one object. `error.hint` names the next command to run when there is one.
+
 `error.data` is omitted when there is no structured recovery data.
 Stable fields are `serverCode` for server-provided error codes, `repository`, and `environmentsUrl`.
 
@@ -104,11 +106,23 @@ Exit codes:
 2   auth error (401/403)
 3   not found (404)
 4   conflict (409)
+5   review still running (`review --no-wait`)
 10  server or network error
 130 interrupted
 ```
 
-`sandbox build` sends an `Idempotency-Key` header. The CLI does not auto-retry that endpoint; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. It uses auto-random keys by default, so only an explicit key makes cross-invocation retries safe.
+## Command discovery for agents
+
+`arcanist help --json` prints the whole command tree as one JSON object, so an agent learns every command in one call. `arcanist help <command...> --json` prints one branch.
+
+```bash
+arcanist help --json
+arcanist help sessions events --json
+```
+
+Each node is `{path, description, aliases, arguments, options, notes?, subcommands}`. The node you ask for also has `globalOptions`, the flags it inherits from its parent commands. `arguments` entries are `{name, description, required, variadic}`, `options` entries are `{flags, description, required, defaultValue?}`, and `notes` holds the examples and JSON output shape that `--help` prints below the options.
+
+Commands that need a person at a terminal (`environments login` without `--clear`, `claude login` without `--token-stdin`) fail at once with exit code `1` when stdin or stderr is not a terminal.
 
 ## Commands
 
@@ -143,6 +157,27 @@ arcanist environments retry owner/repo --wait --json
 arcanist environments retry owner/repo --wait --poll-interval 5000 --json
 ```
 
+### `arcanist environments export`
+
+Write an environment's configuration as one JSON file: name, description, provisioning kind and app runtime config, helper files, cache settings (setup, maintenance and smoke scripts, dependencies, CPU and memory) and trusted domains. Secrets, the saved browser login and the review doc are not exported. Read-scoped tokens can export. Pass an environment id or `owner/repo` outside a checkout.
+
+```bash
+arcanist environments export owner/repo -o environment.json
+ARCANIST_API_URL=https://app.tryarcanist.com arcanist environments export owner/repo > prod.json
+```
+
+### `arcanist environments import`
+
+Apply an exported file to the same repository's environment on the current deployment, so one deployment can mirror another (for example QA from production). A write-scoped token is required. The target's primary repository must match the file. `--dry-run` lists the fields that differ without changing anything. When a build input changes, the server schedules a rebuild.
+
+`--create` creates the environment from the file when the deployment has no team environment for the file's primary repository, and the server schedules its first build. It applies only without an `[environment]` argument. The Arcanist GitHub App must be installed for the repository there. A created environment has no secrets, browser login or review doc.
+
+```bash
+ARCANIST_API_URL=https://staging.example.com arcanist environments import prod.json --dry-run
+ARCANIST_API_URL=https://staging.example.com arcanist environments import prod.json --json
+ARCANIST_API_URL=https://staging.example.com arcanist environments import local.json --create
+```
+
 ### `arcanist environments login`
 
 Log into your app once in a throwaway local browser and save that login on the environment so Arcanist sessions start signed in. Alias: `arcanist env login`. A write-scoped token is required. Pass an environment id or `owner/repo` outside a checkout; the environment must have an app runtime configured.
@@ -346,7 +381,7 @@ The upload limit is 3 MB. Each delivered review counts toward your plan's review
 
 Held-back files are committed, so they ship with your branch; the CLI lists them as `Committed but not uploaded for review (pass --include <path> to upload)`.
 
-Output is the headline (`Arcanist review: Hold off on merging.` when a finding blocks merge, else `Arcanist review: Ready to merge.`), the summary, then each finding as `file:line - title` followed by its full text. A blocking finding's title ends with `(blocks merge)`; a non-blocking finding has no tag. Nitpicks come last, under `Nitpicks (N)`. JSON mode returns `{status, requestId, sessionId, verdict, summary, findings}`, where each finding is `{file, line, blocksMerge, title, body}`, plus `nit: true` on a nitpick.
+Output is the headline (`Arcanist review: Hold off on merging.` when a finding blocks merge, else `Arcanist review: Ready to merge.`), the summary, then each finding as `file:line - title` followed by its full text. A blocking finding's title ends with `(blocks merge)`; a non-blocking finding has no tag. A finding with an agent prompt shows it under `Agent prompt:`, ready to paste into a coding agent in this checkout. Then `✅ Ruled out (N)` lists what the review tried to break and why it held. JSON mode returns `{status, requestId, sessionId, verdict, summary, findings, alsoChecked}`, where each finding is `{file, line, blocksMerge, title, body}`, plus `agentPrompt` when it has one; each Ruled out item is `{title, conclusion}`. `alsoChecked` is left out when empty. `environmentDegradedReason` is added when the review ran without a prepared environment.
 
 Exit codes: `0` when no finding blocks merge, `1` when a finding blocks merge or the review could not start, `4` when another review of yours is still running, `5` when the review is still running (`--no-wait`), `10` when the review failed, `130` when interrupted (Ctrl-C or SIGTERM).
 
@@ -367,3 +402,27 @@ For cron, prefer `ARCANIST_TOKEN` or a logged-in `~/.arcanist/config.json` over
 - **401 on a previously working token**: the token may have expired or been revoked in Settings. Regenerate and log in again.
 - **`You do not have access to this repository on GitHub`**: the token's user lacks repo access; fix the GitHub connection or use an accessible repo.
 - **`command not found`**: run `npm install -g @tryarcanist/cli`.
+
+### Read existing review diagnostics
+
+```bash
+arcanist reviews get <pr-request-id> --json
+arcanist reviews stages <session-id> --json
+arcanist reviews stages <session-id> judge --json
+arcanist sessions view <session-id> --json
+```
+
+These commands read existing data. They start no review or model run and do not poll.
+Successful reads exit 0, including active reviews and results with blocking findings.
+API errors retain the normal exit codes. Quiet text mode suppresses output. JSON mode preserves the complete response.
+
+`reviews get` accepts a **PR request ID** and returns `{review, requestStatus}`.
+The lifecycle snapshot preserves `unavailableRequestIds` and retry/recovery state.
+For a **local request ID**, use `arcanist review --request <id> --no-wait --json` with its existing review exit codes.
+
+Stage reads require Arcanist membership. The index lists stage names, byte sizes, and upload timestamps.
+A selected record includes full structured `input`, `output`, and `threads`. The CLI fetches no other records.
+
+`sessions view` returns the enriched session envelope for the token workspace.
+Its prompts contain the first page only (`promptLimit=1`). Use `sessions transcript` for full activity and `sessions artifacts` for files.
+`sessions get` keeps its raw session response.