CLI Options

Command Syntax

./ralph.sh [--tool <name>] [max_iterations]

All arguments are optional and can be provided in any order.

Available Options

—tool

Selects which AI coding tool Ralph uses for each iteration.

--tool

string

default:"amp"

Type: String (required after flag)Default: ampValid values:

amp - Uses the Amp CLI
claude - Uses Claude Code

Syntax variations:

--tool amp        # Space-separated
--tool=amp        # Equals-separated

Validation:The script validates the tool choice and exits with code 1 if invalid:

$ ./ralph.sh --tool invalid
Error: Invalid tool 'invalid'. Must be 'amp' or 'claude'.

Tool-Specific Behavior

# Command executed per iteration:
cat prompt.md | amp --dangerously-allow-all

# Reads: prompt.md
# Flags: --dangerously-allow-all (bypasses permission prompts)

Both tools run with “dangerously” flags to enable fully autonomous operation. This allows Ralph to make file changes, run commands, and commit code without user interaction.

max_iterations

Defines the maximum number of agent iterations before Ralph stops.

max_iterations

integer

default:"10"

Type: Positive integerDefault: 10Position: Can appear anywhere in arguments (detected by regex pattern)Range: Any positive integer (1 to unlimited)Examples:

./ralph.sh 5              # Run max 5 iterations
./ralph.sh 100            # Run max 100 iterations
./ralph.sh --tool claude 25  # Works in any position
./ralph.sh 15 --tool amp  # Position doesn't matter

Early exit:If all tasks complete before reaching max_iterations, Ralph exits immediately with success (code 0).

Parsing Logic

The script identifies max_iterations using pattern matching:

if [[ "$1" =~ ^[0-9]+$ ]]; then
  MAX_ITERATIONS="$1"
fi

Any numeric argument is treated as max_iterations. Non-numeric arguments are either flags or ignored.

Argument Parsing Order

Ralph processes arguments left-to-right:

—tool flag: Consumes next argument as tool name
—tool=value: Extracts value after equals sign
Numeric arguments: Sets max_iterations
Other arguments: Ignored

Examples

./ralph.sh
# Tool: amp (default)
# Max iterations: 10 (default)

Internal Variables

Ralph sets these variables based on CLI arguments:

TOOL

TOOL="amp"  # Default value

Source: --tool flag or default
Used by: Iteration loop to select AI command
Validation: Must be exactly “amp” or “claude”

MAX_ITERATIONS

MAX_ITERATIONS=10  # Default value

Source: Numeric positional argument or default
Used by: Loop counter seq 1 $MAX_ITERATIONS
Validation: None (any positive integer accepted)

Script Paths

These are derived from the script location, not CLI arguments:

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PRD_FILE="$SCRIPT_DIR/prd.json"
PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
ARCHIVE_DIR="$SCRIPT_DIR/archive"
LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"

Error Handling

Invalid Tool Name

$ ./ralph.sh --tool unknown
Error: Invalid tool 'unknown'. Must be 'amp' or 'claude'.
$ echo $?
1

Exit code: 1

Missing Tool Argument

$ ./ralph.sh --tool
# Behavior: TOOL variable becomes empty string
# Result: Fails validation, exits with code 1

Non-Numeric max_iterations

$ ./ralph.sh abc
# Behavior: "abc" doesn't match numeric regex
# Result: Ignored, uses default (10)

Invalid numeric values are silently ignored and don’t cause errors. Only the --tool validation is strict.

Exit Codes Reference

Code	Condition	Meaning
`0`	Success	All tasks completed (found `<promise>COMPLETE</promise>`)
`1`	Error	Invalid tool name provided
`1`	Incomplete	Reached max_iterations without completing all tasks

Integration with prd.json

While not a CLI option, prd.json affects Ralph’s behavior:

{
  "branchName": "ralph/my-feature",
  "userStories": [
    {
      "id": "001",
      "title": "Add login form",
      "passes": false
    }
  ]
}

branchName

string

Triggers archive creation when changed between runs.Ralph compares the current branchName with .last-branch and archives the previous run if they differ.

userStories[].passes

boolean

Controls iteration behavior.When all stories have passes: true, the AI outputs <promise>COMPLETE</promise> and Ralph exits successfully.

