# Ralph CLI Options Reference

Complete reference for all `ralph` command-line flags and `.ralphrc` configuration patterns.

> **Quick start**: Run `ralph --help` for a summary. This document covers every flag in depth with examples and common `.ralphrc` patterns.

---

## Core Flags

### `-h, --help`
Show the help message and exit.

```bash
ralph --help
```

---

### `-c, --calls NUM`
Maximum API calls per hour before rate-limiting kicks in.

| Default | `.ralphrc` key |
|---------|----------------|
| `100` | `MAX_CALLS_PER_HOUR` |

```bash
ralph --calls 50          # Conservative — slow, careful projects
ralph --calls 200         # Aggressive — large task backlog
```

> **Tip**: Set this low during initial project setup to avoid runaway loops while your `.ralph/PROMPT.md` is still being tuned.

---

### `-p, --prompt FILE`
Path to the prompt file that drives each loop iteration.

| Default | `.ralphrc` key |
|---------|----------------|
| `.ralph/PROMPT.md` | `PROMPT_FILE` |

```bash
ralph --prompt .ralph/PROMPT_experimental.md
```

---

### `-s, --status`
Print the current loop status from `.ralph/status.json` and exit. Does not start a loop.

```bash
ralph --status
```

---

### `-m, --monitor`
Launch an integrated tmux session with the loop in the left pane and the live monitor dashboard in the right pane. Requires `tmux`.

```bash
ralph --monitor
ralph --monitor --calls 50 --prompt my_prompt.md
```

> **Recommended for interactive use.** Gives a real-time view of loop progress, circuit breaker state, and API call counts without a separate terminal.

---

### `-v, --verbose`
Show detailed progress updates during execution (logged to stdout and the log file).

```bash
ralph --verbose
ralph --live --verbose    # Live streaming + verbose logging
```

---

### `-l, --live`
Stream Claude Code output in real time to the terminal. Automatically switches `--output-format` to `json` if it was set to `text`.

```bash
ralph --live
ralph --live --timeout 30
```

> **Note**: Live mode pipes output through a streaming pipeline. The output is verbose — consider `--monitor` for a cleaner view during long runs.

---

### `-t, --timeout MIN`
Maximum time (in minutes) to allow a single Claude Code invocation to run before it is terminated with exit code 124.

| Default | `.ralphrc` key |
|---------|----------------|
| `15` | `CLAUDE_TIMEOUT_MINUTES` |

```bash
ralph --timeout 5     # Fast tasks / tight feedback loop
ralph --timeout 60    # Long refactors or large codebases
```

When a timeout occurs, Ralph checks git for changes made during the run:
- **Files changed** → productive timeout: analysis runs, loop continues
- **No files changed** → idle timeout: counted as a failed iteration

---

## Circuit Breaker Flags

### `--reset-circuit`
Reset the circuit breaker to `CLOSED` (normal) state and exit. Use after resolving the underlying issue that tripped the breaker.

```bash
ralph --reset-circuit
```

---

### `--circuit-status`
Print the current circuit breaker state (`CLOSED`, `HALF_OPEN`, or `OPEN`) and exit.

```bash
ralph --circuit-status
```

---

### `--auto-reset-circuit`
Reset the circuit breaker to `CLOSED` on startup, bypassing the cooldown timer. Applied to a single run only; does not persist.

| `.ralphrc` key | Default |
|----------------|---------|
| `CB_AUTO_RESET` | `false` |

```bash
ralph --auto-reset-circuit    # One-off reset + run
```

> **When to use**: Fully unattended deployments (CI, cron jobs) where a human won't be around to run `--reset-circuit` manually. For interactive use, prefer `--reset-circuit` so you can inspect the cause first.

---

### `--reset-session`
Clear the saved Claude session ID and exit. Forces the next loop to start a fresh conversation without prior context.

```bash
ralph --reset-session
```

> Use when a session has drifted or Claude is stuck in an unproductive pattern. Session state lives in `.ralph/.claude_session_id`.

---

### `--dry-run`
Simulate loop execution without making actual Claude API calls. Ralph runs the full loop scaffolding (rate-limit checks, exit detection, integrity validation) but skips the Claude invocation and does not increment the API call counter.

| Default | Environment variable |
|---------|----------------------|
| `false` | `DRY_RUN` |

```bash
ralph --dry-run               # Verify configuration before burning API calls
ralph --dry-run --verbose     # Watch what each loop iteration would do
```

> Useful for validating a new `.ralphrc` or prompt setup, and for demos.

