Skip to main content

ironbridge/
cli.rs

1// Copyright (c) 2024-2026 Nervosys LLC
2// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-IronBridge-Commercial
3//! CLI argument definitions using clap derive macros
4
5use clap::{Parser, Subcommand};
6
7/// CHAt System Manager (ironbridge) - Manage and merge chat sessions across workspaces
8#[derive(Parser)]
9#[command(name = "ironbridge")]
10#[command(author = "Nervosys")]
11#[command(version)]
12#[command(about = "Manage and merge chat sessions across workspaces", long_about = None)]
13pub struct Cli {
14    #[command(subcommand)]
15    pub command: Commands,
16}
17
18#[derive(Subcommand)]
19pub enum Commands {
20    // ============================================================================
21    // List Commands
22    // ============================================================================
23    /// List workspaces, sessions, or paths
24    #[command(visible_alias = "ls")]
25    List {
26        #[command(subcommand)]
27        command: Option<ListCommands>,
28    },
29
30    // ============================================================================
31    // Find Commands
32    // ============================================================================
33    /// Search workspaces or sessions by text pattern (title, content, ID)
34    Find {
35        #[command(subcommand)]
36        command: Option<FindCommands>,
37    },
38
39    // ============================================================================
40    // Show Commands
41    // ============================================================================
42    /// Show workspaces, sessions, or paths
43    #[command(visible_alias = "info")]
44    Show {
45        #[command(subcommand)]
46        command: Option<ShowCommands>,
47    },
48
49    // ============================================================================
50    // Fetch Commands
51    // ============================================================================
52    /// Fetch chat sessions from workspaces, sessions, or paths
53    Fetch {
54        #[command(subcommand)]
55        command: Option<FetchCommands>,
56    },
57
58    // ============================================================================
59    // Merge Commands
60    // ============================================================================
61    /// Merge chat sessions from workspaces, sessions, or paths
62    Merge {
63        #[command(subcommand)]
64        command: Option<MergeCommands>,
65    },
66
67    // ============================================================================
68    // Export Commands
69    // ============================================================================
70    /// Export chat sessions from workspaces, sessions, or paths
71    Export {
72        #[command(subcommand)]
73        command: Option<ExportCommands>,
74    },
75
76    // ============================================================================
77    // Import Commands
78    // ============================================================================
79    /// Import session files from external directories into a workspace
80    Import {
81        #[command(subcommand)]
82        command: Option<ImportCommands>,
83    },
84
85    // ============================================================================
86    // Move Commands
87    // ============================================================================
88    /// Move chat sessions between workspaces
89    #[command(visible_alias = "mv")]
90    Move {
91        #[command(subcommand)]
92        command: Option<MoveCommands>,
93    },
94
95    // ============================================================================
96    // Git Integration Commands
97    // ============================================================================
98    /// Git integration for chat session versioning
99    Git {
100        #[command(subcommand)]
101        command: GitCommands,
102    },
103
104    // ============================================================================
105    // Migration Commands
106    // ============================================================================
107    /// Migration commands for moving chat sessions between machines
108    Migration {
109        #[command(subcommand)]
110        command: MigrationCommands,
111    },
112
113    // ============================================================================
114    // Run Commands (Agent Launcher + TUI)
115    // ============================================================================
116    /// Launch an AI coding agent with auto-save, or run interactive tools
117    ///
118    /// Supported agents: claude, open, claw, cursor, codex, droid, gemini
119    Run {
120        #[command(subcommand)]
121        command: RunCommands,
122    },
123
124    // ============================================================================
125    // Watch Command (File-System Monitor)
126    // ============================================================================
127    /// Watch agent session directories for changes and auto-harvest
128    ///
129    /// Monitors session storage paths for new or modified files.
130    /// Default: watches all known agent directories.
131    #[command(visible_alias = "w")]
132    Watch {
133        /// Watch a specific agent's session directory (e.g., claude, gemini)
134        #[arg(short, long)]
135        agent: Option<String>,
136
137        /// Watch a custom path instead of agent directories
138        #[arg(short, long)]
139        path: Option<String>,
140
141        /// Debounce interval in seconds before harvesting (default: 3)
142        #[arg(short, long, default_value = "3")]
143        debounce: u64,
144
145        /// Detect changes without harvesting (dry-run)
146        #[arg(long)]
147        no_harvest: bool,
148
149        /// Show detailed file change events
150        #[arg(short, long)]
151        verbose: bool,
152    },
153
154    // ============================================================================
155    // Provider Commands
156    // ============================================================================
157    /// Manage LLM providers (Ollama, vLLM, Foundry, Cursor, etc.)
158    Provider {
159        #[command(subcommand)]
160        command: ProviderCommands,
161    },
162
163    // ============================================================================
164    // Detect Commands
165    // ============================================================================
166    /// Auto-detect workspace and provider information
167    Detect {
168        #[command(subcommand)]
169        command: Option<DetectCommands>,
170    },
171
172    // ============================================================================
173    // Analyze Commands
174    // ============================================================================
175    /// Analyze a session's topics, sentiment and key points
176    ///
177    /// Uses a language model when OPENAI_API_KEY is set, and offline
178    /// heuristics otherwise. The output always states which one ran.
179    Analyze {
180        /// Session file to analyze (.json or .jsonl)
181        file: String,
182
183        /// Emit the analysis as JSON
184        #[arg(long)]
185        json: bool,
186
187        /// Fail instead of falling back to heuristics when the model is
188        /// unavailable, for callers that must not receive keyword counts
189        #[arg(long)]
190        require_model: bool,
191    },
192
193    // ============================================================================
194    // Register Commands
195    // ============================================================================
196    /// Add on-disk sessions to VS Code's database index (makes orphaned sessions visible)
197    Register {
198        #[command(subcommand)]
199        command: RegisterCommands,
200    },
201
202    // ============================================================================
203    // Sync Commands (shortcut to harvest sync)
204    // ============================================================================
205    /// Sync sessions between the harvest database and provider workspaces
206    Sync {
207        /// Path to the harvest database
208        #[arg(long)]
209        path: Option<String>,
210
211        /// Push sessions from database to provider workspaces (restore)
212        #[arg(long)]
213        push: bool,
214
215        /// Pull sessions from provider workspaces into database (backup)
216        #[arg(long)]
217        pull: bool,
218
219        /// Filter by provider name
220        #[arg(long)]
221        provider: Option<String>,
222
223        /// Filter by workspace/project path
224        #[arg(long)]
225        workspace: Option<String>,
226
227        /// Session IDs to sync (space-separated)
228        #[arg(long, num_args = 1..)]
229        sessions: Option<Vec<String>>,
230
231        /// Target format for push: auto (detect from provider), jsonl, json
232        #[arg(long, default_value = "auto")]
233        format: String,
234
235        /// Overwrite existing files without prompting
236        #[arg(long)]
237        force: bool,
238
239        /// Dry run - show what would be synced without making changes
240        #[arg(long)]
241        dry_run: bool,
242    },
243
244    // ============================================================================
245    // Harvest Commands
246    // ============================================================================
247    /// Harvest chat sessions from all providers into a unified database
248    Harvest {
249        #[command(subcommand)]
250        command: HarvestCommands,
251    },
252
253    // ============================================================================
254    // Recover Commands
255    // ============================================================================
256    /// Recover lost chat sessions from backups, recording state, or corrupted files
257    #[command(visible_alias = "restore")]
258    Recover {
259        #[command(subcommand)]
260        command: RecoverCommands,
261    },
262
263    // ============================================================================
264    // API Server Commands
265    // ============================================================================
266    /// Start the HTTP API server for the web frontend
267    #[command(visible_alias = "serve")]
268    Api {
269        #[command(subcommand)]
270        command: ApiCommands,
271    },
272
273    // ============================================================================
274    // Agency Commands
275    // ============================================================================
276    /// Agent Development Kit - manage agents and orchestration
277    Agency {
278        #[command(subcommand)]
279        command: AgencyCommands,
280    },
281
282    // ============================================================================
283    // Telemetry Commands
284    // ============================================================================
285    /// Manage anonymous usage data collection (opt-in by default)
286    Telemetry {
287        #[command(subcommand)]
288        command: Option<TelemetryCommands>,
289    },
290
291    // ============================================================================
292    // Completions Command
293    // ============================================================================
294    /// Generate shell completions for bash, zsh, fish, or PowerShell
295    Completions {
296        /// Shell to generate completions for
297        #[arg(value_enum)]
298        shell: CompletionShell,
299    },
300
301    // ============================================================================
302    // Shard Commands
303    // ============================================================================
304    /// Split oversized sessions into linked shards (by request count or file size)
305    Shard {
306        #[command(subcommand)]
307        command: ShardCommands,
308    },
309
310    // ============================================================================
311    // Doctor Command
312    // ============================================================================
313    /// Check system environment, providers, and configuration health
314    #[command(visible_alias = "check")]
315    Doctor {
316        /// Run all checks including network connectivity
317        #[arg(long)]
318        full: bool,
319
320        /// Output format: text, json
321        #[arg(long, default_value = "text")]
322        format: String,
323
324        /// Attempt to fix detected issues automatically
325        #[arg(long)]
326        fix: bool,
327
328        /// Skip the session-file scan, which is the slow part on large stores
329        #[arg(long)]
330        quick: bool,
331    },
332
333    // ============================================================================
334    // Inspect Commands
335    // ============================================================================
336    /// Inspect VS Code state databases, session indices, caches, and file validity
337    Inspect {
338        #[command(subcommand)]
339        command: InspectCommands,
340    },
341
342    // ============================================================================
343    // Schema Commands
344    // ============================================================================
345    /// Database schema registry, version detection, ontology, and cross-provider mappings
346    ///
347    /// Provides persistent schema definitions for every known AI chat provider format,
348    /// an ontology for AI agent discovery, and backwards compatibility guarantees.
349    Schema {
350        #[command(subcommand)]
351        command: SchemaCommands,
352    },
353
354    // ============================================================================
355    // SDK Commands
356    // ============================================================================
357    /// Generate a single-file API client for Python, Node.js, Go, Rust, Java, C#, Ruby, or PHP
358    Sdk {
359        #[command(subcommand)]
360        command: SdkCommands,
361    },
362
363    // ============================================================================
364    // Internal Commands (hidden)
365    // ============================================================================
366    /// Internal commands used by ironbridge background processes
367    #[command(hide = true)]
368    Internal {
369        #[command(subcommand)]
370        command: InternalCommands,
371    },
372
373    // ============================================================================
374    // Easter Egg
375    // ============================================================================
376    /// Show banner
377    #[command(hide = true)]
378    Banner,
379}
380
381// ============================================================================
382// SDK Subcommands
383// ============================================================================
384
385#[derive(Subcommand)]
386pub enum SdkCommands {
387    /// List the languages a client can be generated for
388    List {
389        /// Output as JSON
390        #[arg(long)]
391        json: bool,
392    },
393
394    /// Write a client for one language, or for every language with --all
395    #[command(visible_alias = "gen")]
396    Generate {
397        /// Language to generate; omit and pass --all for every language
398        #[arg(value_enum)]
399        language: Option<crate::api::sdk::SdkLanguage>,
400
401        /// Generate every supported language
402        #[arg(long, conflicts_with = "language")]
403        all: bool,
404
405        /// Directory to write into (created if absent). Defaults to the current directory
406        #[arg(short, long)]
407        output: Option<String>,
408
409        /// Write to stdout instead of a file; requires a single language
410        #[arg(long, conflicts_with = "output")]
411        stdout: bool,
412
413        /// Base URL baked into the generated client as its fallback
414        #[arg(long, default_value = "http://localhost:8787")]
415        base_url: String,
416
417        /// Overwrite existing files rather than refusing
418        #[arg(long)]
419        force: bool,
420    },
421}
422
423// ============================================================================
424// Internal Subcommands (hidden, used by background processes)
425// ============================================================================
426
427#[derive(Subcommand)]
428pub enum InternalCommands {
429    /// Re-apply a pending session registration after VS Code exits
430    ApplyPending {
431        /// Path to the pending registration JSON file
432        pending_file: String,
433    },
434}
435
436// ============================================================================
437// List Subcommands
438// ============================================================================
439
440#[derive(Subcommand)]
441pub enum ListCommands {
442    /// List all VS Code workspaces
443    #[command(visible_alias = "ws")]
444    Workspaces,
445
446    /// List all chat sessions
447    #[command(visible_alias = "s")]
448    Sessions {
449        /// Filter by project path
450        #[arg(long)]
451        project_path: Option<String>,
452
453        /// Show file sizes
454        #[arg(long, short = 's')]
455        size: bool,
456
457        /// Filter by provider (vscode, cursor, cursorcli, claudecode, codexcli, geminicli, antigravitycli, copilotcli, opencode, openclaw, antigravity, qwencode, pi, goose, cline, roocode, kilocode, windsurf, trae)
458        #[arg(long, short = 'p')]
459        provider: Option<String>,
460
461        /// Include all providers
462        #[arg(long)]
463        all_providers: bool,
464    },
465
466    /// List available AI coding agents and their installation status
467    #[command(visible_alias = "a")]
468    Agents,
469
470    /// List agent mode sessions (Copilot Edits / chatEditingSessions)
471    #[command(visible_alias = "e")]
472    Edits {
473        /// Filter by project path
474        #[arg(long)]
475        project_path: Option<String>,
476
477        /// Show file sizes
478        #[arg(long, short = 's')]
479        size: bool,
480
481        /// Filter by provider (vscode, cursor, cursorcli, claudecode, codexcli, geminicli, antigravitycli, copilotcli, opencode, openclaw, antigravity, qwencode, pi, goose, cline, roocode, kilocode, windsurf, trae)
482        #[arg(long, short = 'p')]
483        provider: Option<String>,
484    },
485
486    /// List sessions for a specific project path
487    Path {
488        /// Project path (default: current directory)
489        project_path: Option<String>,
490    },
491
492    /// List unregistered sessions (exist on disk but invisible to VS Code)
493    Orphaned {
494        /// Project path (default: current directory)
495        #[arg(long)]
496        path: Option<String>,
497    },
498}
499
500// ============================================================================
501// Find Subcommands
502// ============================================================================
503
504#[derive(Subcommand)]
505pub enum FindCommands {
506    /// Search workspaces by name pattern (defaults to current directory name)
507    #[command(visible_alias = "ws")]
508    Workspace {
509        /// Text pattern to match (case-insensitive, defaults to current directory name)
510        pattern: Option<String>,
511    },
512
513    /// Search sessions by title, content, or ID pattern
514    #[command(visible_alias = "s")]
515    Session {
516        /// Text pattern to match (case-insensitive, defaults to current directory name)
517        pattern: Option<String>,
518
519        /// Filter by project path or workspace name
520        #[arg(long, short = 'w')]
521        workspace: Option<String>,
522
523        /// Only search in session titles (faster, skip content search)
524        #[arg(long, short = 't')]
525        title_only: bool,
526
527        /// Include message content in search (slower)
528        #[arg(long, short = 'c')]
529        content: bool,
530
531        /// Filter sessions modified after this date (YYYY-MM-DD)
532        #[arg(long)]
533        after: Option<String>,
534
535        /// Filter sessions modified before this date (YYYY-MM-DD)
536        #[arg(long)]
537        before: Option<String>,
538
539        /// Filter by internal message timestamp date (YYYY-MM-DD)
540        #[arg(long)]
541        date: Option<String>,
542
543        /// Search across all workspaces (not just current project)
544        #[arg(long, short = 'a')]
545        all: bool,
546
547        /// Filter by provider (vscode, cursor, cursorcli, claudecode, codexcli, geminicli, antigravitycli, copilotcli, opencode, openclaw, antigravity, qwencode, pi, goose, cline, roocode, kilocode, windsurf, trae)
548        #[arg(long, short = 'p')]
549        provider: Option<String>,
550
551        /// Search across all providers
552        #[arg(long)]
553        all_providers: bool,
554
555        /// Limit number of results
556        #[arg(long, short = 'n', default_value = "50")]
557        limit: usize,
558    },
559
560    /// Search sessions within a specific project path
561    Path {
562        /// Search pattern (case-insensitive, defaults to current directory name)
563        pattern: Option<String>,
564
565        /// Project path (default: current directory)
566        #[arg(long)]
567        project_path: Option<String>,
568    },
569}
570
571// ============================================================================
572// Show Subcommands
573// ============================================================================
574
575#[derive(Subcommand)]
576pub enum ShowCommands {
577    /// Show workspace details
578    #[command(visible_alias = "ws")]
579    Workspace {
580        /// Workspace name or hash
581        workspace: String,
582    },
583
584    /// Show session details
585    #[command(visible_alias = "s")]
586    Session {
587        /// Session ID or filename
588        session_id: String,
589
590        /// Project path to search in
591        #[arg(long)]
592        project_path: Option<String>,
593    },
594
595    /// Show agent mode session details (Copilot Edits)
596    #[command(visible_alias = "a")]
597    Agent {
598        /// Agent session ID
599        session_id: String,
600
601        /// Project path to search in
602        #[arg(long)]
603        project_path: Option<String>,
604    },
605
606    /// Show the VS Code session index (state.vscdb) for a workspace
607    #[command(visible_alias = "idx")]
608    Index {
609        /// Project path (default: current directory)
610        #[arg(long)]
611        path: Option<String>,
612
613        /// Show indexes for all workspaces that have chat sessions
614        #[arg(long, short)]
615        all: bool,
616    },
617
618    /// Show chat history timeline for a project path
619    Path {
620        /// Path to the project (default: current directory)
621        project_path: Option<String>,
622    },
623
624    /// Show timeline of session activity with gaps visualization
625    Timeline {
626        /// Path to the project (default: current directory)
627        project_path: Option<String>,
628
629        /// Include agent mode sessions
630        #[arg(long, short = 'a')]
631        agents: bool,
632
633        /// Filter by provider (vscode, cursor, cursorcli, claudecode, codexcli, geminicli, antigravitycli, copilotcli, opencode, openclaw, antigravity, qwencode, pi, goose, cline, roocode, kilocode, windsurf, trae)
634        #[arg(long, short = 'p')]
635        provider: Option<String>,
636
637        /// Include all providers (aggregate timeline)
638        #[arg(long)]
639        all_providers: bool,
640    },
641}
642
643// ============================================================================
644// Fetch Subcommands
645// ============================================================================
646
647#[derive(Subcommand)]
648pub enum FetchCommands {
649    /// Fetch sessions from workspaces matching a pattern
650    #[command(visible_alias = "ws")]
651    Workspace {
652        /// Workspace name pattern (case-insensitive)
653        workspace_name: String,
654
655        /// Target project path (default: current directory)
656        #[arg(long)]
657        target_path: Option<String>,
658
659        /// Overwrite existing sessions
660        #[arg(long)]
661        force: bool,
662
663        /// Don't register sessions in VS Code index
664        #[arg(long)]
665        no_register: bool,
666    },
667
668    /// Fetch specific sessions by ID
669    #[command(visible_alias = "s")]
670    Session {
671        /// Session IDs to fetch (space-separated)
672        #[arg(required = true, num_args = 1..)]
673        session_ids: Vec<String>,
674
675        /// Target project path (default: current directory)
676        #[arg(long)]
677        target_path: Option<String>,
678
679        /// Overwrite existing sessions
680        #[arg(long)]
681        force: bool,
682
683        /// Don't register sessions in VS Code index
684        #[arg(long)]
685        no_register: bool,
686    },
687
688    /// Fetch chat sessions from other workspaces by project path
689    Path {
690        /// Path to the project (default: current directory)
691        project_path: Option<String>,
692
693        /// Overwrite existing sessions and skip VS Code running check
694        #[arg(long)]
695        force: bool,
696
697        /// Don't register sessions in VS Code index
698        #[arg(long)]
699        no_register: bool,
700    },
701}
702
703// ============================================================================
704// Merge Subcommands
705// ============================================================================
706
707#[derive(Subcommand)]
708pub enum MergeCommands {
709    /// Merge sessions from workspaces matching a name pattern
710    #[command(visible_alias = "ws")]
711    Workspace {
712        /// Workspace name pattern to search for (case-insensitive)
713        workspace_name: String,
714
715        /// Title for the merged session
716        #[arg(short, long)]
717        title: Option<String>,
718
719        /// Target project path to save the merged session (default: current directory)
720        #[arg(long)]
721        target_path: Option<String>,
722
723        /// Skip VS Code running check
724        #[arg(long)]
725        force: bool,
726
727        /// Don't create backup of current sessions
728        #[arg(long)]
729        no_backup: bool,
730    },
731
732    /// Merge sessions from multiple workspace name patterns
733    #[command(visible_alias = "wss")]
734    Workspaces {
735        /// Workspace name patterns to search for (space-separated, case-insensitive)
736        #[arg(required = true, num_args = 1..)]
737        workspace_names: Vec<String>,
738
739        /// Title for the merged session
740        #[arg(short, long)]
741        title: Option<String>,
742
743        /// Target project path to save the merged session (default: current directory)
744        #[arg(long)]
745        target_path: Option<String>,
746
747        /// Skip VS Code running check
748        #[arg(long)]
749        force: bool,
750
751        /// Don't create backup of current sessions
752        #[arg(long)]
753        no_backup: bool,
754    },
755
756    /// Merge specific sessions by their IDs or filenames
757    #[command(visible_alias = "s")]
758    Sessions {
759        /// Session IDs or filenames (comma-separated or space-separated)
760        #[arg(required = true, num_args = 1..)]
761        sessions: Vec<String>,
762
763        /// Title for the merged session
764        #[arg(short, long)]
765        title: Option<String>,
766
767        /// Target project path to save the merged session (default: current directory)
768        #[arg(long)]
769        target_path: Option<String>,
770
771        /// Skip VS Code running check
772        #[arg(long)]
773        force: bool,
774
775        /// Don't create backup of current sessions
776        #[arg(long)]
777        no_backup: bool,
778    },
779
780    /// Merge all sessions for a project path into one unified chat
781    Path {
782        /// Path to the project (default: current directory)
783        project_path: Option<String>,
784
785        /// Title for the merged session
786        #[arg(short, long)]
787        title: Option<String>,
788
789        /// Skip VS Code running check
790        #[arg(long)]
791        force: bool,
792
793        /// Don't create backup of current sessions
794        #[arg(long)]
795        no_backup: bool,
796    },
797
798    /// Merge sessions from an LLM provider (Ollama, Cursor, etc.)
799    Provider {
800        /// Provider name (copilot, cursor, ollama, vllm, foundry, etc.)
801        provider_name: String,
802
803        /// Title for the merged session
804        #[arg(short, long)]
805        title: Option<String>,
806
807        /// Target project path to save the merged session (default: current directory)
808        #[arg(long)]
809        target_path: Option<String>,
810
811        /// Session IDs from the provider to include (omit for all)
812        #[arg(long)]
813        sessions: Option<Vec<String>>,
814
815        /// Skip VS Code running check
816        #[arg(long)]
817        force: bool,
818
819        /// Don't create backup of current sessions
820        #[arg(long)]
821        no_backup: bool,
822    },
823
824    /// Merge sessions from multiple providers
825    #[command(name = "providers")]
826    Providers {
827        /// Provider names (space-separated: copilot cursor ollama)
828        #[arg(required = true, num_args = 1..)]
829        providers: Vec<String>,
830
831        /// Title for the merged session
832        #[arg(short, long)]
833        title: Option<String>,
834
835        /// Target project path to save the merged session (default: current directory)
836        #[arg(long)]
837        target_path: Option<String>,
838
839        /// Filter by workspace name pattern (applies to providers that support workspaces)
840        #[arg(long)]
841        workspace: Option<String>,
842
843        /// Skip VS Code running check
844        #[arg(long)]
845        force: bool,
846
847        /// Don't create backup of current sessions
848        #[arg(long)]
849        no_backup: bool,
850    },
851
852    /// Merge all sessions across all available providers
853    All {
854        /// Title for the merged session
855        #[arg(short, long)]
856        title: Option<String>,
857
858        /// Target project path to save the merged session (default: current directory)
859        #[arg(long)]
860        target_path: Option<String>,
861
862        /// Filter by workspace name pattern (applies to providers that support workspaces)
863        #[arg(long)]
864        workspace: Option<String>,
865
866        /// Skip VS Code running check
867        #[arg(long)]
868        force: bool,
869
870        /// Don't create backup of current sessions
871        #[arg(long)]
872        no_backup: bool,
873    },
874}
875
876// ============================================================================
877// Export Subcommands
878// ============================================================================
879
880#[derive(Subcommand)]
881pub enum ExportCommands {
882    /// Export sessions from a workspace by hash
883    #[command(visible_alias = "ws")]
884    Workspace {
885        /// Destination directory for exported sessions
886        destination: String,
887
888        /// Source workspace hash
889        hash: String,
890    },
891
892    /// Export specific sessions by ID
893    #[command(visible_alias = "s")]
894    Sessions {
895        /// Destination directory for exported sessions
896        destination: String,
897
898        /// Session IDs to export (space-separated)
899        #[arg(required = true, num_args = 1..)]
900        session_ids: Vec<String>,
901
902        /// Source project path
903        #[arg(long)]
904        project_path: Option<String>,
905    },
906
907    /// Export chat sessions from a project path
908    Path {
909        /// Destination directory for exported sessions
910        destination: String,
911
912        /// Source project path (default: current directory)
913        project_path: Option<String>,
914    },
915
916    /// Export chat sessions from multiple project paths (batch operation)
917    Batch {
918        /// Base destination directory (subdirectories created per project)
919        destination: String,
920
921        /// Project paths to export (space-separated)
922        #[arg(required = true, num_args = 1..)]
923        project_paths: Vec<String>,
924    },
925}
926
927// ============================================================================
928// Import Subcommands
929// ============================================================================
930
931#[derive(Subcommand)]
932pub enum ImportCommands {
933    /// Copy session files from external directory into a workspace
934    #[command(visible_alias = "ws")]
935    Workspace {
936        /// Source directory containing session JSON files to import
937        source: String,
938
939        /// Target workspace hash
940        hash: String,
941
942        /// Overwrite existing sessions
943        #[arg(long)]
944        force: bool,
945    },
946
947    /// Copy specific session files into a workspace
948    #[command(visible_alias = "s")]
949    Sessions {
950        /// Session files to import (space-separated paths)
951        #[arg(required = true, num_args = 1..)]
952        session_files: Vec<String>,
953
954        /// Target project path (default: current directory)
955        #[arg(long)]
956        target_path: Option<String>,
957
958        /// Overwrite existing sessions
959        #[arg(long)]
960        force: bool,
961    },
962
963    /// Copy session files from external directory into a project workspace
964    Path {
965        /// Source directory containing session JSON files to import
966        source: String,
967
968        /// Target project path (default: current directory)
969        target_path: Option<String>,
970
971        /// Overwrite existing sessions
972        #[arg(long)]
973        force: bool,
974    },
975}
976
977// ============================================================================
978// Move Subcommands
979// ============================================================================
980
981#[derive(Subcommand)]
982pub enum MoveCommands {
983    /// Move all sessions from one workspace to another
984    #[command(visible_alias = "ws")]
985    Workspace {
986        /// Source workspace hash
987        source_hash: String,
988
989        /// Target workspace hash or project path
990        target: String,
991    },
992
993    /// Move specific sessions by ID
994    #[command(visible_alias = "s")]
995    Sessions {
996        /// Session IDs to move (space-separated)
997        #[arg(required = true, num_args = 1..)]
998        session_ids: Vec<String>,
999
1000        /// Target project path
1001        target_path: String,
1002    },
1003
1004    /// Move sessions from a source path to target path
1005    Path {
1006        /// Source project path
1007        source_path: String,
1008
1009        /// Target project path
1010        target_path: String,
1011    },
1012}
1013
1014// ============================================================================
1015// Git Subcommands
1016// ============================================================================
1017
1018#[derive(Subcommand)]
1019pub enum GitCommands {
1020    /// Configure git settings for chat sessions
1021    Config {
1022        /// Git user name
1023        #[arg(long)]
1024        name: Option<String>,
1025
1026        /// Git user email
1027        #[arg(long)]
1028        email: Option<String>,
1029
1030        /// Project path
1031        #[arg(long)]
1032        path: Option<String>,
1033    },
1034
1035    /// Initialize git versioning for chat sessions
1036    Init {
1037        /// Project path
1038        path: String,
1039    },
1040
1041    /// Add chat sessions to git (stage and optionally commit)
1042    Add {
1043        /// Project path
1044        path: String,
1045
1046        /// Also commit the changes
1047        #[arg(long)]
1048        commit: bool,
1049
1050        /// Commit message (requires --commit)
1051        #[arg(short, long)]
1052        message: Option<String>,
1053    },
1054
1055    /// Show git status of chat sessions
1056    Status {
1057        /// Project path
1058        path: String,
1059    },
1060
1061    /// Create a git tag snapshot of chat sessions
1062    Snapshot {
1063        /// Project path
1064        path: String,
1065
1066        /// Tag name (auto-generated if not provided)
1067        #[arg(long)]
1068        tag: Option<String>,
1069
1070        /// Snapshot message
1071        #[arg(short, long)]
1072        message: Option<String>,
1073    },
1074
1075    /// Track chat sessions together with associated file changes
1076    Track {
1077        /// Project path
1078        path: String,
1079
1080        /// Commit message describing the changes
1081        #[arg(short, long)]
1082        message: Option<String>,
1083
1084        /// Include all staged and unstaged file changes
1085        #[arg(long)]
1086        all: bool,
1087
1088        /// Include specific files in addition to chat sessions
1089        #[arg(long)]
1090        files: Option<Vec<String>>,
1091
1092        /// Create a tag for this tracked state
1093        #[arg(long)]
1094        tag: Option<String>,
1095    },
1096
1097    /// Show history of chat session commits with associated file changes
1098    Log {
1099        /// Project path
1100        path: String,
1101
1102        /// Number of commits to show
1103        #[arg(short = 'n', long, default_value = "10")]
1104        count: usize,
1105
1106        /// Show only commits that include chat session changes
1107        #[arg(long)]
1108        sessions_only: bool,
1109    },
1110
1111    /// Diff chat sessions between commits or current state
1112    Diff {
1113        /// Project path
1114        path: String,
1115
1116        /// First commit (default: HEAD)
1117        #[arg(long)]
1118        from: Option<String>,
1119
1120        /// Second commit (default: working directory)
1121        #[arg(long)]
1122        to: Option<String>,
1123
1124        /// Show associated file changes alongside chat diffs
1125        #[arg(long)]
1126        with_files: bool,
1127    },
1128
1129    /// Restore chat sessions from a specific commit
1130    Restore {
1131        /// Project path
1132        path: String,
1133
1134        /// Commit hash, tag, or reference to restore from
1135        commit: String,
1136
1137        /// Also restore associated files from the same commit
1138        #[arg(long)]
1139        with_files: bool,
1140
1141        /// Create a backup before restoring
1142        #[arg(long)]
1143        backup: bool,
1144    },
1145}
1146
1147// ============================================================================
1148// Migration Subcommands
1149// ============================================================================
1150
1151#[derive(Subcommand)]
1152pub enum MigrationCommands {
1153    /// Create a migration package for moving to a new machine
1154    Create {
1155        /// Output directory for migration package
1156        output: String,
1157
1158        /// Comma-separated list of project paths to include
1159        #[arg(long)]
1160        projects: Option<String>,
1161
1162        /// Include all workspaces with chat sessions
1163        #[arg(long)]
1164        all: bool,
1165    },
1166
1167    /// Restore a migration package on a new machine
1168    Restore {
1169        /// Path to migration package directory
1170        package: String,
1171
1172        /// Project path mapping: 'old1:new1;old2:new2'
1173        #[arg(long)]
1174        mapping: Option<String>,
1175
1176        /// Show what would be done without doing it
1177        #[arg(long)]
1178        dry_run: bool,
1179    },
1180}
1181
1182// ============================================================================
1183// Run Subcommands
1184// ============================================================================
1185
1186#[derive(Subcommand)]
1187pub enum RunCommands {
1188    /// Launch interactive TUI (Text User Interface)
1189    Tui,
1190
1191    /// Launch Claude Code with auto-save
1192    #[command(visible_aliases = ["claude-code", "claudecode"])]
1193    Claude {
1194        /// Extra arguments to pass to the agent
1195        #[arg(last = true)]
1196        args: Vec<String>,
1197        /// Disable auto-save
1198        #[arg(long)]
1199        no_save: bool,
1200        /// Verbose output
1201        #[arg(short, long)]
1202        verbose: bool,
1203    },
1204
1205    /// Launch OpenCode with auto-save
1206    #[command(visible_aliases = ["opencode", "open-code"])]
1207    Open {
1208        #[arg(last = true)]
1209        args: Vec<String>,
1210        #[arg(long)]
1211        no_save: bool,
1212        #[arg(short, long)]
1213        verbose: bool,
1214    },
1215
1216    /// Launch OpenClaw (ClawdBot) with auto-save
1217    #[command(visible_aliases = ["openclaw", "clawdbot"])]
1218    Claw {
1219        #[arg(last = true)]
1220        args: Vec<String>,
1221        #[arg(long)]
1222        no_save: bool,
1223        #[arg(short, long)]
1224        verbose: bool,
1225    },
1226
1227    /// Launch Cursor CLI with auto-save
1228    Cursor {
1229        #[arg(last = true)]
1230        args: Vec<String>,
1231        #[arg(long)]
1232        no_save: bool,
1233        #[arg(short, long)]
1234        verbose: bool,
1235    },
1236
1237    /// Launch Codex CLI (OpenAI) with auto-save
1238    #[command(visible_aliases = ["codex-cli", "codexcli"])]
1239    Codex {
1240        #[arg(last = true)]
1241        args: Vec<String>,
1242        #[arg(long)]
1243        no_save: bool,
1244        #[arg(short, long)]
1245        verbose: bool,
1246    },
1247
1248    /// Launch Droid CLI (Factory) with auto-save
1249    #[command(visible_aliases = ["droid-cli", "droidcli", "factory"])]
1250    Droid {
1251        #[arg(last = true)]
1252        args: Vec<String>,
1253        #[arg(long)]
1254        no_save: bool,
1255        #[arg(short, long)]
1256        verbose: bool,
1257    },
1258
1259    /// Launch Gemini CLI (Google) with auto-save
1260    #[command(visible_aliases = ["gemini-cli", "geminicli"])]
1261    Gemini {
1262        #[arg(last = true)]
1263        args: Vec<String>,
1264        #[arg(long)]
1265        no_save: bool,
1266        #[arg(short, long)]
1267        verbose: bool,
1268    },
1269}
1270
1271// ============================================================================
1272// Provider Subcommands
1273// ============================================================================
1274
1275#[derive(Subcommand)]
1276pub enum ProviderCommands {
1277    /// List all discovered LLM providers
1278    List,
1279
1280    /// Show detailed info about a specific provider
1281    Info {
1282        /// Provider name (copilot, cursor, ollama, vllm, foundry, lm-studio, etc.)
1283        provider: String,
1284    },
1285
1286    /// Configure a provider
1287    Config {
1288        /// Provider name
1289        provider: String,
1290
1291        /// API endpoint URL
1292        #[arg(long)]
1293        endpoint: Option<String>,
1294
1295        /// API key
1296        #[arg(long)]
1297        api_key: Option<String>,
1298
1299        /// Default model
1300        #[arg(long)]
1301        model: Option<String>,
1302
1303        /// Enable or disable the provider
1304        #[arg(long)]
1305        enabled: Option<bool>,
1306    },
1307
1308    /// Import sessions from another provider
1309    Import {
1310        /// Source provider name
1311        #[arg(long)]
1312        from: String,
1313
1314        /// Target project path (or current directory)
1315        #[arg(long)]
1316        path: Option<String>,
1317
1318        /// Session ID to import (omit for all)
1319        #[arg(long)]
1320        session: Option<String>,
1321    },
1322
1323    /// Test connection to a provider
1324    Test {
1325        /// Provider name
1326        provider: String,
1327    },
1328}
1329
1330// ============================================================================
1331// Detect Subcommands
1332// ============================================================================
1333
1334#[derive(Subcommand)]
1335pub enum DetectCommands {
1336    /// Detect workspace for a path
1337    Workspace {
1338        /// Project path (default: current directory)
1339        path: Option<String>,
1340    },
1341
1342    /// Detect available providers
1343    Providers {
1344        /// Only show providers with sessions
1345        #[arg(long)]
1346        with_sessions: bool,
1347    },
1348
1349    /// Detect which provider a session belongs to
1350    Session {
1351        /// Session ID or filename
1352        session_id: String,
1353
1354        /// Project path to search in
1355        #[arg(long)]
1356        path: Option<String>,
1357    },
1358
1359    /// Detect everything (workspace, providers, sessions) for a path
1360    All {
1361        /// Project path (default: current directory)
1362        path: Option<String>,
1363
1364        /// Show detailed information
1365        #[arg(long)]
1366        verbose: bool,
1367    },
1368
1369    /// Find all workspace hashes for a project path (including orphaned workspaces with sessions)
1370    Orphaned {
1371        /// Project path (default: current directory)
1372        path: Option<String>,
1373
1374        /// Automatically recover orphaned sessions by copying to active workspace
1375        #[arg(long, short)]
1376        recover: bool,
1377    },
1378}
1379
1380// ============================================================================
1381// Register Subcommands
1382// ============================================================================
1383
1384#[derive(Subcommand)]
1385pub enum RegisterCommands {
1386    /// Register all on-disk sessions into VS Code's index (fixes orphaned sessions)
1387    All {
1388        /// Project path (default: current directory)
1389        #[arg(long)]
1390        path: Option<String>,
1391
1392        /// Merge all sessions into one before registering
1393        #[arg(long, short)]
1394        merge: bool,
1395
1396        /// Force registration (from external terminal: close/reopen VS Code without prompt;
1397        /// from VS Code terminal: write to DB with background watchdog to survive shutdown)
1398        #[arg(long, short)]
1399        force: bool,
1400
1401        /// Close VS Code before registering (ensures index is not overwritten by cache)
1402        #[arg(long)]
1403        close_vscode: bool,
1404
1405        /// Reopen VS Code after registering (implies --close-vscode)
1406        #[arg(long)]
1407        reopen: bool,
1408
1409        /// Write directly to DB without closing VS Code. A background watchdog
1410        /// re-applies the index after VS Code exits to survive the shutdown cache flush.
1411        #[arg(long, short = 'w')]
1412        write_only: bool,
1413    },
1414
1415    /// Register specific sessions by ID or title into VS Code's index
1416    #[command(visible_alias = "s")]
1417    Session {
1418        /// Session IDs or filenames (without .json extension)
1419        #[arg(required_unless_present = "title")]
1420        ids: Vec<String>,
1421
1422        /// Match sessions by title instead of ID
1423        #[arg(long, short, num_args = 1.., value_delimiter = ' ')]
1424        title: Option<Vec<String>>,
1425
1426        /// Project path (default: current directory)
1427        #[arg(long)]
1428        path: Option<String>,
1429
1430        /// Force registration even if VS Code is running
1431        #[arg(long, short)]
1432        force: bool,
1433    },
1434
1435    /// Recursively walk directories to find and register orphaned sessions for all workspaces
1436    #[command(visible_alias = "r")]
1437    Recursive {
1438        /// Root path to start recursive search (default: current directory)
1439        path: Option<String>,
1440
1441        /// Maximum directory depth to recurse (default: unlimited)
1442        #[arg(long, short)]
1443        depth: Option<usize>,
1444
1445        /// Force registration even if VS Code is running
1446        #[arg(long, short)]
1447        force: bool,
1448
1449        /// Only show what would be registered without making changes
1450        #[arg(long)]
1451        dry_run: bool,
1452
1453        /// Skip directories matching these patterns (can be used multiple times)
1454        #[arg(long, short = 'x')]
1455        exclude: Vec<String>,
1456    },
1457
1458    /// Repair sessions: compact large JSONL files and rebuild the index with correct metadata
1459    #[command(visible_alias = "fix")]
1460    Repair {
1461        /// Project path (default: current directory)
1462        #[arg(long)]
1463        path: Option<String>,
1464
1465        /// Repair all workspaces that have chat sessions
1466        #[arg(long, short)]
1467        all: bool,
1468
1469        /// Recursively scan a directory tree for workspaces and repair all discovered sessions
1470        #[arg(long, short)]
1471        recursive: bool,
1472
1473        /// Maximum directory depth when using --recursive (default: unlimited)
1474        #[arg(long, short)]
1475        depth: Option<usize>,
1476
1477        /// Skip directories matching these patterns when using --recursive
1478        #[arg(long, short = 'x')]
1479        exclude: Vec<String>,
1480
1481        /// Only show what would be repaired without making changes
1482        #[arg(long)]
1483        dry_run: bool,
1484
1485        /// Force even if VS Code is running
1486        #[arg(long, short)]
1487        force: bool,
1488
1489        /// Close VS Code before repairing (ensures index is not overwritten)
1490        #[arg(long)]
1491        close_vscode: bool,
1492
1493        /// Reopen VS Code after repairing (implies --close-vscode)
1494        #[arg(long)]
1495        reopen: bool,
1496    },
1497
1498    /// Trim oversized sessions by keeping only the most recent requests
1499    #[command(visible_alias = "t")]
1500    Trim {
1501        /// Project path (default: current directory)
1502        #[arg(long)]
1503        path: Option<String>,
1504
1505        /// Number of recent requests to keep (default: 20)
1506        #[arg(long, short, default_value = "20")]
1507        keep: usize,
1508
1509        /// Session ID to trim (default: largest session)
1510        #[arg(long, short)]
1511        session: Option<String>,
1512
1513        /// Trim all sessions over the size threshold
1514        #[arg(long, short)]
1515        all: bool,
1516
1517        /// Only trim sessions larger than this size in MB (default: 10)
1518        #[arg(long, default_value = "10")]
1519        threshold_mb: u64,
1520
1521        /// Force even if VS Code is running
1522        #[arg(long, short)]
1523        force: bool,
1524    },
1525}
1526
1527// ============================================================================
1528// Harvest Subcommands
1529// ============================================================================
1530
1531#[derive(Subcommand)]
1532pub enum HarvestCommands {
1533    /// Initialize a harvest database
1534    Init {
1535        /// Path to the database file (default: ./chat_sessions.db)
1536        #[arg(long)]
1537        path: Option<String>,
1538
1539        /// Initialize git tracking for the database
1540        #[arg(long)]
1541        git: bool,
1542    },
1543
1544    /// Scan for available providers and sessions
1545    Scan {
1546        /// Show individual sessions
1547        #[arg(long)]
1548        sessions: bool,
1549
1550        /// Scan for web-based LLM providers (ChatGPT, Claude, etc.)
1551        #[arg(long)]
1552        web: bool,
1553
1554        /// Timeout in seconds for web provider checks (default: 5)
1555        #[arg(long, default_value = "5")]
1556        timeout: u64,
1557
1558        /// Show verbose debug output for browser scanning
1559        #[arg(long, short)]
1560        verbose: bool,
1561    },
1562
1563    /// Run the harvest to collect sessions from all providers
1564    Run {
1565        /// Path to the harvest database
1566        #[arg(long)]
1567        path: Option<String>,
1568
1569        /// Only include specific providers (comma-separated: copilot,cursor,ollama)
1570        #[arg(long, value_delimiter = ',')]
1571        providers: Option<Vec<String>>,
1572
1573        /// Exclude specific providers (comma-separated)
1574        #[arg(long, value_delimiter = ',')]
1575        exclude: Option<Vec<String>>,
1576
1577        /// Only harvest sessions changed since last run
1578        #[arg(long)]
1579        incremental: bool,
1580
1581        /// Auto-commit changes to git after harvest
1582        #[arg(long)]
1583        commit: bool,
1584
1585        /// Commit message (requires --commit)
1586        #[arg(short, long)]
1587        message: Option<String>,
1588
1589        /// Also download every file attached to harvested cloud conversations
1590        /// (currently ChatGPT only). Files are stored in
1591        /// `<db_dir>/files/<provider>/<conversation_id>/<name>`.
1592        #[arg(long)]
1593        with_files: bool,
1594    },
1595
1596    /// Show harvest database status
1597    Status {
1598        /// Path to the harvest database
1599        #[arg(long)]
1600        path: Option<String>,
1601    },
1602
1603    /// List sessions in the harvest database
1604    List {
1605        /// Path to the harvest database
1606        #[arg(long)]
1607        path: Option<String>,
1608
1609        /// Filter by provider name
1610        #[arg(long)]
1611        provider: Option<String>,
1612
1613        /// Maximum number of sessions to show
1614        #[arg(long, default_value = "20")]
1615        limit: usize,
1616
1617        /// Search sessions by title or ID
1618        #[arg(long)]
1619        search: Option<String>,
1620    },
1621
1622    /// Export sessions from the harvest database
1623    Export {
1624        /// Output file path
1625        output: String,
1626
1627        /// Path to the harvest database
1628        #[arg(long)]
1629        path: Option<String>,
1630
1631        /// Export format: json, jsonl, md (markdown)
1632        #[arg(long, default_value = "json")]
1633        format: String,
1634
1635        /// Filter by provider name
1636        #[arg(long)]
1637        provider: Option<String>,
1638
1639        /// Export specific sessions by ID (comma-separated)
1640        #[arg(long, value_delimiter = ',')]
1641        sessions: Option<Vec<String>>,
1642    },
1643
1644    /// Import a shared chat session from a URL
1645    Share {
1646        /// Share link URL (ChatGPT, Claude, etc.)
1647        url: String,
1648
1649        /// Path to the harvest database
1650        #[arg(long)]
1651        path: Option<String>,
1652
1653        /// Custom name for the imported session
1654        #[arg(long)]
1655        name: Option<String>,
1656
1657        /// Associate with a workspace path
1658        #[arg(long)]
1659        workspace: Option<String>,
1660    },
1661
1662    /// Download a single authenticated chat session from a provider URL
1663    ///
1664    /// Uses your browser's session cookies to fetch a specific conversation
1665    /// (e.g. https://chatgpt.com/c/<id>, https://claude.ai/chat/<uuid>).
1666    /// You must be logged in to the provider in a supported browser.
1667    Pull {
1668        /// Conversation URL (e.g. https://chatgpt.com/c/<id>, https://claude.ai/chat/<uuid>)
1669        url: String,
1670
1671        /// Output file path (default: ./<provider>-<id>.json). Ignored if --path is set.
1672        #[arg(short, long)]
1673        output: Option<String>,
1674
1675        /// Path to the harvest database. If set, store in DB instead of writing a file.
1676        #[arg(long)]
1677        path: Option<String>,
1678
1679        /// Workspace name to associate with the imported session
1680        #[arg(long)]
1681        workspace: Option<String>,
1682
1683        /// Pretty-print JSON file output
1684        #[arg(long)]
1685        pretty: bool,
1686
1687        /// Also download every file attached to the conversation
1688        /// (user uploads, generated images, code-interpreter outputs).
1689        /// Implies `--bundle` when no other output mode is chosen.
1690        #[arg(long)]
1691        with_files: bool,
1692
1693        /// Package the conversation, raw provider response, manifest, and
1694        /// (optionally) downloaded files into a single `.tar.gz` archive.
1695        /// Output path defaults to `./<provider>-<id>.tar.gz` when set.
1696        #[arg(long)]
1697        bundle: bool,
1698    },
1699
1700    /// List pending or imported share links
1701    Shares {
1702        /// Path to the harvest database
1703        #[arg(long)]
1704        path: Option<String>,
1705
1706        /// Filter by status: pending, imported, failed, expired
1707        #[arg(long)]
1708        status: Option<String>,
1709
1710        /// Maximum number of links to show
1711        #[arg(long, default_value = "20")]
1712        limit: usize,
1713    },
1714
1715    /// Create a checkpoint (version snapshot) of a session
1716    Checkpoint {
1717        /// Session ID to checkpoint
1718        session: String,
1719
1720        /// Path to the harvest database
1721        #[arg(long)]
1722        path: Option<String>,
1723
1724        /// Checkpoint description message
1725        #[arg(short, long)]
1726        message: Option<String>,
1727    },
1728
1729    /// List checkpoints for a session
1730    Checkpoints {
1731        /// Session ID to list checkpoints for
1732        session: String,
1733
1734        /// Path to the harvest database
1735        #[arg(long)]
1736        path: Option<String>,
1737    },
1738
1739    /// Revert a session to a previous checkpoint
1740    Revert {
1741        /// Session ID to revert
1742        session: String,
1743
1744        /// Checkpoint number to revert to
1745        checkpoint: i64,
1746
1747        /// Path to the harvest database
1748        #[arg(long)]
1749        path: Option<String>,
1750    },
1751
1752    /// Sync sessions between the harvest database and provider workspaces
1753    Sync {
1754        /// Path to the harvest database
1755        #[arg(long)]
1756        path: Option<String>,
1757
1758        /// Push sessions from database to provider workspaces (restore)
1759        #[arg(long)]
1760        push: bool,
1761
1762        /// Pull sessions from provider workspaces into database (backup)
1763        #[arg(long)]
1764        pull: bool,
1765
1766        /// Filter by provider name
1767        #[arg(long)]
1768        provider: Option<String>,
1769
1770        /// Filter by workspace/project path
1771        #[arg(long)]
1772        workspace: Option<String>,
1773
1774        /// Session IDs to sync (space-separated)
1775        #[arg(long, num_args = 1..)]
1776        sessions: Option<Vec<String>>,
1777
1778        /// Target format for push: auto (detect from provider), jsonl, json
1779        #[arg(long, default_value = "auto")]
1780        format: String,
1781
1782        /// Overwrite existing files without prompting
1783        #[arg(long)]
1784        force: bool,
1785
1786        /// Dry run - show what would be synced without making changes
1787        #[arg(long)]
1788        dry_run: bool,
1789    },
1790
1791    /// Compact the database by stripping session_json blobs (data preserved in messages_v2)
1792    #[command(visible_alias = "gc")]
1793    Compact {
1794        /// Path to the harvest database
1795        #[arg(long)]
1796        path: Option<String>,
1797
1798        /// Show what would be compacted without making changes
1799        #[arg(long)]
1800        dry_run: bool,
1801    },
1802
1803    /// Rebuild the full-text search index
1804    Rebuild {
1805        /// Path to the harvest database
1806        #[arg(long)]
1807        path: Option<String>,
1808    },
1809
1810    /// Search messages across all sessions (full-text search)
1811    Search {
1812        /// Search query
1813        query: String,
1814
1815        /// Path to the harvest database
1816        #[arg(long)]
1817        path: Option<String>,
1818
1819        /// Filter by provider
1820        #[arg(long)]
1821        provider: Option<String>,
1822
1823        /// Maximum results to show
1824        #[arg(long, default_value = "20")]
1825        limit: usize,
1826    },
1827
1828    /// Git operations for the harvest database
1829    Git {
1830        #[command(subcommand)]
1831        command: HarvestGitCommands,
1832    },
1833}
1834
1835#[derive(Subcommand)]
1836pub enum HarvestGitCommands {
1837    /// Initialize git tracking for the harvest database
1838    Init {
1839        /// Path to the harvest database
1840        #[arg(long)]
1841        path: Option<String>,
1842    },
1843
1844    /// Commit changes to the harvest database
1845    Commit {
1846        /// Path to the harvest database
1847        #[arg(long)]
1848        path: Option<String>,
1849
1850        /// Commit message
1851        #[arg(short, long)]
1852        message: Option<String>,
1853    },
1854
1855    /// Show git log for the harvest database
1856    Log {
1857        /// Path to the harvest database
1858        #[arg(long)]
1859        path: Option<String>,
1860
1861        /// Number of commits to show
1862        #[arg(short = 'n', long, default_value = "10")]
1863        count: usize,
1864    },
1865
1866    /// Show changes to the harvest database
1867    Diff {
1868        /// Path to the harvest database
1869        #[arg(long)]
1870        path: Option<String>,
1871
1872        /// Compare against specific commit
1873        #[arg(long)]
1874        commit: Option<String>,
1875    },
1876
1877    /// Restore harvest database from a commit
1878    Restore {
1879        /// Commit hash to restore from
1880        commit: String,
1881
1882        /// Path to the harvest database
1883        #[arg(long)]
1884        path: Option<String>,
1885    },
1886}
1887
1888// ============================================================================
1889// Recover Subcommands
1890// ============================================================================
1891
1892#[derive(Subcommand)]
1893pub enum RecoverCommands {
1894    /// Scan for recoverable sessions from various sources
1895    Scan {
1896        /// Provider to scan: vscode, cursor, all (default: all)
1897        #[arg(long, default_value = "all")]
1898        provider: String,
1899
1900        /// Show detailed information about each session
1901        #[arg(short, long)]
1902        verbose: bool,
1903
1904        /// Include sessions older than normal retention period
1905        #[arg(long)]
1906        include_old: bool,
1907    },
1908
1909    /// Recover sessions from the recording API server
1910    Recording {
1911        /// Server URL (default: http://localhost:8787)
1912        #[arg(long, default_value = "http://localhost:8787")]
1913        server: String,
1914
1915        /// Only recover specific session ID
1916        #[arg(long)]
1917        session: Option<String>,
1918
1919        /// Output directory for recovered sessions
1920        #[arg(short, long)]
1921        output: Option<String>,
1922    },
1923
1924    /// Recover sessions from SQLite database backups
1925    Database {
1926        /// Path to the database backup file
1927        backup: String,
1928
1929        /// Extract specific session by ID
1930        #[arg(long)]
1931        session: Option<String>,
1932
1933        /// Output directory for recovered sessions
1934        #[arg(short, long)]
1935        output: Option<String>,
1936
1937        /// Output format: json, jsonl, md (default: json)
1938        #[arg(long, default_value = "json")]
1939        format: String,
1940    },
1941
1942    /// Recover sessions from incomplete/corrupted JSONL files
1943    Jsonl {
1944        /// Path to the JSONL file to repair
1945        file: String,
1946
1947        /// Output file for recovered sessions (default: same name with .recovered suffix)
1948        #[arg(short, long)]
1949        output: Option<String>,
1950
1951        /// Attempt aggressive recovery (may produce incomplete sessions)
1952        #[arg(long)]
1953        aggressive: bool,
1954    },
1955
1956    /// List sessions from VS Code's workspaceStorage that may be orphaned
1957    Orphans {
1958        /// Provider to check: vscode, cursor, all (default: all)
1959        #[arg(long, default_value = "all")]
1960        provider: String,
1961
1962        /// Show sessions not in the SQLite state database
1963        #[arg(long)]
1964        unindexed: bool,
1965
1966        /// Check if files actually exist on disk
1967        #[arg(long)]
1968        verify: bool,
1969    },
1970
1971    /// Repair corrupted session files in place
1972    Repair {
1973        /// Path to the session directory or file
1974        path: String,
1975
1976        /// Create backup before repair
1977        #[arg(long, default_value = "true")]
1978        backup: bool,
1979
1980        /// Dry run - show what would be repaired without making changes
1981        #[arg(long)]
1982        dry_run: bool,
1983    },
1984
1985    /// Show recovery status and recommendations
1986    Status {
1987        /// Provider to check: vscode, cursor, all (default: all)
1988        #[arg(long, default_value = "all")]
1989        provider: String,
1990
1991        /// Check disk space and file system health
1992        #[arg(long)]
1993        system: bool,
1994    },
1995
1996    /// Convert session files between JSON and JSONL formats
1997    Convert {
1998        /// Input file to convert (.json or .jsonl)
1999        input: String,
2000
2001        /// Output file (auto-detects format from extension, or uses --format)
2002        #[arg(short, long)]
2003        output: Option<String>,
2004
2005        /// Output format: json, jsonl (default: opposite of input)
2006        #[arg(long)]
2007        format: Option<String>,
2008
2009        /// VS Code version compatibility: legacy (< 1.109), modern (>= 1.109), both
2010        #[arg(long, default_value = "both")]
2011        compat: String,
2012    },
2013
2014    /// Extract sessions from a VS Code workspace by project path
2015    Extract {
2016        /// Project directory path (will find corresponding workspace hash)
2017        path: String,
2018
2019        /// Output directory for extracted sessions
2020        #[arg(short, long)]
2021        output: Option<String>,
2022
2023        /// Include both JSON and JSONL formats if available
2024        #[arg(long)]
2025        all_formats: bool,
2026
2027        /// Include editing session fragments (agent mode work)
2028        #[arg(long)]
2029        include_edits: bool,
2030    },
2031
2032    /// Detect and display session format and version information
2033    Detect {
2034        /// Session file to analyze (.json or .jsonl)
2035        file: String,
2036
2037        /// Show raw format detection details
2038        #[arg(long)]
2039        verbose: bool,
2040
2041        /// Output detection result as JSON
2042        #[arg(long)]
2043        json: bool,
2044    },
2045
2046    /// Upgrade session files to the current provider format (JSON to JSONL for VS Code 1.109+)
2047    Upgrade {
2048        /// Project paths to upgrade (space-separated)
2049        #[arg(required = true, num_args = 1..)]
2050        project_paths: Vec<String>,
2051
2052        /// Provider to use: vscode, cursor, auto (default: auto-detect)
2053        #[arg(long, default_value = "auto")]
2054        provider: String,
2055
2056        /// Target format: jsonl (VS Code 1.109+), json (legacy). Default: jsonl
2057        #[arg(long, default_value = "jsonl")]
2058        target_format: String,
2059
2060        /// Skip creating backup of original files
2061        #[arg(long)]
2062        no_backup: bool,
2063
2064        /// Dry run - show what would be upgraded without making changes
2065        #[arg(long)]
2066        dry_run: bool,
2067    },
2068
2069    /// Show Copilot Chat extension version info and compatibility analysis
2070    CopilotInfo {
2071        /// Path to session directory to scan for version info (default: auto-detect)
2072        #[arg(long)]
2073        session_dir: Option<String>,
2074
2075        /// Output as JSON instead of human-readable table
2076        #[arg(long)]
2077        json: bool,
2078    },
2079
2080    /// Restore truncated sessions from .jsonl.bak backup files across all workspaces
2081    #[command(visible_alias = "b")]
2082    Backups {
2083        /// Root path to scan (default: all VS Code workspaces)
2084        path: Option<String>,
2085
2086        /// Only show what would be restored without making changes
2087        #[arg(long)]
2088        dry_run: bool,
2089
2090        /// Force operation even if VS Code is running
2091        #[arg(long, short)]
2092        force: bool,
2093    },
2094
2095    /// Recursively walk directories to find and recover orphaned sessions for all workspaces
2096    #[command(visible_alias = "r")]
2097    Recursive {
2098        /// Root path to start recursive search (default: current directory)
2099        path: Option<String>,
2100
2101        /// Maximum directory depth to recurse (default: unlimited)
2102        #[arg(long, short)]
2103        depth: Option<usize>,
2104
2105        /// Force registration even if VS Code is running
2106        #[arg(long, short)]
2107        force: bool,
2108
2109        /// Only show what would be recovered without making changes
2110        #[arg(long)]
2111        dry_run: bool,
2112
2113        /// Skip directories matching these patterns (can be used multiple times)
2114        #[arg(long, short = 'x')]
2115        exclude: Vec<String>,
2116
2117        /// Also register recovered sessions in VS Code's index
2118        #[arg(long)]
2119        register: bool,
2120    },
2121}
2122
2123// ============================================================================
2124// Shard Subcommands
2125// ============================================================================
2126
2127#[derive(Subcommand)]
2128pub enum ShardCommands {
2129    /// Shard a single session file into linked parts
2130    Session {
2131        /// Path to the session file (.json or .jsonl)
2132        file: String,
2133
2134        /// Maximum requests per shard (default: 50). Mutually exclusive with --max-size
2135        #[arg(long, short = 'n')]
2136        max_requests: Option<usize>,
2137
2138        /// Maximum file size per shard (e.g. "10MB", "500KB"). Mutually exclusive with --max-requests
2139        #[arg(long, short = 's')]
2140        max_size: Option<String>,
2141
2142        /// Output directory for shard files (default: same directory as input)
2143        #[arg(long, short = 'o')]
2144        output: Option<String>,
2145
2146        /// Update the VS Code session index after sharding
2147        #[arg(long)]
2148        update_index: bool,
2149
2150        /// Workspace hash or project path (for --update-index; auto-detected from file path if omitted)
2151        #[arg(long, short = 'w')]
2152        workspace: Option<String>,
2153
2154        /// Show what would be done without writing any files
2155        #[arg(long)]
2156        dry_run: bool,
2157
2158        /// Skip creating a .oversized backup of the original file
2159        #[arg(long)]
2160        no_backup: bool,
2161    },
2162
2163    /// Shard all oversized sessions in a workspace
2164    Workspace {
2165        /// Workspace hash or project path (default: current directory)
2166        #[arg(long, short = 'w')]
2167        workspace: Option<String>,
2168
2169        /// Maximum requests per shard (default: 50). Mutually exclusive with --max-size
2170        #[arg(long, short = 'n')]
2171        max_requests: Option<usize>,
2172
2173        /// Maximum file size per shard (e.g. "10MB", "500KB"). Mutually exclusive with --max-requests
2174        #[arg(long, short = 's')]
2175        max_size: Option<String>,
2176
2177        /// Show what would be done without writing any files
2178        #[arg(long)]
2179        dry_run: bool,
2180
2181        /// Skip creating .oversized backups of original files
2182        #[arg(long)]
2183        no_backup: bool,
2184    },
2185
2186    /// Show shard metadata for a session file
2187    Info {
2188        /// Path to the session file (.json or .jsonl)
2189        file: String,
2190    },
2191}
2192
2193// ============================================================================
2194// API Server Subcommands
2195// ============================================================================
2196
2197#[derive(Subcommand)]
2198pub enum ApiCommands {
2199    /// Start the API server
2200    Serve {
2201        /// Host to bind to. Defaults to 127.0.0.1 (this machine only).
2202        ///
2203        /// Pass --host 0.0.0.0 to expose the server on all interfaces. Do that
2204        /// deliberately: the API has endpoints that run commands and read local
2205        /// data, and binding to the network makes them reachable by anything
2206        /// that can route to this host.
2207        #[arg(long, default_value = "127.0.0.1")]
2208        host: String,
2209
2210        /// Port to listen on (default: 8787)
2211        #[arg(short, long, default_value = "8787")]
2212        port: u16,
2213
2214        /// Path to the database file
2215        #[arg(long)]
2216        database: Option<String>,
2217    },
2218}
2219
2220// ============================================================================
2221// Agency (Agent Development Kit) Subcommands
2222// ============================================================================
2223
2224#[derive(Subcommand)]
2225pub enum AgencyCommands {
2226    /// List available agents and their roles
2227    List {
2228        /// Show detailed information
2229        #[arg(short, long)]
2230        verbose: bool,
2231    },
2232
2233    /// Show agent information
2234    Info {
2235        /// Agent name or ID
2236        name: String,
2237    },
2238
2239    /// List supported orchestration modes
2240    Modes,
2241
2242    /// Run an agent with a prompt
2243    Run {
2244        /// Agent name to run
2245        #[arg(short, long, default_value = "assistant")]
2246        agent: String,
2247
2248        /// Prompt or task for the agent
2249        prompt: String,
2250
2251        /// Model to use (e.g., gemini-2.0-flash, gpt-4o)
2252        #[arg(short, long)]
2253        model: Option<String>,
2254
2255        /// Orchestration mode (single, sequential, parallel, swarm)
2256        #[arg(long, default_value = "single")]
2257        orchestration: String,
2258
2259        /// Enable verbose output
2260        #[arg(short, long)]
2261        verbose: bool,
2262    },
2263
2264    /// Create a new agent configuration
2265    Create {
2266        /// Agent name
2267        name: String,
2268
2269        /// Agent role (coordinator, researcher, coder, reviewer, executor, writer, tester, custom)
2270        #[arg(short, long, default_value = "custom")]
2271        role: String,
2272
2273        /// System instruction for the agent
2274        #[arg(short, long)]
2275        instruction: Option<String>,
2276
2277        /// Model to use
2278        #[arg(short, long)]
2279        model: Option<String>,
2280    },
2281
2282    /// List available tools
2283    Tools,
2284
2285    /// Show swarm templates
2286    Templates,
2287}
2288
2289// ============================================================================
2290// Telemetry Subcommands
2291// ============================================================================
2292
2293#[derive(Subcommand)]
2294pub enum TelemetryCommands {
2295    /// Show telemetry status and what data is collected
2296    #[command(visible_alias = "status")]
2297    Info,
2298
2299    /// Enable anonymous usage data collection (this is the default)
2300    #[command(visible_alias = "enable")]
2301    OptIn,
2302
2303    /// Disable anonymous usage data collection
2304    #[command(visible_alias = "disable")]
2305    OptOut,
2306
2307    /// Reset telemetry ID (generates new anonymous identifier)
2308    Reset,
2309
2310    /// Record structured data for later AI analysis
2311    #[command(visible_alias = "log")]
2312    Record {
2313        /// Event category (e.g., 'workflow', 'error', 'performance', 'usage')
2314        #[arg(short, long, default_value = "custom")]
2315        category: String,
2316
2317        /// Event name or type
2318        #[arg(short, long)]
2319        event: String,
2320
2321        /// JSON data payload (or use --kv for key=value pairs)
2322        #[arg(short, long)]
2323        data: Option<String>,
2324
2325        /// Key-value pairs (can be repeated: -k foo=bar -k baz=123)
2326        #[arg(short = 'k', long = "kv", value_parser = parse_key_value)]
2327        kv: Vec<(String, String)>,
2328
2329        /// Add tags for filtering (can be repeated: -t important -t session-123)
2330        #[arg(short, long)]
2331        tags: Vec<String>,
2332
2333        /// Optional session or context ID to associate with
2334        #[arg(long)]
2335        context: Option<String>,
2336
2337        /// Print recorded event details
2338        #[arg(short, long)]
2339        verbose: bool,
2340    },
2341
2342    /// Show recorded telemetry data
2343    #[command(visible_alias = "logs")]
2344    Show {
2345        /// Filter by category
2346        #[arg(short, long)]
2347        category: Option<String>,
2348
2349        /// Filter by event name
2350        #[arg(short, long)]
2351        event: Option<String>,
2352
2353        /// Filter by tag
2354        #[arg(short, long)]
2355        tag: Option<String>,
2356
2357        /// Maximum number of records to show
2358        #[arg(short = 'n', long, default_value = "20")]
2359        limit: usize,
2360
2361        /// Output format: table, json, jsonl
2362        #[arg(short, long, default_value = "table")]
2363        format: String,
2364
2365        /// Show records after this date (YYYY-MM-DD)
2366        #[arg(long)]
2367        after: Option<String>,
2368
2369        /// Show records before this date (YYYY-MM-DD)
2370        #[arg(long)]
2371        before: Option<String>,
2372    },
2373
2374    /// Export recorded data for AI analysis
2375    Export {
2376        /// Output file path
2377        output: String,
2378
2379        /// Export format: json, jsonl, csv
2380        #[arg(short, long, default_value = "jsonl")]
2381        format: String,
2382
2383        /// Filter by category
2384        #[arg(short, long)]
2385        category: Option<String>,
2386
2387        /// Include installation metadata in export
2388        #[arg(long)]
2389        with_metadata: bool,
2390    },
2391
2392    /// Clear recorded telemetry data
2393    Clear {
2394        /// Skip confirmation prompt
2395        #[arg(short, long)]
2396        force: bool,
2397
2398        /// Only clear records older than N days
2399        #[arg(long)]
2400        older_than: Option<u32>,
2401    },
2402
2403    /// Configure remote telemetry endpoint
2404    Config {
2405        /// Set the remote endpoint URL
2406        #[arg(long)]
2407        endpoint: Option<String>,
2408
2409        /// Set the API key for authentication
2410        #[arg(long)]
2411        api_key: Option<String>,
2412
2413        /// Enable remote telemetry sending
2414        #[arg(long)]
2415        enable_remote: bool,
2416
2417        /// Disable remote telemetry sending
2418        #[arg(long)]
2419        disable_remote: bool,
2420    },
2421
2422    /// Sync telemetry records to remote server
2423    Sync {
2424        /// Maximum number of records to sync
2425        #[arg(short = 'n', long)]
2426        limit: Option<usize>,
2427
2428        /// Clear local records after successful sync
2429        #[arg(long)]
2430        clear_after: bool,
2431    },
2432
2433    /// Test connection to remote telemetry server
2434    Test,
2435
2436    /// Configure OpenTelemetry OTLP export (writes service-scoped .env)
2437    Setup {
2438        /// OTLP endpoint URL
2439        #[arg(long)]
2440        endpoint: Option<String>,
2441
2442        /// OTLP protocol (default: http/protobuf)
2443        #[arg(long, default_value = "http/protobuf")]
2444        protocol: String,
2445
2446        /// OTLP headers (e.g. "Authorization=Bearer <token>")
2447        #[arg(long)]
2448        headers: Option<String>,
2449
2450        /// Service name (default: ironbridge-cli)
2451        #[arg(long, default_value = "ironbridge-cli")]
2452        service_name: String,
2453    },
2454}
2455
2456// ============================================================================
2457// Inspect Subcommands
2458// ============================================================================
2459
2460#[derive(Subcommand)]
2461pub enum InspectCommands {
2462    /// Show the ChatSessionStore index entries from state.vscdb
2463    Index {
2464        /// Project path (default: current directory)
2465        #[arg(long)]
2466        path: Option<String>,
2467
2468        /// Workspace storage hash (alternative to --path)
2469        #[arg(long, short = 'w')]
2470        workspace_id: Option<String>,
2471
2472        /// Output as JSON
2473        #[arg(long)]
2474        json: bool,
2475    },
2476
2477    /// Show session memento (input history and active session state)
2478    Memento {
2479        /// Project path (default: current directory)
2480        #[arg(long)]
2481        path: Option<String>,
2482
2483        /// Workspace storage hash (alternative to --path)
2484        #[arg(long, short = 'w')]
2485        workspace_id: Option<String>,
2486
2487        /// Output as JSON
2488        #[arg(long)]
2489        json: bool,
2490    },
2491
2492    /// Show agentSessions model and state caches (drives sidebar visibility)
2493    Cache {
2494        /// Project path (default: current directory)
2495        #[arg(long)]
2496        path: Option<String>,
2497
2498        /// Workspace storage hash (alternative to --path)
2499        #[arg(long, short = 'w')]
2500        workspace_id: Option<String>,
2501
2502        /// Output as JSON
2503        #[arg(long)]
2504        json: bool,
2505    },
2506
2507    /// Validate session files on disk (format, size, parse, index consistency)
2508    Validate {
2509        /// Project path (default: current directory)
2510        #[arg(long)]
2511        path: Option<String>,
2512
2513        /// Workspace storage hash (alternative to --path)
2514        #[arg(long, short = 'w')]
2515        workspace_id: Option<String>,
2516
2517        /// Output as JSON
2518        #[arg(long)]
2519        json: bool,
2520    },
2521
2522    /// List keys in state.vscdb with value sizes
2523    Keys {
2524        /// Project path (default: current directory)
2525        #[arg(long)]
2526        path: Option<String>,
2527
2528        /// Workspace storage hash (alternative to --path)
2529        #[arg(long, short = 'w')]
2530        workspace_id: Option<String>,
2531
2532        /// Show ALL keys (not just session-related)
2533        #[arg(long, short)]
2534        all: bool,
2535
2536        /// Output as JSON
2537        #[arg(long)]
2538        json: bool,
2539    },
2540
2541    /// List all files in the chatSessions directory with format and size details
2542    Files {
2543        /// Project path (default: current directory)
2544        #[arg(long)]
2545        path: Option<String>,
2546
2547        /// Workspace storage hash (alternative to --path)
2548        #[arg(long, short = 'w')]
2549        workspace_id: Option<String>,
2550
2551        /// Output as JSON
2552        #[arg(long)]
2553        json: bool,
2554    },
2555
2556    /// Rebuild session index and model cache from session files on disk
2557    ///
2558    /// Scans the chatSessions directory, parses each file to extract metadata
2559    /// (title, timestamps, request count), then overwrites the index and
2560    /// rebuilds the agentSessions.model.cache so sessions appear in the Chat
2561    /// sidebar. Also cleans up the state cache and fixes the active-session
2562    /// memento.
2563    #[command(visible_alias = "fix")]
2564    Rebuild {
2565        /// Project path (default: current directory)
2566        #[arg(long)]
2567        path: Option<String>,
2568
2569        /// Workspace storage hash (alternative to --path)
2570        #[arg(long, short = 'w')]
2571        workspace_id: Option<String>,
2572
2573        /// Only show what would change without writing (dry run)
2574        #[arg(long)]
2575        dry_run: bool,
2576
2577        /// Output as JSON
2578        #[arg(long)]
2579        json: bool,
2580    },
2581}
2582
2583/// Parse key=value pairs for telemetry record command
2584fn parse_key_value(s: &str) -> std::result::Result<(String, String), String> {
2585    let pos = s
2586        .find('=')
2587        .ok_or_else(|| format!("invalid key=value pair: no '=' found in '{s}'"))?;
2588    Ok((s[..pos].to_string(), s[pos + 1..].to_string()))
2589}
2590
2591// ============================================================================
2592// Schema Subcommands
2593// ============================================================================
2594
2595#[derive(Subcommand)]
2596pub enum SchemaCommands {
2597    /// List all known provider schemas (session formats and DB key layouts)
2598    #[command(visible_alias = "ls")]
2599    List {
2600        /// Filter by provider name (e.g., copilot, cursor, claude-code)
2601        #[arg(long, short = 'p')]
2602        provider: Option<String>,
2603
2604        /// Output as JSON
2605        #[arg(long)]
2606        json: bool,
2607    },
2608
2609    /// Show detailed schema for a specific version ID
2610    ///
2611    /// Example IDs: copilot-json-v3, copilot-jsonl-v1, cursor-jsonl-v1
2612    Show {
2613        /// Schema version ID (use `ironbridge schema list` to see available IDs)
2614        schema_id: String,
2615
2616        /// Output as JSON
2617        #[arg(long)]
2618        json: bool,
2619    },
2620
2621    /// Auto-detect the schema version for a workspace or session file
2622    Detect {
2623        /// Path to a session file or workspace directory (default: current directory)
2624        #[arg(long)]
2625        path: Option<String>,
2626
2627        /// Workspace storage hash (alternative to --path)
2628        #[arg(long, short = 'w')]
2629        workspace_id: Option<String>,
2630
2631        /// Output as JSON
2632        #[arg(long)]
2633        json: bool,
2634    },
2635
2636    /// Export the full schema registry + ontology as JSON (for AI agent consumption)
2637    Export {
2638        /// Compact JSON output (single line)
2639        #[arg(long)]
2640        compact: bool,
2641
2642        /// Write to file instead of stdout
2643        #[arg(long, short = 'o')]
2644        output: Option<String>,
2645    },
2646
2647    /// Show the cross-provider ontology (entity types, relationships, semantic tags)
2648    Ontology {
2649        /// Output as JSON
2650        #[arg(long)]
2651        json: bool,
2652    },
2653
2654    /// Show cross-provider field mappings and transformation rules
2655    Mappings {
2656        /// Source schema ID (e.g., copilot-json-v3)
2657        #[arg(long, short = 's')]
2658        source: Option<String>,
2659
2660        /// Target schema ID (e.g., copilot-jsonl-v1)
2661        #[arg(long, short = 't')]
2662        target: Option<String>,
2663
2664        /// Filter mappings by semantic tag (e.g., session_id, message_content)
2665        #[arg(long)]
2666        tag: Option<String>,
2667
2668        /// Output as JSON
2669        #[arg(long)]
2670        json: bool,
2671    },
2672}
2673
2674// ============================================================================
2675// Shell Completion Enum
2676// ============================================================================
2677
2678/// Supported shells for completion generation
2679#[derive(Clone, Debug, clap::ValueEnum)]
2680pub enum CompletionShell {
2681    /// Bash shell
2682    Bash,
2683    /// Zsh shell
2684    Zsh,
2685    /// Fish shell
2686    Fish,
2687    /// PowerShell
2688    Powershell,
2689    /// Elvish shell
2690    Elvish,
2691}