hivemind/cli/
commands.rs

1//! CLI command definitions.
2//!
3//! All features are accessible via CLI. The UI is a projection, not a controller.
4
5use super::output::OutputFormat;
6use clap::{Args, Parser, Subcommand};
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
9pub enum RuntimeRoleArg {
10    Worker,
11    Validator,
12}
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
15pub enum RunModeArg {
16    Manual,
17    Auto,
18}
19
20#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
21pub enum MergeExecuteModeArg {
22    Local,
23    Pr,
24}
25
26/// Hivemind CLI - Structured orchestration for agentic coding workflows.
27#[derive(Parser)]
28#[command(name = "hivemind")]
29#[command(
30    version,
31    about,
32    long_about = "CLI-first orchestration for agentic coding workflows.\n\nStart with: docs/overview/quickstart.md"
33)]
34#[command(propagate_version = true)]
35pub struct Cli {
36    /// Output format
37    #[arg(long, short = 'f', global = true, default_value = "table")]
38    pub format: OutputFormat,
39
40    /// Verbose output
41    #[arg(long, short = 'v', global = true)]
42    pub verbose: bool,
43
44    #[command(subcommand)]
45    pub command: Option<Commands>,
46}
47
48/// Top-level commands.
49#[derive(Subcommand)]
50pub enum Commands {
51    /// Show version information
52    Version,
53
54    /// Run the HTTP server (API + UI)
55    Serve(ServeArgs),
56
57    /// Project management commands
58    #[command(subcommand)]
59    Project(ProjectCommands),
60
61    /// Global governance artifact registry commands
62    #[command(subcommand)]
63    Global(GlobalCommands),
64
65    /// Project constitution lifecycle and validation commands
66    #[command(subcommand)]
67    Constitution(ConstitutionCommands),
68
69    /// Task management commands
70    #[command(subcommand)]
71    Task(TaskCommands),
72
73    /// Task graphs (planning): define tasks + dependencies as a DAG
74    #[command(subcommand)]
75    Graph(GraphCommands),
76
77    /// Task flows (execution): run a graph using a configured runtime adapter
78    #[command(subcommand)]
79    Flow(FlowCommands),
80
81    /// Event inspection commands
82    #[command(subcommand)]
83    Events(EventCommands),
84
85    /// Runtime adapter discovery and health checks
86    #[command(subcommand)]
87    Runtime(RuntimeCommands),
88
89    /// Verification commands
90    #[command(subcommand)]
91    Verify(VerifyCommands),
92
93    /// Merge commands
94    #[command(subcommand)]
95    Merge(MergeCommands),
96
97    /// Attempt inspection commands
98    #[command(subcommand)]
99    Attempt(AttemptCommands),
100
101    /// Checkpoint lifecycle commands
102    #[command(subcommand)]
103    Checkpoint(CheckpointCommands),
104
105    /// Inspect and manage git worktrees used for task execution
106    #[command(subcommand)]
107    Worktree(WorktreeCommands),
108}
109
110/// Constitution subcommands.
111#[derive(Subcommand)]
112pub enum ConstitutionCommands {
113    /// Initialize a project constitution (requires explicit confirmation)
114    Init(ConstitutionInitArgs),
115    /// Show the current project constitution
116    Show(ConstitutionShowArgs),
117    /// Validate the current project constitution schema and semantics
118    Validate(ConstitutionValidateArgs),
119    /// Update the current project constitution (requires explicit confirmation)
120    Update(ConstitutionUpdateArgs),
121}
122
123#[derive(Args)]
124pub struct ConstitutionInitArgs {
125    /// Project ID or name
126    pub project: String,
127
128    /// Optional YAML content payload for initialization
129    #[arg(long, conflicts_with = "from_file")]
130    pub content: Option<String>,
131
132    /// Optional path to YAML constitution content
133    #[arg(long = "from-file", conflicts_with = "content")]
134    pub from_file: Option<String>,
135
136    /// Explicit confirmation gate for constitution mutation
137    #[arg(long, default_value_t = false)]
138    pub confirm: bool,
139
140    /// Optional actor attribution override (defaults to OS user)
141    #[arg(long)]
142    pub actor: Option<String>,
143
144    /// Optional mutation intent note for audit trail
145    #[arg(long)]
146    pub intent: Option<String>,
147}
148
149#[derive(Args)]
150pub struct ConstitutionShowArgs {
151    /// Project ID or name
152    pub project: String,
153}
154
155#[derive(Args)]
156pub struct ConstitutionValidateArgs {
157    /// Project ID or name
158    pub project: String,
159}
160
161#[derive(Args)]
162pub struct ConstitutionUpdateArgs {
163    /// Project ID or name
164    pub project: String,
165
166    /// Inline YAML constitution content
167    #[arg(long, conflicts_with = "from_file")]
168    pub content: Option<String>,
169
170    /// Path to YAML constitution content
171    #[arg(long = "from-file", conflicts_with = "content")]
172    pub from_file: Option<String>,
173
174    /// Explicit confirmation gate for constitution mutation
175    #[arg(long, default_value_t = false)]
176    pub confirm: bool,
177
178    /// Optional actor attribution override (defaults to OS user)
179    #[arg(long)]
180    pub actor: Option<String>,
181
182    /// Optional mutation intent note for audit trail
183    #[arg(long)]
184    pub intent: Option<String>,
185}
186
187/// Checkpoint subcommands.
188#[derive(Subcommand)]
189pub enum CheckpointCommands {
190    /// List checkpoints for an attempt
191    List(CheckpointListArgs),
192    /// Complete the currently active checkpoint for an attempt
193    Complete(CheckpointCompleteArgs),
194}
195
196/// Arguments for checkpoint listing.
197#[derive(Args)]
198pub struct CheckpointListArgs {
199    /// Attempt ID
200    pub attempt_id: String,
201}
202
203/// Arguments for checkpoint completion.
204#[derive(Args)]
205pub struct CheckpointCompleteArgs {
206    /// Attempt ID (optional when `HIVEMIND_ATTEMPT_ID` is set)
207    #[arg(long)]
208    pub attempt_id: Option<String>,
209
210    /// Checkpoint ID
211    #[arg(long = "id")]
212    pub checkpoint_id: String,
213
214    /// Optional completion summary
215    #[arg(long)]
216    pub summary: Option<String>,
217}
218
219#[derive(Args)]
220pub struct ServeArgs {
221    #[arg(long, default_value = "127.0.0.1")]
222    pub host: String,
223
224    #[arg(long, default_value_t = 8787)]
225    pub port: u16,
226
227    #[arg(long, default_value_t = 200)]
228    pub events_limit: usize,
229}
230
231#[derive(Subcommand)]
232pub enum WorktreeCommands {
233    /// List worktree status for each task in a flow
234    List(WorktreeListArgs),
235    /// Inspect the worktree path and git metadata for a single task
236    Inspect(WorktreeInspectArgs),
237    /// Remove worktrees for a flow (best-effort)
238    Cleanup(WorktreeCleanupArgs),
239}
240
241#[derive(Args)]
242pub struct WorktreeListArgs {
243    /// Flow ID
244    pub flow_id: String,
245}
246
247#[derive(Args)]
248pub struct WorktreeInspectArgs {
249    /// Task ID
250    pub task_id: String,
251}
252
253#[derive(Args)]
254pub struct WorktreeCleanupArgs {
255    /// Flow ID
256    pub flow_id: String,
257    /// Force cleanup when flow is still running
258    #[arg(long, default_value_t = false)]
259    pub force: bool,
260    /// Show what would be cleaned without removing worktrees
261    #[arg(long, default_value_t = false)]
262    pub dry_run: bool,
263}
264
265#[derive(Subcommand)]
266pub enum GraphCommands {
267    /// Create a new task graph from project tasks
268    Create(GraphCreateArgs),
269    /// Add a dependency edge to a draft graph (fails once graph is locked by a flow)
270    AddDependency(GraphAddDependencyArgs),
271    /// Add a verification check to a task in a draft graph
272    AddCheck(GraphAddCheckArgs),
273    /// Validate a graph for cycles and structural issues
274    Validate(GraphValidateArgs),
275    /// List graphs (optionally filtered by project)
276    List(GraphListArgs),
277}
278
279#[derive(Args)]
280pub struct GraphCreateArgs {
281    /// Project ID or name
282    pub project: String,
283    /// Human-friendly graph name
284    pub name: String,
285
286    /// Task IDs to include in the graph
287    #[arg(long, num_args = 1..)]
288    pub from_tasks: Vec<String>,
289}
290
291#[derive(Args)]
292pub struct GraphAddDependencyArgs {
293    /// Graph ID
294    pub graph_id: String,
295    /// Upstream task. Semantics: `to_task` depends on `from_task`.
296    pub from_task: String,
297    /// Downstream task that depends on `from_task`.
298    pub to_task: String,
299}
300
301#[derive(Args)]
302pub struct GraphAddCheckArgs {
303    /// Graph ID
304    pub graph_id: String,
305    /// Task ID within the graph
306    pub task_id: String,
307
308    /// Check name
309    #[arg(long)]
310    pub name: String,
311
312    /// Shell command to execute for the check
313    #[arg(long)]
314    pub command: String,
315
316    /// Whether this check is required for verification success
317    #[arg(long, default_value_t = true)]
318    pub required: bool,
319
320    /// Optional timeout in milliseconds for this check
321    #[arg(long)]
322    pub timeout_ms: Option<u64>,
323}
324
325#[derive(Args)]
326pub struct GraphValidateArgs {
327    /// Graph ID
328    pub graph_id: String,
329}
330
331#[derive(Args)]
332pub struct GraphListArgs {
333    /// Optional project ID or name to filter graphs
334    #[arg(long)]
335    pub project: Option<String>,
336}
337
338#[derive(Subcommand)]
339pub enum FlowCommands {
340    /// Create a new flow from a graph (locks the graph)
341    Create(FlowCreateArgs),
342    /// List flows (optionally filtered by project)
343    List(FlowListArgs),
344    /// Start a flow (transitions it into running state)
345    Start(FlowStartArgs),
346    /// Advance execution by one scheduling/execution step
347    Tick(FlowTickArgs),
348    /// Pause scheduling new tasks (running tasks may continue)
349    Pause(FlowPauseArgs),
350    /// Resume a paused flow
351    Resume(FlowResumeArgs),
352    /// Abort a flow
353    Abort(FlowAbortArgs),
354    /// Restart an aborted flow by creating a new flow from the same graph
355    Restart(FlowRestartArgs),
356    /// Show flow state and per-task execution state
357    Status(FlowStatusArgs),
358    /// Set flow run mode (`manual` or `auto`)
359    SetRunMode(FlowSetRunModeArgs),
360    /// Add a dependency between flows (`flow` depends on `depends_on_flow`)
361    AddDependency(FlowAddDependencyArgs),
362    /// Configure or clear a flow-level runtime default by role
363    RuntimeSet(FlowRuntimeSetArgs),
364}
365
366#[derive(Args)]
367pub struct FlowCreateArgs {
368    /// Graph ID
369    pub graph_id: String,
370    /// Optional flow name
371    #[arg(long)]
372    pub name: Option<String>,
373}
374
375#[derive(Args)]
376pub struct FlowListArgs {
377    /// Optional project ID or name to filter flows
378    #[arg(long)]
379    pub project: Option<String>,
380}
381
382#[derive(Args)]
383pub struct FlowStartArgs {
384    /// Flow ID
385    pub flow_id: String,
386}
387
388#[derive(Args)]
389pub struct FlowTickArgs {
390    /// Flow ID
391    pub flow_id: String,
392
393    /// Deprecated: interactive mode is no longer supported
394    #[arg(long)]
395    pub interactive: bool,
396
397    /// Override max tasks to schedule this tick (must be >= 1)
398    #[arg(long)]
399    pub max_parallel: Option<u16>,
400}
401
402#[derive(Args)]
403pub struct FlowPauseArgs {
404    /// Flow ID
405    pub flow_id: String,
406    /// If set, wait for running tasks to finish before returning
407    #[arg(long)]
408    pub wait: bool,
409}
410
411#[derive(Args)]
412pub struct FlowResumeArgs {
413    /// Flow ID
414    pub flow_id: String,
415}
416
417#[derive(Args)]
418pub struct FlowAbortArgs {
419    /// Flow ID
420    pub flow_id: String,
421    #[arg(long)]
422    pub force: bool,
423    #[arg(long)]
424    pub reason: Option<String>,
425}
426
427#[derive(Args)]
428pub struct FlowRestartArgs {
429    /// Aborted flow ID
430    pub flow_id: String,
431    /// Optional name for the restarted flow
432    #[arg(long)]
433    pub name: Option<String>,
434    /// Start the restarted flow immediately
435    #[arg(long, default_value_t = false)]
436    pub start: bool,
437}
438
439#[derive(Args)]
440pub struct FlowSetRunModeArgs {
441    /// Flow ID
442    pub flow_id: String,
443    /// Run mode
444    #[arg(value_enum)]
445    pub mode: RunModeArg,
446}
447
448#[derive(Args)]
449pub struct FlowAddDependencyArgs {
450    /// Dependent flow ID
451    pub flow_id: String,
452    /// Required upstream flow ID
453    pub depends_on_flow_id: String,
454}
455
456#[derive(Args)]
457pub struct FlowRuntimeSetArgs {
458    /// Flow ID
459    pub flow_id: String,
460
461    /// Clear existing flow-level runtime default for role
462    #[arg(long)]
463    pub clear: bool,
464
465    /// Runtime role
466    #[arg(long, value_enum, default_value = "worker")]
467    pub role: RuntimeRoleArg,
468
469    /// Runtime adapter name
470    #[arg(long, default_value = "opencode")]
471    pub adapter: String,
472
473    /// Path to runtime binary
474    #[arg(long, default_value = "opencode")]
475    pub binary_path: String,
476
477    /// Optional model identifier
478    #[arg(long)]
479    pub model: Option<String>,
480
481    /// Extra args to pass to runtime
482    #[arg(long = "arg", allow_hyphen_values = true)]
483    pub args: Vec<String>,
484
485    /// Extra environment variables in KEY=VALUE form
486    #[arg(long = "env")]
487    pub env: Vec<String>,
488
489    /// Execution timeout in milliseconds
490    #[arg(long, default_value = "600000")]
491    pub timeout_ms: u64,
492
493    /// Max number of tasks that may execute concurrently per flow tick
494    #[arg(long, default_value_t = 1)]
495    pub max_parallel_tasks: u16,
496}
497
498#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
499pub enum TaskRetryMode {
500    Clean,
501    Continue,
502}
503
504#[derive(Args)]
505pub struct TaskRetryArgs {
506    pub task_id: String,
507    #[arg(long)]
508    pub reset_count: bool,
509    #[arg(long, value_enum, default_value_t = TaskRetryMode::Clean)]
510    pub mode: TaskRetryMode,
511}
512
513#[derive(Args)]
514pub struct TaskAbortArgs {
515    /// Task ID
516    pub task_id: String,
517    /// Optional abort reason
518    #[arg(long)]
519    pub reason: Option<String>,
520}
521
522#[derive(Args)]
523pub struct FlowStatusArgs {
524    /// Flow ID
525    pub flow_id: String,
526}
527
528/// Project subcommands.
529#[derive(Subcommand)]
530pub enum ProjectCommands {
531    /// Create a new project
532    Create(ProjectCreateArgs),
533
534    /// List all projects
535    List,
536
537    /// Show project details
538    Inspect(ProjectInspectArgs),
539
540    /// Update a project
541    Update(ProjectUpdateArgs),
542
543    /// Configure the runtime adapter used to execute `TaskFlows`
544    RuntimeSet(ProjectRuntimeSetArgs),
545
546    /// Attach a repository to a project
547    AttachRepo(AttachRepoArgs),
548
549    /// Detach a repository from a project
550    DetachRepo(DetachRepoArgs),
551
552    /// Governance storage lifecycle commands
553    #[command(subcommand)]
554    Governance(ProjectGovernanceCommands),
555}
556
557/// Project governance subcommands.
558#[derive(Subcommand)]
559pub enum ProjectGovernanceCommands {
560    /// Initialize governance storage layout for a project
561    Init(ProjectGovernanceInitArgs),
562    /// Migrate legacy governance artifacts to the canonical global layout
563    Migrate(ProjectGovernanceMigrateArgs),
564    /// Inspect governance storage paths and projection metadata for a project
565    Inspect(ProjectGovernanceInspectArgs),
566    /// Project document lifecycle and metadata commands
567    #[command(subcommand)]
568    Document(ProjectGovernanceDocumentCommands),
569    /// Task-level document attachment inclusion/exclusion controls
570    #[command(subcommand)]
571    Attachment(ProjectGovernanceAttachmentCommands),
572    /// Project notepad lifecycle commands (non-executional)
573    #[command(subcommand)]
574    Notepad(ProjectGovernanceNotepadCommands),
575}
576
577/// Global governance artifact commands.
578#[derive(Subcommand)]
579pub enum GlobalCommands {
580    /// Global skill registry lifecycle commands
581    #[command(subcommand)]
582    Skill(GlobalSkillCommands),
583    /// Global system prompt registry lifecycle commands
584    #[command(subcommand)]
585    SystemPrompt(GlobalSystemPromptCommands),
586    /// Global template registry and instantiation commands
587    #[command(subcommand)]
588    Template(GlobalTemplateCommands),
589    /// Global notepad lifecycle commands (non-executional)
590    #[command(subcommand)]
591    Notepad(GlobalNotepadCommands),
592}
593
594#[derive(Subcommand)]
595pub enum ProjectGovernanceDocumentCommands {
596    /// Create a project document with metadata and revision history
597    Create(ProjectGovernanceDocumentCreateArgs),
598    /// List project documents
599    List(ProjectGovernanceDocumentListArgs),
600    /// Inspect a single project document and revision history
601    Inspect(ProjectGovernanceDocumentInspectArgs),
602    /// Update a project document (creates a new immutable revision)
603    Update(ProjectGovernanceDocumentUpdateArgs),
604    /// Delete a project document
605    Delete(ProjectGovernanceDocumentDeleteArgs),
606}
607
608#[derive(Args)]
609pub struct ProjectGovernanceDocumentCreateArgs {
610    /// Project ID or name
611    pub project: String,
612    /// Stable document identifier
613    pub document_id: String,
614    /// Human title for the document
615    #[arg(long)]
616    pub title: String,
617    /// Document owner metadata
618    #[arg(long)]
619    pub owner: String,
620    /// Tags (repeatable)
621    #[arg(long = "tag")]
622    pub tags: Vec<String>,
623    /// Document body content
624    #[arg(long)]
625    pub content: String,
626}
627
628#[derive(Args)]
629pub struct ProjectGovernanceDocumentListArgs {
630    /// Project ID or name
631    pub project: String,
632}
633
634#[derive(Args)]
635pub struct ProjectGovernanceDocumentInspectArgs {
636    /// Project ID or name
637    pub project: String,
638    /// Stable document identifier
639    pub document_id: String,
640}
641
642#[derive(Args)]
643pub struct ProjectGovernanceDocumentUpdateArgs {
644    /// Project ID or name
645    pub project: String,
646    /// Stable document identifier
647    pub document_id: String,
648    /// Optional title override
649    #[arg(long)]
650    pub title: Option<String>,
651    /// Optional owner override
652    #[arg(long)]
653    pub owner: Option<String>,
654    /// Optional tags override (repeatable, when provided)
655    #[arg(long = "tag")]
656    pub tags: Option<Vec<String>>,
657    /// Optional content update (creates next revision)
658    #[arg(long)]
659    pub content: Option<String>,
660}
661
662#[derive(Args)]
663pub struct ProjectGovernanceDocumentDeleteArgs {
664    /// Project ID or name
665    pub project: String,
666    /// Stable document identifier
667    pub document_id: String,
668}
669
670#[derive(Subcommand)]
671pub enum ProjectGovernanceAttachmentCommands {
672    /// Explicitly include a project document for task execution context
673    Include(ProjectGovernanceAttachmentSetArgs),
674    /// Explicitly exclude a project document from task execution context
675    Exclude(ProjectGovernanceAttachmentSetArgs),
676}
677
678#[derive(Args)]
679pub struct ProjectGovernanceAttachmentSetArgs {
680    /// Project ID or name
681    pub project: String,
682    /// Task ID
683    pub task_id: String,
684    /// Document identifier
685    pub document_id: String,
686}
687
688#[derive(Subcommand)]
689pub enum ProjectGovernanceNotepadCommands {
690    /// Create project notepad content
691    Create(ProjectGovernanceNotepadCreateArgs),
692    /// Show project notepad content
693    Show(ProjectGovernanceNotepadShowArgs),
694    /// Update project notepad content
695    Update(ProjectGovernanceNotepadUpdateArgs),
696    /// Delete project notepad content
697    Delete(ProjectGovernanceNotepadDeleteArgs),
698}
699
700#[derive(Args)]
701pub struct ProjectGovernanceNotepadCreateArgs {
702    /// Project ID or name
703    pub project: String,
704    /// Notepad content
705    #[arg(long)]
706    pub content: String,
707}
708
709#[derive(Args)]
710pub struct ProjectGovernanceNotepadShowArgs {
711    /// Project ID or name
712    pub project: String,
713}
714
715#[derive(Args)]
716pub struct ProjectGovernanceNotepadUpdateArgs {
717    /// Project ID or name
718    pub project: String,
719    /// Notepad content
720    #[arg(long)]
721    pub content: String,
722}
723
724#[derive(Args)]
725pub struct ProjectGovernanceNotepadDeleteArgs {
726    /// Project ID or name
727    pub project: String,
728}
729
730#[derive(Subcommand)]
731pub enum GlobalSkillCommands {
732    /// Create a global reusable skill artifact
733    Create(GlobalSkillCreateArgs),
734    /// List global skill artifacts
735    List,
736    /// Inspect a single global skill artifact
737    Inspect(GlobalSkillInspectArgs),
738    /// Update a global skill artifact
739    Update(GlobalSkillUpdateArgs),
740    /// Delete a global skill artifact
741    Delete(GlobalSkillDeleteArgs),
742}
743
744#[derive(Args)]
745pub struct GlobalSkillCreateArgs {
746    /// Skill identifier
747    pub skill_id: String,
748    /// Skill display name
749    #[arg(long)]
750    pub name: String,
751    /// Skill body content
752    #[arg(long)]
753    pub content: String,
754    /// Skill tags (repeatable)
755    #[arg(long = "tag")]
756    pub tags: Vec<String>,
757}
758
759#[derive(Args)]
760pub struct GlobalSkillInspectArgs {
761    /// Skill identifier
762    pub skill_id: String,
763}
764
765#[derive(Args)]
766pub struct GlobalSkillUpdateArgs {
767    /// Skill identifier
768    pub skill_id: String,
769    /// Optional display name update
770    #[arg(long)]
771    pub name: Option<String>,
772    /// Optional content update
773    #[arg(long)]
774    pub content: Option<String>,
775    /// Optional tags update (repeatable, when provided)
776    #[arg(long = "tag")]
777    pub tags: Option<Vec<String>>,
778}
779
780#[derive(Args)]
781pub struct GlobalSkillDeleteArgs {
782    /// Skill identifier
783    pub skill_id: String,
784}
785
786#[derive(Subcommand)]
787pub enum GlobalSystemPromptCommands {
788    /// Create a global system prompt artifact
789    Create(GlobalSystemPromptCreateArgs),
790    /// List global system prompt artifacts
791    List,
792    /// Inspect a global system prompt artifact
793    Inspect(GlobalSystemPromptInspectArgs),
794    /// Update a global system prompt artifact
795    Update(GlobalSystemPromptUpdateArgs),
796    /// Delete a global system prompt artifact
797    Delete(GlobalSystemPromptDeleteArgs),
798}
799
800#[derive(Args)]
801pub struct GlobalSystemPromptCreateArgs {
802    /// System prompt identifier
803    pub prompt_id: String,
804    /// System prompt body content
805    #[arg(long)]
806    pub content: String,
807}
808
809#[derive(Args)]
810pub struct GlobalSystemPromptInspectArgs {
811    /// System prompt identifier
812    pub prompt_id: String,
813}
814
815#[derive(Args)]
816pub struct GlobalSystemPromptUpdateArgs {
817    /// System prompt identifier
818    pub prompt_id: String,
819    /// Updated prompt body content
820    #[arg(long)]
821    pub content: String,
822}
823
824#[derive(Args)]
825pub struct GlobalSystemPromptDeleteArgs {
826    /// System prompt identifier
827    pub prompt_id: String,
828}
829
830#[derive(Subcommand)]
831pub enum GlobalTemplateCommands {
832    /// Create a global template artifact
833    Create(GlobalTemplateCreateArgs),
834    /// List global template artifacts
835    List,
836    /// Inspect a global template artifact
837    Inspect(GlobalTemplateInspectArgs),
838    /// Update a global template artifact
839    Update(GlobalTemplateUpdateArgs),
840    /// Delete a global template artifact
841    Delete(GlobalTemplateDeleteArgs),
842    /// Instantiate template references for a project and emit resolved artifact event
843    Instantiate(GlobalTemplateInstantiateArgs),
844}
845
846#[derive(Args)]
847pub struct GlobalTemplateCreateArgs {
848    /// Template identifier
849    pub template_id: String,
850    /// Required global system prompt identifier
851    #[arg(long)]
852    pub system_prompt_id: String,
853    /// Referenced global skill identifiers (repeatable)
854    #[arg(long = "skill-id")]
855    pub skill_ids: Vec<String>,
856    /// Referenced project document identifiers (repeatable)
857    #[arg(long = "document-id")]
858    pub document_ids: Vec<String>,
859    /// Optional template description/body
860    #[arg(long)]
861    pub description: Option<String>,
862}
863
864#[derive(Args)]
865pub struct GlobalTemplateInspectArgs {
866    /// Template identifier
867    pub template_id: String,
868}
869
870#[derive(Args)]
871pub struct GlobalTemplateUpdateArgs {
872    /// Template identifier
873    pub template_id: String,
874    /// Optional system prompt identifier override
875    #[arg(long)]
876    pub system_prompt_id: Option<String>,
877    /// Optional skill identifiers override (repeatable, when provided)
878    #[arg(long = "skill-id")]
879    pub skill_ids: Option<Vec<String>>,
880    /// Optional document identifiers override (repeatable, when provided)
881    #[arg(long = "document-id")]
882    pub document_ids: Option<Vec<String>>,
883    /// Optional template description/body override
884    #[arg(long)]
885    pub description: Option<String>,
886}
887
888#[derive(Args)]
889pub struct GlobalTemplateDeleteArgs {
890    /// Template identifier
891    pub template_id: String,
892}
893
894#[derive(Args)]
895pub struct GlobalTemplateInstantiateArgs {
896    /// Project ID or name used for document resolution
897    pub project: String,
898    /// Template identifier
899    pub template_id: String,
900}
901
902#[derive(Subcommand)]
903pub enum GlobalNotepadCommands {
904    /// Create global notepad content
905    Create(GlobalNotepadCreateArgs),
906    /// Show global notepad content
907    Show,
908    /// Update global notepad content
909    Update(GlobalNotepadUpdateArgs),
910    /// Delete global notepad content
911    Delete,
912}
913
914#[derive(Args)]
915pub struct GlobalNotepadCreateArgs {
916    /// Notepad content
917    #[arg(long)]
918    pub content: String,
919}
920
921#[derive(Args)]
922pub struct GlobalNotepadUpdateArgs {
923    /// Notepad content
924    #[arg(long)]
925    pub content: String,
926}
927
928#[derive(Args)]
929pub struct ProjectGovernanceInitArgs {
930    /// Project ID or name
931    pub project: String,
932}
933
934#[derive(Args)]
935pub struct ProjectGovernanceMigrateArgs {
936    /// Project ID or name
937    pub project: String,
938}
939
940#[derive(Args)]
941pub struct ProjectGovernanceInspectArgs {
942    /// Project ID or name
943    pub project: String,
944}
945
946/// Arguments for project create.
947#[derive(Args)]
948pub struct ProjectCreateArgs {
949    /// Project name
950    pub name: String,
951
952    /// Project description
953    #[arg(long, short = 'd')]
954    pub description: Option<String>,
955}
956
957#[derive(Args)]
958pub struct ProjectRuntimeSetArgs {
959    /// Project ID or name
960    pub project: String,
961
962    /// Runtime adapter name (default: opencode)
963    #[arg(long, default_value = "opencode")]
964    pub adapter: String,
965
966    /// Path to the runtime binary (default: opencode)
967    #[arg(long, default_value = "opencode")]
968    pub binary_path: String,
969
970    /// Optional model identifier for the runtime (adapter-specific)
971    #[arg(long)]
972    pub model: Option<String>,
973
974    /// Extra args to pass to the runtime (repeatable)
975    #[arg(long = "arg", allow_hyphen_values = true)]
976    pub args: Vec<String>,
977
978    /// Extra environment variables for the runtime in KEY=VALUE form (repeatable).
979    /// Empty keys are rejected, empty values are allowed (KEY=), and duplicate keys use the last value.
980    #[arg(long = "env")]
981    pub env: Vec<String>,
982
983    /// Execution timeout in milliseconds
984    #[arg(long, default_value = "600000")]
985    pub timeout_ms: u64,
986
987    /// Max number of tasks that may execute concurrently per flow tick
988    #[arg(long, default_value_t = 1)]
989    pub max_parallel_tasks: u16,
990
991    /// Runtime role
992    #[arg(long, value_enum, default_value = "worker")]
993    pub role: RuntimeRoleArg,
994}
995
996/// Arguments for project inspect.
997#[derive(Args)]
998pub struct ProjectInspectArgs {
999    /// Project ID or name
1000    pub project: String,
1001}
1002
1003/// Arguments for project update.
1004#[derive(Args)]
1005pub struct ProjectUpdateArgs {
1006    /// Project ID or name
1007    pub project: String,
1008
1009    /// New name
1010    #[arg(long)]
1011    pub name: Option<String>,
1012
1013    /// New description
1014    #[arg(long, short = 'd')]
1015    pub description: Option<String>,
1016}
1017
1018/// Arguments for attaching a repository.
1019#[derive(Args)]
1020pub struct AttachRepoArgs {
1021    /// Project ID or name
1022    pub project: String,
1023
1024    /// Path to the git repository
1025    pub path: String,
1026
1027    /// Optional repository name override
1028    #[arg(long)]
1029    pub name: Option<String>,
1030
1031    /// Access mode (ro|rw)
1032    #[arg(long, default_value = "rw")]
1033    pub access: String,
1034}
1035
1036/// Arguments for detaching a repository.
1037#[derive(Args)]
1038pub struct DetachRepoArgs {
1039    /// Project ID or name
1040    pub project: String,
1041
1042    /// Repository name
1043    pub repo_name: String,
1044}
1045
1046/// Task subcommands.
1047#[derive(Subcommand)]
1048pub enum TaskCommands {
1049    /// Create a new task
1050    Create(TaskCreateArgs),
1051
1052    /// List tasks in a project
1053    List(TaskListArgs),
1054
1055    /// Show task details
1056    Inspect(TaskInspectArgs),
1057
1058    /// Update a task
1059    Update(TaskUpdateArgs),
1060
1061    /// Configure or clear a task-level runtime override
1062    RuntimeSet(TaskRuntimeSetArgs),
1063
1064    /// Close a task
1065    Close(TaskCloseArgs),
1066
1067    /// Start executing a ready task
1068    Start(TaskStartArgs),
1069    /// Mark a running task as complete
1070    Complete(TaskCompleteArgs),
1071
1072    /// Request a retry for a failed task
1073    Retry(TaskRetryArgs),
1074    /// Abort a task within its flow
1075    Abort(TaskAbortArgs),
1076    /// Set task run mode (`manual` or `auto`)
1077    SetRunMode(TaskSetRunModeArgs),
1078}
1079
1080#[derive(Args)]
1081pub struct TaskStartArgs {
1082    /// Task ID
1083    pub task_id: String,
1084}
1085
1086#[derive(Args)]
1087pub struct TaskCompleteArgs {
1088    /// Task ID
1089    pub task_id: String,
1090}
1091
1092/// Arguments for task create.
1093#[derive(Args)]
1094pub struct TaskCreateArgs {
1095    /// Project ID or name
1096    pub project: String,
1097
1098    /// Task title
1099    pub title: String,
1100
1101    /// Task description
1102    #[arg(long, short = 'd')]
1103    pub description: Option<String>,
1104
1105    /// Scope contract as a JSON string.
1106    /// Required shape: {"filesystem":{"rules":[...]},"repositories":[],"git":{"permissions":[]},"execution":{"allowed":[],"denied":[]}}
1107    #[arg(long)]
1108    pub scope: Option<String>,
1109}
1110
1111/// Arguments for task list.
1112#[derive(Args)]
1113pub struct TaskListArgs {
1114    /// Project ID or name
1115    pub project: String,
1116
1117    /// Filter by state
1118    #[arg(long)]
1119    pub state: Option<String>,
1120}
1121
1122/// Arguments for task inspect.
1123#[derive(Args)]
1124pub struct TaskInspectArgs {
1125    /// Task ID
1126    pub task_id: String,
1127}
1128
1129/// Arguments for task update.
1130#[derive(Args)]
1131pub struct TaskUpdateArgs {
1132    /// Task ID
1133    pub task_id: String,
1134
1135    /// New title
1136    #[arg(long)]
1137    pub title: Option<String>,
1138
1139    /// New description
1140    #[arg(long, short = 'd')]
1141    pub description: Option<String>,
1142}
1143
1144/// Arguments for task runtime override.
1145#[derive(Args)]
1146pub struct TaskRuntimeSetArgs {
1147    /// Task ID
1148    pub task_id: String,
1149
1150    /// Clear any existing task runtime override
1151    #[arg(long)]
1152    pub clear: bool,
1153
1154    /// Runtime adapter name
1155    #[arg(long, default_value = "opencode")]
1156    pub adapter: String,
1157
1158    /// Path to runtime binary
1159    #[arg(long, default_value = "opencode")]
1160    pub binary_path: String,
1161
1162    /// Optional model identifier
1163    #[arg(long)]
1164    pub model: Option<String>,
1165
1166    /// Extra args to pass to runtime
1167    #[arg(long = "arg", allow_hyphen_values = true)]
1168    pub args: Vec<String>,
1169
1170    /// Extra environment variables in KEY=VALUE form
1171    #[arg(long = "env")]
1172    pub env: Vec<String>,
1173
1174    /// Execution timeout in milliseconds
1175    #[arg(long, default_value = "600000")]
1176    pub timeout_ms: u64,
1177
1178    /// Runtime role
1179    #[arg(long, value_enum, default_value = "worker")]
1180    pub role: RuntimeRoleArg,
1181}
1182
1183#[derive(Args)]
1184pub struct TaskSetRunModeArgs {
1185    /// Task ID
1186    pub task_id: String,
1187    /// Run mode
1188    #[arg(value_enum)]
1189    pub mode: RunModeArg,
1190}
1191
1192/// Runtime subcommands.
1193#[derive(Subcommand)]
1194pub enum RuntimeCommands {
1195    /// List built-in runtime adapters and local availability
1196    List,
1197    /// Run runtime adapter health checks
1198    Health(RuntimeHealthArgs),
1199    /// Configure global runtime defaults by role
1200    DefaultsSet(RuntimeDefaultsSetArgs),
1201}
1202
1203/// Arguments for runtime health checks.
1204#[derive(Args)]
1205pub struct RuntimeHealthArgs {
1206    /// Optional project ID or name to health-check configured runtime
1207    #[arg(long)]
1208    pub project: Option<String>,
1209
1210    /// Optional task ID to health-check effective runtime (task override or project default)
1211    #[arg(long)]
1212    pub task: Option<String>,
1213
1214    /// Optional flow ID to health-check effective runtime defaults
1215    #[arg(long)]
1216    pub flow: Option<String>,
1217
1218    /// Runtime role to evaluate
1219    #[arg(long, value_enum, default_value = "worker")]
1220    pub role: RuntimeRoleArg,
1221}
1222
1223#[derive(Args)]
1224pub struct RuntimeDefaultsSetArgs {
1225    /// Runtime role
1226    #[arg(long, value_enum, default_value = "worker")]
1227    pub role: RuntimeRoleArg,
1228
1229    /// Runtime adapter name
1230    #[arg(long, default_value = "opencode")]
1231    pub adapter: String,
1232
1233    /// Path to the runtime binary
1234    #[arg(long, default_value = "opencode")]
1235    pub binary_path: String,
1236
1237    /// Optional model identifier for the runtime
1238    #[arg(long)]
1239    pub model: Option<String>,
1240
1241    /// Extra args to pass to the runtime (repeatable)
1242    #[arg(long = "arg", allow_hyphen_values = true)]
1243    pub args: Vec<String>,
1244
1245    /// Extra environment variables for the runtime in KEY=VALUE form (repeatable)
1246    #[arg(long = "env")]
1247    pub env: Vec<String>,
1248
1249    /// Execution timeout in milliseconds
1250    #[arg(long, default_value = "600000")]
1251    pub timeout_ms: u64,
1252
1253    /// Max number of tasks that may execute concurrently per flow tick
1254    #[arg(long, default_value_t = 1)]
1255    pub max_parallel_tasks: u16,
1256}
1257
1258/// Arguments for task close.
1259#[derive(Args)]
1260pub struct TaskCloseArgs {
1261    /// Task ID
1262    pub task_id: String,
1263
1264    /// Optional reason
1265    #[arg(long)]
1266    pub reason: Option<String>,
1267}
1268
1269/// Event subcommands.
1270#[derive(Subcommand)]
1271pub enum EventCommands {
1272    /// List events
1273    List(EventListArgs),
1274
1275    /// Show event details
1276    Inspect(EventInspectArgs),
1277
1278    /// Stream events with filters
1279    Stream(EventStreamArgs),
1280
1281    /// Replay events to reconstruct state
1282    Replay(EventReplayArgs),
1283}
1284
1285/// Arguments for event list.
1286#[derive(Args)]
1287pub struct EventListArgs {
1288    /// Filter by project
1289    #[arg(long)]
1290    pub project: Option<String>,
1291
1292    /// Filter by graph ID
1293    #[arg(long)]
1294    pub graph: Option<String>,
1295
1296    /// Filter by flow ID
1297    #[arg(long)]
1298    pub flow: Option<String>,
1299
1300    /// Filter by task ID
1301    #[arg(long)]
1302    pub task: Option<String>,
1303
1304    /// Filter by attempt ID
1305    #[arg(long)]
1306    pub attempt: Option<String>,
1307
1308    /// Lower bound timestamp (RFC3339), inclusive
1309    #[arg(long)]
1310    pub since: Option<String>,
1311
1312    /// Upper bound timestamp (RFC3339), inclusive
1313    #[arg(long)]
1314    pub until: Option<String>,
1315
1316    /// Maximum number of events
1317    #[arg(long, default_value = "50")]
1318    pub limit: usize,
1319}
1320
1321/// Arguments for event inspect.
1322#[derive(Args)]
1323pub struct EventInspectArgs {
1324    /// Event ID
1325    pub event_id: String,
1326}
1327
1328/// Arguments for event stream.
1329#[derive(Args)]
1330pub struct EventStreamArgs {
1331    /// Filter by flow ID
1332    #[arg(long)]
1333    pub flow: Option<String>,
1334
1335    /// Filter by task ID
1336    #[arg(long)]
1337    pub task: Option<String>,
1338
1339    /// Filter by project
1340    #[arg(long)]
1341    pub project: Option<String>,
1342
1343    /// Filter by graph ID
1344    #[arg(long)]
1345    pub graph: Option<String>,
1346
1347    /// Filter by attempt ID
1348    #[arg(long)]
1349    pub attempt: Option<String>,
1350
1351    /// Lower bound timestamp (RFC3339), inclusive
1352    #[arg(long)]
1353    pub since: Option<String>,
1354
1355    /// Upper bound timestamp (RFC3339), inclusive
1356    #[arg(long)]
1357    pub until: Option<String>,
1358
1359    /// Maximum number of events
1360    #[arg(long, default_value = "100")]
1361    pub limit: usize,
1362}
1363
1364/// Arguments for event replay.
1365#[derive(Args)]
1366pub struct EventReplayArgs {
1367    /// Flow ID to replay
1368    pub flow_id: String,
1369
1370    /// Verify replayed state against current state
1371    #[arg(long)]
1372    pub verify: bool,
1373}
1374
1375/// Verify subcommands.
1376#[derive(Subcommand)]
1377pub enum VerifyCommands {
1378    /// Apply a human override to verification outcome for a task
1379    Override(VerifyOverrideArgs),
1380
1381    /// Manually trigger verification for a task in an active flow
1382    Run(VerifyRunArgs),
1383
1384    /// Show verification results for an attempt
1385    Results(VerifyResultsArgs),
1386}
1387
1388/// Arguments for verify override.
1389#[derive(Args)]
1390pub struct VerifyOverrideArgs {
1391    /// Task ID
1392    pub task_id: String,
1393
1394    /// Decision: pass or fail
1395    pub decision: String,
1396
1397    /// Reason for override
1398    #[arg(long)]
1399    pub reason: String,
1400}
1401
1402#[derive(Args)]
1403pub struct VerifyRunArgs {
1404    /// Task ID
1405    pub task_id: String,
1406}
1407
1408#[derive(Args)]
1409pub struct VerifyResultsArgs {
1410    /// Attempt ID
1411    pub attempt_id: String,
1412
1413    /// Include full check output payloads
1414    #[arg(long)]
1415    pub output: bool,
1416}
1417
1418/// Merge subcommands.
1419#[derive(Subcommand)]
1420pub enum MergeCommands {
1421    #[command(
1422        about = "Prepare a completed flow for integration (sandbox merge)",
1423        long_about = "Prepare a completed flow for merge by building an integration sandbox, applying successful task branches, and running required integration checks before approval."
1424    )]
1425    Prepare(MergePrepareArgs),
1426
1427    #[command(
1428        about = "Approve a prepared merge (explicit human gate)",
1429        long_about = "Record the approving HUMAN user (HIVEMIND_USER or USER), ensure no unresolved conflicts/check failures remain, and emit MergeApproved so execute can proceed."
1430    )]
1431    Approve(MergeApproveArgs),
1432
1433    #[command(
1434        about = "Execute an approved merge (fast-forward target)",
1435        long_about = "Acquire the per-flow integration lock and fast-forward the chosen target branch from integration/<flow>/prepare, then clean up integration/<flow>/prepare, integration/<flow>/<task>, _integration_prepare, and exec branches. Emits MergeCompleted."
1436    )]
1437    Execute(MergeExecuteArgs),
1438}
1439
1440/// Arguments for merge prepare.
1441#[derive(Args)]
1442pub struct MergePrepareArgs {
1443    /// Flow ID
1444    pub flow_id: String,
1445
1446    /// Target branch (set explicitly if your default branch is not 'main')
1447    #[arg(long)]
1448    pub target: Option<String>,
1449}
1450
1451/// Arguments for merge approve.
1452#[derive(Args)]
1453pub struct MergeApproveArgs {
1454    /// Flow ID
1455    pub flow_id: String,
1456}
1457
1458/// Arguments for merge execute.
1459#[derive(Args)]
1460pub struct MergeExecuteArgs {
1461    /// Flow ID
1462    pub flow_id: String,
1463
1464    /// Merge execution mode (`local` or `pr`)
1465    #[arg(long, value_enum, default_value = "local")]
1466    pub mode: MergeExecuteModeArg,
1467
1468    /// For `pr` mode: wait for CI checks to complete
1469    #[arg(long)]
1470    pub monitor_ci: bool,
1471
1472    /// For `pr` mode: request automatic squash merge
1473    #[arg(long)]
1474    pub auto_merge: bool,
1475
1476    /// After merge, pull target branch from origin
1477    #[arg(long)]
1478    pub pull_after: bool,
1479}
1480
1481/// Attempt subcommands.
1482#[derive(Subcommand)]
1483pub enum AttemptCommands {
1484    /// List attempts (optionally filtered)
1485    List(AttemptListArgs),
1486    /// Inspect an attempt
1487    Inspect(AttemptInspectArgs),
1488}
1489
1490/// Arguments for attempt list.
1491#[derive(Args)]
1492pub struct AttemptListArgs {
1493    /// Optional flow ID filter
1494    #[arg(long)]
1495    pub flow: Option<String>,
1496    /// Optional task ID filter
1497    #[arg(long)]
1498    pub task: Option<String>,
1499    /// Maximum number of attempts
1500    #[arg(long, default_value = "50")]
1501    pub limit: usize,
1502}
1503
1504/// Arguments for attempt inspect.
1505#[derive(Args)]
1506pub struct AttemptInspectArgs {
1507    /// Attempt ID
1508    pub attempt_id: String,
1509
1510    /// Show retry context
1511    #[arg(long)]
1512    pub context: bool,
1513
1514    /// Show changes diff
1515    #[arg(long)]
1516    pub diff: bool,
1517
1518    /// Show runtime output
1519    #[arg(long)]
1520    pub output: bool,
1521}
hivemind/cli/commands.rs

hivemind/cli/
commands.rs
