Crate fire 

Turn a Rust function or module into a command-line application with one attribute.

Rust Fire derives the command-line interface from ordinary Rust function signatures. It does not use a global command registry and does not require a separate runner macro.

Quick start

Add #[fire::main] to a function:

/// Welcome a person.
#[fire::main]
fn welcome(
    /// Person to welcome.
    name: String,
    /// Add an exclamation mark.
    excited: bool,
) {
    let suffix = if excited { "!" } else { "." };
    println!("Welcome, {name}{suffix}");
}

The generated executable accepts both --name Ferris and --name=Ferris. Boolean parameters are flags, so excited is enabled with --excited.

Subcommands

Applying main to an inline module turns each function in that module into a subcommand:

/// Account management commands.
#[fire::main]
mod cli {
    /// Create an account.
    pub fn create(
        /// Account name.
        name: String,
        /// Assign administrator privileges.
        admin: bool,
    ) {
        println!("creating {name}, admin={admin}");
    }

    /// Remove an account.
    pub fn remove(name: String) {
        println!("removing {name}");
    }
}

Function and parameter names are converted from snake_case to kebab-case. The example exposes create and remove as subcommands.

Parameter mapping

Rust type	Command-line behavior
T	Required --name <VALUE> option parsed with FromStr
Option<T>	Optional --name <VALUE> option
bool	Value-less --name flag, defaulting to false
&str	Borrowed string option

Every non-string value is parsed through FromStr. A parse failure, missing value, unknown option, or unknown command is reported on stderr together with the relevant usage line. CLI errors exit with status code 2.

Generated help

Rust Fire automatically supports -h and --help. Function, module, and parameter documentation comments become command descriptions:

Welcome a person.

Usage: app --name <NAME> [--excited]

Options:
    --name <NAME>    Person to welcome.
    --excited        Add an exclamation mark.
    -h, --help       Print help

Module applications additionally support app --help to list commands and app <COMMAND> --help to describe one command.

Fallible commands

Commands may return Result. An error is formatted through Display, printed to stderr, and causes status code 2:

#[fire::main]
fn deploy(target: String) -> Result<(), &'static str> {
    if target == "production" {
        return Err("production deployments are disabled");
    }
    Ok(())
}

Current limitations

• Command modules must be inline modules.
• Methods, generic functions, and async functions are not supported.
• Parameters are named options; positional arguments and short option names are not currently supported.
• Parameter attributes other than documentation comments are rejected.

Attribute Macros

main

Turns a function or inline module into a complete command-line application.