CLI Reference¶

Complete reference for Ralph's command-line interface.

Global Options¶

These options are accepted by all commands.

Core Config Sources (-c)¶

The -c flag specifies where to load core configuration from. If not provided, ralph falls back to:

1. $RALPH_CONFIG when present
2. ralph.yml

Core source types:

-c builtin:<name> is no longer supported. Use -H builtin:<name> for hat collections.

The first non-override core source is used as the base config. Later core overrides replace earlier values.

Backward compatibility: a -c config file may still contain hats/events (single-file combined config).

If -H/--hats is provided, it takes precedence over hats in -c: - hats and events from -H replace hats/events from -c - event_loop values from -H override matching event_loop keys from -c - -c core.*=... overrides are still applied last

Supported override fields:

Hat Collection Sources (-H)¶

The -H flag specifies where to load hat collections from.

Examples:

# Core only (hatless)
ralph run -c ralph.yml

# Core + built-in hat collection
ralph run -c ralph.yml -H builtin:code-assist

# Core + file hat collection
ralph run -c ralph.yml -H hats/review.yml

# Core override + hats
ralph run -c ralph.yml -c core.specs_dir=./my-specs -H builtin:debug

Commands¶

ralph run¶

Run the orchestration loop.

ralph run [OPTIONS]

Options:

ralph init¶

Initialize ralph.yml.

ralph init [OPTIONS]

Options:

ralph preflight¶

Run the preflight check suite.

ralph preflight [OPTIONS]

Options:

Default check names:

• config
• hooks
• backend
• telegram
• git
• paths
• tools
• specs

Notes:

• --check can be repeated (for example: --check hooks --check config).
• --strict fails when there are warnings (not just failures).
• During ralph run, auto-preflight uses features.preflight.skip to skip checks by these names.

ralph hooks¶

Validate hooks configuration and command wiring without starting loop execution.

ralph hooks <COMMAND>

Subcommands:

• validate [--format human|json]

ralph hooks validate behavior:

• Exit code 0: validation passed.
• Exit code 1: one or more diagnostics (or config load/parse failure).
• --format human (default): readable report with diagnostics.
• --format json: structured report (pass, source, hooks_enabled, checked_hooks, diagnostics).

Try it against the minimal sample hooks config:

• ralph hooks validate -c examples/hooks/minimal/ralph.hooks.yml
• Config: examples/hooks/minimal/ralph.hooks.yml
• Scripts: examples/hooks/scripts/env-guard.sh, examples/hooks/scripts/notify.sh

ralph doctor¶

Run environment and first-run diagnostic checks.

ralph doctor [OPTIONS]

ralph tutorial¶

Run interactive intro walkthrough.

ralph tutorial [OPTIONS]

ralph plan¶

Start an interactive PDD planning session.

ralph plan [OPTIONS] [IDEA]

Options:

ralph code-task¶

Generate code task files from a description or PDD plan.

ralph code-task [OPTIONS] [INPUT]

ralph task¶

Deprecated legacy alias for ralph code-task.

ralph task [OPTIONS] [INPUT]

ralph events¶

View event history for the current or selected run.

ralph events [OPTIONS]

Options:

ralph emit¶

Emit an event to the current run's events file.

ralph emit <TOPIC> [PAYLOAD] [OPTIONS]

Options:

ralph clean¶

Clean .ralph/agent scratchpad and memory state.

ralph clean [OPTIONS]

Options:

ralph loops¶

Manage parallel loops and worktree loop lifecycle.

ralph loops [OPTIONS] [COMMAND]

Subcommands:

• list [--json] [--all]
• logs <loop-id> [--follow]
• history <loop-id> [--json]
• retry <loop-id>
• discard <loop-id> [--yes]
• stop [loop-id] [--force]
• resume <loop-id>
• prune
• attach <loop-id>
• diff <loop-id> [--stat]
• merge <loop-id> [--force]
• process
• merge-button-state <loop-id>

ralph loops resume <loop-id> writes a resume signal for suspended loops. It is idempotent: re-running the command reports that resume was already requested (or that the loop is not suspended).

ralph hats¶

Manage and inspect configured hats.

ralph hats [OPTIONS] [COMMAND]

Subcommands:

• list [--format table|json]
• show <name>
• validate
• graph [--format unicode|ascii|compact|mermaid] [--backend <backend>]

ralph web¶

Run the web dashboard.

ralph web [OPTIONS]

Options:

ralph mcp¶

Run Ralph as a Model Context Protocol server over stdio.

ralph mcp serve

Notes:

• v1 is tools-only and stdio-only.
• Launch it from an MCP client configuration, not an interactive terminal workflow.
• The server exposes Ralph control-plane methods as MCP tools, including polling stream tools such as stream_next.

ralph bot¶

Manage Telegram bot setup and testing.

ralph bot [OPTIONS] <COMMAND>

Subcommands:

• onboard [--token <TOKEN>] [--chat-id <CHAT_ID>] [--timeout <SECONDS>]
• status
• test [MESSAGE]
• token set <TOKEN> [--config <path>]
• daemon

ralph tools¶

Runtime tools for memories, tasks, and skills.

ralph tools memory¶

ralph tools memory <SUBCOMMAND>

Subcommands:

ralph tools task¶

ralph tools task <SUBCOMMAND>

Subcommands:

ralph tools skill¶

ralph tools skill <SUBCOMMAND>

ralph tools interact¶

Interact with human via Telegram progress/proactiveness hooks.

ralph completions¶

Generate shell completions.

ralph completions <SHELL>

Supported shells: bash, elvish, fish, powershell, zsh.

Exit Codes¶

Environment Variables¶

Shell Completion¶

Generate shell completions:

# Bash
ralph completions bash > ~/.local/share/bash-completion/completions/ralph

# Zsh
ralph completions zsh > ~/.zfunc/_ralph

# Fish
ralph completions fish > ~/.config/fish/completions/ralph.fish