CLI Commands

Ralph provides a simple but powerful command-line interface.

Basic Usage

# Run workflow in current directory
$ ralph

# Initialize with a template
$ ralph --init <template>

# Resume interrupted workflow
$ ralph --resume

Commands & Flags

ralph

Run the workflow pipeline in the current directory.

$ ralph [OPTIONS]

--init

Initialize a project with a work guide template. Creates PROMPT.md from the selected template.

$ ralph --init feature-spec
$ ralph --init bug-fix
$ ralph --init refactor

--resume

Resume an interrupted workflow from the last checkpoint.

$ ralph --resume

Ralph reads .agent/checkpoint.json and continues from where it stopped. Useful after:

• Rate limit errors
• Network interruptions
• Manual pauses (Ctrl+C)
• System restarts

--diagnose

Run diagnostics to verify your setup:

$ ralph --diagnose

Ralph Workflow Diagnostics

 Ralph version: 0.1.0
 Git repository: detected
 Configuration: ~/.config/ralph-workflow.toml
 Available agents: opencode, ccs
 Developer fallback chain: configured
 Reviewer fallback chain: configured

All checks passed!

--with-rebase

Rebase the current branch before starting the workflow:

$ ralph --with-rebase

Useful when working on feature branches that may have fallen behind main.

--dry-run

Preview what Ralph would do without making changes:

$ ralph --dry-run

Shows the planned phases and agents without executing.

Shell Completions

Generate shell completions for tab-completion support:

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

# Zsh
$ ralph --completion zsh > ~/.zfunc/_ralph

# Fish
$ ralph --completion fish > ~/.config/fish/completions/ralph.fish

Exit Codes

Next Steps

• Configuration File - Customize Ralph's behavior
• Work Guide Templates - Explore all available templates