@tryarcanist/cli 0.1.98 → 0.1.100

package/README.md

@@ -0,0 +1,295 @@
+# Arcanist CLI
+
+Command-line interface for [Arcanist](https://www.tryarcanist.com): create coding agent sessions, follow their output, and manage access tokens from your terminal or automation.
+
+## Install
+
+```bash
+npm install -g @tryarcanist/cli
+```
+
+Requires Node.js 22 or newer.
+
+## Quick start
+
+```bash
+arcanist auth login                 # paste a token from Settings > CLI Tokens
+arcanist sessions create https://github.com/your-org/your-repo "fix the login bug"
+```
+
+```bash
+export ARCANIST_TOKEN=arc_...       # write-scoped for create/send/stop
+SESSION_ID=$(arcanist sessions create your-org/your-repo "add tests for the auth module" --json | jq -r .sessionId)
+arcanist sessions events "$SESSION_ID" --follow --json
+```
+
+## Authentication
+
+Generate a CLI token in the Arcanist UI at **Settings > CLI Tokens**, then:
+
+```bash
+arcanist auth login
+# paste your arc_... token when prompted; input is masked
+```
+
+Token config is stored at `~/.arcanist/config.json`. 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 only to create sessions, send prompts, or stop runs.
+
+You can also pipe the token via stdin:
+
+```bash
+printf "arc_..." | arcanist auth login --token-stdin
+```
+
+Auth and API URL precedence:
+
+```text
+flag > environment > ~/.arcanist/config.json
+```
+
+Supported environment variables:
+
+```bash
+export ARCANIST_TOKEN=arc_...
+export ARCANIST_API_URL=https://app.tryarcanist.com
+```
+
+`--token` and `--api-url` are available for one-off invocations. Prefer `ARCANIST_TOKEN` over `--token` for persistent use; CLI flags can appear in shell history and process lists.
+
+Non-local API URLs must use HTTPS and must not embed credentials.
+
+## Global flags
+
+```bash
+arcanist --json
+arcanist --quiet
+arcanist --api-url https://app.tryarcanist.com
+arcanist --token arc_...
+arcanist --no-color
+```
+
+## JSON output, errors, and exit codes
+
+With `--json`, successful command output is machine-readable and newline-terminated. Errors are written to stderr as:
+
+```json
+{
+  "error": { "code": "auth", "message": "Not logged in.", "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`." }
+}
+```
+
+Exit codes:
+
+```text
+0   ok
+1   user/input error
+2   auth error (401/403)
+3   not found (404)
+4   conflict (409)
+10  server or network error
+130 interrupted
+```
+
+Mutation commands send an `Idempotency-Key` header. The CLI does not auto-retry mutation endpoints; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. `--idempotency-key` is available on `sessions create` and `sessions send`.
+
+## Commands
+
+### `arcanist auth login`
+
+```bash
+arcanist auth login
+printf "arc_..." | arcanist auth login --token-stdin
+arcanist auth login --api-url https://app.tryarcanist.com
+```
+
+### `arcanist auth whoami`
+
+```bash
+arcanist auth whoami
+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 sessions create <repo-url> [prompt]`
+
+Creates a new session and sends the initial prompt.
+
+```bash
+arcanist sessions create https://github.com/your-org/your-repo "fix the login bug"
+printf "add tests" | arcanist sessions create your-org/your-repo --prompt-stdin --json
+printf "add tests" | arcanist sessions create your-org/your-repo --prompt-stdin --wait
+arcanist sessions create your-org/your-repo - --model gpt-5.5
+arcanist sessions create your-org/your-repo "port to claude" --backend claude_code --model claude-opus-4-8
+arcanist sessions create your-org/your-repo "refactor auth" --reasoning-effort xhigh
+arcanist sessions create your-org/your-repo "review the trace" --uploaded-file trace.txt
+arcanist sessions create your-org/your-repo "verify the deployed change" --cold
+arcanist sessions create your-org/your-repo "retry-safe create" --idempotency-key 1f0e6f1a-...
+```
+
+`--backend` picks the agent runtime backend: `codex` (default) or `claude_code`. `--model` must be valid for the chosen backend — codex runs OpenAI models (`gpt-5.5` default, `gpt-5.4`), `claude_code` runs Anthropic models (`claude-opus-4-8` default, `claude-sonnet-4-6`) — and the CLI rejects a mismatch before any network call. `claude_code` sessions require an Anthropic API key configured in Settings.
+
+`--wait` blocks until the created prompt finishes and exits non-zero if the prompt finishes with `status: failed`, making it suitable for cron or other schedulers that alert on command failure. `--poll-interval <ms>` tunes the completion check frequency.
+
+Repeatable `--uploaded-file <path>` flags attach local UTF-8 text files to the prompt. Uploaded file names come from the local basename; directory components are not sent.
+
+`--cold` forces a fresh sandbox and skips the warm pool — useful for verifying freshly deployed code when a pre-warmed sandbox may predate the deploy.
+
+`--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server. The CLI derives separate session and prompt idempotency keys from the provided value.
+
+JSON mode returns `{sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, promptId?}`. `sessionUrl` is emitted only when the server returns it; `agentRuntimeBackend` only when `--backend` is passed.
+
+### `arcanist sessions send <session-id> [prompt]`
+
+Sends a follow-up message to an existing session.
+
+```bash
+arcanist sessions send abc123 "also update the tests"
+arcanist sessions send abc123 "use this failure log" --uploaded-file failure.log
+printf "summarize current status" | arcanist sessions send abc123 --prompt-stdin --json
+arcanist sessions send abc123 "retry-safe send" --idempotency-key 1f0e6f1a-...
+```
+
+JSON mode returns `{sessionId, promptId?}`.
+
+### `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}` where status is `stopping` or `already_stopped`.
+
+### `arcanist sessions get <session-id>`
+
+```bash
+arcanist sessions get abc123
+arcanist sessions get abc123 --json
+```
+
+### `arcanist sessions list`
+
+```bash
+arcanist sessions list
+arcanist sessions list --status idle --limit 20 --json
+arcanist sessions list --search "architect agent" --repo your-org/your-repo
+arcanist sessions list --scope business --cursor <cursor>
+```
+
+JSON mode returns `{sessions, nextCursor}`. Search is metadata-only: generated titles and repo metadata.
+
+### `arcanist sessions search <query>`
+
+```bash
+arcanist sessions search "architect agent"
+arcanist sessions search "mcp debugging" --repo your-org/your-repo --json
+arcanist sessions search "repo access" --status idle --scope business --limit 20 --cursor <cursor>
+```
+
+Uses the same metadata-only index and filters as `sessions list`: `--status`, `--scope`, `--repo`, `--limit`, and `--cursor`.
+
+### `arcanist sessions events <session-id>`
+
+Reads canonical session replay events. Cursors are sequence-based.
+
+```bash
+arcanist sessions events abc123 --json
+arcanist sessions events abc123 --after-sequence 50 --limit 250 --json
+arcanist sessions events abc123 --before-sequence 100 --poll-interval 500 --json
+arcanist sessions events abc123 --prompt-id p-123 --json
+arcanist sessions events abc123 --follow --json
+```
+
+`--after` and `--before` are aliases for `--after-sequence` and `--before-sequence`.
+
+Follow mode emits NDJSON, one replay event per line, until the session becomes idle.
+
+### `arcanist sessions transcript <session-id>`
+
+Renders a session transcript from the stored session export.
+
+```bash
+arcanist sessions transcript abc123
+arcanist sessions transcript abc123 --json
+```
+
+### `arcanist sessions watch <session-id>`
+
+Watches session activity until the session becomes idle. For machine-readable streaming, prefer `arcanist sessions events --follow --json`.
+
+```bash
+arcanist sessions watch abc123
+arcanist sessions watch abc123 --poll-interval 500
+```
+
+### `arcanist sessions usage <session-id>`
+
+```bash
+arcanist sessions usage abc123
+arcanist sessions usage abc123 --json
+```
+
+### `arcanist tokens list`
+
+```bash
+arcanist tokens list
+arcanist tokens list --limit 10 --json
+arcanist tokens list --cursor <cursor> --json
+```
+
+### `arcanist tokens create`
+
+Creates a CLI token and prints the plaintext token exactly once.
+
+```bash
+arcanist tokens create --scope read
+arcanist tokens create --scope read --expires-in-days 30 --json
+```
+
+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
+```
+
+Under `--json`, `--yes` is required.
+
+## Automation recipes
+
+Run a prompt on a schedule and alert only when the prompt itself fails — `sessions create --wait` makes the exit code reflect the prompt outcome:
+
+```cron
+*/15 * * * * printf 'summarize new error-tracker regressions' | \
+  ARCANIST_TOKEN=arc_... \
+  arcanist sessions create your-org/your-repo --prompt-stdin --wait \
+  || notify-send "Arcanist scheduled run failed"
+```
+
+Chain commands with `--json` and `jq`:
+
+```bash
+SESSION_ID=$(arcanist sessions create your-org/your-repo "audit dependency licenses" --json | jq -r .sessionId)
+arcanist sessions events "$SESSION_ID" --follow --json | jq -r 'select(.type == "assistant_message")'
+```
+
+Verify a freshly deployed change with a guaranteed-fresh sandbox:
+
+```bash
+arcanist sessions create your-org/your-repo "verify the new rate limiter is active" --cold --wait
+```
+
+For cron, prefer `ARCANIST_TOKEN` or a logged-in `~/.arcanist/config.json` over passing `--token` on the command line.
+
+## Troubleshooting
+
+- **401 on login verification**: token may be invalid or expired. Regenerate in **Settings > CLI Tokens**.
+- **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`.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.98",
+  "version": "0.1.100",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {
     "arcanist": "dist/index.js"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "files": [
     "dist"
   ],