📎 nanoargs

A lightweight, zero-dependency argument parser for Rust.

Part of the nano crate family — minimal, zero-dependency building blocks for Rust:

nanocolor — terminal colors and styles
nanospinner — terminal spinners
nanoprogress — progress bars
nanologger — minimal logger
nanotime — time utilities
nanoargs — argument parser

Everything you'd expect from a CLI parser — flags, options, subcommands, help generation, env fallback, typed parsing — with zero dependencies.

Why nanoargs?

clap pulls in 10+ transitive dependencies. pico-args and lexopt are zero-dep but skip help generation, env var fallback, and subcommands. nanoargs covers the gap: everything you'd reach for clap for in a typical CLI, with zero dependencies.

If your CLI needs advanced features like derive macros, argument groups, shell completions, or value validation, clap and bpaf are great choices. nanoargs is for the common, lightweight case.

Feature	`nanoargs`	`clap`	`bpaf`	`pico-args`	`lexopt`
Dependencies (transitive)	0	~12*	5**	0	0
Auto help text	✓	✓	✓	✗	✗
Version flag (`--version`)	✓	✓	✓	✗	✗
Env var fallback	✓	✓	✓	✗	✗
Multi-value options	✓	✓	✓	✗	✗
Subcommands	✓	✓	✓	✗†	✗†
Combined short flags (`-abc`)	✓	✓	✓	✓‡	✓
Default values	✓	✓	✓	✗	✗
Required args	✓	✓	✓	✗	✗
Hidden args	✓	✓	✓	—	—
Colored help	✓§	✓	✓§	✗	✗
Derive macros	✗	✓	✓	✗	✗
Shell completions	✗	✓	✓§	✗	✗
Other advanced features	✗	✓	✓	✗	✗

* clap with default features. With derive, ~17 total. ** bpaf combinatoric API has 0 deps. With derive, 5 total (bpaf_derive + syn tree). † No built-in support. Achievable manually by matching on positional tokens. ‡ Via opt-in cargo features (combined-flags, short-space-opt). § Via opt-in cargo features.

Quick Start (full demo)

cargo add nanoargs

use nanoargs::{ArgBuilder, Flag, Opt, Pos, ParseError};

fn main() {
    let parser = ArgBuilder::new()
        .name("myapp")
        .description("A sample CLI tool")
        .flag(Flag::new("verbose").desc("Enable verbose output").short('v'))
        .option(Opt::new("output").placeholder("FILE").desc("Output file path"))
        .positional(Pos::new("input").desc("Input file").required())
        .build()
        .unwrap();

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

    match parser.parse(args) {
        Ok(result) => {
            println!("verbose: {}", result.get_flag("verbose"));
            println!("output:  {:?}", result.get_option("output"));
            println!("input:   {:?}", result.get_positionals());
        }
        Err(ParseError::HelpRequested(text)) => print!("{}", text),
        Err(ParseError::VersionRequested(text)) => println!("{}", text),
        Err(e) => eprintln!("error: {}", e),
    }
}

Or for throwaway scripts, see Schema-Free Parsing below.

Usage

Flags (example)

Boolean switches toggled by presence.

let parser = ArgBuilder::new()
    .flag(Flag::new("verbose").desc("Enable verbose output").short('v'))
    .flag(Flag::new("dry-run").desc("Simulate without side effects"))
    .build();

myapp --verbose --dry-run
myapp -v

Options (example)

Key-value arguments with fluent modifiers. Construct an Opt with Opt::new(), chain .placeholder(), .desc(), .short(), .required(), .default(), .env(), .multi(), or .hidden() as needed, then pass it to .option().

let parser = ArgBuilder::new()
    .option(Opt::new("format").placeholder("FMT").desc("Output format").short('f'))
    .option(Opt::new("output").placeholder("FILE").desc("Output file path").short('o').required())
    .option(Opt::new("jobs").placeholder("NUM").desc("Parallel jobs").short('j').default("4"))
    .option(Opt::new("include").placeholder("DIR").desc("Directories to include").short('i').multi())
    .build();

myapp --output result.txt --jobs 8 --include src --include tests
myapp -o=result.txt -j 8

Environment Variable Fallback (example)

Options can fall back to environment variables when not provided on the command line. Chain .env() on the Opt builder. The resolution order is: CLI value → env var → default → error (if required).

let parser = ArgBuilder::new()
    .option(Opt::new("log-level").placeholder("LEVEL").desc("Log level").short('l').env("MYAPP_LOG_LEVEL"))
    .option(Opt::new("output").placeholder("FILE").desc("Output file").short('o').env("MYAPP_OUTPUT").required())
    .option(Opt::new("format").placeholder("FMT").desc("Output format").short('f').env("MYAPP_FORMAT").default("text"))
    .build();

