@tryarcanist/cli 0.1.381 → 0.1.383

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
 
@@ -186,6 +200,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
@@ -197,6 +213,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
@@ -206,6 +224,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
@@ -216,6 +236,62 @@ 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`
+
+Removes the saved Codex subscription `auth.json`. OpenAI sessions fall back to the platform key.
+
+```bash
+arcanist codex logout
+```
+
+### `arcanist settings …`
+
+Reads and changes every customer-facing setting the web app exposes. A read-scope token reads; a write-scope token changes.
+Workspace-wide changes (team defaults, exclusions, members, invite, secrets, integrations) also need the admin role.
+`approvals show` and `approvals set` both need a write-scope token and the admin role. `repo-reviews set`,
+`review-instructions set`, and `learned-doc clear` need write permission on the repository on GitHub.
+Every subcommand supports `--json`, which prints the API payload. Secret values are never printed.
+
+```bash
+arcanist settings show                                   # your review display preferences
+arcanist settings set --inline-nits on
+arcanist settings team-reviews show
+arcanist settings team-reviews set --auto-review on --drafts off
+arcanist settings repo-reviews list
+arcanist settings repo-reviews set acme/widgets --check blocking
+arcanist settings my-reviews set acme/widgets --auto-review inherit
+arcanist settings branch-exclusions add acme/widgets 'release/*'
+arcanist settings bot-exclusions add dependabot[bot]
+arcanist settings approvals show acme/widgets
+arcanist settings approvals set --policy-file policy.json
+arcanist settings review-instructions set acme/widgets --file REVIEW.md
+arcanist settings learned-doc clear acme/widgets
+arcanist settings members set-role 42 admin
+arcanist settings invite rotate
+arcanist settings secrets set acme/widgets NPM_TOKEN --value-file token.txt --sensitive on
+arcanist settings secrets import acme/widgets --file secrets.env
+arcanist settings integrations list
+arcanist settings setup answer acme/widgets <question-id> "use pnpm"
+```
+
+Run `arcanist settings <group> --help` for the flags of each group.
+
+### `arcanist resource-pools …` and `arcanist environments resources …`
+
+Manages shared resource pools (pooled credentials that sandboxes lease) and which environments draw from them.
+
+```bash
+arcanist resource-pools create accounts
+arcanist resource-pools list
+arcanist resource-pools slots add accounts --name primary --credentials-file creds.env
+arcanist resource-pools slots set accounts <slot-id> --name primary --credentials-file creds.env
+arcanist resource-pools slots rm accounts <slot-id>
+arcanist resource-pools rm accounts
+arcanist environments resources list <environment-id>
+arcanist environments resources attach <environment-id> --name db --pool accounts
+arcanist environments resources detach <environment-id> --name db
+```
+
 ### `arcanist sessions get <session-id>`
 
 ```bash
@@ -308,6 +384,42 @@ arcanist repos list --json
 
 JSON mode returns `{repos, ssoOrgs}`.
 
+### `arcanist review [pr-url]`
+
+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 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
+```
+
+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.
+
+What is left out:
+
+- 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.
+
+The upload limit is 3 MB. Each delivered review counts toward your plan's review usage; a review that fails does not.
+
+- `--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`).
+
+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. A finding with an agent prompt shows it under `Agent prompt:`, ready to paste into a coding agent in this checkout. Then `Code quality (N)` lists maintainability notes (never blocking), `Nitpicks (N)` lists nitpicks, and `✅ Ruled out (N)` lists what the review tried to break and why it held. JSON mode returns `{status, requestId, sessionId, verdict, summary, findings, codeQuality, alsoChecked}`, where each finding is `{file, line, blocksMerge, title, body}`, plus `nit: true` on a nitpick and `agentPrompt` when it has one; each code quality note is `{file, line, title, detail}` and each Ruled out item is `{title, conclusion}`. `codeQuality` and `alsoChecked` are 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).
+
 ## Automation recipes
 
 Chain commands with `--json` and `jq`: