Getting started

This guide assumes the CLI is already installed and on your PATH. For install steps, see Installation.

Where do I type these commands?

• authright ... runs in your terminal.
• Cursor chat: /auth-scan, /auth-explore, /auth-change, … (from .cursor/commands/auth-*.md).
• Claude Code chat: /auth:scan, /auth:explore, /auth:change, … (from .claude/commands/auth/<id>.md).
• $authright-scan, … run in Codex (skills).

Full explanation: How commands work.

Your first loop

TERMINAL   $ npm install -g @authright/cli@latest
TERMINAL   $ cd your-project && authright init
TERMINAL   $ authright scan
AI CHAT      pick /auth-explore (HITL) or /auth-change (auto-plan)
TERMINAL   $ authright change AUTH-YYYY-NNNN --analyze   # Auth Change record, either command
AI CHAT      explore: answer Agenda next via native HITL (recommended ≠ selected)
             change: review auto-plan → --set → --confirm-plan
TERMINAL   $ authright change AUTH-YYYY-NNNN --ready
AI CHAT      /auth:request-match AUTH-YYYY-NNNN
AI CHAT      pick /auth:to-openspec AUTH-YYYY-NNNN
             # or: switch to Plan mode, then /auth:to-plan AUTH-YYYY-NNNN
AI CHAT      /auth:review AUTH-YYYY-NNNN

Greenfield and brownfield may use /auth:explore or /auth:change — pick one Decide command. After request-match, pick one handoff command: /auth:to-openspec or /auth:to-plan. Both Decide paths start from an IAM Brief (.authright/brief/brief.yaml) and an accepted slice. Explore walks remaining slice slots with native HITL (recommended ≠ selected); after a slice is accepted, Decide continues in the same session. Change presents a full auto-plan instead. An unaccepted unbounded slice does not start Decide. If context is missing or stale, intake scans first; you can still run /auth:scan yourself. Later change <id> flags are follow-up on the Auth Change record either Decide command created. To check what’s risky in the current code, use /auth:doctor / /auth-doctor (report at .authright/diagnosis/report.md)—including before you pick a Decide command.

Initialize a project

cd your-project
authright init

Omit --tools to pick Cursor, Codex, or Claude Code interactively (detected hosts are pre-selected on first run). Pass --tools cursor (or claude / codex) when you already know. Scripts that want CLI-only must pass --tools none. Full forms: Installation.

Init writes Cursor/Claude command files + skills, and Codex skills only.

Scan understands IAM in Java and Node.js / TypeScript repos best today. Python and Go are supported and being strengthened; more languages and stacks will follow. Concepts.

Understand, decide, request match, export

HITL (explore):

authright scan
authright explore -- "Integrate OIDC via adapter"
authright change AUTH-YYYY-NNNN --analyze

Present Agenda chooses in chat; do not treat recommended or rank-1 as already selected. Map answers into decisions.yaml and engineering_strategy, fill contract.md, then ready → request-match → export.

Auto-plan (change):

authright change -- "Integrate OIDC via adapter"
authright change AUTH-YYYY-NNNN --plan
authright change AUTH-YYYY-NNNN --set identity_role=arch.service-provider
authright change AUTH-YYYY-NNNN --confirm-plan

authright change AUTH-YYYY-NNNN --ready
authright request-match AUTH-YYYY-NNNN
# OpenSpec CLI on PATH:
authright to-openspec AUTH-YYYY-NNNN
# Or Plan mode handoff (no OpenSpec CLI required; switch host to Plan mode first in chat):
authright to-plan AUTH-YYYY-NNNN

--ready does not silently Implicit-Preserve. Drive handoff from chat: pick /auth:to-openspec (needs OpenSpec installed) or switch to Plan mode and run /auth:to-plan—same locked change, two commands. If OpenSpec is missing, to-openspec stops—use Plan mode + to-plan. If Decide is unfinished (pending explore questions or unresolved auto-plan), those handoff skills stay on that gap. When nothing is pending they summarize the decisions, including whether the locked plan still matches what you asked, and ask whether to continue — they do not run --ready until you confirm (explore) or until the plan is confirmed (change).

AuthRight Harness does not write application source. See OpenSpec · Agent Plan-mode.

Verify after implementation

authright review AUTH-YYYY-NNNN
# or: /auth:review

Next

• Workflows — day-to-day patterns
• OpenSpec — export handoff
• Commands — chat command lookup
• Overview — mental model when you want depth