Skip to main content

Crate cornerstone

Crate cornerstone 

Source
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 man page (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-in docs <man|markdown> path.
error
Errors and exit codes.
guard
Safety guards for privileged and destructive operations, implementing the workflow standard: --sudo paired with a real root check, a self-documenting confirmation flag, and --dry-run support surfaced through the context.
help
Help rendering with selectable presets.
json
Minimal JSON output. A small Json value type with a builder and a correct serializer, so commands can emit structured --json output without a serde dependency and without hand-assembling strings (which is where escaping bugs live). This is output-only — for parsing config JSON, see crate::config.
log
Logging: a leveled logger separate from the user-facing crate::out helpers. out is for what the user reads; log is for diagnostics that can also be written to a file. Levels map to verbosity: -v enables debug, -vv enables 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 termios on 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 interrupted at safe points and exit cleanly, so partial files aren’t left corrupt. Zero dependencies — uses a raw sigaction on 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 on crate::app::App and Command.
style
ANSI styling — a Color enum 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.