osarg is a tiny, zero-dependency, borrow-first CLI parser for Rust binaries.
It is built for size-sensitive tools that want explicit control flow, OS-native
argument handling, and enough ergonomics for real --help, --version,
options, values, and positionals.
osarg is not a CLI framework. It does not use derive macros, schemas, or
generated help text.
-v-abc--verbose--port=8080--port 8080-p 8080-p8080--- positional arguments
- repeated options
- passthrough via
Parser::current_value_and_remaining()/into_remaining()/remaining_vec()
Call parser.check_flag()? before handling an option that takes no value.
store_flag() performs this check automatically. An attached value such as
--verbose=false or --help= is rejected with ErrorKind::UnexpectedValue.
If an attached long value is left unread, next() reports it before advancing.
For help/version output, classify the argument with standard::classify(),
validate it with check_flag(), and then call Flag::write().
into_remaining() and remaining_vec() return Result; callers upgrading
from the previous API must add ? or handle the error. A short tail beginning
with - cannot be reconstructed without changing its meaning, so forwarding
it returns ErrorKind::InvalidOptionName. Attached values such as -p-1 still
work when consumed with value() or parse() before forwarding.
use osarg::{Arg, Parser};
use std::path::PathBuf;
fn main() -> Result<(), osarg::Error> {
let mut parser = Parser::from_args(["-p", "8080", "./data"]);
let mut port = 8080;
let mut path: Option<PathBuf> = None;
while let Some(arg) = parser.next()? {
match arg {
Arg::Short('p') | Arg::Long("port") => {
port = parser.parse::<u16>()?;
}
Arg::Value(value) => {
value.store_path_buf(&mut path)?;
}
other => return Err(other.unexpected()),
}
}
let path = osarg::required(path, "<PATH>")?;
let _ = (port, path);
Ok(())
}See examples/ for:
- basic single-command parsing
- optional values
- repeated options
- passthrough wrappers
Size benchmark:
bash ./scripts/size-bench.shThe Clap comparison uses the checked-in manifest and lock file under
scripts/size-bench/clap/. Dependency changes to that baseline must update
those files explicitly. The script explicitly builds for CARGO_BUILD_TARGET
when set, or the host target reported by rustc otherwise, and measures the
binaries in that target's output directory.
Runtime benchmark:
cargo bench --bench parse -- --quick