Struct CliBackend 

pub struct CliBackend {
    pub command: String,
    pub args: Vec<String>,
    pub prompt_mode: PromptMode,
    pub prompt_flag: Option<String>,
    pub output_format: OutputFormat,
    pub env_vars: Vec<(String, String)>,
}

A CLI backend configuration for executing prompts.

Fields

command: String

The command to execute.

args: Vec<String>

Additional arguments before the prompt.

prompt_mode: PromptMode

How to pass the prompt.

prompt_flag: Option<String>

Argument flag for prompt (if prompt_mode is Arg).

output_format: OutputFormat

Output format emitted by this backend.

env_vars: Vec<(String, String)>

Environment variables to set when spawning the process.

Implementations

impl CliBackend

pub fn from_config(config: &CliConfig) -> Result<Self, CustomBackendError>

Creates a backend from configuration.

Errors

Returns CustomBackendError if backend is “custom” but no command is specified.

pub fn claude() -> Self

Creates the Claude backend.

Uses --print for headless execution and sends the prompt over stdin. This avoids Claude’s large-prompt -p behavior, which can stall before emitting any stream output when asked to read the real prompt from an intermediate temp-file instruction.

Emits --output-format stream-json for NDJSON streaming output. Note: --verbose is required when using --output-format stream-json.

pub fn claude_interactive() -> Self

Creates the Claude backend for interactive prompt injection.

Runs Claude without -p flag, passing prompt as a positional argument. Used by SOP runner for interactive command injection.

Note: This is NOT for TUI mode - Ralph’s TUI uses the standard claude() backend. This is for cases where Claude’s interactive mode is needed. Uses = syntax for --disallowedTools to prevent variadic consumption of the positional prompt argument.

pub fn kiro() -> Self

Creates the Kiro backend.

Uses kiro-cli in headless mode with all tools trusted.

pub fn kiro_with_agent(agent: String, extra_args: &[String]) -> Self

Creates the Kiro backend with a specific agent and optional extra args.

Uses kiro-cli with –agent flag to select a specific agent.

pub fn kiro_acp() -> Self

Creates the Kiro ACP backend.

Uses kiro-cli with the ACP subcommand for structured JSON-RPC communication over stdio instead of PTY text scraping.

pub fn kiro_acp_with_options(agent: Option<&str>, model: Option<&str>) -> Self

Creates the Kiro ACP backend with an optional agent and/or model.

pub fn from_name_with_args( name: &str, extra_args: &[String], ) -> Result<Self, CustomBackendError>

Creates a backend from a named backend with additional args.

Errors

Returns error if the backend name is invalid.

pub fn from_name(name: &str) -> Result<Self, CustomBackendError>

Creates a backend from a named backend string.

Errors

Returns error if the backend name is invalid.

pub fn from_hat_backend( hat_backend: &HatBackend, ) -> Result<Self, CustomBackendError>

Creates a backend from a HatBackend configuration.

Errors

Returns error if the backend configuration is invalid.

pub fn gemini() -> Self

Creates the Gemini backend.

pub fn codex() -> Self

Creates the Codex backend.

pub fn amp() -> Self

Creates the Amp backend.

pub fn copilot() -> Self

Creates the Copilot backend for autonomous mode.

Uses GitHub Copilot CLI with --allow-all-tools for automated tool approval. Prompt mode emits JSONL via --output-format json for programmatic parsing.

pub fn copilot_tui() -> Self

Creates the Copilot TUI backend for interactive mode.

Runs Copilot in full interactive mode (no -p flag), allowing Copilot’s native TUI to render. The prompt is passed as a positional argument.

pub fn claude_interactive_teams() -> Self

Creates the Claude interactive backend with Agent Teams support.

Like claude_interactive() but with reduced --disallowedTools (only TodoWrite) and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var.

pub fn for_interactive_prompt( backend_name: &str, ) -> Result<Self, CustomBackendError>

Creates a backend configured for interactive mode with initial prompt.

This factory method returns the correct backend configuration for running an interactive session with an initial prompt. The key differences from headless mode are:

Backend	Interactive + Prompt
Claude	positional arg (no -p flag)
Kiro	removes --no-interactive
Gemini	uses -i instead of -p
Codex	no exec subcommand
Amp	removes --dangerously-allow-all
Copilot	removes --allow-all-tools
OpenCode	run subcommand with positional prompt

Errors

Returns CustomBackendError if the backend name is not recognized.

pub fn kiro_interactive() -> Self

Kiro in interactive mode (removes –no-interactive).

Unlike headless kiro(), this allows the user to interact with Kiro’s TUI while still passing an initial prompt.

pub fn gemini_interactive() -> Self

Gemini in interactive mode with initial prompt (uses -i, not -p).

Critical quirk: Gemini requires -i flag for interactive+prompt mode. Using -p would make it run headless and exit after one response.

pub fn codex_interactive() -> Self

Codex in interactive TUI mode (no exec subcommand).

Unlike headless codex(), this runs without exec and --full-auto flags, allowing interactive TUI mode.

pub fn amp_interactive() -> Self

Amp in interactive mode (removes –dangerously-allow-all).

Unlike headless amp(), this runs without the auto-approve flag, requiring user confirmation for tool usage.

pub fn copilot_interactive() -> Self

Copilot in interactive mode (removes –allow-all-tools).

Unlike headless copilot(), this runs without the auto-approve flag, requiring user confirmation for tool usage.

pub fn opencode() -> Self

Creates the OpenCode backend for autonomous mode.

Uses OpenCode CLI with run subcommand. The prompt is passed as a positional argument after the subcommand:

opencode run "prompt text here"

Output is plain text (no JSON streaming available).

pub fn opencode_tui() -> Self

Creates the OpenCode TUI backend for interactive mode.

Runs OpenCode with run subcommand. The prompt is passed as a positional argument:

opencode run "prompt text here"

pub fn opencode_interactive() -> Self

OpenCode in interactive TUI mode.

Runs OpenCode TUI with an initial prompt via --prompt flag:

opencode --prompt "prompt text here"

Unlike opencode() which uses opencode run (headless mode), this launches the interactive TUI and injects the prompt.

pub fn pi() -> Self

Creates the Pi backend for headless execution.

Uses -p for print mode with --mode json for NDJSON streaming output. Emits PiStreamJson output format for structured event parsing.

pub fn pi_interactive() -> Self

Creates the Pi backend for interactive mode with initial prompt.

Runs pi TUI without -p or --mode json, passing the prompt as a positional argument. Used by ralph plan for interactive sessions.

pub fn roo() -> Self

Creates the Roo backend for headless execution.

Uses --print for non-interactive output and --ephemeral for clean disk state. Prompts are always passed via --prompt-file (handled in build_command()). Roo auto-approves tools by default, so no --trust-all-tools equivalent is needed.

pub fn roo_interactive() -> Self

Creates the Roo backend for interactive mode with initial prompt.

Runs roo TUI without --print or --ephemeral, passing the prompt as a positional argument. Used by ralph plan for interactive sessions.

pub fn custom(config: &CliConfig) -> Result<Self, CustomBackendError>

Creates a custom backend from configuration.

Errors

Returns CustomBackendError if no command is specified.

pub fn build_command( &self, prompt: &str, interactive: bool, ) -> (String, Vec<String>, Option<String>, Option<NamedTempFile>)

Builds the full command with arguments for execution.

Arguments

• prompt - The prompt text to pass to the agent
• interactive - Whether to run in interactive mode (affects agent flags)

Trait Implementations

impl Clone for CliBackend

fn clone(&self) -> CliBackend

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CliBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.