@tryarcanist/cli 0.1.383 → 0.1.385

package/README.md

@@ -13,7 +13,8 @@ Requires Node.js 22 or newer.
 ## Quick start
 
 ```bash
-printf "arc_..." | arcanist auth login --token-stdin
+arcanist auth login                                    # opens the browser; approve once
+printf "arc_..." | arcanist auth login --token-stdin   # automation: a token from Settings > CLI
 arcanist sessions list --json
 ```
 
@@ -25,7 +26,9 @@ arcanist sessions events "$SESSION_ID" --follow --json
 
 ## Authentication
 
-Mint a token in **Settings > CLI**, then pipe it to the CLI:
+In a terminal, `arcanist auth login` opens the Arcanist app in your browser. Approve once and the CLI saves a new token. Pass `--scope write` for a write-scoped token (default `read`).
+
+For automation, mint a token in **Settings > CLI** and pipe it to the CLI:
 
 ```bash
 printf "arc_..." | arcanist auth login --token-stdin
@@ -122,7 +125,7 @@ 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 that need a person at a terminal (`auth login` without a token, `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
 
@@ -157,6 +160,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.
@@ -198,6 +222,14 @@ ARCANIST_TOKEN=arc_... arcanist auth whoami --json
 
 JSON mode prints the raw `/api/auth/whoami` API response. Fields currently include `userId`, `email`, `tokenId`, `tokenScope`, and `authMode`.
 
+### `arcanist auth browser-session`
+
+QA only. Trades a write-scope CLI token for a 24-hour browser session for the same user and prints it as a Playwright storage state (`{"cookies":[...],"origins":[]}`) on stdout. Only GitHub logins listed in the QA worker's `QA_BROWSER_SESSION_LOGINS` may do this; production returns 404. The output holds a live session token, so write it to a private file.
+
+```bash
+ARCANIST_API_URL=https://qa.tryarcanist.com arcanist auth browser-session > storage-state.json
+```
+
 ### `arcanist codex login`
 
 Local development only; deployed workspaces return 403.
@@ -236,62 +268,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`
-
-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
@@ -416,7 +392,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. 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.
+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 only for repositories an operator runs without their 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).
 
@@ -437,3 +413,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.