refactor CLI command structure

.gitignore

···
 target
-plcbundle-*
+plcbundle-go
+plcbundle-rs
+plcbundle
 test_bundles
 test_bundles*
 .claude

Cargo.toml

···
 
 [[bin]]
 name = "plcbundle-rs"
-path = "src/cli/plcbundle-rs.rs"
+path = "src/cli/mod.rs"
 
 [lib]
 crate-type = ["cdylib", "rlib"]

RULES.md

···
 Index::init(&dir, origin, force)?;
 Index::rebuild_from_bundles(&dir, origin, callback)?;
 
-// ✅ CORRECT - Via BundleManager API
+// ❌ WRONG - Direct BundleManager::new (no helpful error messages)
+let manager = BundleManager::new(dir)?;
+
+// ✅ CORRECT - Via cli::utils::create_manager (with helpful errors)
+let manager = super::utils::create_manager(dir, verbose)?;
 manager.load_bundle(num, options)?;
 manager.get_operation_raw(bundle, pos)?;
 manager.delete_bundle_files(&[num])?;
-manager.init_repository(origin, force)?;
-manager.rebuild_index(origin, callback)?;
+
+// For static operations (init/rebuild don't need existing repository)
+BundleManager::init_repository(origin, force)?;
+BundleManager::rebuild_index(origin, callback)?;
 ```
 
 ## Architecture

src/cli/cmd_bench.rs

···
 use anyhow::Result;
 use clap::Args;
 use plcbundle::BundleManager;
-use std::io::{Read, Write};
+use std::io::Read;
 use std::path::PathBuf;
 use std::time::Instant;
 
 #[derive(Args)]
+#[command(
+    about = "Benchmark bundle operations",
+    after_help = "Examples:\n  \
+            # Run all benchmarks with default iterations\n  \
+            plcbundle bench\n\n  \
+            # Benchmark specific operation\n  \
+            plcbundle bench --op-read --iterations 1000\n\n  \
+            # Benchmark DID lookup\n  \
+            plcbundle bench --did-lookup -n 500\n\n  \
+            # Run on specific bundle\n  \
+            plcbundle bench --bundle 100\n\n  \
+            # JSON output for analysis\n  \
+            plcbundle bench --format json > benchmark.json"
+)]
 pub struct BenchCommand {
     /// Number of iterations for each benchmark
     #[arg(short = 'n', long, default_value = "100")]
···
 }
 
 pub fn run(cmd: BenchCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     // Determine which benchmarks to run
     let run_all = cmd.all
···
     };
 
     let mut processed = 0;
-    for (i, &bundle_num) in bundles.iter().enumerate() {
+    for (_i, &bundle_num) in bundles.iter().enumerate() {
         let size = match bundle_compressed_size(manager, bundle_num)? {
             Some(size) => size,
             None => continue,

src/cli/cmd_did.rs

···
 // DID Resolution and Query commands
 use anyhow::Result;
+use clap::{Args, Subcommand};
 use plcbundle::{BundleManager, DIDLookupStats, DIDLookupTimings};
 use std::path::PathBuf;
 
-// ============================================================================
+#[derive(Args)]
+#[command(
+    about = "DID operations and queries",
+    long_about = "Query and analyze DIDs in the bundle repository. All commands\nrequire a DID index to be built for optimal performance.",
+    after_help = "Examples:\n  \
+            # Resolve DID to current document\n  \
+            plcbundle did resolve did:plc:524tuhdhh3m7li5gycdn6boe\n\n  \
+            # Show DID operation log\n  \
+            plcbundle did log did:plc:524tuhdhh3m7li5gycdn6boe\n\n  \
+            # Show complete audit log\n  \
+            plcbundle did history did:plc:524tuhdhh3m7li5gycdn6boe"
+)]
+pub struct DidCommand {
+    #[command(subcommand)]
+    pub command: DIDCommands,
+}
+
+#[derive(Args)]
+#[command(
+    about = "Resolve handle to DID",
+    long_about = "Resolves an AT Protocol handle to its DID using the handle resolver."
+)]
+pub struct HandleCommand {
+    /// Handle to resolve (e.g., tree.fail)
+    pub handle: String,
+
+    /// Handle resolver URL (defaults to quickdid.smokesignal.tools)
+    #[arg(long)]
+    pub handle_resolver: Option<String>,
+}
+
+#[derive(Subcommand)]
+pub enum DIDCommands {
+    /// Resolve DID to current W3C DID document
+    #[command(alias = "doc", alias = "document")]
+    Resolve {
+        /// DID or handle to resolve
+        did: String,
+
+        /// Handle resolver URL (e.g., https://quickdid.smokesignal.tools)
+        #[arg(long)]
+        handle_resolver: Option<String>,
+
+        /// Verbose output
+        #[arg(short, long)]
+        verbose: bool,
+    },
+
+    /// Show DID operation log
+    #[command(alias = "lookup", alias = "find", alias = "get", alias = "history")]
+    Log {
+        /// DID to show log for
+        did: String,
+
+        /// Verbose output
+        #[arg(short, long)]
+        verbose: bool,
+
+        /// Output as JSON
+        #[arg(long)]
+        json: bool,
+    },
+
+    /// Process multiple DIDs from file or stdin (TODO)
+    Batch {
+        /// Action: lookup, resolve, export
+        #[arg(long, default_value = "lookup")]
+        action: String,
+
+        /// Number of parallel workers
+        #[arg(long, default_value = "4")]
+        workers: usize,
+
+        /// Output file
+        #[arg(short, long)]
+        output: Option<PathBuf>,
+
+        /// Read from stdin
+        #[arg(long)]
+        stdin: bool,
+    },
+}
+
+pub fn run_did(cmd: DidCommand, dir: PathBuf) -> Result<()> {
+    match cmd.command {
+        DIDCommands::Resolve {
+            did,
+            handle_resolver,
+            verbose,
+        } => {
+            cmd_did_resolve(dir, did, handle_resolver, verbose)?;
+        }
+        DIDCommands::Log { did, verbose, json } => {
+            cmd_did_lookup(dir, did, verbose, json)?;
+        }
+        DIDCommands::Batch {
+            action,
+            workers,
+            output,
+            stdin,
+        } => {
+            cmd_did_batch(dir, action, workers, output, stdin)?;
+        }
+    }
+    Ok(())
+}
+
+pub fn run_handle(cmd: HandleCommand, dir: PathBuf) -> Result<()> {
+    cmd_did_handle(dir, cmd.handle, cmd.handle_resolver)?;
+    Ok(())
+}
+
 // DID RESOLVE - Convert DID to W3C DID Document
-// ============================================================================
 
 pub fn cmd_did_resolve(
     dir: PathBuf,
···
     (hash % 256) as u8
 }
 
-// ============================================================================
 // DID HANDLE - Resolve handle to DID
-// ============================================================================
 
 pub fn cmd_did_handle(
     dir: PathBuf,
···
     Ok(())
 }
 
-// ============================================================================
 // DID LOOKUP - Find all operations for a DID
-// ============================================================================
 
 pub fn cmd_did_lookup(dir: PathBuf, input: String, verbose: bool, json: bool) -> Result<()> {
     use plcbundle::constants;
···
     }
 }
 
-// ============================================================================
 // DID BATCH - Process multiple DIDs (TODO)
-// ============================================================================
 
 pub fn cmd_did_batch(
     _dir: PathBuf,

src/cli/cmd_diff.rs

···
 }
 
 pub fn run(cmd: DiffCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     let rt = Runtime::new()?;
 
···
         };
 
         // Try to load bundle from target directory
-        let target_manager = BundleManager::new(target_dir.to_path_buf())
-            .context("Failed to create manager for target directory")?;
+        let target_manager = super::utils::create_manager(target_dir.to_path_buf(), false, false)?;
         let target_result = target_manager
             .load_bundle(bundle_num, plcbundle::LoadOptions::default())
             .context("Failed to load bundle from target directory")?;

src/cli/cmd_export.rs

···
 use anyhow::Result;
+use clap::{Args, ValueEnum};
 use indicatif::HumanDuration;
-use plcbundle::BundleManager;
 use std::fs::File;
 use std::io::{self, BufRead, BufReader, BufWriter, Write};
 use std::path::PathBuf;
···
 
 use super::progress::ProgressBar;
 use super::utils;
-// ExportFormat is defined in plcbundle-rs.rs
-// Access it via the parent module
-use super::ExportFormat;
+
+#[derive(Args)]
+#[command(about = "Export operations to different formats")]
+pub struct ExportCommand {
+    /// Bundle range (e.g., "1-100")
+    #[arg(short, long)]
+    pub range: Option<String>,
+
+    /// Export all bundles
+    #[arg(long)]
+    pub all: bool,
+
+    /// Bundle range (legacy, use --range instead)
+    #[arg(long, hide = true)]
+    pub bundles: Option<String>,
+
+    /// Output format
+    #[arg(short = 'f', long, default_value = "jsonl")]
+    pub format: ExportFormat,
+
+    /// Output file (default: stdout)
+    #[arg(short, long)]
+    pub output: Option<PathBuf>,
+
+    /// Limit number of operations to export
+    #[arg(long)]
+    pub count: Option<usize>,
+
+    /// Export operations after this timestamp (ISO 8601 format)
+    #[arg(long)]
+    pub after: Option<String>,
+
+    /// Filter by DID
+    #[arg(long)]
+    pub did: Option<String>,
+
+    /// Filter by operation type
+    #[arg(long)]
+    pub op_type: Option<String>,
+
+    /// Compression
+    #[arg(short = 'z', long)]
+    pub compress: bool,
+}
 
-pub fn cmd_export(
-    dir: PathBuf,
-    range: Option<String>,
-    all: bool,
-    bundles: Option<String>, // Legacy flag
-    format: ExportFormat,
-    output: Option<PathBuf>,
-    count: Option<usize>,
-    after: Option<String>,
-    did: Option<String>,
-    op_type: Option<String>,
-    _compress: bool,
-    quiet: bool,
-    verbose: bool,
-) -> Result<()> {
+#[derive(Debug, Clone, ValueEnum)]
+pub enum ExportFormat {
+    Jsonl,
+    Json,
+    Csv,
+    Parquet,
+}
+
+pub fn run(cmd: ExportCommand, dir: PathBuf, quiet: bool, verbose: bool) -> Result<()> {
+    let range = cmd.range;
+    let all = cmd.all;
+    let bundles = cmd.bundles;
+    let format = cmd.format;
+    let output = cmd.output;
+    let count = cmd.count;
+    let after = cmd.after;
+    let did = cmd.did;
+    let op_type = cmd.op_type;
+    let _compress = cmd.compress;
     // Create BundleManager (follows RULES.md - NO direct file access from CLI)
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), verbose, quiet)?;
     let index = manager.get_index();
     let max_bundle = index.last_bundle;
 
···
     let start = Instant::now();
     let mut exported_count = 0;
     let mut bundles_processed = 0;
-    let mut bytes_written = Arc::new(Mutex::new(0u64));
+    let bytes_written = Arc::new(Mutex::new(0u64));
     let mut output_buffer = String::with_capacity(1024 * 1024); // 1MB buffer
     const BATCH_SIZE: usize = 10000;
 

src/cli/cmd_index.rs

···
 // DID Index CLI commands
 use super::utils;
 use anyhow::Result;
+use clap::{Args, Subcommand};
 use plcbundle::{BundleManager, constants};
 use std::path::PathBuf;
 use std::time::Instant;
 
+#[derive(Args)]
+#[command(
+    about = "DID index management",
+    long_about = "Manage the DID position index which maps DIDs to their bundle locations.\nThis index enables fast O(1) DID lookups and is required for DID\nresolution and query operations.",
+    after_help = "Examples:\n  \
+            # Build DID position index\n  \
+            plcbundle index build\n\n  \
+            # Repair DID index (rebuild from bundles)\n  \
+            plcbundle index repair\n\n  \
+            # Show DID index statistics\n  \
+            plcbundle index stats\n\n  \
+            # Verify DID index integrity\n  \
+            plcbundle index verify"
+)]
+pub struct IndexCommand {
+    #[command(subcommand)]
+    pub command: IndexCommands,
+}
+
+#[derive(Subcommand)]
+pub enum IndexCommands {
+    /// Build DID position index
+    #[command(after_help = "Examples:\n  \
+            # Build index\n  \
+            plcbundle index build\n\n  \
+            # Force rebuild from scratch\n  \
+            plcbundle index build --force")]
+    Build {
+        /// Rebuild even if index exists
+        #[arg(long)]
+        force: bool,
+    },
+
+    /// Repair DID index
+    #[command(alias = "rebuild")]
+    Repair {},
+
+    /// Show DID index statistics
+    #[command(alias = "info")]
+    Stats {
+        /// Output as JSON
+        #[arg(long)]
+        json: bool,
+    },
+
+    /// Verify DID index integrity
+    #[command(alias = "check")]
+    Verify {
+        /// Verbose output
+        #[arg(short, long)]
+        verbose: bool,
+    },
+
+    /// Debug and inspect DID index internals
+    #[command(alias = "inspect")]
+    Debug {
+        /// Show specific shard (0-255 or hex like 0xac)
+        #[arg(short, long)]
+        shard: Option<String>,
+
+        /// Output as JSON
+        #[arg(long)]
+        json: bool,
+    },
+
+    /// Compact delta segments in DID index
+    #[command(after_help = "Examples:\n  \
+            # Compact all shards\n  \
+            plcbundle index compact\n\n  \
+            # Compact specific shards\n  \
+            plcbundle index compact --shards 0xac 0x12 0xff")]
+    Compact {
+        /// Specific shards to compact (0-255 or hex like 0xac)
+        #[arg(short, long, value_delimiter = ' ')]
+        shards: Option<Vec<String>>,
+    },
+}
+
+pub fn run(cmd: IndexCommand, dir: PathBuf) -> Result<()> {
+    match cmd.command {
+        IndexCommands::Build { force } => {
+            cmd_index_build(dir, force)?;
+        }
+        IndexCommands::Repair {} => {
+            cmd_index_repair(dir)?;
+        }
+        IndexCommands::Stats { json } => {
+            cmd_index_stats(dir, json)?;
+        }
+        IndexCommands::Verify { verbose } => {
+            cmd_index_verify(dir, verbose)?;
+        }
+        IndexCommands::Debug { shard, json } => {
+            let shard_num = shard.map(|s| parse_shard(&s)).transpose()?;
+            cmd_index_debug(dir, shard_num, json)?;
+        }
+        IndexCommands::Compact { shards } => {
+            let shard_nums = shards
+                .map(|shard_list| {
+                    shard_list
+                        .iter()
+                        .map(|s| parse_shard(s))
+                        .collect::<Result<Vec<u8>>>()
+                })
+                .transpose()?;
+            cmd_index_compact(dir, shard_nums)?;
+        }
+    }
+    Ok(())
+}
+
+/// Parse shard number from string (supports hex 0xac or decimal)
+fn parse_shard(s: &str) -> Result<u8> {
+    if s.starts_with("0x") || s.starts_with("0X") {
+        u8::from_str_radix(&s[2..], 16)
+            .map_err(|_| anyhow::anyhow!("Invalid shard number: {}", s))
+    } else {
+        s.parse::<u8>()
+            .map_err(|_| anyhow::anyhow!("Invalid shard number: {}", s))
+    }
+}
+
 pub fn cmd_index_build(dir: PathBuf, force: bool) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     // Check if index exists
     let did_index = manager.get_did_index_stats();
···
 }
 
 pub fn cmd_index_repair(dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     // Check if index config exists (even if corrupted)
     let did_index = manager.get_did_index();
···
 }
 
 pub fn cmd_index_stats(dir: PathBuf, json: bool) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     // Get raw stats from did_index
     let did_index = manager.get_did_index();
···
 }
 
 pub fn cmd_index_verify(dir: PathBuf, verbose: bool) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     let did_index = manager.get_did_index();
     let stats_map = did_index.read().unwrap().get_stats();
···
 }
 
 pub fn cmd_index_debug(dir: PathBuf, shard: Option<u8>, json: bool) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     let did_index = manager.get_did_index();
     let stats_map = did_index.read().unwrap().get_stats();
···
     Ok(())
 }
 
-#[allow(dead_code)]
 pub fn cmd_index_compact(dir: PathBuf, shards: Option<Vec<u8>>) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     let did_index = manager.get_did_index();
     let stats_map = did_index.read().unwrap().get_stats();

src/cli/cmd_init.rs

···
 use std::path::PathBuf;
 
 #[derive(Args)]
+#[command(
+    about = "Initialize a new PLC bundle repository",
+    long_about = "Creates a new repository with an empty index file. Similar to 'git init'.",
+    after_help = "Examples:\n  \
+            # Initialize in current directory\n  \
+            plcbundle init\n\n  \
+            # Initialize in specific directory\n  \
+            plcbundle init /path/to/bundles\n\n  \
+            # Set custom origin identifier\n  \
+            plcbundle init --origin my-node\n\n  \
+            # Force reinitialize existing repository\n  \
+            plcbundle init --force"
+)]
 pub struct InitCommand {
     /// Directory to initialize (default: current directory)
     #[arg(default_value = ".")]

src/cli/cmd_inspect.rs

···
                   • Service endpoint analysis\n  \
                   • Temporal distribution\n  \
                   • Size analysis\n\n\
-                  Can inspect either by bundle number (from repository) or direct file path."
+                  Can inspect either by bundle number (from repository) or direct file path.",
+    after_help = "Examples:\n  \
+            # Inspect from repository\n  \
+            plcbundle inspect 42\n\n  \
+            # Inspect specific file\n  \
+            plcbundle inspect /path/to/000042.jsonl.zst\n  \
+            plcbundle inspect 000042.jsonl.zst\n\n  \
+            # Skip certain analysis sections\n  \
+            plcbundle inspect 42 --skip-patterns\n\n  \
+            # Show sample operations\n  \
+            plcbundle inspect 42 --samples --sample-count 20\n\n  \
+            # JSON output (for scripting)\n  \
+            plcbundle inspect 42 --json"
 )]
 pub struct InspectCommand {
     /// Bundle number or file path to inspect
···
 }
 
 pub fn run(cmd: InspectCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+    let manager = super::utils::create_manager(dir.clone(), false, false)?;
 
     // Resolve target to bundle number or file path
     let (bundle_num, file_path) = resolve_target(&cmd.target, &dir)?;

src/cli/cmd_ls.rs

···
 use anyhow::Result;
 use clap::Args;
-use plcbundle::BundleManager;
 use plcbundle::format::format_duration_compact;
 use std::path::PathBuf;
 
 #[derive(Args)]
+#[command(
+    about = "List bundles (machine-readable)",
+    after_help = "Examples:\n  \
+            # List all bundles\n  \
+            plcbundle ls\n\n  \
+            # Last 10 bundles\n  \
+            plcbundle ls -n 10\n\n  \
+            # Oldest first\n  \
+            plcbundle ls --reverse\n\n  \
+            # Custom format\n  \
+            plcbundle ls --format \"bundle,hash,date,size\"\n\n  \
+            # CSV format\n  \
+            plcbundle ls --separator \",\"\n\n  \
+            # Scripting examples\n  \
+            plcbundle ls | awk '{print $1}'           # Just bundle numbers\n  \
+            plcbundle ls | grep 000150                # Find specific bundle\n  \
+            plcbundle ls -n 5 | cut -f1,4             # First and 4th columns\n  \
+            plcbundle ls --format bundle,hash         # Custom columns\n  \
+            plcbundle ls --separator \",\" > bundles.csv # Export to CSV"
+)]
 pub struct LsCommand {
     /// Show only last N bundles (0 = all)
     #[arg(short = 'n', long, default_value = "0")]
···
     pub separator: String,
 }
 
-pub fn run(cmd: LsCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir)?;
+pub fn run(cmd: LsCommand, dir: PathBuf, verbose: bool, quiet: bool) -> Result<()> {
+    let manager = super::utils::create_manager(dir, verbose, quiet)?;
 
     // Get all bundle metadata from the index
     let bundles = super::utils::get_all_bundle_metadata(&manager);

src/cli/cmd_mempool.rs

···
 // src/bin/commands/mempool.rs
 use super::utils;
+use super::utils::HasGlobalFlags;
 use anyhow::Result;
 use clap::{Args, Subcommand};
 use plcbundle::format::format_number;
···
 use std::path::PathBuf;
 
 #[derive(Args)]
+#[command(
+    about = "Manage mempool operations",
+    long_about = "The mempool stores operations waiting to be bundled. It maintains\nstrict chronological order and automatically validates consistency.",
+    alias = "mp",
+    after_help = "Examples:\n  \
+            # Show mempool status\n  \
+            plcbundle mempool\n  \
+            plcbundle mempool status\n\n  \
+            # Clear all operations\n  \
+            plcbundle mempool clear\n\n  \
+            # Export operations as JSONL\n  \
+            plcbundle mempool dump\n  \
+            plcbundle mempool dump > operations.jsonl\n\n  \
+            # Using alias\n  \
+            plcbundle mp status"
+)]
 pub struct MempoolCommand {
     #[command(subcommand)]
     pub command: Option<MempoolSubcommand>,
···
     },
 }
 
+impl HasGlobalFlags for MempoolCommand {
+    fn verbose(&self) -> bool { self.verbose }
+    fn quiet(&self) -> bool { false }
+}
+
 pub fn run(cmd: MempoolCommand) -> Result<()> {
-    let manager = utils::create_manager(cmd.dir.clone(), cmd.verbose)?;
+    let manager = utils::create_manager_from_cmd(cmd.dir.clone(), &cmd)?;
 
     match cmd.command {
         Some(MempoolSubcommand::Status { verbose }) => {

src/cli/cmd_migrate.rs

···
 // Migrate command - convert bundles to multi-frame format
 use super::progress::ProgressBar;
-use super::utils::format_bytes;
+use super::utils::{format_bytes, HasGlobalFlags};
 use anyhow::{Result, bail};
 use clap::Args;
 use plcbundle::BundleManager;
···
     pub verbose: bool,
 }
 
-pub fn run(cmd: MigrateCommand, dir: PathBuf) -> Result<()> {
-    let manager = super::utils::create_manager(dir.clone(), cmd.verbose)?;
+impl HasGlobalFlags for MigrateCommand {
+    fn verbose(&self) -> bool { self.verbose }
+    fn quiet(&self) -> bool { false }
+}
+
+pub fn run(mut cmd: MigrateCommand, dir: PathBuf, global_verbose: bool) -> Result<()> {
+    // Merge global verbose flag with command's verbose flag
+    cmd.verbose = cmd.verbose || global_verbose;
+    let manager = super::utils::create_manager_from_cmd(dir.clone(), &cmd)?;
 
     // Auto-detect number of workers if 0
-    let workers = super::utils::get_num_workers(cmd.workers, 4);
+    let workers = super::utils::get_worker_threads(cmd.workers, 4);
 
     eprintln!("Scanning for legacy bundles in: {}\n", dir.display());
 
···
 
                         // Only update progress bar periodically to reduce lock contention
                         if current_count % update_interval == 0 || current_count == 1 {
-                            let mut prog = progress_arc.lock().unwrap();
+                            let prog = progress_arc.lock().unwrap();
                             prog.set_with_bytes(current_count, total_bytes);
                         }
 
···
                 let total_bytes = bytes_atomic.fetch_add(info.old_size, Ordering::Relaxed) + info.old_size;
 
                 // Update every bundle in sequential mode (no contention)
-                let mut prog = progress_arc.lock().unwrap();
+                let prog = progress_arc.lock().unwrap();
                 prog.set_with_bytes(current_count, total_bytes);
 
                 (info, result)
···
     {
         let final_count = count_atomic.load(Ordering::Relaxed);
         let final_bytes = bytes_atomic.load(Ordering::Relaxed);
-        let mut prog = progress_arc.lock().unwrap();
+        let prog = progress_arc.lock().unwrap();
         prog.set_with_bytes(final_count, final_bytes);
         prog.finish();
     }

src/cli/cmd_op.rs

···
 use anyhow::Result;
-use plcbundle::{BundleManager, LoadOptions, constants};
+use clap::{Args, Subcommand};
+use plcbundle::{LoadOptions, constants};
 use std::path::PathBuf;
 use std::time::Instant;
 
+#[derive(Args)]
+#[command(
+    about = "Operation queries and inspection",
+    long_about = "Direct access to individual operations within bundles using either:\n  • Bundle number + position (e.g., 42 1337)\n  • Global position (e.g., 420000)\n\nGlobal position format: (bundleNumber × 10,000) + position\nExample: 88410345 = bundle 8841, position 345",
+    alias = "operation",
+    alias = "record",
+    after_help = "Examples:\n  \
+            # Get operation as JSON\n  \
+            plcbundle op get 42 1337\n  \
+            plcbundle op get 420000\n\n  \
+            # Show operation (formatted)\n  \
+            plcbundle op show 42 1337\n  \
+            plcbundle op show 88410345\n\n  \
+            # Find by CID\n  \
+            plcbundle op find bafyreig3..."
+)]
+pub struct OpCommand {
+    #[command(subcommand)]
+    pub command: OpCommands,
+}
+
+#[derive(Subcommand)]
+pub enum OpCommands {
+    /// Get operation as JSON (machine-readable)
+    ///
+    /// Supports two input formats:
+    ///   1. Bundle number + position: get 42 1337
+    ///   2. Global position: get 420000
+    ///
+    /// Global position = (bundleNumber × 10,000) + position
+    #[command(after_help = "Examples:\n  \
+            # By bundle + position\n  \
+            plcbundle op get 42 1337\n\n  \
+            # By global position\n  \
+            plcbundle op get 88410345\n\n  \
+            # Pipe to jq\n  \
+            plcbundle op get 42 1337 | jq .did")]
+    Get {
+        /// Bundle number (or global position if only one arg)
+        bundle: u32,
+
+        /// Operation position within bundle (optional if using global position)
+        position: Option<usize>,
+    },
+
+    /// Show operation with formatted output
+    ///
+    /// Displays operation in human-readable format with:
+    ///   • Bundle location and global position
+    ///   • DID and CID
+    ///   • Timestamp
+    ///   • Nullification status
+    ///   • Parsed operation details
+    ///   • Performance metrics (when not quiet)
+    #[command(after_help = "Examples:\n  \
+            # By bundle + position\n  \
+            plcbundle op show 42 1337\n\n  \
+            # By global position\n  \
+            plcbundle op show 88410345\n\n  \
+            # Quiet mode (minimal output)\n  \
+            plcbundle op show 42 1337 -q")]
+    Show {
+        /// Bundle number (or global position if only one arg)
+        bundle: u32,
+
+        /// Operation position within bundle (optional if using global position)
+        position: Option<usize>,
+    },
+
+    /// Find operation by CID across all bundles
+    ///
+    /// Searches the entire repository for an operation with the given CID
+    /// and returns its location (bundle + position).
+    ///
+    /// Note: This performs a full scan and can be slow on large repositories.
+    #[command(after_help = "Examples:\n  \
+            # Find by CID\n  \
+            plcbundle op find bafyreig3tg4k...\n\n  \
+            # Use with op get\n  \
+            plcbundle op find bafyreig3... | awk '{print $3, $5}' | xargs plcbundle op get")]
+    Find {
+        /// CID to search for
+        cid: String,
+    },
+}
+
+pub fn run(cmd: OpCommand, dir: PathBuf, quiet: bool) -> Result<()> {
+    match cmd.command {
+        OpCommands::Get { bundle, position } => {
+            cmd_op_get(dir, bundle, position, quiet)?;
+        }
+        OpCommands::Show { bundle, position } => {
+            cmd_op_show(dir, bundle, position, quiet)?;
+        }
+        OpCommands::Find { cid } => {
+            cmd_op_find(dir, cid, quiet)?;
+        }
+    }
+    Ok(())
+}
+
 /// Parse operation position - supports both global position and bundle + position
 /// Mimics Go version: small numbers (< 10000) are treated as bundle 1, position N
 pub fn parse_op_position(bundle: u32, position: Option<usize>) -> (u32, usize) {
···
 pub fn cmd_op_get(dir: PathBuf, bundle: u32, position: Option<usize>, quiet: bool) -> Result<()> {
     let (bundle_num, op_index) = parse_op_position(bundle, position);
 
-    let manager = BundleManager::new(dir)?;
+    let manager = super::utils::create_manager(dir, false, quiet)?;
 
     if quiet {
         // Just output JSON - no stats
···
 pub fn cmd_op_show(dir: PathBuf, bundle: u32, position: Option<usize>, quiet: bool) -> Result<()> {
     let (bundle_num, op_index) = parse_op_position(bundle, position);
 
-    let manager = BundleManager::new(dir)?;
+    let manager = super::utils::create_manager(dir, false, quiet)?;
 
     // Use the new get_operation API instead of loading entire bundle
     let load_start = Instant::now();
···
 }
 
 pub fn cmd_op_find(dir: PathBuf, cid: String, quiet: bool) -> Result<()> {
-    let manager = BundleManager::new(dir)?;
+    let manager = super::utils::create_manager(dir, false, quiet)?;
     let last_bundle = manager.get_last_bundle();
 
     if !quiet {

src/cli/cmd_query.rs

···
 use anyhow::Result;
+use clap::{Args, ValueEnum};
 use plcbundle::*;
 use std::io::Write;
 use std::path::PathBuf;
···
 
 use super::progress::ProgressBar as CustomProgressBar;
 use super::utils;
-// QueryModeArg and OutputFormat are defined in plcbundle-rs.rs
-// Access them via the parent module
-use super::{OutputFormat, QueryModeArg};
+
+#[derive(Args)]
+#[command(
+    about = "Query bundles with JMESPath or simple path",
+    alias = "q"
+)]
+pub struct QueryCommand {
+    /// Query expression (e.g., "did", "operation.type", etc.)
+    pub expression: String,
+
+    /// Bundle range (e.g., "1-10,15,20-25" or "latest:10" for last 10)
+    #[arg(short, long)]
+    pub bundles: Option<String>,
+
+    /// Number of threads (0 = auto)
+    #[arg(short = 'j', long, default_value = "0")]
+    pub threads: usize,
+
+    /// Query mode
+    #[arg(short = 'm', long, default_value = "auto")]
+    pub mode: QueryModeArg,
+
+    /// Batch size for output
+    #[arg(long, default_value = "2000")]
+    pub batch_size: usize,
+
+    /// Output format
+    #[arg(short = 'f', long, default_value = "jsonl")]
+    pub format: OutputFormat,
+
+    /// Output file (default: stdout)
+    #[arg(short, long)]
+    pub output: Option<PathBuf>,
 
-pub struct StdoutHandler {
-    lock: Mutex<()>,
-    stats_only: bool,
+    /// Show statistics only, don't output results
+    #[arg(long)]
+    pub stats_only: bool,
 }
 
-impl StdoutHandler {
-    pub fn new(stats_only: bool) -> Self {
-        Self {
-            lock: Mutex::new(()),
-            stats_only,
-        }
-    }
+#[derive(Debug, Clone, ValueEnum)]
+pub enum QueryModeArg {
+    /// Auto-detect based on query
+    Auto,
+    /// Simple path mode (faster)
+    Simple,
+    /// JMESPath mode (flexible)
+    Jmespath,
 }
 
-impl OutputHandler for StdoutHandler {
-    fn write_batch(&self, batch: &str) -> Result<()> {
-        if self.stats_only {
-            return Ok(());
-        }
-        let _lock = self.lock.lock().unwrap();
-        std::io::stdout().write_all(batch.as_bytes())?;
-        Ok(())
-    }
+#[derive(Debug, Clone, ValueEnum)]
+pub enum OutputFormat {
+    /// JSON Lines (one per line)
+    Jsonl,
+    /// Pretty JSON
+    Json,
+    /// CSV
+    Csv,
+    /// Plain text (values only)
+    Plain,
 }
 
-pub fn cmd_query(
-    expression: String,
-    dir: PathBuf,
-    bundles_spec: Option<String>,
-    threads: usize,
-    mode: QueryModeArg,
-    batch_size: usize,
-    _format: OutputFormat,
-    _output: Option<PathBuf>,
+pub struct StdoutHandler {
+    lock: Mutex<()>,
     stats_only: bool,
-    quiet: bool,
-    verbose: bool,
-) -> Result<()> {
+}
+
+pub fn run(cmd: QueryCommand, dir: PathBuf, quiet: bool, verbose: bool) -> Result<()> {
+    let expression = cmd.expression;
+    let bundles_spec = cmd.bundles;
+    let threads = cmd.threads;
+    let mode = cmd.mode;
+    let batch_size = cmd.batch_size;
+    let _format = cmd.format;
+    let _output = cmd.output;
+    let stats_only = cmd.stats_only;
     let num_threads = if threads == 0 {
         std::thread::available_parallelism()
             .map(|n| n.get())
···
 
     Ok(())
 }
+
+impl StdoutHandler {
+    pub fn new(stats_only: bool) -> Self {
+        Self {
+            lock: Mutex::new(()),
+            stats_only,
+        }
+    }
+}
+
+impl OutputHandler for StdoutHandler {
+    fn write_batch(&self, batch: &str) -> Result<()> {
+        if self.stats_only {
+            return Ok(());
+        }
+        let _lock = self.lock.lock().unwrap();
+        std::io::stdout().write_all(batch.as_bytes())?;
+        Ok(())
+    }
+}

src/cli/cmd_random.rs

···
 use anyhow::Result;
 use clap::Args;
-use plcbundle::BundleManager;
 use std::path::PathBuf;
 
-/// Sample random DIDs without touching bundle files.
 #[derive(Args, Debug)]
+#[command(about = "Output random DIDs sampled from the index")]
 pub struct RandomCommand {
     /// Number of random DIDs to output
     #[arg(short = 'n', long = "count", default_value = "10")]
···
 }
 
 pub fn run(cmd: RandomCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir)?;
+    let manager = super::utils::create_manager(dir, false, false)?;
     let count = cmd.count.max(1);
     let dids = manager.sample_random_dids(count, cmd.seed)?;
 

src/cli/cmd_rebuild.rs

···
 // Rebuild plc_bundles.json from existing bundle files
 use super::progress::ProgressBar;
-use super::utils::format_bytes;
+use super::utils::{format_bytes, HasGlobalFlags};
 use anyhow::Result;
 use clap::Args;
 use plcbundle::BundleManager;
···
     pub verbose: bool,
 }
 
-pub fn run(cmd: RebuildCommand, dir: PathBuf) -> Result<()> {
+impl HasGlobalFlags for RebuildCommand {
+    fn verbose(&self) -> bool { self.verbose }
+    fn quiet(&self) -> bool { false }
+}
+
+pub fn run(mut cmd: RebuildCommand, dir: PathBuf, global_verbose: bool) -> Result<()> {
+    // Merge global verbose flag with command's verbose flag
+    cmd.verbose = cmd.verbose || global_verbose;
     eprintln!("Rebuilding bundle index from: {}\n", dir.display());
 
     let start = Instant::now();

src/cli/cmd_rollback.rs

···
 use std::path::PathBuf;
 
 #[derive(Args)]
+#[command(
+    about = "Rollback repository to earlier state",
+    after_help = "Examples:\n  \
+            # Rollback TO bundle 100 (keeps 1-100, removes 101+)\n  \
+            plcbundle rollback --to 100\n\n  \
+            # Remove last 5 bundles\n  \
+            plcbundle rollback --last 5\n\n  \
+            # Rollback without confirmation\n  \
+            plcbundle rollback --to 50 --force\n\n  \
+            # Rollback and rebuild DID index\n  \
+            plcbundle rollback --to 100 --rebuild-did-index\n\n  \
+            # Rollback but keep bundle files (index-only)\n  \
+            plcbundle rollback --to 100 --keep-files"
+)]
 pub struct RollbackCommand {
     /// Rollback TO this bundle (keeps it)
     #[arg(long)]
···
 
 pub fn run(cmd: RollbackCommand, dir: PathBuf) -> Result<()> {
     // Step 1: Validate options and calculate plan
-    let mut manager = BundleManager::new(dir.clone())?;
+    let mut manager = super::utils::create_manager(dir.clone(), false, false)?;
     let plan = calculate_rollback_plan(&manager, &cmd)?;
 
     // Step 2: Display plan and get confirmation

src/cli/cmd_server.rs

···
 #[cfg(feature = "server")]
 use super::utils;
 #[cfg(feature = "server")]
-use chrono::Utc;
-#[cfg(feature = "server")]
 use plcbundle::BundleManager;
 #[cfg(feature = "server")]
 use plcbundle::server::{Server, ServerConfig};

src/cli/cmd_stats.rs

···
-// Stats command implementation will be moved here
-// For now, this is handled in main.rs
-// TODO: Extract the full stats implementation
+use anyhow::Result;
+use clap::{Args, ValueEnum};
+use std::path::PathBuf;
+
+#[derive(Args)]
+#[command(about = "Display statistics about bundles")]
+pub struct StatsCommand {
+    /// Bundle range
+    #[arg(short, long)]
+    pub bundles: Option<String>,
+
+    /// Statistics type
+    #[arg(short = 't', long, default_value = "summary")]
+    pub stat_type: StatType,
+
+    /// Output format
+    #[arg(short = 'f', long, default_value = "human")]
+    pub format: InfoFormat,
+}
+
+#[derive(Debug, Clone, ValueEnum)]
+pub enum StatType {
+    /// Summary statistics
+    Summary,
+    /// Operation type distribution
+    Operations,
+    /// DID statistics
+    Dids,
+    /// Timeline statistics
+    Timeline,
+}
+
+#[derive(Debug, Clone, ValueEnum)]
+pub enum InfoFormat {
+    /// Human-readable output
+    Human,
+    /// JSON output
+    Json,
+    /// YAML output
+    Yaml,
+    /// Table format
+    Table,
+}
+
+pub fn run(_cmd: StatsCommand, _dir: PathBuf) -> Result<()> {
+    println!("Stats not yet implemented");
+    Ok(())
+}

src/cli/cmd_status.rs

···
 use plcbundle::*;
 use std::path::PathBuf;
 
+use super::cmd_stats::InfoFormat;
 use super::utils;
 
 #[derive(Parser)]
+#[command(
+    about = "Show comprehensive repository status",
+    long_about = "Displays an overview of the repository including bundle statistics,\nDID index status, mempool state, and health recommendations.",
+    alias = "info",
+    after_help = "Examples:\n  \
+            # Show repository status\n  \
+            plcbundle status\n\n  \
+            # Show detailed status with recent bundles\n  \
+            plcbundle status --detailed\n\n  \
+            # JSON output for scripting\n  \
+            plcbundle status --format json\n\n  \
+            # Using legacy 'info' alias\n  \
+            plcbundle info"
+)]
 pub struct StatusCommand {
     /// Show detailed information
     #[arg(short, long)]
···
 
     /// Output format
     #[arg(short = 'f', long, default_value = "human")]
-    pub format: super::InfoFormat,
+    pub format: InfoFormat,
 }
 
 pub fn run(cmd: StatusCommand, dir: PathBuf) -> Result<()> {
-    let manager = utils::create_manager(dir.clone(), false)?;
+    let manager = utils::create_manager(dir.clone(), false, false)?;
     let index = manager.get_index();
 
     match cmd.format {
-        super::InfoFormat::Human => print_human_status(&manager, &index, &dir, cmd.detailed)?,
-        super::InfoFormat::Json => print_json_status(&manager, &index, &dir)?,
+        InfoFormat::Human => print_human_status(&manager, &index, &dir, cmd.detailed)?,
+        InfoFormat::Json => print_json_status(&manager, &index, &dir)?,
         _ => {
             anyhow::bail!("Only 'human' and 'json' formats are supported");
         }

src/cli/cmd_sync.rs

···
 use super::utils;
+use super::utils::HasGlobalFlags;
 use anyhow::Result;
 use clap::Args;
 use plcbundle::{
-    BundleManager, constants,
+    constants,
     sync::{CliLogger, PLCClient, ServerLogger, SyncConfig, SyncManager},
 };
 use std::path::PathBuf;
···
 use std::time::Duration;
 
 #[derive(Args)]
+#[command(
+    about = "Fetch new bundles from PLC directory",
+    long_about = "Download new operations from the PLC directory and create bundles.\nSimilar to 'git fetch' - updates your local repository with new data.",
+    alias = "fetch",
+    after_help = "Examples:\n  \
+            # Fetch new bundles once\n  \
+            plcbundle sync\n\n  \
+            # Run continuously (daemon mode)\n  \
+            plcbundle sync --continuous\n\n  \
+            # Custom sync interval\n  \
+            plcbundle sync --continuous --interval 30s\n\n  \
+            # Fetch maximum 10 bundles then stop\n  \
+            plcbundle sync --max-bundles 10"
+)]
 pub struct SyncCommand {
     /// PLC directory URL
     #[arg(long, default_value = constants::DEFAULT_PLC_DIRECTORY_URL)]
···
     pub quiet: bool,
 }
 
+impl HasGlobalFlags for SyncCommand {
+    fn verbose(&self) -> bool { self.verbose }
+    fn quiet(&self) -> bool { self.quiet }
+}
+
 fn parse_duration(s: &str) -> Result<Duration, String> {
     if let Some(s) = s.strip_suffix('s') {
         s.parse::<u64>()
···
         }
 
         let client = PLCClient::new(&cmd.plc)?;
-        let manager = Arc::new(BundleManager::new(cmd.dir)?.with_verbose(cmd.verbose));
+        let dir = cmd.dir.clone();
+        let manager = Arc::new(super::utils::create_manager_from_cmd(dir, &cmd)?);
 
         let config = SyncConfig {
             plc_url: cmd.plc.clone(),

src/cli/cmd_verify.rs

···
 use super::progress::ProgressBar;
-use super::utils::{format_bytes, format_number, parse_bundle_range_simple};
+use super::utils::{format_bytes, format_number, parse_bundle_range_simple, HasGlobalFlags};
 use anyhow::{Result, bail};
 use clap::Args;
 use plcbundle::{BundleManager, VerifySpec};
···
 use std::time::Instant;
 
 #[derive(Args)]
+#[command(
+    about = "Verify bundle integrity and chain",
+    after_help = "Examples:\n  \
+            # Verify entire chain\n  \
+            plcbundle verify\n  \
+            plcbundle verify --chain\n\n  \
+            # Verify specific bundle\n  \
+            plcbundle verify --bundle 42\n\n  \
+            # Verify range of bundles\n  \
+            plcbundle verify --range 1-100\n\n  \
+            # Verbose output\n  \
+            plcbundle verify --chain -v\n\n  \
+            # Parallel verification (faster for ranges)\n  \
+            plcbundle verify --range 1-1000 --parallel --workers 8"
+)]
 pub struct VerifyCommand {
     /// Verify specific bundle number
     #[arg(short, long)]
···
     pub threads: usize,
 }
 
-pub fn run(cmd: VerifyCommand, dir: PathBuf) -> Result<()> {
-    let manager = BundleManager::new(dir.clone())?;
+impl HasGlobalFlags for VerifyCommand {
+    fn verbose(&self) -> bool { self.verbose }
+    fn quiet(&self) -> bool { false }
+}
+
+pub fn run(mut cmd: VerifyCommand, dir: PathBuf, global_verbose: bool) -> Result<()> {
+    // Merge global verbose flag with command's verbose flag
+    cmd.verbose = cmd.verbose || global_verbose;
+    let manager = super::utils::create_manager_from_cmd(dir.clone(), &cmd)?;
 
     // Determine number of threads
     let num_threads = if cmd.threads == 0 {

src/cli/mod.rs

···
+use anyhow::Result;
+use clap::{Parser, Subcommand};
+use plcbundle::*;
+use std::path::PathBuf;
+
+// CLI Commands (cmd_ prefix)
+mod cmd_bench;
+mod cmd_did;
+mod cmd_diff;
+mod cmd_export;
+mod cmd_index;
+mod cmd_init;
+mod cmd_inspect;
+mod cmd_ls;
+mod cmd_mempool;
+mod cmd_migrate;
+mod cmd_op;
+mod cmd_query;
+mod cmd_random;
+mod cmd_rebuild;
+mod cmd_rollback;
+mod cmd_server;
+mod cmd_stats;
+mod cmd_status;
+mod cmd_sync;
+mod cmd_verify;
+
+// Helper modules (no cmd_ prefix)
+mod logger;
+mod progress;
+mod utils;
+
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+#[derive(Parser)]
+#[command(name = "plcbundle")]
+#[command(version = VERSION)]
+#[command(about = concat!("plcbundle v", env!("CARGO_PKG_VERSION"), " (rust) - DID PLC Bundle Management"))]
+#[command(long_about = concat!(
+    "plcbundle v", env!("CARGO_PKG_VERSION"), " - DID PLC Bundle Management\n\n",
+    "Tool for archiving AT Protocol's DID PLC Directory operations\n",
+    "into immutable, cryptographically-chained bundles of 10,000\n",
+    "operations each.\n\n",
+    "Documentation: https://tangled.org/@atscan.net/plcbundle"
+))]
+#[command(author)]
+#[command(propagate_version = true)]
+struct Cli {
+    /// Repository directory
+    #[arg(short = 'C', long = "dir", global = true, default_value = ".")]
+    dir: PathBuf,
+
+    /// Suppress progress output
+    #[arg(short, long, global = true)]
+    quiet: bool,
+
+    /// Enable verbose output
+    #[arg(short, long, global = true)]
+    verbose: bool,
+
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    Query(cmd_query::QueryCommand),
+    Init(cmd_init::InitCommand),
+    Status(cmd_status::StatusCommand),
+    Ls(cmd_ls::LsCommand),
+    Verify(cmd_verify::VerifyCommand),
+    Export(cmd_export::ExportCommand),
+    Op(cmd_op::OpCommand),
+    Stats(cmd_stats::StatsCommand),
+    Did(cmd_did::DidCommand),
+    Handle(cmd_did::HandleCommand),
+    Index(cmd_index::IndexCommand),
+    Mempool(cmd_mempool::MempoolCommand),
+    Sync(cmd_sync::SyncCommand),
+    Rollback(cmd_rollback::RollbackCommand),
+    Diff(cmd_diff::DiffCommand),
+    Inspect(cmd_inspect::InspectCommand),
+    Server(cmd_server::ServerCommand),
+    Migrate(cmd_migrate::MigrateCommand),
+    Rebuild(cmd_rebuild::RebuildCommand),
+    Bench(cmd_bench::BenchCommand),
+    Random(cmd_random::RandomCommand),
+}
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    // Initialize logger based on verbosity flags
+    logger::init_logger(cli.verbose, cli.quiet);
+
+    match cli.command {
+        Commands::Query(cmd) => cmd_query::run(cmd, cli.dir, cli.quiet, cli.verbose)?,
+        Commands::Init(cmd) => cmd_init::run(cmd)?,
+        Commands::Status(cmd) => cmd_status::run(cmd, cli.dir)?,
+        Commands::Ls(cmd) => cmd_ls::run(cmd, cli.dir, cli.verbose, cli.quiet)?,
+        Commands::Verify(cmd) => cmd_verify::run(cmd, cli.dir, cli.verbose)?,
+        Commands::Export(cmd) => cmd_export::run(cmd, cli.dir, cli.quiet, cli.verbose)?,
+        Commands::Op(cmd) => cmd_op::run(cmd, cli.dir, cli.quiet)?,
+        Commands::Stats(cmd) => cmd_stats::run(cmd, cli.dir)?,
+        Commands::Handle(cmd) => cmd_did::run_handle(cmd, cli.dir)?,
+        Commands::Did(cmd) => cmd_did::run_did(cmd, cli.dir)?,
+        Commands::Index(cmd) => cmd_index::run(cmd, cli.dir)?,
+        Commands::Mempool(cmd) => cmd_mempool::run(cmd)?,
+        Commands::Sync(cmd) => cmd_sync::run(cmd)?,
+        Commands::Rollback(cmd) => cmd_rollback::run(cmd, cli.dir)?,
+        Commands::Diff(cmd) => cmd_diff::run(cmd, cli.dir)?,
+        Commands::Inspect(cmd) => cmd_inspect::run(cmd, cli.dir)?,
+        Commands::Server(cmd) => cmd_server::run(cmd, cli.dir)?,
+        Commands::Migrate(cmd) => cmd_migrate::run(cmd, cli.dir, cli.verbose)?,
+        Commands::Rebuild(cmd) => cmd_rebuild::run(cmd, cli.dir, cli.verbose)?,
+        Commands::Bench(cmd) => cmd_bench::run(cmd, cli.dir)?,
+        Commands::Random(cmd) => cmd_random::run(cmd, cli.dir)?,
+    }
+
+    Ok(())
+}

src/cli/progress.rs

···
     pb: IndicatifProgressBar,
     show_bytes: bool,
     current_bytes: Arc<Mutex<u64>>,
-    total_bytes: u64,
 }
 
 impl ProgressBar {
···
             pb,
             show_bytes: false,
             current_bytes: Arc::new(Mutex::new(0)),
-            total_bytes: 0,
         }
     }
 
     /// Create a progress bar with byte tracking
-    pub fn with_bytes(total: usize, total_bytes: u64) -> Self {
+    pub fn with_bytes(total: usize, _total_bytes: u64) -> Self {
         let pb = IndicatifProgressBar::new(total as u64);
         
         // Custom template that shows MB/s calculated from our tracked bytes
···
             pb,
             show_bytes: true,
             current_bytes: Arc::new(Mutex::new(0)),
-            total_bytes,
         }
     }
 
···
         };
         self.pb.set_message(new_msg);
     }
-
-    /// Add bytes to current progress
-    #[allow(dead_code)]
-    pub fn add_bytes(&self, increment: usize, bytes: u64) {
-        self.pb.inc(increment as u64);
-        let mut bytes_guard = self.current_bytes.lock().unwrap();
-        *bytes_guard += bytes;
-        let current_msg = self.pb.message().to_string();
-        drop(bytes_guard);
-        
-        // Update message to include MB/s, preserving user message if present
-        let elapsed = self.pb.elapsed().as_secs_f64();
-        let bytes_guard = self.current_bytes.lock().unwrap();
-        let bytes = *bytes_guard;
-        drop(bytes_guard);
-        
-        let mb_per_sec = if elapsed > 0.0 {
-            (bytes as f64 / 1_000_000.0) / elapsed
-        } else {
-            0.0
-        };
-        
-        // Extract user message (everything after " | " if present)
-        let user_msg = if let Some(pos) = current_msg.find(" | ") {
-            &current_msg[pos + 3..]
-        } else {
-            ""
-        };
-        
-        let new_msg = if user_msg.is_empty() {
-            format!("{:.1} MB/s", mb_per_sec)
-        } else {
-            format!("{:.1} MB/s | {}", mb_per_sec, user_msg)
-        };
-        self.pb.set_message(new_msg);
-    }
-
 
     pub fn set_message<S: Into<String>>(&self, msg: S) {
         let msg_str: String = msg.into();

src/cli/utils.rs

···
 
 pub use plcbundle::format::{format_bytes, format_number};
 
+/// Trait for extracting global flags from command objects
+/// Commands that have verbose/quiet fields should implement this trait
+pub trait HasGlobalFlags {
+    fn verbose(&self) -> bool;
+    fn quiet(&self) -> bool;
+}
+
 /// Parse bundle specification string into a vector of bundle numbers
 pub fn parse_bundle_spec(spec: Option<String>, max_bundle: u32) -> Result<Vec<u32>> {
     match spec {
···
 ///
 /// # Returns
 /// Number of worker threads to use
-pub fn get_num_workers(workers: usize, fallback: usize) -> usize {
+pub fn get_worker_threads(workers: usize, fallback: usize) -> usize {
     if workers == 0 {
-        match std::thread::available_parallelism() {
-            Ok(n) => n.get(),
-            Err(e) => {
-                eprintln!(
-                    "Warning: Failed to detect CPU count: {}, using fallback: {}",
-                    e, fallback
-                );
-                fallback
-            }
-        }
+        std::thread::available_parallelism()
+            .map(|n| n.get())
+            .unwrap_or(fallback)
     } else {
         workers
     }
···
     manager.get_last_bundle() == 0
 }
 
-/// Create BundleManager with optional verbose flag
-pub fn create_manager(dir: PathBuf, verbose: bool) -> Result<BundleManager> {
-    Ok(BundleManager::new(dir)?.with_verbose(verbose))
+/// Create BundleManager with verbose/quiet flags
+///
+/// This is the standard way to create a BundleManager from CLI commands.
+/// It respects the verbose and quiet flags for logging.
+pub fn create_manager(dir: PathBuf, verbose: bool, _quiet: bool) -> Result<BundleManager> {
+    let manager = BundleManager::new(dir)?;
+
+    if verbose {
+        Ok(manager.with_verbose(true))
+    } else {
+        Ok(manager)
+    }
+}
+
+/// Create BundleManager with global flags extracted from command
+///
+/// Convenience function for commands that implement `HasGlobalFlags`.
+/// The global flags (verbose, quiet) are automatically extracted from the command.
+pub fn create_manager_from_cmd<C: HasGlobalFlags>(dir: PathBuf, cmd: &C) -> Result<BundleManager> {
+    create_manager(dir, cmd.verbose(), cmd.quiet())
 }
 
 /// Get all bundle metadata from the repository

src/did_index.rs

···
 // ============================================================================
 
 struct Shard {
-    #[allow(dead_code)]
-    shard_num: u8,
     base: Option<Mmap>,
-    #[allow(dead_code)]
-    base_file: Option<File>,
     segments: Vec<SegmentLayer>,
     last_used: AtomicU64,
     access_count: AtomicU64,
 }
 
 struct SegmentLayer {
-    #[allow(dead_code)]
     meta: DeltaSegmentMeta,
     mmap: Mmap,
     _file: File,
···
 }
 
 impl Shard {
-    fn new_empty(shard_num: u8) -> Self {
+    fn new_empty(_shard_num: u8) -> Self {
         Shard {
-            shard_num,
             base: None,
-            base_file: None,
             segments: Vec::new(),
             last_used: AtomicU64::new(unix_timestamp()),
             access_count: AtomicU64::new(0),
         }
     }
 
-    fn load(shard_num: u8, shard_path: &Path) -> Result<Self> {
-        let file = File::open(shard_path)?;
-        let mmap = unsafe { MmapOptions::new().map(&file)? };
+    fn load(_shard_num: u8, shard_path: &Path) -> Result<Self> {
+        let _file = File::open(shard_path)?;
+        let mmap = unsafe { MmapOptions::new().map(&_file)? };
 
         Ok(Shard {
-            shard_num,
             base: Some(mmap),
-            base_file: Some(file),
             segments: Vec::new(),
             last_used: AtomicU64::new(unix_timestamp()),
             access_count: AtomicU64::new(1),
···
         }
 
         Ok(())
-    }
-
-    #[allow(dead_code)]
-    fn update_config(&self, total_dids: i64, last_bundle: i32) -> Result<()> {
-        self.modify_config(|config| {
-            config.total_dids = total_dids;
-            config.last_bundle = last_bundle;
-        })
     }
 
     fn modify_config<F>(&self, mutator: F) -> Result<()>

src/manager.rs

···
         ))
     }
 
-    /// Save bundle to disk with compression and index updates (backwards compatibility)
-    #[allow(dead_code)]
-    async fn save_bundle(&self, bundle_num: u32, operations: Vec<Operation>) -> Result<()> {
-        self.save_bundle_with_timing(bundle_num, operations).await?;
-        Ok(())
-    }
-
     /// Migrate a bundle to multi-frame format
     ///
     /// This method loads a bundle and re-saves it with multi-frame compression
···
 
     /// Rollback repository to a specific bundle
     pub fn rollback_to_bundle(&mut self, target_bundle: u32) -> Result<()> {
-        use anyhow::Context;
-
         let mut index = self.index.write().unwrap();
 
         // Keep only bundles up to target

src/server/error.rs

···
     msg.contains("not found") || msg.contains("not in index")
 }
 
-/// Convert a Result to an HTTP response, handling common error cases
-pub fn handle_result<T: IntoResponse>(
-    result: Result<T, anyhow::Error>,
-) -> impl IntoResponse {
-    match result {
-        Ok(response) => response.into_response(),
-        Err(e) => {
-            if e.to_string().contains("deactivated") {
-                gone("DID has been deactivated").into_response()
-            } else if is_not_found_error(&e) {
-                not_found(&e.to_string()).into_response()
-            } else {
-                internal_error(&e.to_string()).into_response()
-            }
-        }
-    }
-}
-