CLI reference

Every flag accepted by ralphterm (and the bundled ralphex alias). Usage:

ralphterm [flags] [plan-file]
ralphterm run PLAN [flags]            # explicit subcommand still works
ralphterm smoke --agent <name>        # one-shot smoke run
ralphterm serve [flags]               # start the local daemon
ralphterm workspace <subcommand>      # workspace management

Modes

--tasks-only, -t

Type: flag. Default: off. Skip the review gate. Equivalent to ralphex tasks-only mode.

--review, -r

Type: flag. Default: off. Review-only mode: skip task execution, run the full review pipeline.

--external-only, -e

Type: flag. Default: off. Run the external review and fixer loop only.

--codex-only, -c

Type: flag. Default: off. Alias for the codex external-only loop.

Implementation agent

--claude-command <cmd>

Type: string. Default: claude. Implementation CLI executable. Drives a real PTY; never uses --print or -p.

--claude-args <args>

Type: string. Default: empty. Extra arguments appended to --claude-command.

--task-model <model>

Type: string. Default: provider default. Model identifier passed to the implementation CLI.

--agent <name>

Type: enum (claude | codex | copilot | gemini | opencode). Default: claude. Selects a wrapper script under scripts/wrappers/. --claude-command wins when both are set.

Review pipeline

--review-model <model>

Type: string. Default: provider default. Model identifier passed to the review CLI.

--external-review-tool=<codex|custom|none>

Type: enum. Default: codex. Selects the reviewer kind. custom requires --custom-review-script; none disables review.

--custom-review-script <cmd>

Type: string. Default: empty. Custom reviewer executable mapped to RalphTerm's independent review command.

--review-patience <n>

Type: integer. Default: 1. Consecutive clean reviews required before acceptance.

--max-iterations <n>, -m

Type: integer. Default: 3. Implementation+review iteration cap per task.

--max-external-iterations <n>

Type: integer. Default: 3. External-review loop cap.

--require-review

Type: flag. Default: off. Hard gate: refuse to start without --review-command or --review-agent.

--review-command <cmd>

Type: string. Default: empty. Independent reviewer command.

--review-agent <name>

Type: string. Default: empty. Use a known agent identity for review.

--max-review-retries <n>

Type: integer. Default: 1. Retry budget for REVIEW_FAIL. 0 blocks on the first failed review.

--skip-finalize

Type: flag. Default: off. Suppress the final-review pass; commits still gated by per-task review.

Timing and base ref

--base-ref <ref>, -b

Type: string. Default: HEAD. Diff baseline included in reviewer context.

--wait

Type: flag. Default: off. Block until the daemon/run finishes.

--session-timeout <duration>

Type: duration (e.g. 30m). Default: provider default. Per-session wall-clock timeout.

--idle-timeout <duration>

Type: duration. Default: provider default. Idle PTY timeout before the session is cancelled.

Workspace and worktree

--worktree

Type: flag. Default: off. Create an isolated git worktree for the run.

--branch <name>

Type: string. Default: plan filename slug. Worktree branch override.

--workspace-id <id>

Type: string. Default: empty. Run inside .ralphterm/workspaces/<id>; does not auto-clean after the run.

Daemon and dashboard

--serve, -s

Type: flag. Default: off. Start the local daemon with progress/dashboard endpoints.

--port <n>, -p

Type: integer. Default: 7878. Daemon port.

--host <addr>

Type: string. Default: 127.0.0.1. Daemon bind host.

--watch <dir>, -w

Type: path. Default: empty. Watch a plans directory and process new plans automatically.

Notifications

--notify-telegram-token <token>

Type: string. Default: from config. Telegram bot token override.

--notify-telegram-chat <chat-id>

Type: string. Default: from config. Telegram chat id override.

--notify-slack <webhook>

Type: URL. Default: from config. Slack webhook URL override.

--notify-webhook <url>

Type: URL. Default: from config. Generic JSON POST webhook URL.

--notify-on <a,b,c>

Type: comma-separated list. Default: plan_done,task_failed,review_failed,rate_limit. Events that fire notifications.

Docker isolation

--docker

Type: flag. Default: off. Run the agent and reviewer inside a container.

--docker-image <image>

Type: string. Default: ralphterm:latest. Container image to use.

--preserve-anthropic-api-key

Type: flag. Default: off. Pass ANTHROPIC_API_KEY through to the container.

Config

--config-dir <path>

Type: path. Default: ~/.config/ralphex/ or RALPHEX_CONFIG_DIR. Global config directory.

--plan <path>

Type: path. Default: positional argument. Explicit plan-path flag; positional <plan> is the canonical form.

--init

Type: flag. Default: off. Scaffold a .ralphex/ directory with default config (pending).

--reset

Type: flag. Default: off. Reset local .ralphex/ state to defaults (pending).

--dump-defaults

Type: flag. Default: off. Print the default config to stdout.

Output

--debug, -d

Type: flag. Default: off. Verbose logging.

--no-color

Type: flag. Default: off. Disable ANSI color in RalphTerm-owned output.

--no-commit

Type: flag. Default: off. Do not create a checkpoint commit after a passed review.

--dry-run

Type: flag. Default: off. Preview pending tasks, review mode, and validation without starting an agent.

--version, -v

Type: flag. Default: off. Print the RalphTerm version.