ralph/cli/task/args/
mod.rs

1//! CLI argument definitions for `ralph task ...` commands.
2//!
3//! Responsibilities:
4//! - Define all `#[derive(Args)]` structs for task subcommands.
5//! - Define all `#[derive(Subcommand)]` enums for command routing.
6//! - Define all `#[derive(ValueEnum)]` enums for typed arguments.
7//! - Provide conversions from CLI types to internal types.
8//!
9//! Not handled here:
10//! - Command execution logic (see individual handler modules).
11//! - Business logic or queue operations.
12//!
13//! Invariants/assumptions:
14//! - All argument types must be `Clone` where needed for clap flattening.
15//! - Defaults should match the behavior described in help text.
16
17use clap::{Args, Subcommand};
18
19// Submodules
20mod batch;
21mod build;
22mod edit;
23mod lifecycle;
24mod relations;
25mod template;
26mod types;
27
28// Re-exports for backward compatibility
29pub use batch::{
30    BatchEditArgs, BatchFieldArgs, BatchOperation, BatchSelectArgs, BatchStatusArgs, TaskBatchArgs,
31};
32pub use build::{TaskBuildArgs, TaskBuildRefactorArgs};
33pub use edit::{TaskEditArgs, TaskFieldArgs, TaskUpdateArgs};
34pub use lifecycle::{
35    TaskDoneArgs, TaskReadyArgs, TaskRejectArgs, TaskScheduleArgs, TaskShowArgs, TaskStartArgs,
36    TaskStatusArgs,
37};
38pub use relations::{
39    TaskBlocksArgs, TaskChildrenArgs, TaskCloneArgs, TaskMarkDuplicateArgs, TaskParentArgs,
40    TaskRelateArgs, TaskRelationFormat, TaskSplitArgs,
41};
42pub use template::{
43    TaskFromArgs, TaskFromCommand, TaskFromTemplateArgs, TaskTemplateArgs, TaskTemplateBuildArgs,
44    TaskTemplateCommand, TaskTemplateShowArgs,
45};
46pub use types::{BatchMode, TaskEditFieldArg, TaskStatusArg};
47
48#[derive(Args)]
49#[command(
50    about = "Create and build tasks from freeform requests",
51    subcommand_required = false,
52    after_long_help = "Common journeys:\n - Create a task:\n   ralph task \"Refactor queue parsing\"\n   ralph task build-refactor\n - Start work on a task:\n   ralph task ready RQ-0001\n   ralph task start RQ-0001\n - Complete a task:\n   ralph task status done RQ-0001\n   ralph task done --note \"Build checks pass\" RQ-0001\n - Split a task:\n   ralph task split RQ-0001\n   ralph task split --number 3 RQ-0001\n\nCommand intent sections:\nCreate and build: task, build, refactor, build-refactor\nLifecycle: show, ready, status, done, reject, start, schedule\nEdit: field, edit, update\nRelationships: clone, split, relate, blocks, mark-duplicate, children, parent\nBatch and templates: batch, template"
53)]
54pub struct TaskArgs {
55    #[command(subcommand)]
56    pub command: Option<TaskCommand>,
57
58    #[command(flatten)]
59    pub build: TaskBuildArgs,
60}
61
62#[derive(Subcommand)]
63pub enum TaskCommand {
64    /// Build a new task from a natural language request.
65    #[command(
66        next_help_heading = "Create and build",
67        after_long_help = "Runner selection:\n - Override runner/model/effort for this invocation using flags.\n - Defaults come from config when flags are omitted.\n\nRunner CLI options:\n - Override approval/sandbox/verbosity/plan-mode via flags.\n - Unsupported options follow --unsupported-option-policy.\n\nExamples:\n ralph task \"Add integration tests for run one\"\n ralph task --tags cli,rust \"Refactor queue parsing\"\n ralph task --scope crates/ralph \"Fix queue graph output\"\n ralph task --runner opencode --model gpt-5.2 \"Add docs for OpenCode setup\"\n ralph task --runner gemini --model gemini-3-flash-preview \"Draft risk checklist\"\n ralph task --runner pi --model gpt-5.2 \"Draft risk checklist\"\n ralph task --runner codex --model gpt-5.4 --effort high \"Fix queue validation\"\n ralph task --approval-mode auto-edits --runner claude \"Audit approvals\"\n ralph task --sandbox disabled --runner codex \"Audit sandbox\"\n ralph task --repo-prompt plan \"Audit error handling\"\n ralph task --repo-prompt off \"Quick typo fix\"\n echo \"Triage flaky CI\" | ralph task --runner codex --model gpt-5.4 --effort medium\n\nExplicit subcommand:\n ralph task build \"Add integration tests for run one\""
68    )]
69    Build(TaskBuildArgs),
70
71    /// Automatically create refactoring tasks for large files.
72    #[command(
73        next_help_heading = "Create and build",
74        alias = "ref",
75        after_long_help = "Examples:\n ralph task refactor\n ralph task refactor --threshold 700\n ralph task refactor --path crates/ralph/src/cli\n ralph task refactor --dry-run --threshold 500\n ralph task refactor --batch never\n ralph task refactor --tags urgent,technical-debt\n ralph task ref --threshold 800"
76    )]
77    Refactor(TaskBuildRefactorArgs),
78
79    /// Automatically create refactoring tasks for large files (alternative to 'refactor').
80    #[command(
81        next_help_heading = "Create and build",
82        name = "build-refactor",
83        after_long_help = "Alternative command name. Prefer 'ralph task refactor'.\n\nExamples:\n ralph task build-refactor\n ralph task build-refactor --threshold 700"
84    )]
85    BuildRefactor(TaskBuildRefactorArgs),
86
87    /// Show a task by ID (queue + done).
88    #[command(
89        next_help_heading = "Lifecycle",
90        alias = "details",
91        after_long_help = "Examples:\n ralph task show RQ-0001\n ralph task details RQ-0001 --format compact"
92    )]
93    Show(TaskShowArgs),
94
95    /// Promote a draft task to todo.
96    #[command(
97        next_help_heading = "Lifecycle",
98        after_long_help = "Examples:\n ralph task ready RQ-0005\n ralph task ready --note \"Ready for implementation\" RQ-0005"
99    )]
100    Ready(TaskReadyArgs),
101
102    /// Update a task's status (draft, todo, doing, done, rejected).
103    ///
104    /// Note: terminal statuses (done, rejected) complete and archive the task.
105    #[command(
106        next_help_heading = "Lifecycle",
107        after_long_help = "Examples:\n ralph task status doing RQ-0001\n ralph task status doing --note \"Starting work\" RQ-0001\n ralph task status todo --note \"Back to backlog\" RQ-0001\n ralph task status done RQ-0001\n ralph task status rejected --note \"Invalid request\" RQ-0002"
108    )]
109    Status(TaskStatusArgs),
110
111    /// Complete a task as done and move it to the done archive.
112    #[command(
113        next_help_heading = "Lifecycle",
114        after_long_help = "Examples:\n ralph task done RQ-0001\n ralph task done --note \"Finished work\" --note \"make ci green\" RQ-0001"
115    )]
116    Done(TaskDoneArgs),
117
118    /// Complete a task as rejected and move it to the done archive.
119    #[command(
120        next_help_heading = "Lifecycle",
121        alias = "rejected",
122        after_long_help = "Examples:\n ralph task reject RQ-0002\n ralph task reject --note \"No longer needed\" RQ-0002"
123    )]
124    Reject(TaskRejectArgs),
125
126    /// Set a custom field on a task.
127    #[command(
128        next_help_heading = "Edit",
129        after_long_help = "Examples:\n ralph task field severity high RQ-0001\n ralph task field complexity \"O(n log n)\" RQ-0002"
130    )]
131    Field(TaskFieldArgs),
132
133    /// Edit any task field (default or custom).
134    ///
135    /// Side effect: When auto_archive_terminal_after_days is configured in the queue
136    /// settings, this command may auto-archive terminal tasks (Done/Rejected) that
137    /// are older than the configured threshold. The command output will list which
138    /// specific tasks were archived. Use --no-auto-archive to disable this behavior.
139    #[command(
140        next_help_heading = "Edit",
141        after_long_help = "Examples:\n ralph task edit title \"Clarify CLI edit\" RQ-0001\n ralph task edit status doing RQ-0001\n ralph task edit priority high RQ-0001\n ralph task edit tags \"cli, rust\" RQ-0001\n ralph task edit custom_fields \"severity=high, owner=ralph\" RQ-0001\n ralph task edit agent '{\"runner\":\"codex\",\"model\":\"gpt-5.4\",\"phases\":2}' RQ-0001\n ralph task edit request \"\" RQ-0001\n ralph task edit completed_at \"2026-01-20T12:00:00Z\" RQ-0001\n ralph task edit --dry-run title \"Preview change\" RQ-0001\n ralph task edit --no-auto-archive title \"Update without archiving\" RQ-0001"
142    )]
143    Edit(TaskEditArgs),
144
145    /// Update existing task fields based on current repository state.
146    #[command(
147        next_help_heading = "Edit",
148        after_long_help = "Runner selection:\n - Override runner/model/effort for this invocation using flags.\n - Defaults come from config when flags are omitted.\n\nRunner CLI options:\n - Override approval/sandbox/verbosity/plan-mode via flags.\n - Unsupported options follow --unsupported-option-policy.\n\nField selection:\n - By default, all updatable fields are refreshed: scope, evidence, plan, notes, tags, depends_on.\n - Use --fields to specify which fields to update.\n\nTask selection:\n - Omit TASK_ID to update every task in the active queue.\n\nExamples:\n ralph task update\n ralph task update RQ-0001\n ralph task update --fields scope,evidence,plan RQ-0001\n ralph task update --runner opencode --model gpt-5.2 RQ-0001\n ralph task update --approval-mode auto-edits --runner claude RQ-0001\n ralph task update --repo-prompt plan RQ-0001\n ralph task update --repo-prompt off --fields scope,evidence RQ-0001\n ralph task update --fields tags RQ-0042\n ralph task update --dry-run RQ-0001"
149    )]
150    Update(TaskUpdateArgs),
151
152    /// Manage task templates for common task types.
153    #[command(
154        next_help_heading = "Batch and templates",
155        after_long_help = "Examples:\n ralph task template list\n ralph task template show bug\n ralph task template show add-tests\n ralph task template build bug \"Fix login timeout\"\n ralph task template build add-tests src/module.rs \"Add tests for module\"\n ralph task template build refactor-performance src/bottleneck.rs \"Optimize performance\"\n\nAvailable templates:\n - bug: Bug fix with reproduction steps and regression tests\n - feature: New feature with design, implementation, and documentation\n - refactor: Code refactoring with behavior preservation\n - test: Test addition or improvement\n - docs: Documentation update or creation\n - add-tests: Add tests for existing code with coverage verification\n - refactor-performance: Optimize performance with profiling and benchmarking\n - fix-error-handling: Fix error handling with proper types and context\n - add-docs: Add documentation for a specific file or module\n - security-audit: Security audit with vulnerability checks"
156    )]
157    Template(TaskTemplateArgs),
158
159    /// Clone an existing task to create a new task from it.
160    #[command(
161        next_help_heading = "Relationships",
162        alias = "duplicate",
163        after_long_help = "Examples:\n ralph task clone RQ-0001\n ralph task clone RQ-0001 --status todo\n ralph task clone RQ-0001 --title-prefix \"[Follow-up] \"\n ralph task clone RQ-0001 --dry-run\n ralph task duplicate RQ-0001"
164    )]
165    Clone(TaskCloneArgs),
166
167    /// Perform batch operations on multiple tasks efficiently.
168    #[command(
169        next_help_heading = "Batch and templates",
170        after_long_help = "Examples:\n ralph task batch status doing RQ-0001 RQ-0002 RQ-0003\n ralph task batch status done --tag-filter ready\n ralph task batch field priority high --tag-filter urgent\n ralph task batch edit tags \"reviewed\" --tag-filter rust\n ralph task batch --dry-run status doing --tag-filter cli\n ralph task batch --continue-on-error status doing RQ-0001 RQ-0002 RQ-9999\n ralph task batch delete RQ-0001 RQ-0002\n ralph task batch delete --tag-filter stale --older-than 30d\n ralph task batch archive --tag-filter done --status-filter done\n ralph task batch clone --tag-filter template --status todo --title-prefix \"[Sprint] \"\n ralph task batch split --tag-filter epic --number 3 --distribute-plan\n ralph task batch plan-append --tag-filter rust --plan-item \"Run make ci\"\n ralph task batch plan-prepend RQ-0001 --plan-item \"Confirm repro\""
171    )]
172    Batch(TaskBatchArgs),
173
174    /// Schedule a task to start after a specific time.
175    #[command(
176        next_help_heading = "Lifecycle",
177        after_long_help = "Examples:\n ralph task schedule RQ-0001 '2026-02-01T09:00:00Z'\n ralph task schedule RQ-0001 'tomorrow 9am'\n ralph task schedule RQ-0001 'in 2 hours'\n ralph task schedule RQ-0001 'next monday'\n ralph task schedule RQ-0001 --clear"
178    )]
179    Schedule(TaskScheduleArgs),
180
181    /// Add a relationship between tasks.
182    #[command(
183        next_help_heading = "Relationships",
184        after_long_help = "Examples:\n ralph task relate RQ-0001 blocks RQ-0002\n ralph task relate RQ-0001 relates_to RQ-0003\n ralph task relate RQ-0001 duplicates RQ-0004"
185    )]
186    Relate(TaskRelateArgs),
187
188    /// Mark a task as blocking another task (shorthand for `relate <task> blocks <blocked>`).
189    #[command(
190        next_help_heading = "Relationships",
191        after_long_help = "Examples:\n ralph task blocks RQ-0001 RQ-0002\n ralph task blocks RQ-0001 RQ-0002 RQ-0003"
192    )]
193    Blocks(TaskBlocksArgs),
194
195    /// Mark a task as a duplicate of another task (shorthand for `relate <task> duplicates <original>`).
196    #[command(
197        next_help_heading = "Relationships",
198        name = "mark-duplicate",
199        after_long_help = "Examples:\n ralph task mark-duplicate RQ-0001 RQ-0002"
200    )]
201    MarkDuplicate(TaskMarkDuplicateArgs),
202
203    /// Split a task into multiple child tasks for better granularity.
204    #[command(
205        next_help_heading = "Relationships",
206        after_long_help = "Examples:\n ralph task split RQ-0001\n ralph task split --number 3 RQ-0001\n ralph task split --status todo --number 2 RQ-0001\n ralph task split --distribute-plan RQ-0001"
207    )]
208    Split(TaskSplitArgs),
209
210    /// Start work on a task (sets started_at and moves it to doing).
211    #[command(
212        next_help_heading = "Lifecycle",
213        after_long_help = "Examples:\n ralph task start RQ-0001\n ralph task start --reset RQ-0001"
214    )]
215    Start(TaskStartArgs),
216
217    /// List child tasks for a given task (based on parent_id).
218    #[command(
219        next_help_heading = "Relationships",
220        after_long_help = "Examples:\n ralph task children RQ-0001\n ralph task children RQ-0001 --recursive\n ralph task children RQ-0001 --include-done\n ralph task children RQ-0001 --format json"
221    )]
222    Children(TaskChildrenArgs),
223
224    /// Show the parent task for a given task (based on parent_id).
225    #[command(
226        next_help_heading = "Relationships",
227        after_long_help = "Examples:\n ralph task parent RQ-0002\n ralph task parent RQ-0002 --include-done\n ralph task parent RQ-0002 --format json"
228    )]
229    Parent(TaskParentArgs),
230
231    /// Build a task from a template with variable substitution.
232    ///
233    /// This is a convenience command that combines template selection,
234    /// variable substitution, and task creation in one step.
235    #[command(
236        name = "from",
237        next_help_heading = "Batch and templates",
238        after_long_help = "Examples:\n  ralph task from template bug --title \"Fix login timeout\"\n  ralph task from template feature --title \"Add dark mode\" --set target=src/ui/theme.rs\n  ralph task from template add-tests --title \"Test auth\" --set target=src/auth/mod.rs\n\nSee 'ralph task template list' for available templates."
239    )]
240    From(TaskFromArgs),
241}
ralph/cli/task/args/mod.rs

ralph/cli/task/args/
mod.rs
