Commands
Reference for the rei CLI, grouped by the task each command solves. Every command accepts rei <command> --help.
Exit codes
The general convention applies unless the command documents its own codes in its detail. The exit code is the signal the workflow uses to know whether a verification passed.
| Code | Meaning |
|---|---|
| 0 | The command finished correctly. |
| 1 | A check failed or the command could not complete. |
| 2 | Incorrect usage: unknown, repeated, valueless or invalid flag. |
Prepare the project
Initialize the harness, generate native subagents and check the state of the customization.
| Command | What it does | Flags |
|---|---|---|
| rei init | Initializes the harness in the project: skeleton, state structure and git if missing. It does not overwrite existing files. | --help |
| rei init status | Tells you which project documentation is still to be customized. | — |
| rei init opencode | Generates the native OpenCode subagents and the /personalize command. | --check |
| rei init claude | Generates the native Claude Code subagents, /personalize and CLAUDE.md. | --check |
| rei init --update | Updates the harness of an already initialized project with marker detection. | --force |
| rei doctor | Read-only diagnosis of the harness, the roles and the pending customization. | — |
rei init
Initializes the harness in the project: skeleton, state structure and git if missing. It does not overwrite existing files.
rei init
--help
rei init0Installation completed.1It could not create a skeleton or structure file, or the OpenCode or Claude generation or verification failed.2Incorrect usage.
- If AGENTS.md already exists, it warns and leaves it unchanged.
- Guided customization is started with /personalize or by invoking the initializer role.
rei init status
Tells you which project documentation is still to be customized.
rei init status
rei init status0No document is pending.1Some document is still to be customized.
rei init opencode
Generates the native OpenCode subagents and the /personalize command.
rei init opencode
--check
rei init opencode0All files match the canonical generation.1One is missing, lacks the mark or differs.
- The files carry the GENERATED mark; it does not overwrite foreign files and it is idempotent.
- Generates /personalize with agent: initializer and subtask: true.
rei init claude
Generates the native Claude Code subagents, /personalize and CLAUDE.md.
rei init claude
--check
rei init claude0All files match the canonical generation.1One is missing, lacks the mark or differs.
- The files carry the GENERATED mark; it does not overwrite foreign files and it is idempotent.
- CLAUDE.md imports AGENTS.md with @AGENTS.md.
rei init --update
Updates the harness of an already initialized project with marker detection.
rei init --update
--force
rei init --updaterei doctor
Read-only diagnosis of the harness, the roles and the pending customization.
rei doctor
rei doctorWork Items and session
Create, plan, approve and move a Work Item through its states.
| Command | What it does | Flags |
|---|---|---|
| rei new <id> <feature|task> [title] | Creates a Work Item in pending state with its identifier and type. | — |
| rei session | Shows the active session and its Work Item. | — |
| rei session start <id> <tipo> | Starts the session of a Work Item only if it exists, the type matches and it is in pending. | — |
| rei session archive | Archives the session once the Work Item is closed. | — |
| rei session reset | Resets current.md to its initial state. | — |
| rei commit set <id> <campo> | Records the current commit in base_commit or last_review_commit. | — |
| rei status set <id> <estado> | Changes the state of a Work Item. done is terminal; leaving it requires --force. | --force |
| rei items status | Lists each Work Item with its type, state, issue and base if there is a link. | — |
| rei item show <id> | Shows the card of a Work Item: metadata, links, documents, session and validation. | — |
rei new <id> <feature|task> [title]
Creates a Work Item in pending state with its identifier and type.
rei new <id> <feature|task> [title]
rei new 2026-10-27_01-54__mi-feature feature "Mi primera feature"rei session
Shows the active session and its Work Item.
rei session
rei session statusrei session start <id> <tipo>
Starts the session of a Work Item only if it exists, the type matches and it is in pending.
rei session start <id> <tipo>
rei session start 2026-10-27_01-54__mi-feature featurerei session archive
Archives the session once the Work Item is closed.
rei session archive
rei session archive0Session archived and current.md reset.1The Work Item is not in a terminal state or current.md is not consistent.
- It only archives if meta.json is in done or blocked and the State in current.md matches.
- It moves the summary to history.md and resets current.md.
rei session reset
Resets current.md to its initial state.
rei session reset
rei session resetrei commit set <id> <campo>
Records the current commit in base_commit or last_review_commit.
rei commit set <id> <campo>
rei commit set 2026-10-27_01-54__mi-feature base_commitrei status set <id> <estado>
Changes the state of a Work Item. done is terminal; leaving it requires --force.
rei status set <id> <estado>
--force
rei status set 2026-10-27_01-54__mi-feature readyrei items status
Lists each Work Item with its type, state, issue and base if there is a link.
rei items status
rei items status0Listing correct.1More than one Work Item is in in_progress; the message names the ones involved.
- It marks the Work Item in in_progress with << ACTIVO.
- An invalid links.json is reported as a note and does not prevent the listing.
rei item show <id>
Shows the card of a Work Item: metadata, links, documents, session and validation.
rei item show <id>
rei item show 2026-10-27_01-54__mi-feature0The card is shown with no validation failures.1There is at least one validation [FAIL].
- The Links section shows the issue, URL, base (branch @ sha) and epic from links.json.
- If links.json is missing it is a note; if it is invalid it is reported as a note and ignored.
Verification and review
Check the consistency of the harness, review the diff and open the local viewer.
| Command | What it does | Flags |
|---|---|---|
| rei validate [<id>] | Checks the internal consistency of a Work Item. An invalid links.json is a recoverable warning. | — |
| rei check | Verifies the harness and runs the checks declared in .rei/config.json. | --quiet, -q |
| rei test | Runs the checks declared in .rei/config.json. | — |
| rei review-diff <id> | Generates the review package with the real changes of the Work Item. | --full |
| rei view [<id>] | Opens the local read-only viewer: documents, validation, session, TOC, diff and FICHA. | --open--stop--enable--disable |
rei validate [<id>]
Checks the internal consistency of a Work Item. An invalid links.json is a recoverable warning.
rei validate [<id>]
rei validate 2026-10-27_01-54__mi-feature0There is no [FAIL].1There is at least one [FAIL].
- Without <id>, it validates the Work Item of the active session.
- An invalid links.json is reported as a recoverable WARN, never as a FAIL.
rei check
Verifies the harness and runs the checks declared in .rei/config.json.
rei check
--quiet, -q
rei check0Everything passes.1There is at least one [FAIL].
- Besides the checks, it creates the structure and initializes git if missing.
rei test
Runs the checks declared in .rei/config.json.
rei test
rei test0There are no checks configured or all pass.1Some check fails.
- It is not REI's test suite; it runs only the project checks.
- With no checks configured it reports it and exits 0.
rei review-diff <id>
Generates the review package with the real changes of the Work Item.
rei review-diff <id>
--full
rei review-diff 2026-10-27_01-54__mi-featurerei view [<id>]
Opens the local read-only viewer: documents, validation, session, TOC, diff and FICHA.
rei view [<id>]
--open--stop--enable--disable
rei view 2026-10-27_01-54__mi-feature0The viewer was opened or stopped correctly.1There is no active session or there was an I/O error.2Incorrect usage; the modes are mutually exclusive.
- In the background it closes shortly after showing «finished» (done); --stop, the idle timeout and Ctrl+C keep working.
- It is read-only: it does not approve and does not modify documents, meta.json or the state of the Work Item.
Maintenance and integration
Update the binary and enable the optional GitHub Issues integration.
| Command | What it does | Flags |
|---|---|---|
| rei update [--check] | Updates the binary from GitHub Releases, verifying the SHA-256 checksum. | --check |
| rei github <enable|disable|status> | Enables, disables or queries the optional GitHub Issues integration. The CLI never calls GitHub. | --repo owner/name--base <rama>--strategy squash|merge|rebase |
rei update [--check]
Updates the binary from GitHub Releases, verifying the SHA-256 checksum.
rei update [--check]
--check
rei update --check0It is up to date, --check worked or Windows guided the download.1Network, permission, integrity or extraction failure.2Incorrect usage.
- On Windows the running .exe cannot be replaced: it reports it and opens the releases page.
- A SHA-256 integrity failure aborts without modifying the binary.
rei github <enable|disable|status>
Enables, disables or queries the optional GitHub Issues integration. The CLI never calls GitHub.
rei github <enable|disable|status>
--repo owner/name--base <rama>--strategy squash|merge|rebase
rei github enable --repo k1wi777/REI-Harness --base main --strategy squash0Operation correct, also with warnings and in status.1Operational or configuration error.2Incorrect usage.
- Without flags, enable detects the repository from origin and the base from origin/HEAD.
- disable and status do not contact GitHub and reject flags.
A human sign-off releases the sheet. Silence is not approval.