---

### `-n, --notify`
Enable desktop notifications for key loop events (loop completion, errors, circuit breaker trips, API limits, project completion). Cross-platform: `osascript` on macOS, `notify-send` on Linux, terminal bell fallback.

| Default | `.ralphrc` key |
|---------|----------------|
| `false` | `ENABLE_NOTIFICATIONS` |

```bash
ralph --notify --monitor      # Get pinged when the loop needs attention
```

---

### `-b, --backup`
Create an automatic git backup branch before each loop iteration, named `ralph-backup-loop-{N}-{timestamp}`. Commits the current state with `--allow-empty` so a restore point exists even with no staged changes. Requires the project to be a git repository (no-op otherwise).

| Default | `.ralphrc` key |
|---------|----------------|
| `false` | `ENABLE_BACKUP` |

```bash
ralph --backup                # Snapshot before every loop
```

---

### `--rollback [BRANCH]`
Roll back to a backup branch created by `--backup`. With no argument, lists available `ralph-backup-loop-*` branches (newest first) and exits; with a branch name, checks it out.

```bash
ralph --rollback                                   # List available backups
ralph --rollback ralph-backup-loop-3-1775155286    # Restore a specific backup
```

---

### `--show-tool-args`
Show tool arguments (commands, file paths, search patterns) in live streaming output. Off by default so raw commands and paths aren't logged.

| Default | `.ralphrc` key |
|---------|----------------|
| `false` | `LIVE_SHOW_TOOL_ARGS` |

```bash
ralph --live --show-tool-args    # Full visibility into each tool call
```

> Only meaningful together with `-l, --live`.

---

## Modern CLI Flags

### `--output-format FORMAT`
Set the output format for Claude Code responses.

| Value | Behaviour |
|-------|-----------|
| `json` (default) | Structured JSON — enables session continuity, exit signal detection, and token counting |
| `text` | Legacy plain text — heuristic-only exit detection, higher false-positive rate |

| Default | `.ralphrc` key |
|---------|----------------|
| `json` | `CLAUDE_OUTPUT_FORMAT` |

```bash
ralph --output-format json    # Default; recommended
ralph --output-format text    # Legacy fallback
```

> **JSON mode is strongly preferred.** In text mode, heuristic exit detection requires `confidence_score >= 70` AND `has_completion_signal=true` to prevent false-positive exits from documentation keywords. In JSON mode, heuristics are suppressed entirely — only an explicit `EXIT_SIGNAL: true` in a `RALPH_STATUS` block can trigger exit.

---

### `--allowed-tools TOOLS`
Comma-separated list of tools Claude is permitted to use. Overrides the `.ralphrc` default for this run.

| Default | `.ralphrc` key |
|---------|----------------|
| See below | `ALLOWED_TOOLS` |

**Default value:**
```
Write,Read,Edit,Bash(git add *),Bash(git commit *),Bash(git diff *),Bash(git log *),
Bash(git status),Bash(git status *),Bash(git push *),Bash(git pull *),Bash(git fetch *),
Bash(git checkout *),Bash(git branch *),Bash(git stash *),Bash(git merge *),Bash(git tag *),
Bash(npm *),Bash(pytest)
```

```bash
# Restrict to read-only for an audit run
ralph --allowed-tools "Read,Grep,Glob"

# Allow all git commands (less safe — includes git clean, git rm)
ralph --allowed-tools "Write,Read,Edit,Bash(git *),Bash(npm *)"
```

