@tryarcanist/cli 0.1.380 → 0.1.382

package/README.md

@@ -1,6 +1,6 @@
 # Arcanist CLI
 
-Command-line interface for [Arcanist](https://www.tryarcanist.com): follow session output and manage access tokens from your terminal or automation.
+Command-line interface for [Arcanist](https://www.tryarcanist.com): follow session output and manage environments from your terminal or automation.
 
 ## Install
 
@@ -13,34 +13,27 @@ Requires Node.js 22 or newer.
 ## Quick start
 
 ```bash
-arcanist auth login                 # approve login in your browser
+printf "arc_..." | arcanist auth login --token-stdin
 arcanist sessions list --json
 ```
 
 ```bash
-export ARCANIST_TOKEN=arc_...       # write-scoped for prepare, review, and stop
+export ARCANIST_TOKEN=arc_...       # write-scoped for prepare, review, and sandbox build
 SESSION_ID=$(arcanist sessions list --json | jq -r '.sessions[0].id')
 arcanist sessions events "$SESSION_ID" --follow --json
 ```
 
 ## Authentication
 
-Start browser authorization from the CLI:
+Mint a token in **Settings > CLI**, then pipe it to the CLI:
 
 ```bash
-arcanist auth login
-# approve the request in the browser
+printf "arc_..." | arcanist auth login --token-stdin
 ```
 
-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 to prepare or retry environments, trigger a Zeus review, stop a session, or manage tokens.
+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.
 
-You can also pipe the token via stdin:
-
-```bash
-printf "arc_..." | arcanist auth login --token-stdin
-```
+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.
 
 Auth and API URL precedence:
 
@@ -115,20 +108,20 @@ Exit codes:
 130 interrupted
 ```
 
-`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.
+`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.
 
 ## Commands
 
 ### `arcanist environments prepare`
 
-Prepare the current repository for Zeus. Pass `owner/repo` outside a checkout. A write-scoped token is required.
+Prepare the current repository for Arcanist. 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.
+Agents should follow `repository.nextAction` and `repository.command`. Request an Arcanist 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`
 
@@ -139,7 +132,7 @@ arcanist environments status owner/repo --json
 arcanist environments status 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.
+Agents should follow `repository.nextAction` and `repository.command`. Request an Arcanist 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`
 
@@ -152,7 +145,7 @@ arcanist environments retry owner/repo --wait --poll-interval 5000 --json
 
 ### `arcanist environments login`
 
-Log into your app once in a throwaway local browser and save that login on the environment so Zeus 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.
+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.
 
 ```bash
 arcanist environments login owner/repo
@@ -172,28 +165,15 @@ What gets captured is the Playwright storage state for that window: cookies and
 
 The capture needs an interactive terminal: stdin and stderr must be a TTY. Instructions and prompts go to stderr, so `--json --yes --validate-path /dashboard > result.json` works. JSON output is `{environmentId, version, counts: {cookieDomainCount, storageOriginCount}, providerHosts, networkPolicy: {added, rejected, skipped}, validatePath}`, or `{environmentId, deleted}` with `--clear`. `arcanist environments status --json` reports the saved login under `browserState`, including whether a re-login is needed.
 
-### `arcanist setup`
-
-Connect Arcanist and prepare one or more repository environments. The command starts browser authentication when needed, lists only repositories where GitHub reports write access, and queues at most 20 builds.
-
-```bash
-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. `--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`
 
 ```bash
-arcanist auth login
 printf "arc_..." | arcanist auth login --token-stdin
+arcanist auth login --token arc_...
 arcanist auth login --api-url https://api.tryarcanist.com
 ```
 
-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.
+Pass a token via `--token-stdin`, `--token`, or `ARCANIST_TOKEN`; the CLI verifies it against `/api/auth/whoami` and persists it for later use.
 
 ### `arcanist auth whoami`
 
@@ -206,6 +186,8 @@ JSON mode prints the raw `/api/auth/whoami` API response. Fields currently inclu
 
 ### `arcanist codex login`
 
+Local development only; deployed workspaces return 403.
+
 Authenticates a Codex/ChatGPT subscription and stores it for your Codex sessions, then activates it (turns on "use subscription auth for OpenAI sessions"). Runs the Codex CLI device-authorization login locally under a temporary `CODEX_HOME`, then uploads the resulting `auth.json` to Arcanist (encrypted, per user). The credential is never written to your default `~/.codex`. Requires a write-scoped token. If activation fails the credential is still saved; run `arcanist codex use on`.
 
 ```bash
@@ -217,6 +199,8 @@ arcanist codex login --codex-path /usr/local/bin/codex
 
 ### `arcanist codex use <on|off>`
 
+`on` works in local development only; deployed workspaces return 403. `off` works everywhere.
+
 Turns using your saved Codex subscription auth for OpenAI sessions on or off, without changing the stored credential. `arcanist codex login` turns it on automatically; use this to toggle it later.
 
 ```bash
@@ -226,6 +210,8 @@ arcanist codex use off
 
 ### `arcanist codex status`
 
+Deployed workspaces report subscription auth as unavailable; it works in local development only.
+
 Shows that Codex subscription auth is available and whether an `auth.json` is currently saved.
 
 ```bash
@@ -236,25 +222,6 @@ arcanist codex status --json
 JSON mode returns `{eligible, credential: {isSet, lastValidationStatus?, lastValidationReasonCode?}}`; `eligible` is always
 `true` and remains for compatibility with older clients.
 
-### `arcanist codex logout`
-
-Deactivates the selector and removes the stored Codex subscription auth for your user (write-scoped token).
-
-```bash
-arcanist codex logout
-```
-
-### `arcanist sessions stop <session-id>`
-
-Stops the active run for a session. Idempotent: if no sandbox is active, the server returns `already_stopped`.
-
-```bash
-arcanist sessions stop abc123
-arcanist sessions stop abc123 --json
-```
-
-JSON mode returns `{sessionId, status}`. `status` is the server stop status or, on a 409 stop-block, the block reason; it is an open set. Known values include `stopping`, `stopped`, `already_stopped`, `not_stoppable`, and lifecycle phase names.
-
 ### `arcanist sessions get <session-id>`
 
 ```bash
@@ -291,7 +258,6 @@ arcanist sessions events abc123 --follow --json
 arcanist sessions events abc123 --follow --timeout 60000 --json
 ```
 
-`--after` and `--before` are aliases for `--after-sequence` and `--before-sequence`.
 `--timeout` bounds `--follow`; omit it or pass `0` for unbounded follow. Process exit is a terminal phase, not `session_idle`.
 
 JSON mode without `--follow` returns one JSON object from `/events/history`: `{events: [...], ...}`. Canonical events carry `phase`.
@@ -314,13 +280,6 @@ arcanist sessions transcript abc123 --last 20
 
 `--last <n>` renders only the last `n` stored transcript events after fetching the session export.
 
-### `arcanist sessions usage <session-id>`
-
-```bash
-arcanist sessions usage abc123
-arcanist sessions usage abc123 --json
-```
-
 ### `arcanist sessions artifacts <session-id>`
 
 Lists the artifacts a session produced (screenshots, videos) as `artifactId`, `kind`, `label`, `filename`, `bytes`, `createdAt`.
@@ -355,58 +314,41 @@ arcanist repos list --json
 
 JSON mode returns `{repos, ssoOrgs}`.
 
-### `arcanist repos branches [repo]`
-
-```bash
-arcanist repos branches tryarcanist/arcanist
-arcanist repos branches https://github.com/tryarcanist/arcanist --json
-```
-
-JSON mode returns `{branches}`.
+### `arcanist review [pr-url]`
 
-### `arcanist models list`
+Review your local commits before you open a pull request. Run it inside a checkout of a repository that Arcanist is installed on. A write-scoped token and a paid Arcanist plan or a pilot are required.
 
 ```bash
-arcanist models list
-arcanist models list --json
+arcanist review
+arcanist review --base origin/release --json
+arcanist review --include config/.env.test
+arcanist review --request <id>
+arcanist review --no-wait --json
+arcanist review --request <id> --no-wait --json
 ```
 
-JSON mode returns `{models}`.
+What is uploaded: the committed changes on your branch that are not on the default branch of `origin`, plus their commit messages. Nothing is posted to GitHub.
 
-### `arcanist tokens list`
+What is left out:
 
-```bash
-arcanist tokens list
-arcanist tokens list --limit 10 --json
-arcanist tokens list --cursor <cursor> --json
-arcanist tokens list --all --json
-```
+- Uncommitted changes are not reviewed. Commit them first.
+- Secret-looking files (dotenv files, keys, certificates) and git-ignored files are held back unless you name them with `--include`.
+- Binary files are skipped.
 
-`--all` follows cursors until completion and returns `nextCursor: null` in JSON mode.
+The upload limit is 3 MB. Each delivered review counts toward your plan's review usage; a review that fails does not.
 
-### `arcanist tokens create`
+- `--base <ref>` compares against this ref instead of the default branch.
+- `--include <path>` uploads a held-back file or folder. Repeat it for more.
+- `--request <id>` gets the result of a review that is already running or finished. Use it when the command was interrupted; the request id is always printed to stderr when the review starts, also with `--json` and `--quiet`.
+- `--no-wait` starts a review, or checks one with `--request <id>`, and returns at once. It exits `5` while the review is still running.
+- `--poll-interval <ms>` sets how often the CLI checks for the result (default `10000`).
+- `--wait` applies only to a PR URL; a local review waits by default, up to 30 minutes, and prints `Still reviewing (Nm)` with the `--request` command every minute (stderr, not with `--json` or `--quiet`).
 
-Creates a CLI token and prints the plaintext token exactly once.
+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)`.
 
-```bash
-arcanist tokens create --scope read
-arcanist tokens create --scope read --expires-in-days 30 --json
-arcanist tokens create --scope read --idempotency-key 1f0e6f1a-...
-```
-
-JSON mode returns `{ok, token, id, scope}`.
-The plaintext token is shown only once.
-Use `--idempotency-key <uuid>` when manually retrying a token create whose first response may have been lost; duplicate keys return `duplicate_request` rather than replaying the raw token.
-Read-scoped tokens cannot create write-scoped tokens; the server enforces that and returns 403.
-
-### `arcanist tokens revoke <id>`
-
-```bash
-arcanist tokens revoke 42
-arcanist tokens revoke 42 --yes --json
-```
+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.
 
-Under `--json`, `--yes` is required.
+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).
 
 ## Automation recipes