ralph-cli¶

Binary entry point and CLI parsing.

Overview¶

ralph-cli is the main binary that:

Parses command-line arguments
Routes to appropriate commands
Handles global options

Commands¶

ralph run¶

Execute the orchestration loop.

pub struct RunCommand {
    pub prompt: Option<String>,
    pub prompt_file: Option<PathBuf>,
    pub max_iterations: Option<usize>,
    pub completion_promise: Option<String>,
    pub dry_run: bool,
    pub no_tui: bool,
    pub autonomous: bool,
    pub idle_timeout: Option<u64>,
    pub record_session: Option<PathBuf>,
    pub quiet: bool,
    pub continue_: bool,
}

ralph init¶

Initialize configuration file.

pub struct InitCommand {
    pub backend: Option<String>,
    pub preset: Option<String>,
    pub list_presets: bool,
    pub force: bool,
}

ralph plan¶

Start PDD planning session.

pub struct PlanCommand {
    pub idea: Option<String>,
    pub backend: Option<String>,
}

ralph task¶

Generate code task files.

pub struct TaskCommand {
    pub input: Option<String>,
    pub backend: Option<String>,
}

ralph events¶

View event history.

pub struct EventsCommand {
    pub limit: Option<usize>,
    pub format: OutputFormat,
}

ralph emit¶

Emit an event.

pub struct EmitCommand {
    pub topic: String,
    pub payload: Option<String>,
    pub json: Option<String>,
}

ralph clean¶

Clean up .agent/ directory.

pub struct CleanCommand {
    pub diagnostics: bool,
    pub all: bool,
}

ralph tools¶

Runtime tools subcommands.

pub enum ToolsCommand {
    Memory(MemoryCommand),
    Task(TaskCliCommand),
}

Global Options¶

pub struct GlobalOptions {
    pub config: PathBuf,
    pub verbose: bool,
    pub color: ColorMode,
}

Implementation¶

Command Dispatch¶

pub async fn run() -> Result<()> {
    let cli = Cli::parse();

    match cli.command {
        Command::Run(cmd) => run_command(cmd, &cli.global).await,
        Command::Init(cmd) => init_command(cmd, &cli.global).await,
        Command::Plan(cmd) => plan_command(cmd, &cli.global).await,
        Command::Task(cmd) => task_command(cmd, &cli.global).await,
        Command::Events(cmd) => events_command(cmd, &cli.global).await,
        Command::Emit(cmd) => emit_command(cmd, &cli.global).await,
        Command::Clean(cmd) => clean_command(cmd, &cli.global).await,
        Command::Tools(cmd) => tools_command(cmd, &cli.global).await,
    }
}

Error Handling¶

fn main() {
    if let Err(e) = ralph_cli::run() {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

Shell Completions¶

Generate shell completions:

pub fn generate_completions(shell: Shell) -> String {
    let mut cmd = Cli::command();
    let mut buf = Vec::new();
    generate(shell, &mut cmd, "ralph", &mut buf);
    String::from_utf8(buf).unwrap()
}

Usage:

ralph completions bash > ~/.local/share/bash-completion/completions/ralph
ralph completions zsh > ~/.zfunc/_ralph
ralph completions fish > ~/.config/fish/completions/ralph.fish

Exit Codes¶

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Backend not found
4	Interrupted

Example: Adding a New Command¶

Define command struct:

#[derive(Parser)]
pub struct MyCommand {
    #[arg(short, long)]
    pub option: Option<String>,
}

Add to command enum:

pub enum Command {
    // ...
    MyCommand(MyCommand),
}

Implement handler:

pub async fn my_command(cmd: MyCommand, global: &GlobalOptions) -> Result<()> {
    // Implementation
    Ok(())
}

Add to dispatch:

Command::MyCommand(cmd) => my_command(cmd, &cli.global).await,