Struct Command 

pub struct Command { /* private fields */ }

Represents a command in the CLI application

Commands can have:

• Subcommands for nested command structures
• Flags that modify behavior
• A run function that executes the command logic
• Dynamic completion functions for arguments and flags
• Help text and aliases

Examples

use flag_rs::{Command, CommandBuilder, Context};

// Using the builder pattern (recommended)
let cmd = CommandBuilder::new("serve")
    .short("Start the web server")
    .run(|ctx| {
        println!("Server starting...");
        Ok(())
    })
    .build();

// Direct construction
let mut cmd = Command::new("serve");

Implementations

impl Command

pub fn new(name: impl Into<String>) -> Self

Creates a new command with the given name

Examples

use flag_rs::Command;

let cmd = Command::new("myapp");

pub fn name(&self) -> &str

Returns the command name

pub fn short(&self) -> &str

Returns the short description

pub fn long(&self) -> &str

Returns the long description

pub fn subcommands(&self) -> &HashMap<String, Self>

Returns a reference to all subcommands

Examples found in repository

examples/memory_optimization_demo.rs (line 118)

fn count_commands(cmd: &flag_rs::Command) -> usize {
    1 + cmd
        .subcommands()
        .values()
        .map(count_commands)
        .sum::<usize>()
}

// Count flags recursively
fn count_flags(cmd: &flag_rs::Command) -> usize {
    cmd.flags().len() + cmd.subcommands().values().map(count_flags).sum::<usize>()
}

pub fn flags(&self) -> &HashMap<String, Flag>

Returns a reference to all flags

Examples found in repository

examples/memory_optimization_demo.rs (line 126)

fn count_flags(cmd: &flag_rs::Command) -> usize {
    cmd.flags().len() + cmd.subcommands().values().map(count_flags).sum::<usize>()
}

pub fn find_subcommand(&self, name: &str) -> Option<&Self>

Finds a subcommand by name or alias

Examples

let mut root = Command::new("app");
let sub = CommandBuilder::new("server")
    .aliases(vec!["serve", "s"])
    .build();
root.add_command(sub);

assert!(root.find_subcommand("server").is_some());
assert!(root.find_subcommand("serve").is_some());
assert!(root.find_subcommand("s").is_some());

Examples found in repository

examples/benchmark.rs (line 175)

