cli-command
A lightweight, ergonomic command-line argument parser for Rust applications that prioritizes simplicity and performance with convenient macros for reduced boilerplate.
Why cli-command?
Perfect for developers who want CLI parsing without the complexity. While clap
is powerful, it's often overkill for simple applications. cli-command
fills the gap with a clean, intuitive API that's both lightweight and feature-rich.
๐ Key Advantages
- Minimal Dependencies - Only 3 lightweight dependencies (proc-macro2, quote, syn)
- Dual API Design - Both method-based and macro-based interfaces for different preferences
- Macro Ergonomics -
cli_args!
macro eliminates boilerplate while maintaining type safety - Generic Type Support - Works with any
FromStr
type out of the box - Smart Error Messages - Helpful error messages that guide users to solutions
- Memory Efficient - Minimal memory footprint with optimized parsing
- Flexible Usage - Choose between explicit method calls or convenient macros
๐ฏ Perfect For
- Simple CLI tools that need basic argument parsing
- Performance-critical applications where binary size matters
- Learning projects where you want to understand the parsing logic
- Rapid prototyping with macro-based argument extraction
- Quick prototypes that need CLI support without complexity
- Applications that benefit from both explicit and macro-based APIs
Features
- ๐ Minimal dependencies - Only 3 lightweight dependencies for macro support
- ๐ฏ Dual API design - Both method-based and macro-based interfaces
- ๐ง Flexible parsing - Supports both
-
and--
argument prefixes - ๐ Type conversion - Built-in support for common types
- โก Error handling - Comprehensive error types with helpful messages
- ๐งช Well tested - Extensive test coverage
- ๐ Generic defaults -
get_argument_or_default<T>()
works with any type - ๐ Multiple values - Support for arguments with multiple parameters
- ๐จ Macro ergonomics -
cli_args!
macro for boilerplate-free argument extraction - ๐ญ Command matching -
cli_match!
macro for clean command routing
Comparison with Other CLI Parsers
Feature | cli-command | clap | pico-args | gumdrop |
---|---|---|---|---|
Dependencies | 3 | 20+ | 0 | 1 |
Binary Size | Minimal | Large | Minimal | Small |
Compile Time | Fast | Slow | Fast | Fast |
API Style | Method + Macro | Derive + Builder | Iterator-based | Derive |
Type Conversion | Built-in + Generic | Built-in | Manual | Built-in |
Error Messages | Helpful | Excellent | Basic | Good |
Learning Curve | Easy | Steep | Medium | Easy |
Macros Available | Optional | Yes | No | Yes |
When to choose cli-command:
- You want minimal dependencies and fast compilation
- You prefer flexible APIs (both method-based and macro-based)
- You need basic to intermediate CLI parsing features
- Binary size and performance are important
- You want to understand the parsing logic
- You like the ergonomics of macros but want the option to use explicit APIs
Basic Usage
use ;
๐ฏ What Makes This Special
Notice how get_argument_or_default<T>()
works with any type that implements FromStr
- no special handling needed! This generic approach makes the API both powerful and intuitive.
Macro-Based Usage
For even more ergonomic code, cli-command
provides convenient macros that eliminate boilerplate while maintaining the same performance:
cli_args!
Macro
The cli_args!
macro allows you to extract multiple arguments with defaults in a single expression:
use ;
cli_match!
Macro
The cli_match!
macro provides clean command routing and automatically parses the command line:
use ;
๐ Macro Benefits
- Reduced Boilerplate - Extract multiple arguments in one line
- Type Safety - Full compile-time type checking
- Same Performance - Macros expand to the same method calls
- Optional Usage - Use macros when convenient, methods when explicit
- Automatic Parsing - No need to call
parse_command_line()
manually - Clean Command Routing -
cli_match!
handles command parsing and routing automatically
Examples
Simple CLI Tool
use ;
Server Configuration
use ;
use SocketAddr;
API Reference
Command Structure
Argument Access Methods
Optional Arguments
get_argument(name)
- Get first value of an argumentget_argument_nth_parameter(name, nth)
- Get nth value of an argumentget_argument_all(name)
- Get all values of an argumentcontains_argument(name)
- Check if argument exists
Required Arguments
get_argument_mandatory(name)
- Get first value, error if missingget_argument_nth_param_mandatory(name, nth)
- Get nth value, error if missingget_argument_mandatory_all(name)
- Get all values, error if missing
Type Conversion
get_argument_usize(name)
- Convert tousize
get_argument_mandatory_usize(name)
- Convert tousize
, error if missingget_argument_or_default(name, default)
- Get value or return default
Error Handling
use ;
match cmd.get_argument_mandatory
Command Line Format
The parser supports standard Unix-style command line arguments:
# Command with arguments
# Multiple values for same argument
# Short and long forms
# Boolean flags (no value needed)
Error Handling
cli-command
provides helpful error messages that guide users to solutions:
use ;
match cmd.get_argument_mandatory
Error Types
MissingArgument
- Required argument not provided (with helpful usage hint)MissingParameter
- Required parameter at specific position not providedParseCommandLine
- General command line parsing errorInner
- Wrapped error from type conversion
Performance
- Minimal dependencies = faster compilation and smaller binaries than clap
- Minimal memory allocation during parsing
- Fast type conversion with built-in optimizations
- Optional macros = use them when convenient, avoid when not needed
- Zero runtime overhead = macros expand to the same method calls
Command Line Format
The parser supports standard Unix-style command line arguments:
# Command with arguments
# Multiple values for same argument
# Short and long forms
# Boolean flags (no value needed)
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Changelog
0.0.5 (Upcoming)
- Added
cli_args!
macro for ergonomic argument extraction - Added
cli_match!
macro for clean command routing - Introduced minimal dependencies (proc-macro2, quote, syn) for macro support
- Maintained backward compatibility with method-based API
- Enhanced usability with dual API design
0.0.4
- Initial release
- Basic command line parsing
- Type conversion support
- Error handling