#error-handling #reporting #cli #output #format #error-reporting

bin+lib narrate

narrate is a set of CLI app utilities for error handling and status reporting

8 unstable releases (3 breaking)

0.4.1 Jun 8, 2023
0.4.0 Nov 24, 2022
0.3.0 Oct 19, 2022
0.2.0 Sep 29, 2022
0.1.3 Sep 28, 2022

#3 in #output

43 downloads per month


717 lines


Crates.io msrv 1.61.1 tests Documentation license

This library provides CLI application error and status reporting utilities. The coloured output formatting aims to be similar to Cargo. Error type is a wrapper around anyhow, with optional help messages.


  • User facing status messages and error reporting
  • Wrap any error with additional context
  • Optional help messages for errors
  • Set of standard CLI errors with exit codes conforming to sysexits.h
  • Convenience Result type
  • Replace/integrate with anyhow

How to use

  • Use narrate::Result<T> as a return type of any fallible function.

    Within the function, use ? to propagate any error that implements the std::error::Error trait. Same as anyhow::Result<T>.

    use narrate::Result;
    fn get_user() -> Result<User> {
        let json = std::fs::read_to_string("user.json")?;
        let user: User = serde_json::from_str(&json)?;
  • Wrap an error with more context by importing the narrate::ErrorWrap trait. Similar to anyhow::Context, this can give your users more information as to why an error happened.

    use narrate::{CliError, ErrorWrap, Result};
    fn run() -> Result<()> {
        // wrap with contextual information
        data.acquire().wrap("unable to acquire data")?;
        // wrap with another error
        // wrap with lazily evaulated string or error
        config.load().wrap_with(|| format!("cannot load {}", path))?;
        // wrap with help information
          .wrap("project directory already exists")
          .add_help("Try using cargo init")?;
    error: project directory already exists
    cause: Is a directory (os error 20)
    Try using cargo init
  • Use the narrate::ExitCode trait to get the sysexits.h conforming exit code from a narrate::Error. By default this is just 70 (software error), but using an apropriate CliError will change this.

  • narrate::CliError collection of typical command line errors. Use them to add context to deeper application errors. Use their exit_code to conform to sysexits.h.

    use narrate::{CliError, ErrorWrap, ExitCode, Result};
    fn main() {
        let res = run();
        if let Err(ref err) = res {
    fn run() -> Result<()> {
  • Report errors to the command line with either report::err or report::err_full for the complete error chain.

    use narrate::{CliError, Error, report};
    fn main() {
        let res = run();
        if let Err(ref err) = res {
    fn run() -> Result<()> {
        let config: Config = serde_json::from_str(&json)
            .wrap("bad config file `/app/config.toml`")
            .add_help("see https://docs.example.rs/config for more help")?;

    report::err_full output

  • Report application status to the command line with report::status. Modeled on the output from Cargo.

    use colored::Color;
    use narrate::report;
    fn main() {
        report::status("Created", "new project `spacetime`", Color::Green);

    report::status output

Please view the API Docs and examples for more information.


Should I use narrate instead of anyhow or eyre?

Anyhow is a great tool for handling errors in your CLI app, but it doesn't come with its own reporting, common set of errors, or the ability to add separate help messages.

Eyre and its companion crates offer fine-grained error reporting and is far more customizable than narrate - which is opinionated in copying Cargo's style. If you don't need that much control, narrate provides a simpler alternative. Plus the added benefit of reporting statuses, not just errors.

Can I just pretty print my anyhow errors?

If you just use the report Cargo feature flag, you can access the report module and thus the anyhow_err and anyhow_err_full functions.

# Cargo.toml
narrate = { version = "0.4.0", default-features = false, features = ["report"] }
// main.rs
use narrate::report;

fn main() {
    if let Err(err) => run() {

fn run() -> anyhow::Result<()> {


Thank you very much for considering to contribute to this project!

We welcome any form of contribution:

  • New issues (feature requests, bug reports, questions, ideas, ...)
  • Pull requests (documentation improvements, code improvements, new features, ...)

Note: Before you take the time to open a pull request, please open an issue first.

See CONTRIBUTING.md for details.


narrate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).



~73K SLoC