bpaf

bpaf is a command line argument parser for Rust built around parser combinators. It offers two complementary styles: a derive API that generates a parser from an annotated struct or enum, and a combinatoric API that composes small parsers into larger ones for maximum flexibility. Both styles share the same keywords and can be freely mixed within a single application.

Beyond parsing flags, arguments, positionals, and subcommands, bpaf generates --help output, validates input, and provides dynamic shell completion for bash, zsh, fish, and elvish. It aims to stay lightweight while giving developers fine-grained control over how their command line interfaces are described and validated.

What You Get

• A derive macro that turns an annotated struct/enum into a ready-to-run argument parser
• A combinatoric API for composing and transforming parsers with full control over layout
• Automatic --help, --version, and usage generation from your option definitions
• Dynamic shell completion for bash, zsh, fish, and elvish
• The ability to mix derive and combinatoric styles within a single parser

Common Use Cases

• Building command line tools with typed, validated arguments in Rust
• Defining subcommand-based CLIs with generated help text
• Adding shell autocompletion to a Rust binary
• Composing reusable argument parsers across multiple commands

Under The Hood

Architecture - bpaf models parsing as a set of composable parser values. Core primitives live in params.rs and structs.rs, argument tokenization in args.rs/arg.rs, and metadata for help and usage in meta.rs, meta_help.rs, and item.rs. Completion is handled by the complete_gen.rs, complete_run.rs, and complete_shell.rs modules, while buffer/ and doc.rs render help and documentation output. The workspace also contains a separate bpaf_derive crate implementing the proc-macro derive front end that ultimately builds the same parser values.

Tech Stack - Written in Rust (edition 2021, MSRV 1.68) with an intentionally light dependency set: optional owo-colors and supports-color for colored output and the in-workspace bpaf_derive for the derive API, all gated behind feature flags so the base crate stays minimal.

Code Quality - The repository is extensively documented, with a documentation/ tree, many examples/, a tests/ suite plus in-crate tests.rs, a comptester harness for completion testing, and a maintained changelog. The multi-crate workspace cleanly separates the runtime library, the derive macro, and supporting tooling.

API Design - Offering both derive and combinatoric APIs is bpaf’s defining ergonomic choice: newcomers get a concise declarative path, while advanced users drop into combinators for precise control, and the two interoperate. Shared keywords and documentation across both styles keep the learning curve reasonable despite the breadth of features.