Expand description
§Lib Cornerstone
The shared foundation every CLI is built on. Declare what your commands are and what they do; Cornerstone supplies everything else: argument parsing, nested subcommands, help menus (three presets or a custom renderer), global flags, colored themeable output, tables, trees, key/value blocks, progress bars and spinners, timers, structured errors with exit codes, config loading with env/flag precedence, interactive prompts, shell-completion generation, fuzzy “did you mean?” suggestions, signal handling, and safety guards for root and destructive operations.
Everything is zero-dependency, neutral by default, and overridable — the library encapsulates the work without imposing a house style.
ⓘ
use cornerstone::prelude::*;
fn main() {
App::new("mytool")
.about("Does the thing")
.command("hello", "Say hello", |ctx| ctx.ok("hello!"))
.run();
}Modules§
- app
- The application builder — the one type most authors use.
- complete
- Shell completion generation. Produces a completion script for bash, zsh, or
fish directly from the app’s declared commands and flags — no annotations
needed. The app exposes this through a built-in
completions <shell>path; authors can also call it directly. - config
- Configuration loading with a clear precedence chain: flag > environment > config file > default.
- ctx
- The context handed to every command body. It bundles the parsed arguments with the global state (quiet, verbose, dry-run, json) and convenience methods for output and guards, so a command body reads as pure logic.
- docs
- Documentation generation. Produces a
manpage (roff) or a Markdown reference straight from the declared commands — the same specs that drive help and completion — so a tool’s docs never drift from its actual interface. Exposed through the built-indocs <man|markdown>path. - error
- Errors and exit codes.
- guard
- Safety guards for privileged and destructive operations, implementing the
workflow standard:
--sudopaired with a real root check, a self-documenting confirmation flag, and--dry-runsupport surfaced through the context. - help
- Help rendering with selectable presets.
- json
- Minimal JSON output. A small
Jsonvalue type with a builder and a correct serializer, so commands can emit structured--jsonoutput without a serde dependency and without hand-assembling strings (which is where escaping bugs live). This is output-only — for parsing config JSON, seecrate::config. - log
- Logging: a leveled logger separate from the user-facing
crate::outhelpers.outis for what the user reads;logis for diagnostics that can also be written to a file. Levels map to verbosity:-venables debug,-vvenables trace. A file sink, if set, always records every level regardless of console verbosity, so a quiet run still leaves a full trace on disk. - out
- Output helpers: leveled messages, tables, and a progress bar. All respect the global quiet/color state so command bodies never branch on it themselves.
- parse
- Zero-dependency argument parser.
- prelude
- The one import a CLI author needs:
- prompt
- Interactive prompts: confirmation, free text, hidden password, and single
selection. Zero dependencies — password entry toggles the terminal echo via
raw
termioson unix. Every prompt errors cleanly when stdin is not a terminal, so scripts fail loudly instead of hanging. - sig
- Signal handling: install a SIGINT (Ctrl-C) handler that flips a global flag
instead of killing the process mid-write. Long-running command bodies poll
interruptedat safe points and exit cleanly, so partial files aren’t left corrupt. Zero dependencies — uses a rawsigactionon unix. - spec
- The declarative model an author fills in: commands, positional arguments,
and flags. This is pure data — the parser (
crate::parse) consumes it and the help renderer (crate::help) prints it. Authors never touch these structs directly; they build them through the fluent methods oncrate::app::AppandCommand. - style
- ANSI styling — a
Colorenum plus attribute wrappers. - suggest
- Fuzzy “did you mean?” suggestions. Pure function, no dependencies. Used by the app to suggest a near-miss when the user types an unknown command or flag, but exposed for authors to use anywhere (e.g. validating an enum arg).
- theme
- Theme: every human-visible string, glyph, and color the library emits lives here, so nothing is hardcoded in the machinery. The default theme is neutral — no personal voice — and any field can be overridden wholesale or piecemeal.