> **Why specific git subcommands?** The default intentionally omits `Bash(git *)` to prevent `git clean`, `git rm`, and `git reset`, which could delete `.ralph/` configuration files. See [File Protection](../CLAUDE.md#file-protection-issue-149).

> **Debugging denied commands.** If a command is denied even though your `ALLOWED_TOOLS` looks correct, run `RALPH_VERBOSE=true ralph` to log the exact argv passed to Claude, or `tools/inspect-allowed-tools.sh` to inspect parsing without invoking Claude. For compound commands with pipes/redirects (e.g., `mvn clean | tail`), ralph automatically downgrades the denial to a warning when the base command is already allowed — see issue #243. The broader `Bash(git *)` wildcard limitation is tracked in issue #154.

---

### `--no-continue`
Disable session continuity. Each loop iteration starts a completely fresh Claude conversation with no memory of previous iterations.

| Default | `.ralphrc` key |
|---------|----------------|
| continuity enabled | `SESSION_CONTINUITY=true` |

```bash
ralph --no-continue
```

> Use when a session has accumulated too much context and Claude is making decisions based on stale assumptions. Also useful for isolating a single iteration for debugging.

---

### `--session-expiry HOURS`
Override how many hours a session ID is kept before it is automatically discarded and a new session starts.

| Default | `.ralphrc` key |
|---------|----------------|
| `24` | `SESSION_EXPIRY_HOURS` |

```bash
ralph --session-expiry 48    # Long-running projects with stable context
ralph --session-expiry 4     # Short-lived tasks where fresh context is better
```

---

## Common `.ralphrc` Patterns

The `.ralphrc` file at your project root is read at startup. Environment variables always take precedence over `.ralphrc` values.

> **Security (Issue #346):** `.ralphrc` lives in the repository, so Ralph parses it as data — it is **never executed**. Only `KEY=VALUE` lines for known configuration keys are applied (optional `export` prefix, `"double"`/`'single'` quotes and trailing `# comments` are fine). Values are literal: `$`, backticks, backslashes and control characters are rejected in **any** value (even single-quoted), unquoted values may not contain other shell syntax, numeric keys (call limits, timeouts, thresholds, costs, `CLAUDE_MIN_VERSION`) must be numbers, unknown keys are ignored with a warning, and `~` is not expanded (write the full path).
>
> Keys that decide what Ralph runs — `CLAUDE_CODE_CMD`, `RALPH_SHELL_INIT_FILE`, `SANDBOX_DOCKER_IMAGE`, `SANDBOX_E2B_TEMPLATE` — accept only their stock values from `.ralphrc` (`claude` / `npx @anthropic-ai/claude-code`, the official sandbox image, the `base` template; `RALPH_SHELL_INIT_FILE` none at all), and `SANDBOX_DOCKER_NETWORK` accepts only `bridge` or `none`. `RALPH_DIR` (where Ralph keeps its state and logs and reads `PROMPT.md`) is environment-only: `RALPH_DIR=.my-ralph ralph` relocates everything, including the integrity check. Set custom values in your environment (or with `--sandbox-image` / `--sandbox-template` / `--sandbox-network`), so a repository can't choose what runs on your machine. The same rules apply to `ralph-import` and `tools/inspect-allowed-tools.sh`.
>
> `ALLOWED_TOOLS` is still read from `.ralphrc`, so it is **not** a permission boundary against an untrusted repository (and `PROMPT.md` is repository-controlled too). Likewise `GITHUB_ISSUE` (with `AUTO_CLOSE`, `CREATE_PR`, …) can name any repository your `gh` login can write to. Run repositories you don't trust with `--sandbox docker` or `--sandbox e2b`, and review their `.ralphrc` before enabling GitHub lifecycle flags.

### Local workstation (default)

```bash
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
CLAUDE_AUTO_UPDATE=true
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
```

---

### Docker container

```bash
# Version is pinned at image build time — skip npm registry check
CLAUDE_AUTO_UPDATE=false

# Containers are ephemeral — no point persisting sessions
SESSION_CONTINUITY=false

# Tighter timeout for predictable CI runtimes
CLAUDE_TIMEOUT_MINUTES=10
```

---

### Air-gapped / offline environment

```bash
# npm registry is unreachable — prevents timeout and warning spam
CLAUDE_AUTO_UPDATE=false

```

Custom Claude CLI paths are not read from `.ralphrc` (see the security note above) — export one instead:

```bash
export CLAUDE_CODE_CMD="/opt/local/bin/claude"
```

---

### Unattended / cron operation

```bash
# Reduce call rate to avoid runaway spend overnight
MAX_CALLS_PER_HOUR=50

# Token budget per hour (0 = disabled). Blocks calls once budget is exhausted.
# Resets together with the call counter on the hour.
MAX_TOKENS_PER_HOUR=50000

# Longer timeout for batch work
CLAUDE_TIMEOUT_MINUTES=30

# Auto-recover from circuit breaker without human intervention
CB_AUTO_RESET=false           # false = use cooldown (safer)
CB_COOLDOWN_MINUTES=30        # Wait 30 min before retry after OPEN
```

---

### Circuit breaker tuning

```bash
# Open circuit after N loops with no file changes (default: 3)
CB_NO_PROGRESS_THRESHOLD=3

# Open circuit after N loops with the same error repeated (default: 5)
CB_SAME_ERROR_THRESHOLD=5

# Open circuit if output size declines by more than N% (default: 70)
CB_OUTPUT_DECLINE_THRESHOLD=70

# Minutes to wait in OPEN state before transitioning to HALF_OPEN (default: 30)
# Set to 0 for immediate retry
CB_COOLDOWN_MINUTES=30

# Skip cooldown and reset directly to CLOSED on startup (default: false)
# Use with care — reduces circuit breaker safety for unattended runs
CB_AUTO_RESET=false
```

---

### Restricting tool permissions

```bash
# Broad (development): all git subcommands allowed
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

# Safe (default): specific git subcommands only, no destructive git commands
ALLOWED_TOOLS="Write,Read,Edit,Bash(git add *),Bash(git commit *),Bash(git diff *),Bash(git log *),Bash(git status),Bash(git push *),Bash(npm *),Bash(pytest)"

# Read-only audit
ALLOWED_TOOLS="Read,Grep,Glob"
```

---

### Model and effort overrides

```bash
# Use a specific Claude model instead of the CLI default
CLAUDE_MODEL="claude-sonnet-4-6"

# Set effort level (high = more thorough, low = faster/cheaper)
CLAUDE_EFFORT="high"
```

Both can also be set as environment variables, which take precedence over `.ralphrc`:

```bash
CLAUDE_MODEL=claude-opus-4-6 ralph --monitor
```

---

### Custom shell initialization

```bash
# Source a script at startup (e.g., to activate a virtualenv or set PATH).
# Environment only — Ralph ignores this key in .ralphrc, since sourcing a file
# the repository chose would run repository code on your machine.
export RALPH_SHELL_INIT_FILE="$HOME/.zshrc"
```

Ralph will warn if the file is set but missing, and skip sourcing if it doesn't exist.

---

## `.ralphrc`-Only Keys

These keys have no CLI flag equivalent — they can only be set in `.ralphrc` or as environment variables.

| Key | Default | Description |
|-----|---------|-------------|
| `CLAUDE_CODE_CMD` | `"claude"` | Claude Code CLI command. `.ralphrc` accepts only `"claude"` or `"npx @anthropic-ai/claude-code"`; export a custom path as an environment variable. |
| `CLAUDE_AUTO_UPDATE` | `true` | Auto-check npm registry and update the Claude CLI at startup. Set `false` for Docker/air-gapped environments. |
| `CLAUDE_MIN_VERSION` | `"2.0.76"` | Minimum Claude CLI version required. Ralph warns and exits if the installed version is older. |
| `MAX_TOKENS_PER_HOUR` | `0` | Hourly token budget (`input + output`). `0` = disabled. Blocks further calls once exhausted; resets with the call counter on the hour. |
| `RALPH_VERBOSE` | `false` | Enable verbose progress logging. Equivalent to running with `--verbose`. |
| `CB_NO_PROGRESS_THRESHOLD` | `3` | Open circuit breaker after N consecutive loops with no file changes. |
| `CB_SAME_ERROR_THRESHOLD` | `5` | Open circuit breaker after N consecutive loops with the same error. |
| `CB_OUTPUT_DECLINE_THRESHOLD` | `70` | Open circuit breaker if output size declines by more than N%. |
| `CB_PERMISSION_DENIAL_THRESHOLD` | `2` | Open circuit breaker after N consecutive loops with permission denials. |
| `MAX_CONSECUTIVE_TEST_LOOPS` | `3` | Exit after N consecutive test-only loops. |
| `MAX_CONSECUTIVE_DONE_SIGNALS` | `2` | Exit after N consecutive "done" signals. |
| `TEST_PERCENTAGE_THRESHOLD` | `30` | Flag when more than N% of recent loops are test-only. |
| `CB_COOLDOWN_MINUTES` | `30` | Minutes in OPEN state before transitioning to HALF_OPEN for recovery attempt. |
| `CB_AUTO_RESET` | `false` | Skip cooldown on startup and reset directly to CLOSED. Reduces safety; prefer for fully unattended CI runs. |
| `PROJECT_NAME` | `"my-project"` | Used in prompts and log output for identification. |
| `PROJECT_TYPE` | `"unknown"` | Project type hint: `javascript`, `typescript`, `python`, `rust`, `go`, `unknown`. |

---

## Environment Variable Precedence

```
Environment variable   ← highest priority
    ↓
.ralphrc value
    ↓
Ralph default          ← lowest priority
```

All `.ralphrc` keys can be set as environment variables using the same name:

```bash
MAX_CALLS_PER_HOUR=200 ralph --monitor   # Override just for this run
```