# CLI value takes priority
myapp --output result.txt

# Falls back to env var when CLI option is omitted
MYAPP_OUTPUT=from_env.txt myapp

# Falls back to default when both CLI and env var are absent
myapp --output result.txt   # format resolves to "text"

Help text automatically shows the associated env var:

Options:
  -l, --log-level <LEVEL>  Log level [env: MYAPP_LOG_LEVEL]
  -o, --output <FILE>      Output file (required) [env: MYAPP_OUTPUT]
  -f, --format <FMT>       Output format [default: text] [env: MYAPP_FORMAT]

Positionals (example)

Unnamed arguments collected in order. Chain .required() on the Pos builder to make a positional mandatory.

let parser = ArgBuilder::new()
    .positional(Pos::new("input").desc("Input file").required())
    .positional(Pos::new("extra").desc("Additional arguments"))
    .build();

myapp input.txt extra1 extra2

Hidden Arguments

Flags and options can be marked as hidden — they parse normally but are excluded from --help output. Useful for internal, debug, or deprecated arguments.

let parser = ArgBuilder::new()
    .flag(Flag::new("debug").desc("Enable debug mode").short('d').hidden())
    .option(Opt::new("trace-id").placeholder("ID").desc("Internal trace ID").hidden())
    .flag(Flag::new("verbose").desc("Enable verbose output").short('v'))
    .build();

# Hidden arguments work on the command line
myapp --debug --trace-id=abc123 --verbose

# But --help only shows --verbose
myapp --help

The .hidden() modifier is available on both Flag and Opt, and can be called in any order relative to other modifiers.

Combined Short Flags (example)

Combine multiple short flags into a single token. The parser walks characters left-to-right against the registered schema.

let parser = ArgBuilder::new()
    .flag(Flag::new("all").desc("Show all").short('a'))
    .flag(Flag::new("brief").desc("Brief output").short('b'))
    .flag(Flag::new("color").desc("Enable color").short('c'))
    .option(Opt::new("width").placeholder("NUM").desc("Column width").short('w'))
    .build();

# Combined flags
myapp -abc              # sets all, brief, color

# Attached option value
myapp -w10              # sets width to "10"

# Flags + option in one token
myapp -abcw10           # sets all, brief, color + width="10"
myapp -abcw 10          # same — value from next token

When the parser encounters an option character during the walk, it claims all remaining characters as the value. If none remain, it consumes the next argument token.

Subcommands (example)

Git-style subcommands, each with their own flags, options, and positionals. Global flags are parsed before the subcommand token.

let build_parser = ArgBuilder::new()
    .name("build")
    .description("Compile the project")
    .flag(Flag::new("release").desc("Build in release mode").short('r'))
    .build();

let test_parser = ArgBuilder::new()
    .name("test")
    .description("Run the test suite")
    .flag(Flag::new("verbose").desc("Show detailed output").short('v'))
    .build();

let parser = ArgBuilder::new()
    .name("myapp")
    .description("A demo CLI")
    .flag(Flag::new("quiet").desc("Suppress output").short('q'))
    .subcommand("build", "Compile the project", build_parser)
    .subcommand("test", "Run the test suite", test_parser)
    .build();

myapp build --release
myapp -q test --verbose
myapp --help              # lists available subcommands
myapp build --help        # subcommand-specific help

Note: When subcommands are registered, the first bare (non-flag/option) token is always treated as the subcommand name. Parent-level positional arguments are not supported alongside subcommands — this matches git-style CLI conventions.
# Supported — global flags before the subcommand:
myapp -q build --release

# NOT supported — positionals before the subcommand:
myapp file.txt build    # "file.txt" is treated as an unknown subcommand

Access results via subcommand() and subcommand_result():

if let Some("build") = result.subcommand() {
    let sub = result.subcommand_result().unwrap();
    println!("release: {}", sub.get_flag("release"));
}

Version Flag (example)

Built-in --version / -V support. Set a version string on the builder and the parser handles the rest.

let parser = ArgBuilder::new()
    .name("myapp")
    .version(env!("CARGO_PKG_VERSION"))
    .flag(Flag::new("verbose").desc("Enable verbose output").short('v'))
    .build()
    .unwrap();

$ myapp --version
myapp 0.1.0

$ myapp -V
myapp 0.1.0

The -V short flag is reserved when a version is configured — the builder will reject any user-registered flag or option that uses 'V' as its short form. When no version is set, --version and -V are treated as unknown arguments, and 'V' is available for user flags.

When both --help and --version appear, whichever comes first wins. After --, both are treated as positionals.

Typed Parsing

