Command map

rafa's commands take the form rafa <subject> <action>, plus a few commands with no subject. Each subject and command has its own page with every action and flag; this page is the map. Commands that chain several of these, such as rafa next and a stretch, are workflows: see Subjects and workflows.

rafa --help                  # every subject and command
rafa loop --help             # the actions of one subject
rafa loop start --help       # one action's arguments, flags and examples
rafa describe --output=json  # the same roster, for a script or an agent

A 🪙 marks a subject or command that starts Claude Code sessions, which spend your Claude usage. Within a subject, only some actions spend; the action's help says which.

Subjects

Subject	Does	Spends
plan	create plans from specs; list, show and validate them; read their risk and needs	🪙 create
loop	start a plan; stop, pause, resume, show and list its sessions	🪙 start
issue	the tracker: list, show, create, edit, comment on and move issues; mark one ready, unblock it, check its references	nothing
pr	the pull request of a branch: show it, open, list, wait on, merge and triage it	🪙 triage --resolve
effort	collect session and commit rows; report per plan; read and repair the store; merge or import another device's store	nothing
module	list the configured modules; run an action a module provides	nothing
agent	copy an agent definition into the project; list what a session sees	🪙 search
skill	check a skills directory; list each tier; demote and backfill it	🪙 backfill --propose, search
instinct	check an instincts directory; list, show, flag and promote its records	nothing
release	read the release state; settle waiting fragments into a version; tag; publish; write the ladder's workflows; write a fragment by hand	nothing
board	list the boards with their owner and epic count; sync the GitHub project	nothing
epic	show one epic's issues; create, defer, promote, move into, close through the gate, or cancel an epic	🪙 close
claim	give up, hand over, accept or take over a claim on an issue	nothing
update	bring this project to the installed rafa (current); the other updates are in development	nothing
config	show every setting and where it came from; set one key, keeping every comment	nothing
ci	read the newest CI run on a branch: its state, its commit and the cases it failed	nothing
stretch	open a stretch: an integration branch with operator sessions (alpha)	🪙
bug	list cause codes, rank the closest to a description, recheck whether a bug still reproduces	nothing
docs	write a plan repairing the open lines of the stale-docs issues	nothing

Commands with no subject

Command	Does	Spends
rafa init	set up a project: its root, .rafa/config.yaml, the folders and the .gitignore block; offers the GitHub board	nothing
rafa doctor	run every check loop start runs before its first session; --deep reads what a session can reach	nothing
rafa status	everything in one snapshot: branch, loops, pull request, board, claims, housekeeping	nothing
rafa next	take you to the next step: wait, triage, merge, settle, plan, start; it asks before each	🪙 when the step does
rafa roadmap	the roadmap as a table	nothing
rafa switch	move this checkout to a board or an epic, or back with -	nothing
rafa cleanup	list merged, stale and unpushed branches and idle worktrees, and remove the ones you tick	nothing
rafa self-update	build and install rafa from a checkout of its repository	nothing
rafa describe	the command roster as data	nothing

There is no rafa hub subject: the hub is a separate server, documented under rafa-hub, and a project reaches it through the effort.sync and hub.* settings.

Global flags

Flag	Does
--output=json	events as NDJSON (one JSON object per line) instead of text (also RAFA_OUTPUT=json)
--output=events	one rafa· line per loop event (also RAFA_OUTPUT=events)
-v, --verbose	more output, up to three times, or --verbose=N
--version	print rafa <version> and exit

Most commands run inside a rafa project: the nearest folder at or above where you are that holds rafa.config.ts, rafa.config.mjs or .rafa/config.yaml. Outside one they print the rafa init hint and exit 1. init, the help and describe run anywhere, and so do a few others, such as rafa skill check.