3 unstable releases

0.2.0 Feb 16, 2024
0.1.1 Nov 24, 2023
0.1.0 Apr 4, 2023

#69 in Configuration

Download history 371/week @ 2023-11-13 260/week @ 2023-11-20 317/week @ 2023-11-27 258/week @ 2023-12-04 298/week @ 2023-12-11 311/week @ 2023-12-18 121/week @ 2023-12-25 347/week @ 2024-01-01 234/week @ 2024-01-08 337/week @ 2024-01-15 283/week @ 2024-01-22 292/week @ 2024-01-29 194/week @ 2024-02-05 490/week @ 2024-02-12 383/week @ 2024-02-19 293/week @ 2024-02-26

1,391 downloads per month
Used in 4 crates


175 lines


crates.io docs Rust CI

Common code for setting up a CLI App and handling errors/printing.


See examples/axoapp.rs for a walkthrough/example.

Some various interesting example invocations to play with:

# clap help
cargo run --example axoapp -- --help

# success
cargo run --example axoapp -- 5
cargo run --example axoapp -- 5 --output-format=json

# normal error
cargo run --example axoapp -- 2
cargo run --example axoapp -- 2 --output-format=json

# panic (setting RUST_BACKTRACE=1 here is also interesting)
cargo run --example axoapp -- 0
cargo run --example axoapp -- 0 --output-format=json

# clap error
cargo run --example axoapp --

What Does It Do?

First off, it handles setting up:

  • a tracing subscriber (currently the kind that cargo-dist uses, more work needed for oranda's use)
  • a miette formatter (so we can have a shared Look And Feel)
  • a panic handler (to get more control over output if the app panics)
  • (not implemented but likely in the future) a tokio runtime

It also handles printing top-level errors, notably including a json_errors mode where the error gets formatted to json and printed to stdout, while still printing a human-friendly version to stderr. This is done for both an error returned from real_main and panics. So anything expecting machine-readable output from our apps will not freak out and get something unparseable when things error/panic. It will also set the process exit code on error (with std::process::exit, on the assumption that all cleanup was done when we returned/panicked out of real_main).

It also exposes the json diagnostic formatting machinery so you can Write them wherever or turn them into serde_json::Values. This is useful for returning a larger result with diagnostics nested inside of it (say, for reporting warnings).


Licensed under either of

at your option.


~178K SLoC