CLI reference

Terminal reference for the authright binary from @authright/cli. Product slash commands live on the Commands page.

Install: Installation. Chat orientation: How commands work.

Global option: --path <dir> selects the project root. Optional --invoke cursor|claude|codex|cli records which host launched the CLI (agent wrappers pass this; humans can omit it).

Three tiers (same binary)

Tier	What you use
Public	Product closed loop + `init` / `update` (table below)
Agent-facing	Same public verbs with `--invoke <host>` and `--json` (skills / `.authright/AGENTS.md`)
Internal	Advanced commands under `authright internal …` (omitted from this public reference cookbook; see product repo `docs/internal/`)

Maintainer notes for omitted advanced CLI live in the product git repo under docs/internal/ (not published on this site).

Thin closed loop

init → scan → pick explore or change
  → on that Auth Change record: --analyze
     (explore: Agenda HITL | change: --plan → --set → --confirm-plan)
  → --ready → request-match → to-openspec | to-plan → review
doctor

/auth:explore and /auth:change are two commands — pick one. doctor checks the app source for identity/security risks whenever you want—including before that choice. It is not a step between scan and the fork. authright change <id> flags are follow-up on the Auth Change record either command created.

Inspect anytime: authright change (list) or authright change <id> (optional --json). Public business commands also accept --json so agents get one snake_case object (ok, command, summary, optional artifact.path / next). Explore intake JSON includes phase (slice while no Brief slice is accepted_for_lock — no change_id yet; decide after an id is allocated or resumed). Missing Brief fails closed (ok false). Change auto-plan uses the same Brief/slice gate. Intake may include context_refresh when an auto-scan ran.

Design intents ↔ terminal

Product intent	In chat (after `init`)	In terminal
`/auth:scan`	Cursor `/auth-scan` · Claude `/auth:scan` · Codex `$authright-scan`	`authright scan`
`/auth:explore`	Cursor `/auth-explore` · Claude `/auth:explore` · Codex `$authright-explore`	`authright explore …` (HITL intake). Pick this or `/auth:change`
`/auth:change`	Cursor `/auth-change` · Claude `/auth:change` · Codex `$authright-change`	`authright change -- <intent>` for auto-plan intake. `change <id>` flags are the Auth Change record, including after explore
`/auth:request-match`	Cursor `/auth-request-match` · Claude `/auth:request-match` · Codex `$authright-request-match`	`authright request-match <id>`
`/auth:to-openspec` (OpenSpec handoff — pick one)	Cursor `/auth-to-openspec` · Claude `/auth:to-openspec` · Codex `$authright-to-openspec`	`authright to-openspec <id>` (requires OpenSpec CLI)
`/auth:to-plan` (Plan-mode handoff — pick one)	Cursor `/auth-to-plan` · Claude `/auth:to-plan` · Codex `$authright-to-plan`	`authright to-plan <id>`
`/auth:review`	Cursor `/auth-review` · Claude `/auth:review` · Codex `$authright-review`	`authright review <id>`
`/auth:doctor`	Cursor `/auth-doctor` · Claude `/auth:doctor` · Codex `$authright-doctor`	`authright doctor`

Terminal commands

