ralph_workflow/cli/args/
args_struct.rs

1/// Ralph: PROMPT-driven agent orchestrator for git repos
2#[derive(Parser, Debug, Default)]
3#[command(name = "ralph")]
4#[command(about = "PROMPT-driven multi-agent orchestrator for git repos")]
5#[command(
6    long_about = "Ralph orchestrates AI coding agents to implement changes based on PROMPT.md.\n\n\
7    It runs a developer agent for code implementation, then a reviewer agent for\n\
8    review and fixes (default), automatically staging and committing the final result."
9)]
10#[command(version)]
11#[command(after_help = "GETTING STARTED:\n\
12    ralph --init                 Smart init (infers what you need)\n\
13    ralph --init <work-guide>    Create PROMPT.md from a Work Guide\n\
14    ralph                        Run the orchestrator\n\
15\n\
16More help: ralph --extended-help  (shell completion, all presets, troubleshooting)")]
17// CLI arguments naturally use many boolean flags. These represent independent
18// user choices, not a state machine, so bools are the appropriate type.
19pub struct Args {
20    /// Verbosity shorthand flags (--quiet, --full)
21    #[command(flatten)]
22    pub verbosity_shorthand: VerbosityShorthand,
23
24    /// Debug verbosity flag
25    #[command(flatten)]
26    pub debug_verbosity: DebugVerbosity,
27
28    /// Quick preset mode flags
29    #[command(flatten)]
30    pub quick_presets: QuickPresets,
31
32    /// Standard preset mode flags
33    #[command(flatten)]
34    pub standard_presets: StandardPresets,
35
36    /// Unified config initialization flags
37    #[command(flatten)]
38    pub unified_init: UnifiedInitFlags,
39
40    /// Agent listing flags
41    #[command(flatten)]
42    pub agent_list: AgentListFlags,
43
44    /// Provider listing flag
45    #[command(flatten)]
46    pub provider_list: ProviderListFlag,
47
48    /// Shell completion generation flag
49    #[command(flatten)]
50    pub completion: CompletionFlag,
51
52    /// Work Guide listing flag
53    #[command(flatten)]
54    pub work_guide_list: WorkGuideListFlag,
55
56    /// Template management commands
57    #[command(flatten)]
58    pub template_commands: TemplateCommands,
59
60    /// Commit message plumbing flags
61    #[command(flatten)]
62    pub commit_plumbing: CommitPlumbingFlags,
63
64    /// Commit display plumbing flags
65    #[command(flatten)]
66    pub commit_display: CommitDisplayFlags,
67
68    /// Recovery command flags
69    #[command(flatten)]
70    pub recovery: RecoveryFlags,
71
72    /// Rebase control flags
73    #[command(flatten)]
74    pub rebase_flags: RebaseFlags,
75
76    /// Number of developer iterations (default: 5)
77    #[arg(
78        long = "developer-iters",
79        short = 'D',
80        env = "RALPH_DEVELOPER_ITERS",
81        value_name = "N",
82        help = "Number of developer agent iterations",
83        aliases = ["developer-iteration", "dev-iter", "d-iters"]
84    )]
85    pub developer_iters: Option<u32>,
86
87    /// Number of review-fix cycles (N=0 skips review, N=1 is one review-fix cycle, etc.)
88    #[arg(
89        long = "reviewer-reviews",
90        short = 'R',
91        env = "RALPH_REVIEWER_REVIEWS",
92        value_name = "N",
93        help = "Number of review-fix cycles (0=skip review, 1=one cycle, default: 2)",
94        aliases = ["reviewer-count", "reviewer-review"]
95    )]
96    pub reviewer_reviews: Option<u32>,
97
98    /// Preset for common agent combinations
99    #[arg(
100        long,
101        env = "RALPH_PRESET",
102        value_name = "NAME",
103        help = "Use a preset agent combination (default, opencode)",
104        hide = true
105    )]
106    pub preset: Option<super::presets::Preset>,
107
108    /// Developer/driver agent to use (from `agent_chain.developer`)
109    #[arg(
110        long,
111        short = 'a',
112        env = "RALPH_DEVELOPER_AGENT",
113        aliases = ["driver-agent", "dev-agent", "developer"],
114        value_name = "AGENT",
115        help = "Developer agent for code implementation (default: first in agent_chain.developer)"
116    )]
117    pub developer_agent: Option<String>,
118
119    /// Reviewer agent to use (from `agent_chain.reviewer`)
120    #[arg(
121        long,
122        short = 'r',
123        env = "RALPH_REVIEWER_AGENT",
124        aliases = ["rev-agent", "reviewer"],
125        value_name = "AGENT",
126        help = "Reviewer agent for code review (default: first in agent_chain.reviewer)"
127    )]
128    pub reviewer_agent: Option<String>,
129
130    /// Developer model/provider override (e.g., "-m opencode/glm-4.7-free")
131    #[arg(
132        long,
133        env = "RALPH_DEVELOPER_MODEL",
134        value_name = "MODEL_FLAG",
135        help = "Model flag for developer agent (e.g., '-m opencode/glm-4.7-free')",
136        hide = true
137    )]
138    pub developer_model: Option<String>,
139
140    /// Reviewer model/provider override (e.g., "-m opencode/claude-sonnet-4")
141    #[arg(
142        long,
143        env = "RALPH_REVIEWER_MODEL",
144        value_name = "MODEL_FLAG",
145        help = "Model flag for reviewer agent (e.g., '-m opencode/claude-sonnet-4')",
146        hide = true
147    )]
148    pub reviewer_model: Option<String>,
149
150    /// Developer provider override (e.g., "opencode", "zai", "anthropic", "openai")
151    /// Use this to switch providers at runtime without changing agent config.
152    /// Combined with the agent's model to form the full model flag.
153    /// Provider types: 'opencode' (Zen gateway), 'zai'/'zhipuai' (Z.AI direct), 'anthropic'/'openai' (direct API)
154    #[arg(
155        long,
156        env = "RALPH_DEVELOPER_PROVIDER",
157        value_name = "PROVIDER",
158        help = "Provider for developer agent: 'opencode' (Zen), 'zai'/'zhipuai' (Z.AI direct), 'anthropic'/'openai' (direct API)",
159        hide = true
160    )]
161    pub developer_provider: Option<String>,
162
163    /// Reviewer provider override (e.g., "opencode", "zai", "anthropic", "openai")
164    /// Use this to switch providers at runtime without changing agent config.
165    /// Combined with the agent's model to form the full model flag.
166    /// Provider types: 'opencode' (Zen gateway), 'zai'/'zhipuai' (Z.AI direct), 'anthropic'/'openai' (direct API)
167    #[arg(
168        long,
169        env = "RALPH_REVIEWER_PROVIDER",
170        value_name = "PROVIDER",
171        help = "Provider for reviewer agent: 'opencode' (Zen), 'zai'/'zhipuai' (Z.AI direct), 'anthropic'/'openai' (direct API)",
172        hide = true
173    )]
174    pub reviewer_provider: Option<String>,
175
176    /// JSON parser for the reviewer agent (overrides agent config)
177    /// Useful for testing different parsers with problematic agents
178    #[arg(
179        long,
180        env = "RALPH_REVIEWER_JSON_PARSER",
181        value_name = "PARSER",
182        help = "JSON parser for reviewer (claude, codex, gemini, opencode, generic); overrides agent config",
183        hide = true
184    )]
185    pub reviewer_json_parser: Option<String>,
186
187    /// Verbosity level (0=quiet, 1=normal, 2=verbose, 3=full, 4=debug)
188    #[arg(
189        short,
190        long,
191        value_name = "LEVEL",
192        value_parser = clap::value_parser!(u8).range(0..=4),
193        help = "Output verbosity (0=quiet, 1=normal, 2=verbose [default], 3=full, 4=debug); overrides RALPH_VERBOSITY"
194    )]
195    pub verbosity: Option<u8>,
196
197    /// Disable isolation mode (allow NOTES.md and ISSUES.md to persist)
198    #[arg(
199        long,
200        help = "Disable isolation mode: keep NOTES.md and ISSUES.md between runs",
201        hide = true
202    )]
203    pub no_isolation: bool,
204
205    /// Review depth level (standard, comprehensive, security, incremental)
206    #[arg(
207        long,
208        value_name = "LEVEL",
209        help = "Review depth: standard (balanced), comprehensive (thorough), security (OWASP-focused), incremental (changed files only)",
210        hide = true
211    )]
212    pub review_depth: Option<String>,
213
214    /// Path to configuration file (default: ~/.config/ralph-workflow.toml)
215    #[arg(
216        long,
217        short = 'c',
218        value_name = "PATH",
219        help = "Path to configuration file (default: ~/.config/ralph-workflow.toml)",
220        hide = true
221    )]
222    pub config: Option<std::path::PathBuf>,
223
224    /// Internal: Working directory override for testing.
225    /// When set, app::run uses this path instead of discovering the repo root
226    /// and does not change the global CWD. This enables test parallelism.
227    #[arg(skip)]
228    pub working_dir_override: Option<std::path::PathBuf>,
229
230    /// Interactive mode: prompt to create PROMPT.md from template when missing
231    #[arg(
232        long,
233        short = 'i',
234        help = "Interactive mode: prompt to create PROMPT.md from template when missing",
235        hide = true
236    )]
237    pub interactive: bool,
238
239    /// Git user name override (highest priority in identity resolution chain)
240    #[arg(
241        long,
242        env = "RALPH_GIT_USER_NAME",
243        value_name = "NAME",
244        help = "Git user name for commits (overrides config, env, and git config)",
245        hide = true
246    )]
247    pub git_user_name: Option<String>,
248
249    /// Git user email override (highest priority in identity resolution chain)
250    #[arg(
251        long,
252        env = "RALPH_GIT_USER_EMAIL",
253        value_name = "EMAIL",
254        help = "Git user email for commits (overrides config, env, and git config)",
255        hide = true
256    )]
257    pub git_user_email: Option<String>,
258
259    /// Show streaming quality metrics at the end of agent output
260    #[arg(
261        long,
262        help = "Display streaming quality metrics (delta stats, repairs, violations) after agent completion",
263        hide = true
264    )]
265    pub show_streaming_metrics: bool,
266}
ralph_workflow/cli/args/args_struct.rs

ralph_workflow/cli/args/
args_struct.rs
