Reference

Commands

Reference for the rei CLI, grouped by the task each command solves. Every command accepts rei <command> --help.

22 commands · 4 categories

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.

CLI exit code convention
CodeMeaning
0The command finished correctly.
1A check failed or the command could not complete.
2Incorrect usage: unknown, repeated, valueless or invalid flag.

Prepare the project

Initialize the harness, generate native subagents and check the state of the customization.

Prepare the project: commands, what they do and flags
CommandWhat it doesFlags
rei initInitializes the harness in the project: skeleton, state structure and git if missing. It does not overwrite existing files.--help
rei init statusTells you which project documentation is still to be customized.—
rei init opencodeGenerates the native OpenCode subagents and the /personalize command.--check
rei init claudeGenerates the native Claude Code subagents, /personalize and CLAUDE.md.--check
rei init --updateUpdates the harness of an already initialized project with marker detection.--force
rei doctorRead-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.

Syntax

rei init

Flags

  • --helpShows the command help.

Example

Shell
rei init

Exit codes

  • 0 Installation completed.
  • 1 It could not create a skeleton or structure file, or the OpenCode or Claude generation or verification failed.
  • 2 Incorrect usage.

Notes

  • 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.

Syntax

rei init status

No flags of its own.

Example

Shell
rei init status

Exit codes

  • 0 No document is pending.
  • 1 Some document is still to be customized.

rei init opencode

Generates the native OpenCode subagents and the /personalize command.

Syntax

rei init opencode

Flags

  • --checkChecks for drift without writing anything.

Example

Shell
rei init opencode

Exit codes

  • 0 All files match the canonical generation.
  • 1 One is missing, lacks the mark or differs.

Notes

  • 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.

Syntax

rei init claude

Flags

  • --checkChecks for drift without writing anything.

Example

Shell
rei init claude

Exit codes

  • 0 All files match the canonical generation.
  • 1 One is missing, lacks the mark or differs.

Notes

  • 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.

Syntax

rei init --update

Flags

  • --forceForces the update of the generated files.

Example

Shell
rei init --update

rei doctor

Read-only diagnosis of the harness, the roles and the pending customization.

Syntax

rei doctor

No flags of its own.

Example

Shell
rei doctor

Work Items and session

Create, plan, approve and move a Work Item through its states.

Work Items and session: commands, what they do and flags
CommandWhat it doesFlags
rei new <id> <feature|task> [title]Creates a Work Item in pending state with its identifier and type.—
rei sessionShows 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 archiveArchives the session once the Work Item is closed.—
rei session resetResets 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 statusLists 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.

Syntax

rei new <id> <feature|task> [title]

No flags of its own.

Example

Shell
rei new 2026-10-27_01-54__mi-feature feature "Mi primera feature"

rei session

Shows the active session and its Work Item.

Syntax

rei session

No flags of its own.

Example

Shell
rei session status

rei session start <id> <tipo>

Starts the session of a Work Item only if it exists, the type matches and it is in pending.

Syntax

rei session start <id> <tipo>

No flags of its own.

Example

Shell
rei session start 2026-10-27_01-54__mi-feature feature

rei session archive

Archives the session once the Work Item is closed.

Syntax

rei session archive

No flags of its own.

Example

Shell
rei session archive

Exit codes

  • 0 Session archived and current.md reset.
  • 1 The Work Item is not in a terminal state or current.md is not consistent.

Notes

  • 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.

Syntax

rei session reset

No flags of its own.

Example

Shell
rei session reset

rei commit set <id> <campo>

Records the current commit in base_commit or last_review_commit.

Syntax

rei commit set <id> <campo>

No flags of its own.

Example

Shell
rei commit set 2026-10-27_01-54__mi-feature base_commit

rei status set <id> <estado>

Changes the state of a Work Item. done is terminal; leaving it requires --force.

Syntax

rei status set <id> <estado>

Flags

  • --forceAllows a non-standard transition other than from done.

Example

Shell
rei status set 2026-10-27_01-54__mi-feature ready

rei items status

Lists each Work Item with its type, state, issue and base if there is a link.

Syntax

rei items status

No flags of its own.

Example

Shell
rei items status

Exit codes

  • 0 Listing correct.
  • 1 More than one Work Item is in in_progress; the message names the ones involved.

Notes

  • 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.

Syntax

rei item show <id>

No flags of its own.

Example

Shell
rei item show 2026-10-27_01-54__mi-feature

Exit codes

  • 0 The card is shown with no validation failures.
  • 1 There is at least one validation [FAIL].

Notes

  • 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.

Verification and review: commands, what they do and flags
CommandWhat it doesFlags
rei validate [<id>]Checks the internal consistency of a Work Item. An invalid links.json is a recoverable warning.—
rei checkVerifies the harness and runs the checks declared in .rei/config.json.--quiet, -q
rei testRuns 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.

Syntax

rei validate [<id>]

No flags of its own.

Example

Shell
rei validate 2026-10-27_01-54__mi-feature

Exit codes

  • 0 There is no [FAIL].
  • 1 There is at least one [FAIL].

Notes

  • 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.

Syntax

rei check

Flags

  • --quiet, -qOmits the [OK] lines and the summary.

Example

Shell
rei check

Exit codes

  • 0 Everything passes.
  • 1 There is at least one [FAIL].

Notes

  • Besides the checks, it creates the structure and initializes git if missing.

rei test

Runs the checks declared in .rei/config.json.

Syntax

rei test

No flags of its own.

Example

Shell
rei test

Exit codes

  • 0 There are no checks configured or all pass.
  • 1 Some check fails.

Notes

  • 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.

Syntax

rei review-diff <id>

Flags

  • --fullShows the full diff, not just the summary.

Example

Shell
rei review-diff 2026-10-27_01-54__mi-feature

rei view [<id>]

Opens the local read-only viewer: documents, validation, session, TOC, diff and FICHA.

Syntax

rei view [<id>]

Flags

  • --openStarts or reuses the server in the background and opens the browser without blocking.
  • --stopStops the viewer server.
  • --enableTurns on viewer.autoOpenOnReady in .rei/config.json.
  • --disableTurns off viewer.autoOpenOnReady in .rei/config.json.

Example

Shell
rei view 2026-10-27_01-54__mi-feature

Exit codes

  • 0 The viewer was opened or stopped correctly.
  • 1 There is no active session or there was an I/O error.
  • 2 Incorrect usage; the modes are mutually exclusive.

Notes

  • 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.

Maintenance and integration: commands, what they do and flags
CommandWhat it doesFlags
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.

Syntax

rei update [--check]

Flags

  • --checkOnly checks whether there is a new version; it changes nothing.

Example

Shell
rei update --check

Exit codes

  • 0 It is up to date, --check worked or Windows guided the download.
  • 1 Network, permission, integrity or extraction failure.
  • 2 Incorrect usage.

Notes

  • 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.

Syntax

rei github <enable|disable|status>

Flags

  • --repo owner/nameTarget repository.
  • --base <rama>Base branch for the changes.
  • --strategy squash|merge|rebaseMerge strategy of the PR.

Example

Shell
rei github enable --repo k1wi777/REI-Harness --base main --strategy squash

Exit codes

  • 0 Operation correct, also with warnings and in status.
  • 1 Operational or configuration error.
  • 2 Incorrect usage.

Notes

  • Without flags, enable detects the repository from origin and the base from origin/HEAD.
  • disable and status do not contact GitHub and reject flags.

Planning approval

Pending

A human sign-off releases the sheet. Silence is not approval.

Approval is recorded from the CLI; the viewer does not replace it.