Struct App 

pub struct App { /* private fields */ }

The top-level CLI application builder.

Construct with App::new, chain configuration methods, register commands with App::add_command, then call App::run to parse std::env::args and dispatch to the appropriate handler.

Example

use vecli::{App, Command, CommandContext};

fn greet(_ctx: &CommandContext) {
    println!("Hello!");
}

let app = App::new("mytool")
    .name("My Tool")
    .version("1.0.0")
    .add_command(Command::new("greet", greet));

// app.run();

Implementations

impl App

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

Creates a new App with the given program name.

prog_name is used in usage strings and error messages (typically the binary name, e.g. "mytool").

Examples found in repository

examples/taskr.rs (line 148)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

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

Sets the display name shown in help and version output.

Examples found in repository

examples/taskr.rs (line 149)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn description(self, desc: impl Into<String>) -> Self

Sets the description shown in the app-level help output.

Examples found in repository

examples/taskr.rs (line 150)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn version(self, version: impl Into<String>) -> Self

Sets the version string shown by --version.

Examples found in repository

examples/taskr.rs (line 151)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn print_help_if_no_args(self, show: bool) -> Self

When true, prints help and exits if no arguments are provided.

Mutually exclusive with App::main. If both are set, the main entry point takes priority and a warning is printed to stderr.

pub fn print_help_on_fail(self, show: bool) -> Self

When true, prints the full help listing after any dispatch error.

Examples found in repository

examples/taskr.rs (line 158)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn strict_flags(self, strict: bool) -> Self

When true, aborts with an error if an unknown app-level flag is passed.

When false (the default), unknown flags produce a warning and execution continues. Per-command strict mode is configured separately via Command::strict_flags.

pub fn add_command(self, command: Command) -> Self

Registers a command built with the Command builder.

Examples found in repository

examples/taskr.rs (lines 159-169)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn flag(self, flag: Flag) -> Self

Registers a flag on the app.

If the flag was created with Flag::global, it is available to all commands and merged into CommandContext::flags automatically. Otherwise it is treated as an entry-point flag, visible in the OPTIONS section of help and delivered via PassedFlags to the main entry handler.

Examples found in repository

examples/taskr.rs (lines 153-157)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn add_command_param( self, name: impl Into<String>, flags: Option<Vec<Flag>>, description: impl Into<String>, handler: fn(&CommandContext), usage: Option<impl Into<String>>, strict_flags: bool, print_help_if_no_args: bool, subcommands: Vec<Command>, ) -> Self

👎Deprecated since 0.2.0:

Use App::add_command instead.

Registers a command from individual parameters without the Command builder.

Prefer App::add_command for most cases. This variant is useful when constructing commands dynamically at runtime.

pub fn main(self, entry: fn(PassedFlags)) -> Self

Registers a handler called when no subcommand is provided.

The handler receives a PassedFlags map containing any flags the user passed before a subcommand. Mutually exclusive with App::print_help_if_no_args; if both are set, this handler takes priority.

Examples found in repository

examples/taskr.rs (line 152)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

pub fn print_help(&self)

Prints the app-level help text to stdout.

Output includes the app name, version, description, COMMANDS listing, OPTIONS (entry-point flags and --version), and GLOBAL FLAGS.

pub fn run(self)

Parses std::env::args, resolves aliases, and dispatches to the matching command handler.

Handles the following built-in flags before reaching any user-defined handler:

• --help / -h: prints command-specific or app-level help and exits.
• --version: prints the app name and version and exits.

If no subcommand is provided and a main entry point is registered, the entry handler is called with the resolved flags. If no subcommand is found in the registry, an error is printed and the function returns without calling any handler. When print_help_on_fail is set, the full help listing is also printed.

Examples found in repository

examples/taskr.rs (line 200)

fn main() {
    App::new("taskr")
        .name("Taskr")
        .description("A toy task manager. Demonstrates all vecli features.")
        .version("0.1.0")
        .main(entry)
        .flag(
            Flag::global("verbose")
                .alias("v")
                .description("Enable verbose output."),
        )
        .print_help_on_fail(true)
        .add_command(
            Command::new("add", add)
                .description("Add a new task.")
                .usage("<task> [--priority <level>]")
                .flag(
                    Flag::new("priority")
                        .alias("p")
                        .description("Task priority: low, medium, or high."),
                )
                .strict_flags(true),
        )
        .add_command(
            Command::new("list", list)
                .description("List pending tasks.")
                .flag(
                    Flag::new("all")
                        .alias("a")
                        .description("Include completed tasks."),
                )
                .subcommand(
                    Command::new("urgent", list_urgent)
                        .description("List only high-priority tasks."),
                ),
        )
        .add_command(
            Command::new("done", done)
                .description("Mark a task as done.")
                .usage("<task>"),
        )
        .add_command(
            Command::parent("config")
                .description("Manage taskr configuration.")
                .print_help_if_no_args(true)
                .subcommand(
                    Command::new("set", config_set)
                        .description("Set a config value.")
                        .usage("<key> <value>"),
                )
                .subcommand(Command::new("show", config_show).description("Show current config.")),
        )
        .add_command(Command::new("clear", clear).description("Clear all tasks."))
        .run();
}

Trait Implementations

impl Default for App

fn default() -> App

Returns the “default value” for a type.