starweaver_cli/
args.rs

1//! CLI argument parsing.
2
3use std::ffi::OsString;
4
5use clap::{Args, CommandFactory, Parser, Subcommand, ValueEnum};
6use clap_complete::Shell;
7use serde::{Deserialize, Serialize};
8
9use crate::{CliError, CliResult};
10
11/// Top-level CLI.
12#[derive(Clone, Debug, Parser)]
13#[command(name = "starweaver-cli", version, about = "Starweaver local CLI")]
14pub struct Cli {
15    /// Prompt shorthand for headless runs.
16    #[arg(short = 'p', long = "prompt", global = false)]
17    pub prompt: Option<String>,
18    /// Append a run to the selected session.
19    #[arg(
20        short = 's',
21        long,
22        global = false,
23        conflicts_with_all = ["new_session", "continue_session"]
24    )]
25    pub session: Option<String>,
26    /// Continue the latest local session.
27    #[arg(long = "continue", global = false, conflicts_with = "new_session")]
28    pub continue_session: bool,
29    /// Create a fresh session.
30    #[arg(long, global = false)]
31    pub new_session: bool,
32    /// Restore from a specific run before appending a run.
33    #[arg(long, global = false)]
34    pub run: Option<String>,
35    /// Branch from a specific run before appending a run.
36    #[arg(long, global = false, conflicts_with = "run")]
37    pub branch_from: Option<String>,
38    /// Agent profile name or YAML path.
39    #[arg(long, global = false)]
40    pub profile: Option<String>,
41    /// Enable worker mode or set an optional worker label.
42    #[arg(long, global = false, num_args = 0..=1, default_missing_value = "true")]
43    pub worker: Option<String>,
44    /// Explicit worker label.
45    #[arg(long = "worker-label", global = false)]
46    pub worker_label: Option<String>,
47    /// Enable a git worktree or set an optional worktree name/path.
48    #[arg(
49        short = 'w',
50        long,
51        global = false,
52        num_args = 0..=1,
53        default_missing_value = "true"
54    )]
55    pub worktree: Option<String>,
56    /// Explicit worktree name/path.
57    #[arg(long = "worktree-name", global = false)]
58    pub worktree_name: Option<String>,
59    /// Git branch for worktree metadata.
60    #[arg(long, global = false)]
61    pub branch: Option<String>,
62    /// Output mode.
63    #[arg(long, global = false)]
64    pub output: Option<OutputMode>,
65    /// Headless human-in-the-loop policy for prompt shorthand.
66    #[arg(long, global = false)]
67    pub hitl: Option<HitlPolicy>,
68    /// Override local store database path.
69    #[arg(long, global = true)]
70    pub store: Option<String>,
71    /// Optional subcommand.
72    #[command(subcommand)]
73    pub command: Option<CliCommand>,
74}
75
76/// CLI command families.
77#[allow(clippy::large_enum_variant)]
78#[derive(Clone, Debug, Subcommand)]
79pub enum CliCommand {
80    /// Print SDK identity.
81    Version,
82    /// Run a prompt.
83    Run(RunCommand),
84    /// Manage local sessions.
85    Session {
86        /// Session subcommand.
87        #[command(subcommand)]
88        command: SessionCommand,
89    },
90    /// Manage agent profiles.
91    Profile {
92        /// Profile subcommand.
93        #[command(subcommand)]
94        command: ProfileCommand,
95    },
96    /// Initialize local CLI configuration and catalogs.
97    Setup(SetupCommand),
98    /// Inspect OAuth-backed provider authentication.
99    Auth {
100        /// Auth subcommand.
101        #[command(subcommand)]
102        command: AuthCommand,
103    },
104    /// Inspect configured skills.
105    Skill {
106        /// Skill subcommand.
107        #[command(subcommand)]
108        command: CatalogCommand,
109    },
110    /// Inspect configured subagents.
111    Subagent {
112        /// Subagent subcommand.
113        #[command(subcommand)]
114        command: CatalogCommand,
115    },
116    /// Inspect configured MCP servers.
117    Mcp {
118        /// MCP subcommand.
119        #[command(subcommand)]
120        command: CatalogCommand,
121    },
122    /// Inspect default CLI tool catalog and policy.
123    Tools {
124        /// Tools subcommand.
125        #[command(subcommand)]
126        command: ToolsCommand,
127    },
128    /// Render a retained terminal UI from local session display messages.
129    Tui(TuiCommand),
130    /// Manage persisted approval requests.
131    Approval {
132        /// Approval subcommand.
133        #[command(subcommand)]
134        command: ApprovalCommand,
135    },
136    /// Manage deferred tool calls.
137    Deferred {
138        /// Deferred subcommand.
139        #[command(subcommand)]
140        command: DeferredCommand,
141    },
142    /// Resume a waiting session by appending a continuation run.
143    Resume(ResumeCommand),
144    /// Remove runtime session state while preserving configuration.
145    Reset(ResetCommand),
146    /// Print diagnostics.
147    Diagnostics,
148    /// Run the JSON-RPC host service.
149    Rpc(RpcCommand),
150    /// Print replay-check guidance.
151    ReplayCheck,
152    /// Update installed Starweaver components.
153    Update(UpdateCommand),
154    /// Get or set configuration values.
155    Config {
156        /// Config subcommand.
157        #[command(subcommand)]
158        command: ConfigCommand,
159    },
160    /// Generate shell completion scripts.
161    Completion {
162        /// Target shell.
163        shell: Shell,
164    },
165}
166
167/// Prompt run command.
168#[derive(Clone, Debug, Args)]
169pub struct RunCommand {
170    /// Prompt text.
171    #[arg(short = 'p', long = "prompt")]
172    pub prompt: Option<String>,
173    /// Positional prompt text.
174    pub prompt_parts: Vec<String>,
175    /// Append a run to the selected session.
176    #[arg(short = 's', conflicts_with_all = ["new_session", "continue_session"], long)]
177    pub session: Option<String>,
178    /// Continue the latest local session.
179    #[arg(long = "continue", conflicts_with = "new_session")]
180    pub continue_session: bool,
181    /// Create a fresh session.
182    #[arg(long)]
183    pub new_session: bool,
184    /// Restore from a specific run before appending a run.
185    #[arg(long)]
186    pub run: Option<String>,
187    /// Branch from a specific run before appending a run.
188    #[arg(long, conflicts_with = "run")]
189    pub branch_from: Option<String>,
190    /// Agent profile name or YAML path.
191    #[arg(long)]
192    pub profile: Option<String>,
193    /// Enable worker mode or set an optional worker label.
194    #[arg(long, num_args = 0..=1, default_missing_value = "true")]
195    pub worker: Option<String>,
196    /// Explicit worker label.
197    #[arg(long = "worker-label")]
198    pub worker_label: Option<String>,
199    /// Enable a git worktree or set an optional worktree name/path.
200    #[arg(short = 'w', long, num_args = 0..=1, default_missing_value = "true")]
201    pub worktree: Option<String>,
202    /// Explicit worktree name/path.
203    #[arg(long = "worktree-name")]
204    pub worktree_name: Option<String>,
205    /// Git branch for worktree metadata.
206    #[arg(long)]
207    pub branch: Option<String>,
208    /// Output mode.
209    #[arg(long)]
210    pub output: Option<OutputMode>,
211    /// Headless human-in-the-loop policy.
212    #[arg(long)]
213    pub hitl: Option<HitlPolicy>,
214    /// Internal runtime goal-mode options.
215    #[arg(skip)]
216    pub goal: Option<GoalCommandOptions>,
217    /// Internal stable provider-routing affinity id.
218    #[arg(skip)]
219    pub session_affinity_id: Option<String>,
220    /// Internal host RPC environment attachments.
221    #[arg(skip)]
222    pub environment_attachments: Vec<starweaver_rpc_core::EnvironmentAttachmentRef>,
223}
224
225/// Internal goal-mode options attached by product surfaces such as the TUI.
226#[derive(Clone, Debug, Eq, PartialEq)]
227pub struct GoalCommandOptions {
228    /// Goal objective.
229    pub objective: String,
230    /// Maximum runtime goal retry iterations.
231    pub max_iterations: usize,
232}
233
234impl RunCommand {
235    /// Return prompt text.
236    pub fn prompt_text(&self) -> CliResult<String> {
237        let prompt = self
238            .prompt
239            .clone()
240            .unwrap_or_else(|| self.prompt_parts.join(" "));
241        if prompt.trim().is_empty() {
242            Err(CliError::Usage(
243                "usage: starweaver-cli run -p <prompt>".to_string(),
244            ))
245        } else {
246            Ok(prompt)
247        }
248    }
249}
250
251/// Compact session commands.
252#[derive(Clone, Debug, Subcommand)]
253pub enum SessionCommand {
254    /// List local sessions.
255    List(SessionListCommand),
256    /// Show one session with recent runs.
257    Show(SessionShowCommand),
258    /// Replay stored display messages.
259    Replay(SessionReplayCommand),
260    /// Delete one local session and its retained evidence.
261    Delete(SessionDeleteCommand),
262    /// Trim retained run evidence.
263    Trim(SessionTrimCommand),
264}
265
266/// Session list command.
267#[derive(Clone, Debug, Args)]
268pub struct SessionListCommand {
269    /// Output mode.
270    #[arg(long, default_value = "display-jsonl")]
271    pub output: OutputMode,
272    /// Maximum sessions to show.
273    #[arg(long, default_value_t = 50)]
274    pub limit: usize,
275}
276
277/// Session show command.
278#[derive(Clone, Debug, Args)]
279pub struct SessionShowCommand {
280    /// Session id.
281    pub session_id: String,
282    /// Output mode.
283    #[arg(long, default_value = "display-jsonl")]
284    pub output: OutputMode,
285    /// Recent run limit.
286    #[arg(long, default_value_t = 20)]
287    pub runs: usize,
288}
289
290/// Session replay command.
291#[derive(Clone, Debug, Args)]
292pub struct SessionReplayCommand {
293    /// Session id.
294    pub session_id: String,
295    /// Optional run id.
296    #[arg(long)]
297    pub run: Option<String>,
298    /// Cursor sequence to replay after.
299    #[arg(long)]
300    pub after: Option<usize>,
301    /// Output mode.
302    #[arg(long, default_value = "display-jsonl")]
303    pub output: OutputMode,
304}
305
306/// Session delete command.
307#[derive(Clone, Debug, Args)]
308pub struct SessionDeleteCommand {
309    /// Session id or unique prefix.
310    pub session_id: String,
311    /// Confirm deletion.
312    #[arg(long)]
313    pub yes: bool,
314    /// Output mode.
315    #[arg(long, default_value = "text")]
316    pub output: OutputMode,
317}
318
319/// Session trim command.
320#[derive(Clone, Debug, Args)]
321pub struct SessionTrimCommand {
322    /// Trim current session.
323    #[arg(long)]
324    pub current: bool,
325    /// Trim all sessions.
326    #[arg(long)]
327    pub all: bool,
328    /// Trim a selected session.
329    #[arg(long)]
330    pub session: Option<String>,
331    /// Retain this many recent runs per session.
332    #[arg(long, default_value_t = 20)]
333    pub keep_runs: usize,
334    /// Trim runs older than a duration such as 7d, 24h, or 3600s.
335    #[arg(long)]
336    pub older_than: Option<String>,
337    /// Preview trim results.
338    #[arg(long)]
339    pub dry_run: bool,
340    /// Output mode.
341    #[arg(long, default_value = "display-jsonl")]
342    pub output: OutputMode,
343}
344
345/// Profile commands.
346#[derive(Clone, Debug, Subcommand)]
347pub enum ProfileCommand {
348    /// List built-in and configured profiles.
349    List,
350    /// Show one built-in or configured profile.
351    Show { name: String },
352}
353
354/// Setup command.
355#[derive(Clone, Debug, Args)]
356pub struct SetupCommand {
357    /// Initialize global configuration only.
358    #[arg(long, conflicts_with = "project")]
359    pub global: bool,
360    /// Initialize project configuration only.
361    #[arg(long)]
362    pub project: bool,
363    /// Replace existing generated files.
364    #[arg(long)]
365    pub force: bool,
366}
367
368/// Auth commands.
369#[derive(Clone, Debug, Subcommand)]
370pub enum AuthCommand {
371    /// Log in to an OAuth provider.
372    Login(AuthProviderCommand),
373    /// Print provider auth status.
374    Status(AuthStatusCommand),
375    /// Refresh provider credentials.
376    Refresh(AuthProviderCommand),
377    /// Remove provider credentials from the local auth store.
378    Logout(AuthLogoutCommand),
379    /// Inspect OAuth store health without printing tokens.
380    Doctor(AuthDoctorCommand),
381}
382
383/// Provider-scoped auth command.
384#[derive(Clone, Debug, Args)]
385pub struct AuthProviderCommand {
386    /// Provider name.
387    #[arg(default_value = "codex", value_parser = ["codex"])]
388    pub provider: String,
389    /// Auth file path. Defaults to ~/.starweaver/auth.json.
390    #[arg(long = "auth-file")]
391    pub auth_file: Option<String>,
392    /// Device authorization timeout in seconds.
393    #[arg(long, default_value_t = 15 * 60)]
394    pub timeout_seconds: u64,
395}
396
397/// Auth status command.
398#[derive(Clone, Debug, Args)]
399pub struct AuthStatusCommand {
400    /// Provider name.
401    #[arg(default_value = "codex", value_parser = ["codex"])]
402    pub provider: Option<String>,
403    /// Auth file path. Defaults to ~/.starweaver/auth.json.
404    #[arg(long = "auth-file")]
405    pub auth_file: Option<String>,
406}
407
408/// Auth logout command.
409#[derive(Clone, Debug, Args)]
410pub struct AuthLogoutCommand {
411    /// Provider name.
412    #[arg(default_value = "codex", value_parser = ["codex"])]
413    pub provider: String,
414    /// Auth file path. Defaults to ~/.starweaver/auth.json.
415    #[arg(long = "auth-file")]
416    pub auth_file: Option<String>,
417    /// Revoke provider tokens before deleting local credentials.
418    #[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
419    pub revoke: bool,
420}
421
422/// Auth doctor command.
423#[derive(Clone, Debug, Args)]
424pub struct AuthDoctorCommand {
425    /// Auth file path. Defaults to ~/.starweaver/auth.json.
426    #[arg(long = "auth-file")]
427    pub auth_file: Option<String>,
428}
429
430/// Catalog inspection commands.
431#[derive(Clone, Debug, Subcommand)]
432pub enum CatalogCommand {
433    /// List configured entries.
434    List,
435    /// Show one configured entry.
436    Show { name: String },
437    /// Validate configured entries and print findings.
438    Doctor,
439}
440
441/// Tool catalog commands.
442#[derive(Clone, Debug, Subcommand)]
443pub enum ToolsCommand {
444    /// List default first-party tools.
445    List,
446    /// Validate tool policy and default catalog.
447    Doctor,
448}
449
450/// TUI command.
451#[derive(Clone, Debug, Args)]
452pub struct TuiCommand {
453    /// Session id to render. Omit for a clean welcome screen.
454    #[arg(long)]
455    pub session: Option<String>,
456    /// Optional run id to render.
457    #[arg(long)]
458    pub run: Option<String>,
459    /// Render only messages after this display cursor.
460    #[arg(long)]
461    pub after: Option<usize>,
462    /// Force interactive terminal UI when stdout is a TTY.
463    #[arg(long)]
464    pub interactive: bool,
465    /// Force deterministic snapshot output for scripts and tests.
466    #[arg(long, conflicts_with = "interactive")]
467    pub snapshot: bool,
468    /// Output mode for non-interactive TUI snapshots.
469    #[arg(long, default_value = "text")]
470    pub output: OutputMode,
471    /// Transcript rendering mode for interactive TUI.
472    #[arg(long = "render-mode")]
473    pub render_mode: Option<TuiRenderMode>,
474}
475
476/// Approval commands.
477#[derive(Clone, Debug, Subcommand)]
478pub enum ApprovalCommand {
479    /// List persisted approval records.
480    List(ApprovalListCommand),
481    /// Show one approval record.
482    Show { approval_id: String },
483    /// Approve one pending approval record.
484    Approve(ApprovalDecisionCommand),
485    /// Reject one pending approval record.
486    Reject(ApprovalDecisionCommand),
487}
488
489/// Approval list command.
490#[derive(Clone, Debug, Args)]
491pub struct ApprovalListCommand {
492    /// Filter by session id.
493    #[arg(long)]
494    pub session: Option<String>,
495    /// Filter by run id.
496    #[arg(long)]
497    pub run: Option<String>,
498    /// Output mode.
499    #[arg(long, default_value = "display-jsonl")]
500    pub output: OutputMode,
501}
502
503/// Approval decision command.
504#[derive(Clone, Debug, Args)]
505pub struct ApprovalDecisionCommand {
506    /// Approval id.
507    pub approval_id: String,
508    /// Decision reason.
509    #[arg(long)]
510    pub reason: Option<String>,
511    /// Output mode.
512    #[arg(long, default_value = "text")]
513    pub output: OutputMode,
514}
515
516/// Deferred tool commands.
517#[derive(Clone, Debug, Subcommand)]
518pub enum DeferredCommand {
519    /// List persisted deferred tool records.
520    List(DeferredListCommand),
521    /// Show one deferred tool record.
522    Show { deferred_id: String },
523    /// Complete one deferred tool record with a JSON result payload.
524    Complete(DeferredCompleteCommand),
525    /// Fail one deferred tool record with an error message.
526    Fail(DeferredFailCommand),
527}
528
529/// Deferred list command.
530#[derive(Clone, Debug, Args)]
531pub struct DeferredListCommand {
532    /// Filter by session id.
533    #[arg(long)]
534    pub session: Option<String>,
535    /// Filter by run id.
536    #[arg(long)]
537    pub run: Option<String>,
538    /// Output mode.
539    #[arg(long, default_value = "display-jsonl")]
540    pub output: OutputMode,
541}
542
543/// Deferred complete command.
544#[derive(Clone, Debug, Args)]
545pub struct DeferredCompleteCommand {
546    /// Deferred id.
547    pub deferred_id: String,
548    /// JSON result payload.
549    #[arg(long)]
550    pub result: String,
551    /// Output mode.
552    #[arg(long, default_value = "text")]
553    pub output: OutputMode,
554}
555
556/// Deferred failure command.
557#[derive(Clone, Debug, Args)]
558pub struct DeferredFailCommand {
559    /// Deferred id.
560    pub deferred_id: String,
561    /// Error message.
562    #[arg(long)]
563    pub error: String,
564    /// Output mode.
565    #[arg(long, default_value = "text")]
566    pub output: OutputMode,
567}
568
569/// Resume command.
570#[derive(Clone, Debug, Args)]
571pub struct ResumeCommand {
572    /// Session id to resume. Defaults to current or latest session.
573    #[arg(long)]
574    pub session: Option<String>,
575    /// Run id to resume from. Defaults to the session active or head run.
576    #[arg(long)]
577    pub run: Option<String>,
578    /// Prompt to append for the continuation run.
579    #[arg(short = 'p', long = "prompt", default_value = "resume waiting run")]
580    pub prompt: String,
581    /// Output mode.
582    #[arg(long)]
583    pub output: Option<OutputMode>,
584    /// Headless human-in-the-loop policy.
585    #[arg(long)]
586    pub hitl: Option<HitlPolicy>,
587}
588
589/// Reset command.
590#[derive(Clone, Debug, Args)]
591pub struct ResetCommand {
592    /// Confirm runtime state removal.
593    #[arg(long)]
594    pub yes: bool,
595    /// Output mode.
596    #[arg(long, default_value = "text")]
597    pub output: OutputMode,
598}
599
600/// RPC runtime command.
601#[derive(Clone, Debug, Args)]
602pub struct RpcCommand {
603    /// Runtime transport.
604    #[arg(default_value = "stdio")]
605    pub transport: RpcTransport,
606    /// HTTP bind host.
607    #[arg(long, default_value = "127.0.0.1")]
608    pub host: String,
609    /// HTTP bind port.
610    #[arg(long, default_value_t = 8765)]
611    pub port: u16,
612}
613
614/// RPC runtime transport.
615#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
616#[serde(rename_all = "kebab-case")]
617pub enum RpcTransport {
618    /// Newline-delimited JSON-RPC over stdin/stdout.
619    #[default]
620    Stdio,
621    /// JSON-RPC request/response over HTTP.
622    Http,
623}
624
625/// Update command.
626#[derive(Clone, Debug, Args)]
627pub struct UpdateCommand {
628    /// Update target, defaults to cli.
629    #[arg(default_value = "cli")]
630    pub target: String,
631    /// Print the update plan without downloading or installing.
632    #[arg(long)]
633    pub dry_run: bool,
634    /// Reinstall even when the selected release matches the current version.
635    #[arg(long, short = 'f')]
636    pub force: bool,
637}
638
639/// Config commands.
640#[derive(Clone, Debug, Subcommand)]
641pub enum ConfigCommand {
642    /// Initialize a Starweaver config file.
643    Init {
644        /// Write the global config file.
645        #[arg(long, conflicts_with = "project")]
646        global: bool,
647        /// Write the project config file.
648        #[arg(long)]
649        project: bool,
650        /// Replace an existing config file.
651        #[arg(long)]
652        force: bool,
653    },
654    /// Get a resolved config value.
655    Get { key: String },
656    /// Set a config value.
657    Set {
658        /// Write the global config file.
659        #[arg(long, conflicts_with = "project")]
660        global: bool,
661        /// Write the project config file.
662        #[arg(long)]
663        project: bool,
664        /// Config key.
665        key: String,
666        /// Config value.
667        value: String,
668    },
669}
670
671/// TUI transcript render mode.
672#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
673#[serde(rename_all = "kebab-case")]
674pub enum TuiRenderMode {
675    /// Show assistant text, reasoning, tool calls, and tool returns.
676    #[default]
677    Normal,
678    /// Hide ordinary tool calls from transcript while keeping high-level events.
679    Concise,
680    /// Show detailed diagnostic rendering.
681    Debug,
682}
683
684/// Output mode.
685#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
686#[serde(rename_all = "kebab-case")]
687pub enum OutputMode {
688    /// Human-readable text.
689    Text,
690    /// Starweaver durable `DisplayMessage` JSON lines.
691    #[default]
692    DisplayJsonl,
693    /// Starweaver/AGUI top-level event JSON lines.
694    AguiJsonl,
695    /// Compact JSON command result.
696    Json,
697    /// Persist and print compact status.
698    Silent,
699}
700
701/// HITL policy.
702#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
703#[serde(rename_all = "snake_case")]
704pub enum HitlPolicy {
705    /// Deny approvals.
706    Deny,
707    /// Defer approvals.
708    Defer,
709    /// Fail on approvals.
710    Fail,
711    /// Prompt interactively.
712    #[default]
713    Prompt,
714}
715
716/// Build the clap command schema.
717#[must_use]
718pub fn command() -> clap::Command {
719    Cli::command()
720}
721
722/// Parse CLI arguments.
723pub fn parse(args: impl IntoIterator<Item = String>) -> CliResult<Cli> {
724    Cli::try_parse_from(args).map_err(|error| clap_error(&error))
725}
726
727/// Parse CLI arguments from OS strings.
728#[allow(dead_code)]
729pub fn parse_os(args: impl IntoIterator<Item = OsString>) -> CliResult<Cli> {
730    Cli::try_parse_from(args).map_err(|error| clap_error(&error))
731}
732
733fn clap_error(error: &clap::Error) -> CliError {
734    match error.kind() {
735        clap::error::ErrorKind::DisplayHelp | clap::error::ErrorKind::DisplayVersion => {
736            CliError::Display(error.to_string())
737        }
738        _ => CliError::Usage(error.to_string()),
739    }
740}
starweaver_cli/args.rs

starweaver_cli/
args.rs