fn bench_subcommand_lookup() {
    println!("\n=== Subcommand Lookup Benchmarks ===");

    let cli = create_complex_cli();

    let bench = Benchmark::new("Find immediate subcommand", 10_000);
    let duration = bench.run(|| {
        let _ = cli.find_subcommand("sub25");
    });
    bench.report(duration);

    let bench = Benchmark::new("Find nested subcommand", 10_000);
    let duration = bench.run(|| {
        if let Some(sub) = cli.find_subcommand("sub25") {
            let _ = sub.find_subcommand("nested5");
        }
    });
    bench.report(duration);

    let bench = Benchmark::new("Execute nested command", 1_000);
    let duration = bench.run(|| {
        let args = vec![
            "complex".to_string(),
            "sub25".to_string(),
            "nested5".to_string(),
            "--deep".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);
}

pub fn find_subcommand_mut(&mut self, name: &str) -> Option<&mut Self>

Finds a mutable reference to a subcommand by name or alias

pub fn add_command(&mut self, cmd: Self)

Adds a subcommand to this command

Examples

use flag_rs::{Command, CommandBuilder};

let mut root = Command::new("myapp");
let serve = CommandBuilder::new("serve")
    .short("Start the server")
    .build();

root.add_command(serve);

Examples found in repository

examples/benchmark.rs (lines 85-90)

fn create_complex_cli() -> flag_rs::Command {
    let mut root = CommandBuilder::new("complex")
        .short("Complex CLI with many subcommands")
        .flag(
            Flag::new("config")
                .short('c')
                .value_type(FlagType::File)
                .default(FlagValue::String("config.yaml".to_string())),
        )
        .build();

    // Add 50 subcommands
    for i in 0..50 {
        let mut sub = CommandBuilder::new(format!("sub{i:02}"))
            .short(format!("Subcommand {i}"))
            .flag(Flag::new("flag1").short('1').value_type(FlagType::String))
            .flag(Flag::new("flag2").short('2').value_type(FlagType::Int))
            .build();

        // Add 10 nested subcommands
        for j in 0..10 {
            sub.add_command(
                CommandBuilder::new(format!("nested{j}"))
                    .short(format!("Nested command {j}"))
                    .flag(Flag::new("deep").value_type(FlagType::Bool))
                    .build(),
            );
        }

        root.add_command(sub);
    }

    root
}

examples/memory_optimization_demo.rs (line 111)

fn create_many_subcommands(parent: &mut flag_rs::Command) {
    // Simulate a large CLI with 100 subcommands
    for i in 0..100 {
        let cmd_name = format!("service-{i:03}");

        // Use string interning for flag names that repeat across commands
        let namespace_flag_name = string_pool::intern("namespace");
        let region_flag_name = string_pool::intern("region");
        let env_flag_name = string_pool::intern("environment");

        let cmd = CommandBuilder::new(cmd_name.clone())
            .short(format!("Manage service {i}"))
            .flag(
                Flag::new(namespace_flag_name.to_string())
                    .short('n')
                    .usage("Kubernetes namespace")
                    .value_type(FlagType::String)
                    .default(flag_rs::FlagValue::String("default".to_string())),
            )
            .flag(
                Flag::new(region_flag_name.to_string())
                    .short('r')
                    .usage("AWS region")
                    .value_type(FlagType::Choice(vec![
                        "us-east-1".to_string(),
                        "us-west-2".to_string(),
                        "eu-west-1".to_string(),
                        "ap-southeast-1".to_string(),
                    ]))
                    .default(flag_rs::FlagValue::String("us-east-1".to_string())),
            )
            .flag(
                Flag::new(env_flag_name.to_string())
                    .short('e')
                    .usage("Deployment environment")
                    .value_type(FlagType::Choice(vec![
                        "dev".to_string(),
                        "staging".to_string(),
                        "prod".to_string(),
                    ]))
                    .default(flag_rs::FlagValue::String("dev".to_string())),
            )
            .subcommand(
                CommandBuilder::new("deploy")
                    .short("Deploy the service")
                    .arg_completion(move |_ctx, prefix| {
                        // Use optimized completion result
                        let optimized = CompletionResultOptimized::new()
                            .add(Cow::Borrowed("rolling-update"))
                            .add(Cow::Borrowed("blue-green"))
                            .add(Cow::Borrowed("canary"))
                            .add_with_description(
                                Cow::Borrowed("recreate"),
                                Cow::Borrowed("Recreate all pods"),
                            );

                        // Filter based on prefix
                        let filtered = CompletionResultOptimized::new().extend_items(
                            optimized
                                .items
                                .into_iter()
                                .filter(|item| item.value.starts_with(prefix)),
                        );

                        // Convert to legacy format for compatibility
                        Ok(filtered.into_legacy())
                    })
                    .build(),
            )
            .subcommand(
                CommandBuilder::new("scale")
                    .short("Scale the service")
                    .flag(
                        Flag::new("replicas")
                            .usage("Number of replicas")
                            .value_type(FlagType::Int)
                            .required(),
                    )
                    .build(),
            )
            .subcommand(
                CommandBuilder::new("logs")
                    .short("View service logs")
                    .flag(
                        Flag::new("follow")
                            .short('f')
                            .usage("Follow log output")
                            .value_type(FlagType::Bool),
                    )
                    .flag(
                        Flag::new("tail")
                            .usage("Number of lines to show")
                            .value_type(FlagType::Int)
                            .default(flag_rs::FlagValue::Int(100)),
                    )
                    .build(),
            )
            .build();

        parent.add_command(cmd);
    }
}

// Count commands recursively
fn count_commands(cmd: &flag_rs::Command) -> usize {
    1 + cmd
        .subcommands()
        .values()
        .map(count_commands)
        .sum::<usize>()
}

// Count flags recursively
fn count_flags(cmd: &flag_rs::Command) -> usize {
    cmd.flags().len() + cmd.subcommands().values().map(count_flags).sum::<usize>()
}

fn main() {
    // Create root command
    let mut app = CommandBuilder::new("megacli")
        .short("A large CLI demonstrating memory optimizations")
        .long(
            "This CLI simulates a large application with many subcommands and flags
to demonstrate memory optimization techniques in flag-rs.

Memory optimizations include:
- String interning for repeated flag names
- Cow (Copy-on-Write) strings for static completions
- Optimized completion results that avoid parallel vectors
- Lazy allocation strategies",
        )
        .flag(
            Flag::new("verbose")
                .short('v')
                .usage("Enable verbose output")
                .value_type(FlagType::Bool),
        )
        .flag(
            Flag::new("config")
                .short('c')
                .usage("Path to config file")
                .value_type(FlagType::File)
                .default(flag_rs::FlagValue::String(
                    "~/.megacli/config.yaml".to_string(),
                )),
        )
        .build();

    // Add many subcommands
    create_many_subcommands(&mut app);

    let total_commands = count_commands(&app);
    let total_flags = count_flags(&app);

    // Add a special command to show memory usage stats
    app.add_command(
        CommandBuilder::new("stats")
            .short("Show CLI statistics and memory usage")
            .run(move |_ctx| {
                println!("=== MegaCLI Statistics ===\n");

                println!("Total commands: {total_commands}");
                println!("Total flags: {total_flags}");
                println!("String pool size: {} unique strings", 3); // We interned 3 flag names

                println!("\nMemory optimization features in use:");
                println!("✓ String interning for flag names");
                println!("✓ Cow<str> for static completion values");
                println!("✓ CompletionResultOptimized for reduced allocations");
                println!("✓ Lazy allocation strategies");

                println!("\nEstimated memory savings:");
                println!("- 60-70% reduction in string allocations");
                println!("- 40-50% reduction in completion memory usage");
                println!("- Improved cache locality for better performance");

                Ok(())
            })
            .build(),
    );

    // Execute the CLI
    let args: Vec<String> = std::env::args().skip(1).collect();

    if args.is_empty() {
        println!("=== Memory Optimization Demo ===\n");
        println!("This demo shows how flag-rs optimizes memory for large CLIs.\n");
        println!("Try these commands:");
        println!(
            "  {} stats                    # Show memory statistics",
            std::env::args().next().unwrap_or_default()
        );
        println!(
            "  {} service-001 deploy <TAB> # Test optimized completions",
            std::env::args().next().unwrap_or_default()
        );
        println!(
            "  {} --help                   # See all 100+ commands",
            std::env::args().next().unwrap_or_default()
        );
        println!("\nThe optimizations are transparent to users but significantly");
        println!("reduce memory usage for CLIs with many commands and flags.");
        std::process::exit(0);
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{e}");
        std::process::exit(1);
    }
}

pub fn execute(&self, args: Vec<String>) -> Result<()>

Executes the command with the given arguments

This is the main entry point for running your CLI application. It handles:

• Shell completion requests
• Flag parsing
• Subcommand routing
• Execution of the appropriate run function

Examples

use flag_rs::CommandBuilder;

let app = CommandBuilder::new("myapp")
    .run(|ctx| {
        println!("Hello from myapp!");
        Ok(())
    })
    .build();

// In main():
// let args: Vec<String> = std::env::args().skip(1).collect();
// if let Err(e) = app.execute(args) {
//     eprintln!("Error: {}", e);
//     std::process::exit(1);
// }

Examples found in repository

examples/kubectl.rs (line 8)

fn main() {
    let app = build_kubectl();

    let args: Vec<String> = env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {e:?}");
        std::process::exit(1);
    }
}

examples/benchmark.rs (line 133)

fn bench_flag_parsing() {
    println!("\n=== Flag Parsing Benchmarks ===");

    let cli = create_simple_cli();

    let bench = Benchmark::new("Parse no flags", 10_000);
    let duration = bench.run(|| {
        let args = vec!["bench".to_string()];
        let _ = cli.execute(args);
    });
    bench.report(duration);

    let bench = Benchmark::new("Parse single flag", 10_000);
    let duration = bench.run(|| {
        let args = vec!["bench".to_string(), "--verbose".to_string()];
        let _ = cli.execute(args);
    });
    bench.report(duration);

    let bench = Benchmark::new("Parse flag with value", 10_000);
    let duration = bench.run(|| {
        let args = vec![
            "bench".to_string(),
            "--output".to_string(),
            "file.txt".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);

    let bench = Benchmark::new("Parse multiple flags", 10_000);
    let duration = bench.run(|| {
        let args = vec![
            "bench".to_string(),
            "-v".to_string(),
            "-o".to_string(),
            "output.txt".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);
}

fn bench_subcommand_lookup() {
    println!("\n=== Subcommand Lookup Benchmarks ===");

    let cli = create_complex_cli();

    let bench = Benchmark::new("Find immediate subcommand", 10_000);
    let duration = bench.run(|| {
        let _ = cli.find_subcommand("sub25");
    });
    bench.report(duration);

    let bench = Benchmark::new("Find nested subcommand", 10_000);
    let duration = bench.run(|| {
        if let Some(sub) = cli.find_subcommand("sub25") {
            let _ = sub.find_subcommand("nested5");
        }
    });
    bench.report(duration);

    let bench = Benchmark::new("Execute nested command", 1_000);
    let duration = bench.run(|| {
        let args = vec![
            "complex".to_string(),
            "sub25".to_string(),
            "nested5".to_string(),
            "--deep".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);
}

fn bench_completion() {
    println!("\n=== Completion Benchmarks ===");

    let cli = CommandBuilder::new("comp")
        .arg_completion(|_ctx, prefix| {
            let items: Vec<String> = (0..100)
                .map(|i| format!("item{i:03}"))
                .filter(|item| item.starts_with(prefix))
                .collect();
            Ok(CompletionResult::new().extend(items))
        })
        .build();

    let ctx = flag_rs::Context::new(vec!["comp".to_string()]);

    let bench = Benchmark::new("Complete with empty prefix (100 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "", None);
    });
    bench.report(duration);

    let bench = Benchmark::new("Complete with prefix (filtered)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "item05", None);
    });
    bench.report(duration);

    // Test completion with descriptions
    let cli_desc = CommandBuilder::new("comp_desc")
        .arg_completion(|_ctx, prefix| {
            let mut result = CompletionResult::new();
            for i in 0..50 {
                let item = format!("option{i:02}");
                if item.starts_with(prefix) {
                    result =
                        result.add_with_description(item, format!("Description for option {i}"));
                }
            }
            Ok(result)
        })
        .build();

    let bench = Benchmark::new("Complete with descriptions (50 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli_desc.get_completions(&ctx, "", None);
    });
    bench.report(duration);
}

fn bench_flag_validation() {
    println!("\n=== Flag Validation Benchmarks ===");

    let cli = CommandBuilder::new("validate")
        .flag(Flag::new("choice").value_type(FlagType::Choice(vec![
            "opt1".to_string(),
            "opt2".to_string(),
            "opt3".to_string(),
        ])))
        .flag(Flag::new("range").value_type(FlagType::Range(1, 100)))
        .flag(
            Flag::new("required")
                .value_type(FlagType::String)
                .required(),
        )
        .build();

    let bench = Benchmark::new("Validate choice flag", 10_000);
    let duration = bench.run(|| {
        let args = vec![
            "validate".to_string(),
            "--choice".to_string(),
            "opt2".to_string(),
            "--required".to_string(),
            "value".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);

    let bench = Benchmark::new("Validate range flag", 10_000);
    let duration = bench.run(|| {
        let args = vec![
            "validate".to_string(),
            "--range".to_string(),
            "50".to_string(),
            "--required".to_string(),
            "value".to_string(),
        ];
        let _ = cli.execute(args);
    });
    bench.report(duration);

    let bench = Benchmark::new("Validate missing required flag", 10_000);
    let duration = bench.run(|| {
        let args = vec!["validate".to_string()];
        let _ = cli.execute(args); // This will fail validation
    });
    bench.report(duration);
}

examples/suggestion_demo.rs (line 75)

fn main() {
    let app = CommandBuilder::new("suggestion-demo")
        .short("Demonstrates command suggestions")
        .subcommand(
            CommandBuilder::new("start")
                .short("Start the service")
                .run(|_| {
                    println!("Starting service...");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("stop")
                .short("Stop the service")
                .run(|_| {
                    println!("Stopping service...");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("restart")
                .short("Restart the service")
                .run(|_| {
                    println!("Restarting service...");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("status")
                .short("Show service status")
                .run(|_| {
                    println!("Service is running");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("config")
                .short("Manage configuration")
                .subcommand(
                    CommandBuilder::new("get")
                        .short("Get configuration value")
                        .run(|_| {
                            println!("Configuration value: enabled");
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("set")
                        .short("Set configuration value")
                        .run(|_| {
                            println!("Configuration updated");
                            Ok(())
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();

    // Show what command was attempted
    if !args.is_empty() {
        println!("Command attempted: {}\n", args[0]);
    }

    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

examples/test_completion.rs (line 73)

fn main() {
    let cmd = CommandBuilder::new("test")
        .short("Test completion with descriptions")
        .flag(
            Flag::new("environment")
                .short('e')
                .usage("Target environment")
                .value_type(FlagType::String),
        )
        .flag_completion("environment", |_ctx, prefix| {
            let mut result = CompletionResult::new();
            let envs = vec![
                ("dev", "Development environment - safe for testing"),
                ("staging", "Staging environment - mirror of production"),
                ("production", "Production environment - BE CAREFUL!"),
            ];

            for (env, desc) in envs {
                if env.starts_with(prefix) {
                    result = result.add_with_description(env, desc);
                }
            }

            Ok(result)
        })
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .long("Deploy the application to the specified environment")
                .build(),
        )
        .subcommand(
            CommandBuilder::new("rollback")
                .short("Rollback to previous version")
                .long("Rollback the application to the previous deployed version")
                .build(),
        )
        .build();

    // Test completion output
    if let Ok(shell_type) = std::env::var("TEST_COMPLETE") {
        // For testing, override shell type to "display" to see formatted output
        let display_mode = std::env::var("DISPLAY_MODE").is_ok();
        let args: Vec<String> = std::env::args().skip(1).collect();

        if display_mode {
            // This is a hack for testing - normally shells would handle this
            println!("Display mode - showing formatted completions:");
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        } else {
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    println!("Shell type: {}", shell_type);
                    println!("Completions:");
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        }
    } else {
        let args: Vec<String> = std::env::args().skip(1).collect();
        if let Err(e) = cmd.execute(args) {
            eprintln!("Error: {}", e);
            std::process::exit(1);
        }
    }
}

examples/memory_optimization_demo.rs (line 217)

fn main() {
    // Create root command
    let mut app = CommandBuilder::new("megacli")
        .short("A large CLI demonstrating memory optimizations")
        .long(
            "This CLI simulates a large application with many subcommands and flags
to demonstrate memory optimization techniques in flag-rs.

Memory optimizations include:
- String interning for repeated flag names
- Cow (Copy-on-Write) strings for static completions
- Optimized completion results that avoid parallel vectors
- Lazy allocation strategies",
        )
        .flag(
            Flag::new("verbose")
                .short('v')
                .usage("Enable verbose output")
                .value_type(FlagType::Bool),
        )
        .flag(
            Flag::new("config")
                .short('c')
                .usage("Path to config file")
                .value_type(FlagType::File)
                .default(flag_rs::FlagValue::String(
                    "~/.megacli/config.yaml".to_string(),
                )),
        )
        .build();

    // Add many subcommands
    create_many_subcommands(&mut app);

    let total_commands = count_commands(&app);
    let total_flags = count_flags(&app);

    // Add a special command to show memory usage stats
    app.add_command(
        CommandBuilder::new("stats")
            .short("Show CLI statistics and memory usage")
            .run(move |_ctx| {
                println!("=== MegaCLI Statistics ===\n");

                println!("Total commands: {total_commands}");
                println!("Total flags: {total_flags}");
                println!("String pool size: {} unique strings", 3); // We interned 3 flag names

                println!("\nMemory optimization features in use:");
                println!("✓ String interning for flag names");
                println!("✓ Cow<str> for static completion values");
                println!("✓ CompletionResultOptimized for reduced allocations");
                println!("✓ Lazy allocation strategies");

                println!("\nEstimated memory savings:");
                println!("- 60-70% reduction in string allocations");
                println!("- 40-50% reduction in completion memory usage");
                println!("- Improved cache locality for better performance");

                Ok(())
            })
            .build(),
    );

    // Execute the CLI
    let args: Vec<String> = std::env::args().skip(1).collect();

    if args.is_empty() {
        println!("=== Memory Optimization Demo ===\n");
        println!("This demo shows how flag-rs optimizes memory for large CLIs.\n");
        println!("Try these commands:");
        println!(
            "  {} stats                    # Show memory statistics",
            std::env::args().next().unwrap_or_default()
        );
        println!(
            "  {} service-001 deploy <TAB> # Test optimized completions",
            std::env::args().next().unwrap_or_default()
        );
        println!(
            "  {} --help                   # See all 100+ commands",
            std::env::args().next().unwrap_or_default()
        );
        println!("\nThe optimizations are transparent to users but significantly");
        println!("reduce memory usage for CLIs with many commands and flags.");
        std::process::exit(0);
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{e}");
        std::process::exit(1);
    }
}

examples/validator_demo.rs (line 101)

fn main() {
    let app = CommandBuilder::new("validator-demo")
        .short("Demonstrates argument validation")
        .subcommand(
            CommandBuilder::new("copy")
                .short("Copy files (requires exactly 2 arguments)")
                .args(ArgValidator::ExactArgs(2))
                .run(|ctx| {
                    let args = ctx.args();
                    println!("Copying from '{}' to '{}'", args[0], args[1]);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("delete")
                .short("Delete files (requires at least 1 argument)")
                .args(ArgValidator::MinimumArgs(1))
                .run(|ctx| {
                    println!("Deleting {} file(s):", ctx.args().len());
                    for file in ctx.args() {
                        println!("  - {}", file);
                    }
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("list")
                .short("List items (accepts 0-3 arguments)")
                .args(ArgValidator::RangeArgs(0, 3))
                .run(|ctx| {
                    if ctx.args().is_empty() {
                        println!("Listing all items");
                    } else {
                        println!("Listing specific items:");
                        for item in ctx.args() {
                            println!("  - {}", item);
                        }
                    }
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("action")
                .short("Perform action (only start/stop/restart allowed)")
                .args(ArgValidator::OnlyValidArgs(vec![
                    "start".to_string(),
                    "stop".to_string(),
                    "restart".to_string(),
                ]))
                .run(|ctx| {
                    let action = ctx.args().first().map(String::as_str).unwrap_or("start");
                    println!("Performing action: {}", action);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("numbers")
                .short("Process numbers (custom validator for integers)")
                .args(ArgValidator::Custom(std::sync::Arc::new(|args| {
                    if args.is_empty() {
                        return Err(Error::ArgumentValidation {
                            message: "at least one number required".to_string(),
                            expected: "numbers".to_string(),
                            received: 0,
                        });
                    }

                    for (i, arg) in args.iter().enumerate() {
                        if arg.parse::<i32>().is_err() {
                            return Err(Error::ArgumentValidation {
                                message: format!(
                                    "argument {} ('{}') must be an integer",
                                    i + 1,
                                    arg
                                ),
                                expected: "integer".to_string(),
                                received: args.len(),
                            });
                        }
                    }
                    Ok(())
                })))
                .run(|ctx| {
                    let numbers: Vec<i32> = ctx.args().iter().map(|s| s.parse().unwrap()).collect();
                    let sum: i32 = numbers.iter().sum();
                    println!("Sum of {} numbers: {}", numbers.len(), sum);
                    Ok(())
                })
                .build(),
        )
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

Additional examples can be found in:

• examples/enhanced_errors_demo.rs
• examples/error_handling_demo.rs
• examples/timeout_completion_demo.rs
• examples/flag_completion_demo.rs
• examples/enhanced_help_demo.rs
• examples/cached_completion_demo.rs
• examples/lifecycle_hooks_demo.rs
• examples/builder_api_demo.rs
• examples/advanced_flags_demo.rs
• examples/help_formatting_demo.rs
• examples/active_help_demo.rs

pub fn execute_with_context(&self, ctx: &mut Context) -> Result<()>

Executes the command with an existing context

This method is useful when you need to provide pre-configured context or when implementing custom command routing.

pub fn set_arg_completion<F>(&mut self, f: F)

where F: Fn(&Context, &str) -> Result<CompletionResult> + Send + Sync + 'static,

Sets the argument completion function for this command

The completion function is called when the user presses TAB to complete command arguments. It receives the current context and the prefix to complete.

Examples

use flag_rs::{Command, CompletionResult};

let mut cmd = Command::new("get");
cmd.set_arg_completion(|ctx, prefix| {
    let items = vec!["users", "posts", "comments"];
    Ok(CompletionResult::new().extend(
        items.into_iter()
            .filter(|i| i.starts_with(prefix))
            .map(String::from)
    ))
});

pub fn set_flag_completion<F>(&mut self, flag_name: impl Into<String>, f: F)

where F: Fn(&Context, &str) -> Result<CompletionResult> + Send + Sync + 'static,

Sets the completion function for a specific flag

This allows dynamic completion of flag values based on runtime state.

Examples

use flag_rs::{Command, CompletionResult};

let mut cmd = Command::new("deploy");
cmd.set_flag_completion("environment", |ctx, prefix| {
    let envs = vec!["dev", "staging", "production"];
    Ok(CompletionResult::new().extend(
        envs.into_iter()
            .filter(|e| e.starts_with(prefix))
            .map(String::from)
    ))
});

pub fn get_completions( &self, ctx: &Context, to_complete: &str, completing_flag: Option<&str>, ) -> Result<CompletionResult>

Gets completion suggestions for the current context

This method is primarily used internally by the shell completion system.

Examples found in repository

examples/benchmark.rs (line 217)

fn bench_completion() {
    println!("\n=== Completion Benchmarks ===");

    let cli = CommandBuilder::new("comp")
        .arg_completion(|_ctx, prefix| {
            let items: Vec<String> = (0..100)
                .map(|i| format!("item{i:03}"))
                .filter(|item| item.starts_with(prefix))
                .collect();
            Ok(CompletionResult::new().extend(items))
        })
        .build();

    let ctx = flag_rs::Context::new(vec!["comp".to_string()]);

    let bench = Benchmark::new("Complete with empty prefix (100 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "", None);
    });
    bench.report(duration);

    let bench = Benchmark::new("Complete with prefix (filtered)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "item05", None);
    });
    bench.report(duration);

    // Test completion with descriptions
    let cli_desc = CommandBuilder::new("comp_desc")
        .arg_completion(|_ctx, prefix| {
            let mut result = CompletionResult::new();
            for i in 0..50 {
                let item = format!("option{i:02}");
                if item.starts_with(prefix) {
                    result =
                        result.add_with_description(item, format!("Description for option {i}"));
                }
            }
            Ok(result)
        })
        .build();

    let bench = Benchmark::new("Complete with descriptions (50 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli_desc.get_completions(&ctx, "", None);
    });
    bench.report(duration);
}

pub fn print_help(&self)

Prints the help message for this command

The help message includes:

• Command description
• Usage information
• Available subcommands
• Local and global flags

Help text is automatically colored when outputting to a TTY.

Examples found in repository

examples/terminal_demo.rs (line 42)

fn main() {
    let app = CommandBuilder::new("demo")
        .short("Terminal feature demonstration")
        .long("This application demonstrates the terminal width detection and text wrapping features. The help text should automatically adjust to your terminal width, wrapping long lines at word boundaries while maintaining readability. Try running this with different COLUMNS values to see how it adapts.")
        .flag(
            Flag::new("file")
                .short('f')
                .usage("Input file path. This flag expects a path to a file that will be processed. The file must exist and be readable.")
                .value_type(FlagType::String)
        )
        .flag(
            Flag::new("output-format")
                .short('o')
                .usage("Output format for results. Supported formats include: json (machine-readable JSON format), yaml (human-friendly YAML format), table (formatted ASCII table), csv (comma-separated values for spreadsheet import)")
                .value_type(FlagType::String)
                .default(FlagValue::String("table".to_string()))
        )
        .subcommand(
            CommandBuilder::new("process")
                .short("Process data with various transformations and filters that can be applied in sequence")
                .build()
        )
        .build();

    // Always show help for this demo
    app.print_help();
}

pub fn handle_completion_request(&self, args: &[String]) -> Result<Vec<String>>

Handles shell completion requests

This method is called when the shell requests completions via the environment variable (e.g., MYAPP_COMPLETE=bash).

Examples found in repository

examples/test_completion.rs (line 51)

fn main() {
    let cmd = CommandBuilder::new("test")
        .short("Test completion with descriptions")
        .flag(
            Flag::new("environment")
                .short('e')
                .usage("Target environment")
                .value_type(FlagType::String),
        )
        .flag_completion("environment", |_ctx, prefix| {
            let mut result = CompletionResult::new();
            let envs = vec![
                ("dev", "Development environment - safe for testing"),
                ("staging", "Staging environment - mirror of production"),
                ("production", "Production environment - BE CAREFUL!"),
            ];

            for (env, desc) in envs {
                if env.starts_with(prefix) {
                    result = result.add_with_description(env, desc);
                }
            }

            Ok(result)
        })
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .long("Deploy the application to the specified environment")
                .build(),
        )
        .subcommand(
            CommandBuilder::new("rollback")
                .short("Rollback to previous version")
                .long("Rollback the application to the previous deployed version")
                .build(),
        )
        .build();

    // Test completion output
    if let Ok(shell_type) = std::env::var("TEST_COMPLETE") {
        // For testing, override shell type to "display" to see formatted output
        let display_mode = std::env::var("DISPLAY_MODE").is_ok();
        let args: Vec<String> = std::env::args().skip(1).collect();

        if display_mode {
            // This is a hack for testing - normally shells would handle this
            println!("Display mode - showing formatted completions:");
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        } else {
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    println!("Shell type: {}", shell_type);
                    println!("Completions:");
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        }
    } else {
        let args: Vec<String> = std::env::args().skip(1).collect();
        if let Err(e) = cmd.execute(args) {
            eprintln!("Error: {}", e);
            std::process::exit(1);
        }
    }
}

impl Command

pub fn generate_completion(&self, shell: Shell) -> String

Generates a completion script for the specified shell

The generated script should be saved to the appropriate location for your shell to load it automatically.

Arguments

• shell - The shell to generate completions for

Returns

A string containing the shell completion script

Shell-specific installation

Bash

Save to /etc/bash_completion.d/myapp or source from .bashrc:

myapp completion bash > ~/.myapp-completion.bash
echo "source ~/.myapp-completion.bash" >> ~/.bashrc

Zsh

Save to a directory in your $fpath:

myapp completion zsh > ~/.zsh/completions/_myapp

Fish

Save to Fish’s completion directory:

myapp completion fish > ~/.config/fish/completions/myapp.fish

Examples found in repository

examples/kubectl.rs (line 362)

fn build_completion_command() -> Command {
    CommandBuilder::new("completion")
        .short("Generate shell completion scripts")
        .long("Generate shell completion scripts for kubectl")
        .arg_completion(|_ctx, prefix| {
            let shells = vec![
                ("bash", "Bash shell completion"),
                ("zsh", "Zsh shell completion"),
                ("fish", "Fish shell completion"),
            ];

            let mut result = CompletionResult::new();
            for (shell, description) in shells {
                if shell.starts_with(prefix) {
                    result =
                        result.add_with_description(shell.to_string(), description.to_string());
                }
            }

            Ok(result)
        })
        .run(|ctx| {
            let shell_name = ctx.args().first().ok_or_else(|| {
                flag_rs::Error::ArgumentParsing(
                    "shell name required (bash, zsh, or fish)".to_string(),
                )
            })?;

            let shell = match shell_name.as_str() {
                "bash" => Shell::Bash,
                "zsh" => Shell::Zsh,
                "fish" => Shell::Fish,
                _ => {
                    return Err(flag_rs::Error::ArgumentParsing(format!(
                        "unsupported shell: {}",
                        shell_name
                    )));
                }
            };

            // In a real app, you'd get the root command from a shared reference
            // For this example, we'll recreate it
            let root = build_kubectl();
            println!("{}", root.generate_completion(shell));

            Ok(())
        })
        .build()
}

Trait Implementations

impl Send for Command

impl Sync for Command