A small set of flags appears on every command that needs to locate the config directory or alter agent behaviour. They are documented once here and cross-referenced from the per-command sections.

The precedence chain for the config directory is --config → $RAVEL_LITE_CONFIG → dirs::config_dir()/ravel-lite. The third is the platform default — ~/Library/Application Support/ravel-lite on macOS, ~/.config/ravel-lite on Linux. If none of the three resolves, every command that needs a config dir errors with a hint that points at ravel-lite init.

Materialises a config directory on disk. Writes the embedded defaults — agent config files, phase prompts, the universal coding-style and memory-style files under fixed-memory/ — into the target directory.

init is the only lifecycle command that does not need the config directory to already exist; it is how the config directory comes into being. After it runs, set RAVEL_LITE_CONFIG=<dir> (or pass --config <dir> to subsequent commands) so the rest of the CLI knows where to look.

The materialised tree is the read source for every subsequent run. Editing files under it is supported — the orchestrator reads them on each invocation, so a customised prompt or a new model setting takes effect on the next phase. See the Configuration and prompts reference for the layout in full.

Bootstraps a new plan directory through an interactive Claude Code session. Reads the create-plan prompt template from the config directory, appends the target plan path, and hands stdio off to claude so the conversation runs in the user’s terminal.

create reuses the work-phase model from agents/claude-code/config.yaml, so the agent it spawns matches the one that will run subsequent work phases. It scopes claude to the parent directory via --add-dir, which keeps the bootstrap conversation focused on the project subtree.

The output of a successful create is a populated plan directory containing backlog.yaml, memory.yaml (seeded with any starter entries the user dictated), phase.md set to work, and the baseline files the phase loop needs. After it returns, run ravel-lite run <plan_dir> to start cycling.

create is interactive — it inherits stdio rather than running through the TUI — because plan creation is a conversation, not a transformation of structured state. Pi is not currently supported as the create-plan agent.

The phase loop entry point. Drives one or more plans through the full work → analyse-work → reflect → (dream?) → triage cycle, looping until the user stops or the backlog empties. The Phase cycle reference documents what each phase does.

The loop reads <plan_dir>/phase.md to decide which phase to run next, so resumption after a crash is automatic — whichever phase was current is the one that runs again. Single-plan mode is the original behaviour: continuous cycling through one plan, with a yes/no prompt between cycles. Multi-plan mode is for users who want to keep several plans in motion: it prioritises plans via the LLM survey and lets the user pick one cycle at a time.

run validates that every plan directory contains a phase.md before starting, and registers each plan’s project subtree in the catalog (with an interactive collision prompt if a project name maps to a different path than catalogued). The TUI then takes over stdio for the duration of the run.

Prints the installed ravel-lite version and exits.

The same output is produced by the --version flag — the subcommand form is provided for symmetry with the rest of the CLI surface. Output shape:

The three components are the crate version, git describe --tags --always --dirty from the build, and the UTC build timestamp. A running binary therefore always identifies the commit it was built from, which makes "what version is this user running?" a one-line question regardless of how the binary was distributed.