微信扫一扫Ralph CLI: Command Reference
Complete reference for all Ralph CLI commands, options, and syntax.
Quick Start
# Check Ralph version
ralph --version
# List all commands
ralph --help
# Initialize from preset
ralph init --list-presets
ralph init --preset feature
# Run orchestration
ralph run
# View events
ralph events --last 20
Command Categories
| Category | Commands | Purpose |
|----------|----------|---------|
| Execution | run, plan, code-task | Run workflows, plan sessions, generate tasks |
| State | events, emit | View/emit event history |
| Setup | init, clean | Initialize configuration, cleanup artifacts |
| Runtime Tools | tools memory, tools task | Manage memories and tasks |
| Parallel | loops | Manage parallel loop workflows |
Command Reference
ralph run
Execute orchestration loop.
Syntax:
ralph run [OPTIONS]
Common Options:
| Option | Description |
|--------|-------------|
| -p, --prompt <TEXT> | Inline prompt text |
| -P, --prompt-file <FILE> | Prompt file path |
| --record-session <FILE> | Record session to JSONL file |
| --continue | Resume from existing scratchpad |
| --dry-run | Show what would execute without running |
| --autonomous | Force autonomous mode |
| --no-tui | Disable TUI mode |
Examples:
# Basic execution
ralph run
# With inline prompt
ralph run -p "Debug the login failure"
# With session recording
ralph run --record-session .ralph/session.jsonl
# Resume from checkpoint
ralph run --continue
# Dry run validation
ralph run --dry-run
See: references/command-tables.md for complete option table.
ralph events
View event history for debugging.
Syntax:
ralph events [OPTIONS]
Common Options:
| Option | Description |
|--------|-------------|
| --last <N> | Show only last N events |
| --topic <TOPIC> | Filter by topic |
| --iteration <N> | Filter by iteration number |
| --format <FORMAT> | Output format: table, json |
| --clear | Clear event history |
Examples:
# Show recent events
ralph events --last 20
# Filter by topic
ralph events --topic "test.passed"
# JSON output
ralph events --format json | jq '.[] | {topic, iteration}'
ralph init
Initialize configuration file.
Syntax:
ralph init [OPTIONS]
Common Options:
| Option | Description |
|--------|-------------|
| --preset <NAME> | Copy embedded preset to ralph.yml |
| --list-presets | List all available presets |
| --backend <BACKEND> | Backend to use |
| --force | Overwrite existing ralph.yml |
Examples:
# List presets
ralph init --list-presets
# Initialize from preset
ralph init --preset feature
# Initialize with backend
ralph init --preset debug --backend gemini
ralph tools
Runtime tools for memory and task management.
Syntax:
ralph tools <COMMAND> [OPTIONS]
Subcommands:
memory- Manage persistent memoriestask- Manage work items
ralph tools memory
Memory Operations:
# Add memory
ralph tools memory add "content" -t pattern --tags tag1,tag2
# List memories
ralph tools memory list --last 10
# Search memories
ralph tools memory search "query" --tags api
# Prime context
ralph tools memory prime --budget 2000
# Delete memory
ralph tools memory delete <id>
ralph tools task
Task Operations:
# Add task
ralph tools task add "Title" -p 1
# List tasks
ralph tools task list
# Show ready tasks
ralph tools task ready
# Close task
ralph tools task close <id>
ralph loops
Manage parallel loop workflows.
Syntax:
ralph loops [COMMAND] [OPTIONS]
Subcommands:
# List all loops
ralph loops list
# View loop logs
ralph loops logs <LOOP_ID>
# Show loop history
ralph loops history <LOOP_ID>
# Merge completed loop
ralph loops merge <LOOP_ID>
# Discard failed loop
ralph loops discard <LOOP_ID> -y
# Clean up stale loops
ralph loops prune
Other Commands
| Command | Description |
|---------|-------------|
| ralph plan | Start PDD planning session |
| ralph code-task | Generate code task files |
| ralph emit | Emit event to event log |
| ralph clean | Clean up artifacts |
Output Formats
Most commands support --format option:
| Format | Use Case |
|--------|----------|
| table | Human-readable display (default) |
| json | Programmatic access, parsing |
| quiet | Scripting, minimal output |
| markdown | Documentation, specific commands |
Example:
# JSON output for parsing
ralph events --format json | jq '.[] | select(.topic == "test.passed")'
# Quiet output for scripting
ralph tools memory list --format quiet
Exit Codes
| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Command usage error | | 124 | Timeout | | 126 | Command not found |
Global Options
Available for all commands:
| Option | Description |
|--------|-------------|
| -c, --config | Config file override |
| -v, --verbose | Enable verbose output |
| --color | Color mode: auto, always, never |
| -h, --help | Print help |
| -V, --version | Print version |
See Also
references/command-tables.md- Complete command tables with all optionsreferences/syntax-examples.md- Detailed syntax examples for each commandreferences/output-formats.md- Output format specifications and parsingreferences/cli-patterns.md- Common CLI usage patterns and workflows
Quick Reference
| Task | Command |
|------|---------|
| Start orchestration | ralph run |
| Monitor events | ralph events --last 20 |
| List presets | ralph init --list-presets |
| Initialize project | ralph init --preset feature |
| Check status | ralph events --topic "test" |
| View tasks | ralph tools task ready |
| View memories | ralph tools memory list |
| Monitor loops | ralph loops list |
| Resume workflow | ralph run --continue |
| Validate config | ralph run --dry-run |