cornerlibstone 0.1.0

Lib Cornerstone — a zero-dependency foundation for building command-line tools in Rust: argument parsing, nested subcommands, themeable help in multiple presets, structured errors and exit codes, config loading, interactive prompts, shell-completion and man/markdown generation, logging, JSON output, and root/destructive-operation guards.
Documentation
  • Coverage
  • 58.98%
    197 out of 334 items documented0 out of 220 items with examples
  • Size
  • Source code size: 153.4 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.1 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Repository
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Ultiminium

Lib Cornerstone

crates.io docs.rs license

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 as cornerstone:

use cornerstone::prelude::*;

Install

[dependencies]
libcornerstone = "0.1"

Quick start

use cornerstone::prelude::*;

fn main() {
    App::new("greet")
        .about("A tiny greeter")
        .version(env!("CARGO_PKG_VERSION"))
        .command_with(
            "hello",
            "Greet someone",
            |c| c.arg("name", "Who to greet").switch("shout", Some('s'), "Greet loudly"),
            |ctx| {
                let name = ctx.arg("name")?;
                let msg = format!("Hello, {}!", name);
                ctx.info(if ctx.flag("shout") { msg.to_uppercase() } else { msg });
                Ok(())
            },
        )
        .run();
}
$ 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, and Sections, each rendering app help, per-subcommand help, and short (-h) / long (--help) tiers. Or plug in your own HelpRenderer.
  • 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}, plus ErrorSet for the collect-all-failures-then-report pattern.
  • Output helpers — leveled messages, auto-aligned Table, Tree, key/value blocks, Progress bars, Spinner, Timer. All respect quiet/color/pipe state.
  • Config loading — TOML-subset / INI / JSON, environment overlay, and flag > env > file > default precedence.
  • 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 Json builder with correct escaping for --json modes.
  • 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 --sudo and real geteuid() == 0) and ctx.require_confirmation(...) for destructive operations, with --dry-run bypassing 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 = Theme::default()
    .success_glyph("»")
    .error_label("fatal:")
    .progress_cells("=", " ");
App::new("tool").theme(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

at your option.