Lib Cornerstone
A zero-dependency foundation for building command-line tools in Rust. Declare what your commands are and what they do; Cornerstone supplies everything else — parsing, help, output, errors, config, prompts, completions, and guards — so a new CLI is a list of commands and their bodies, not a pile of boilerplate.
The package is published as
libcornerstone, but the library is imported ascornerstone:use *;
Install
[]
= "0.1"
Quick start
use *;
$ greet hello world
Hello, world!
$ greet hello world --shout
HELLO, WORLD!
$ greet --help
.run() parses argv, handles --help/--version/global flags, sets up color and quiet state, dispatches, runs lifecycle hooks, and turns a returned error into a printed message plus the right exit code. Use .run_with(args) in tests — it returns the exit code instead of exiting.
What you get
- Argument parsing — long/short/bundled flags,
--key=value,-svalue,--passthrough, required/optional/variadic positionals. No dependencies. - Nested subcommands —
App::group("remote", …, |g| g.command("add", …))to any depth. - Help in three presets —
Standard(clap-like),Banner, andSections, each rendering app help, per-subcommand help, and short (-h) / long (--help) tiers. Or plug in your ownHelpRenderer. - Global flags for free —
-h/--help,-V/--version,-q/--quiet,-v/-vv,--json,--dry-run,--sudo. - Structured errors and stable exit codes —
Error::{msg,usage,not_found,permission,cancelled}, plusErrorSetfor the collect-all-failures-then-report pattern. - Output helpers — leveled messages, auto-aligned
Table,Tree, key/value blocks,Progressbars,Spinner,Timer. All respect quiet/color/pipe state. - Config loading — TOML-subset / INI / JSON, environment overlay, and
flag > env > file > defaultprecedence. - Interactive prompts — confirm, text, hidden password, select, multiselect, and range-checked number.
- Shell completions — bash / zsh / fish generated from your command specs, via a built-in
completions <shell>command. - Docs generation — man page and Markdown reference from the same specs, via a built-in
docs <man|markdown>command. - Logging — leveled logger, verbosity-gated console output plus an always-on file sink.
- JSON output — a small
Jsonbuilder with correct escaping for--jsonmodes. - Fuzzy suggestions — "did you mean?" on unknown commands.
- Signal handling — clean Ctrl-C and correct SIGPIPE behavior (no panic when piped into
head). - Guards —
ctx.require_root()(checks--sudoand realgeteuid() == 0) andctx.require_confirmation(...)for destructive operations, with--dry-runbypassing confirmation.
Themeable and non-prescriptive
Cornerstone ships neutral — no decorative glyphs, no house style — so tools built on it look generic and professional out of the box. Every glyph, label, color, and confirmation wording is overridable through a Theme, and help layout through HelpStyle or a custom HelpRenderer, without forking the crate.
let theme = default
.success_glyph
.error_label
.progress_cells;
new.theme /* ... */;
Platform notes
The guards, hidden-password prompt, and signal handling use Unix syscalls validated on Linux x86-64 (glibc). They degrade gracefully elsewhere. The crate is #![forbid(unsafe_code)]-adjacent — it uses small, contained extern "C" calls only for isatty, geteuid, terminal echo, and signal setup.
Minimum supported Rust version
Rust 1.74 or newer.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.