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
FromStrtype 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 tousizeget_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