@tryarcanist/cli 0.1.381 → 0.1.382

package/README.md

@@ -186,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
@@ -197,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
@@ -206,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
@@ -308,6 +314,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. 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.
+
+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`: