CLI Reference

Complete reference for all ralph commands and options.

Commands

ralph run

Start the agentic loop.

ralph run [options]

Options:

Option	Alias	Type	Description
`--max-iterations`	`-n`	number	Maximum loop iterations (default from config)
`--once`	`-o`	boolean	Run single iteration (no loop)
`--prompt`	`-p`	string	Prompt text or path to prompt file
`--cwd`	`-c`	string	Working directory
`--verbose`	`-v`	boolean	Enable verbose output
`--no-tui`	-	boolean	Disable TUI (plain text output)
`--output-format`	`-f`	string	Output format: `stream-json`, `opencode-json`, `text`
`--log-file`	`-l`	string	Write raw stream-json output to file

Examples:

# Run with default config
ralph run

# Run with specific prompt file
ralph run --prompt .plans/PROMPT.md

# Run single iteration (no loop)
ralph run --once

# Limit iterations
ralph run --max-iterations 5

# Verbose output for debugging
ralph run -v

# Disable TUI for CI/plain output
ralph run --no-tui

Exit Reasons:

The run command exits with one of these reasons:

complete - Task finished (AI output <promise>COMPLETE</promise> marker)
error - Process exited with non-zero code
user_abort - User interrupted (Ctrl+C)
max_iterations - Reached maximum iteration limit

ralph init

Initialize ralph in a project directory.

ralph init [options]

Options:

Option	Alias	Type	Description
`--cwd`	`-c`	string	Working directory for initialization
`--force`	`-f`	boolean	Overwrite existing files

What it creates:

project/
├── .ralph/
│   └── config.toml          # Ralph configuration
└── .plans/
    ├── prd.json             # Product requirements document
    ├── PROMPT.md            # System prompt template
    └── progress.txt         # Progress tracking log

Interactive prompts:

Plans directory name (default: .plans)
AI CLI adapter selection (claude, opencode, or gemini)

Example:

# Initialize in current directory
ralph init

# Initialize with force overwrite
ralph init --force

# Initialize in specific directory
ralph init --cwd /path/to/project

ralph check

Validate the prd.json against the schema.

ralph check [options]

Options:

Option	Alias	Type	Description
`--cwd`	`-c`	string	Working directory

Example:

$ ralph check

✓ prd.json is valid (3 features)

If validation fails, errors are listed and the command exits with code 1.

Global Options

These options work with all commands:

Option	Description
`--help`, `-h`	Show help
`--version`	Show version

Exit Codes

Code	Meaning
`0`	Success
`1`	Error

Configuration

ralph uses a TOML configuration file at .ralph/config.toml. See the Configuration page for details.