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 

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  [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] 

Subcommands:

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

ralph wave

Dispatch wave events for parallel hat execution.

ralph wave emit  --payloads ...

Options:

Each payload becomes an event tagged with a shared wave_id. The loop runner spawns parallel backend instances bounded by the target hat's concurrency setting.

Blocked when RALPH_WAVE_WORKER=1 (prevents nested waves).

See Agent Waves for full details.

ralph tools

Runtime tools for memories, tasks, and skills.

ralph tools memory

ralph tools memory 

Subcommands:

ralph tools task

ralph tools task 

Subcommands:

ralph tools skill

ralph tools skill 

ralph tools interact

Interact with human via Telegram progress/proactiveness hooks.

ralph completions

Generate shell completions.

ralph completions 

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