Parse option values into any type implementing FromStr. Convenience helpers collapse the common three-way match into a single call:

// With a default fallback — returns the parsed value, or the default if absent/unparseable
let jobs: u32 = result.get_option_or_default("jobs", 4);

// With a lazy default — closure only runs if needed
let jobs: u32 = result.get_option_or("jobs", || num_cpus());

// Required with Result — use the ? operator
let jobs: u32 = result.get_option_required("jobs")?;

For fine-grained control over parse errors, the original accessor is still available:

match result.get_option_parsed::<u32>("jobs") {
    Some(Ok(n)) => println!("jobs: {}", n),
    Some(Err(e)) => eprintln!("invalid jobs value: {}", e),
    None => println!("jobs not set"),
}

Help Text (example)

Auto-generated from your schema. Triggered by --help or -h.

$ myapp --help
Usage: myapp [OPTIONS] <input> [extra]

A sample CLI tool

Options:
  -v, --verbose          Enable verbose output
      --dry-run          Simulate without side effects
  -o, --output <FILE>    Output file path (required)
  -j, --jobs <NUM>       Parallel jobs [default: 4]
  -h, --help             Print help

Double-Dash Separator

Everything after -- is treated as a positional, even if it looks like a flag or option.

myapp -- --not-a-flag -abc
# positionals: ["--not-a-flag", "-abc"]

Colored Help (opt-in)

Enable the color feature to get ANSI-colored help text and error messages via nanocolor:

[dependencies]
nanoargs = { version = "0.1", features = ["color"] }

cargo run --example help_text --features color -- --help

When enabled, section headers are bold yellow, flag/option names are green, placeholders are cyan, and metadata like [default: ...] is dim. Error messages get a bold red error: prefix. Color is automatically suppressed when NO_COLOR is set or output is not a TTY (handled by nanocolor). Without the feature, the crate remains zero-dependency and output is unchanged.

Error Handling (example)

match parser.parse(args) {
    Ok(result) => { /* use result */ }
    Err(ParseError::HelpRequested(text)) => print!("{}", text),
    Err(ParseError::VersionRequested(text)) => println!("{}", text),
    Err(ParseError::MissingRequired(name)) => eprintln!("missing: {}", name),
    Err(ParseError::MissingValue(name)) => eprintln!("no value for: --{}", name),
    Err(ParseError::UnknownArgument(token)) => eprintln!("unknown: {}", token),
    Err(ParseError::NoSubcommand(msg)) => eprintln!("{}", msg),
    Err(ParseError::UnknownSubcommand(name)) => eprintln!("unknown subcommand: {}", name),
    Err(ParseError::DuplicateOption(name)) => eprintln!("duplicate: --{}", name),
    Err(ParseError::InvalidFormat(msg)) => eprintln!("bad format: {}", msg),
}

Schema-Free Parsing for Quick Scripts

parse_loose() skips the schema entirely — useful for throwaway scripts where defining flags and options feels like overkill.

fn main() {
    let result = nanoargs::parse_loose().unwrap();
    let verbose = result.get_flag("verbose");
    let output = result.get_option("output");
    let positionals = result.get_positionals();
}

It uses a heuristic to guess whether --key is a flag or an option: if the next token doesn't start with -, it's consumed as the value.

When it works well: simple scripts with clear flag/option boundaries (--verbose --output file.txt).

When it doesn't: --output -v silently treats --output as a flag (not an option), because -v starts with -. If your CLI has options that could receive flag-like values, use ArgBuilder instead.

API Reference

See the full API docs on docs.rs.

Examples

Example	Description	Run
flags	Boolean flags	`cargo run --example flags -- -v --dry-run`
options	Options with defaults and required	`cargo run --example options -- -o=out.txt -j 8`
positionals	Positional arguments	`cargo run --example positionals -- file.txt extra`
short_flags	Combined short flags and attached values	`cargo run --example short_flags -- -abcw10`
help_text	Auto-generated help	`cargo run --example help_text -- --help`
error_handling	Error handling patterns	`cargo run --example error_handling`
version_flag	Built-in version flag	`cargo run --example version_flag -- --version`
env_fallback	Environment variable fallback	`cargo run --example env_fallback -- --output out.txt`
subcommands	Git-style subcommands	`cargo run --example subcommands -- build --release`
full_demo	All features together	`cargo run --example full_demo -- -vj8 -o=result.txt input.txt`

Contributing

Contributions are welcome. To get started:

Fork the repository
Create a feature branch (git checkout -b my-feature)
Make your changes
Run the tests: cargo test
Submit a pull request

Please keep changes minimal and focused. This crate's goal is to stay small and dependency-free.

License

This project is licensed under the MIT License.

nanoargs 0.1.0