Command	Purpose
`authright init [path] [--tools all\|none\|cursor\|claude\|codex]`	Create `.authright/` + agent delivery (omit `--tools` to pick interactively, or to detect hosts in scripts)
`authright update`	Regenerate managed skills/commands
`authright scan [--json]`	Heuristic IAM + Repository Context discovery → `context.yaml`
`authright explore -- <intent> [--json]`	HITL Decide intake: Brief slice first (no `AUTH-` id while `phase: slice`); then create/resume DRAFT. Scans when context is missing or stale
`authright change [--json]`	List Auth Changes
`authright change -- <intent> [--json]`	Auto-plan Decide intake: same Brief/slice gate; allocate/resume DRAFT; analyze + write `auto-plan.yaml`. Scans when context is missing or stale
`authright change <id> [--json]`	Status for one change
`authright change <id> --analyze [--json]`	Fill `analysis.md` → `ANALYZED`. If `auto-plan.yaml` already exists (change path), also re-apply recommended and refresh the plan; explore-style changes are analyze-only
`authright change <id> --plan [--json]`	Rewrite existing `auto-plan.yaml` from current decisions + pending chooses (refuses when no plan file — explore path). Human output and `auto_plan.table` use columns Decision, Current choice, Why, Other options. `--set` still assigns `<slot>=<option_id>`
`authright change <id> --set <slot>=<option_id>`	Apply user assignment(s) (repeatable); recompute plan; reset confirmation to pending
`authright change <id> --confirm-plan [--json]`	Confirm plan when unresolved is empty (`confirmation.status` → `confirmed`)
`authright change <id> --ready [--json] [--force-design]`	Lock `DECIDED` when Decision Package is export-ready (auto-plan: requires confirmed plan with zero unresolved)
`authright request-match <id> [--json]`	After the plan is locked, check that it still matches what you asked. Export waits until this check passes
`authright to-openspec <id> [--phase prepare\|check\|finalize] [--slug] [--force] [--force-tasks] [--json]`	Propose-first OpenSpec handoff: feed/claims → coverage → finalize (requires OpenSpec CLI; hard-fails to `to-plan` otherwise). Omit `--phase` = prepare (host propose required; no silent full-package write)
`authright to-plan <id> [--force] [--force-tasks] [--json]`	Export or refresh Agent Plan-mode package under `.authright/changes/<dir>/agent-plan/`
`authright review <id> [--json] [--no-source]`	Mechanical verify from EXPORTED
`authright doctor [--json]`	Quick machine scan notes under `.authright/findings/`. In chat, `/auth:doctor` writes the human report at `.authright/diagnosis/report.md`
`authright mcp`	Optional MCP handoff adapter (stdio) — advanced; not a product Decide intent

Advanced Internal commands (authright internal …) are omitted from this public cookbook; see the product repo docs/internal/.

Also: authright --version, authright --help.

Exit codes: 0 ok, 1 validation/lifecycle, 2 unexpected.

Notes

Record decisions by editing decisions.yaml (explore HITL) or via auto-plan --set (change), then change <id> --ready
change <id> extra words is rejected (avoids accidental create); use change -- <intent> for intake
explore -- <intent> waits for an accepted Brief slice before allocating an id; cancelled-empty slice-accept does not allocate
change -- <intent> uses the same Brief/slice gate on the auto-plan path
doctor nested-scans when context was never scanned, then diagnoses
Targeted context refresh (on Decide intake) merges into existing signals; it does not wipe a prior full scan
--ready rejects TBD verification placeholders; on auto-plan it also fails while unresolved or confirmation not confirmed — see Editing changes
Happy path on change: confirm-plan → ready → request-match → export
to-openspec / to-plan accept DECIDED (first export → EXPORTED) or EXPORTED (refresh in place)
to-openspec needs the OpenSpec tool; without it the command stops and points to to-plan. Skill path: --phase prepare (feed/claims) → OpenSpec propose → --phase check → --phase finalize. AuthRight does not author full package bytes on the phased path
Same-change refresh updates design/specs/proposal (or agent-plan constraints/requirements); refined non-stub tasks.md is kept unless --force-tasks
Handoff exports from AuthRight Design plus Decision Locks. Stale Design: change <id> --ready then retry
--force overwrites a foreign/unknown export directory and writes a fresh projected tasks.md
--force-tasks regenerates tasks.md from current locks on a same-change refresh
--json includes tasks_disposition (written | preserved | stub_upgraded | force_regenerated) and which handoff was used (peer)
init omits --tools to pick Cursor / Codex / Claude Code interactively. Outside a terminal it installs hosts it detects. Scripts that want CLI-only MUST pass --tools none. --tools all installs every supported host
init --force overwrites context and the empty constitution stub only after confirm (or AUTHRIGHT_FORCE=1 non-interactive). The stub is not project law
AuthRight Harness does not install or invoke OpenSpec for you — OpenSpec · Agent Plan-mode
Optional logging: in config.yaml sets level, JSON stderr, rotation and run retention. Optional scan.fresh_ttl_ms (default 600000) is the Decide/doctor intake freshness window
Agent skills/commands pass --invoke <host> so the process records Cursor vs Claude Code vs Codex. Direct terminal use needs neither flag

Three tiers (same binary)

Thin closed loop

Design intents ↔ terminal

Terminal commands

Notes

On this page