Environment Configuration

Ralph doesn’t use environment variables for configuration, but the AI tools it invokes might:

Amp Configuration

# Amp reads from:
export AMP_API_KEY="your-key"
# Or from: ~/.config/amp/

Claude Code Configuration

# Claude Code reads from:
export ANTHROPIC_API_KEY="your-key"
# Or from: ~/.claude/

Ensure these are configured before running Ralph. The script doesn’t validate API credentials.

Best Practices

Setting max_iterations

Small features (1-3 stories):

./ralph.sh 10  # Usually sufficient

Medium features (4-8 stories):

./ralph.sh 25  # Allow time for debugging

Large features (9+ stories):

./ralph.sh 50  # Extra buffer for complexity

Tool Selection

Choose based on your team’s setup:

# If team uses Amp
./ralph.sh --tool amp

# If team uses Claude Code
./ralph.sh --tool claude

# If testing both
./ralph.sh --tool amp 5 && ./ralph.sh --tool claude 5

Advanced Argument Patterns

Using with xargs

echo "30" | xargs -I {} ./ralph.sh {}
# Runs with 30 iterations

Scripting with variables

#!/bin/bash
TOOL_CHOICE="claude"
ITERATIONS=20

./ralph.sh --tool $TOOL_CHOICE $ITERATIONS

CI/CD Integration

# .github/workflows/ralph.yml
- name: Run Ralph
  run: |
    ./scripts/ralph/ralph.sh \
      --tool ${{ secrets.AI_TOOL }} \
      ${{ vars.MAX_ITERATIONS }}

Comparison with Other Tools

Unlike traditional CLI tools, Ralph’s options are minimal by design: Ralph approach:

./ralph.sh --tool claude 20
# Just two options: tool and iterations

Traditional approach might have:

hypothetical-tool \
  --model claude-opus \
  --temperature 0.7 \
  --max-tokens 4096 \
  --retries 3 \
  --timeout 30s
# Too many knobs

Ralph’s simplicity is intentional. All configuration lives in the prompt files (prompt.md and CLAUDE.md), keeping the CLI interface minimal and focused on orchestration.

CLI

File Formats

Examples

Command Syntax

Available Options

—tool

Tool-Specific Behavior

max_iterations

Parsing Logic

Argument Parsing Order

Examples

Internal Variables

TOOL

MAX_ITERATIONS

Script Paths

Error Handling

Invalid Tool Name

Missing Tool Argument

Non-Numeric max_iterations

Exit Codes Reference

Integration with prd.json

Environment Configuration

Amp Configuration

Claude Code Configuration

Best Practices

Setting max_iterations

Tool Selection

Advanced Argument Patterns

Using with xargs

Scripting with variables

CI/CD Integration

Comparison with Other Tools

Build docs developers (and LLMs) love

CLI

File Formats

Examples

Documentation Index

​Command Syntax

​Available Options

​—tool

​Tool-Specific Behavior

​max_iterations

​Parsing Logic

​Argument Parsing Order

​Examples

​Internal Variables

​TOOL

​MAX_ITERATIONS

​Script Paths

​Error Handling

​Invalid Tool Name

​Missing Tool Argument

​Non-Numeric max_iterations

​Exit Codes Reference

​Integration with prd.json

​Environment Configuration

​Amp Configuration

​Claude Code Configuration

​Best Practices

​Setting max_iterations

​Tool Selection

​Advanced Argument Patterns

​Using with xargs

​Scripting with variables

​CI/CD Integration

​Comparison with Other Tools

Build docs developers (and LLMs) love

Command Syntax

Available Options

—tool

Tool-Specific Behavior

max_iterations

Parsing Logic

Argument Parsing Order

Examples

Internal Variables

TOOL

MAX_ITERATIONS

Script Paths

Error Handling

Invalid Tool Name

Missing Tool Argument

Non-Numeric max_iterations

Exit Codes Reference

Integration with prd.json

Environment Configuration

Amp Configuration

Claude Code Configuration

Best Practices

Setting max_iterations

Tool Selection

Advanced Argument Patterns

Using with xargs

Scripting with variables

CI/CD Integration

Comparison with Other Tools