@tryarcanist/cli 0.1.382 → 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
 
@@ -222,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
@@ -346,7 +416,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 `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).