clish

A Rust CLI framework that derives command-line interfaces from annotated function signatures.

#[command]
fn install(package: Pos<String>, version: Named<Option<String>>, force: bool) { ... }

[!WARNING] clish is in beta. The API is not yet stable.

[dependencies]
clish = "0.1.0-beta.2"

cargo add clish

How it works

The #[command] attribute macro transforms a Rust function into a registered CLI command. Each function parameter type determines the corresponding argument's parsing strategy. The app!() macro collects all registered commands, reads CARGO_PKG_* environment variables from the Cargo.toml at compile time, and dispatches invocation at runtime.

use clish::prelude::*;

#[command]
/// Deploy to an environment
fn deploy(
    target: Pos<String>,
    env: Named<String>,
    force: bool,
) {
    println!("Deploying {target} to {env} (force={force})");
}

fn main() {
    app!().run();
}

myapp deploy production --env prod --force

[!IMPORTANT] Importing clish::* directly exposes internal framework types. Use clish::prelude::* instead for correct name resolution.

Argument types

The parameter type determines how clish parses the corresponding command-line token.

Any type T that implements FromStr is accepted: String, i64, u32, f64, and others. A parse failure at runtime produces a styled error message indicating the expected type:

error: invalid value for <port>: expected u16

The types Option<Vec<T>> and Option<bool> produce a compile-time error: Vec<T> is already zero-or-more (making the outer Option redundant), and bool is parsed as a flag that is either present or absent.

Command metadata

The #[command] attribute accepts metadata keys at the top level:

#[command(
    help = "Deploy the application",
    details = "Runs pre-flight checks, builds the release artifact, then pushes it.",
    aliases = ["ship", "release"],
    deprecated = true,
    deprecation_note = "use 'ship' instead",
)]
fn deploy(...) { ... }

Deprecated commands render with the deprecated style (dim by default) in the command listing and emit a warning when invoked. Aliased commands are invocable by any of their registered aliases.

Parameter metadata

Individual parameters are configured via param(ident, key = value, ...) blocks inside the #[command] attribute. The parameter keyword is also accepted as a synonym.

Display

Value resolution

Resolution order: CLI argument > $ENV_VAR > default > error (if the parameter is required).

#[command(
    param(host, help = "Target host", short = 't', placeholder = "HOST", env = "DEPLOY_HOST"),
    param(port, help = "Port number", short = 'p', default = "8080"),
)]
fn deploy(host: Pos<String>, port: Named<Option<u16>>) { ... }

Validation

#[command(
    param(level, short = 'l', choices = ["debug", "info", "error"]),
    param(verbose, short = 'v', conflicts_with = ["quiet"]),
    param(quiet, short = 'q'),
)]
fn log(level: Named<String>, verbose: bool, quiet: bool) { ... }

Completion

Shell completion generation is not yet implemented.

Help text

Help output is generated automatically from all registered metadata. Two forms are available:

• myapp -h (short): displays name, version, one-line description, and the command listing.
• myapp --help (long): additionally shows the details field when set on the application.
• myapp <command> --help (per-command): shows usage, arguments, options, and any param-level metadata.

myapp deploy --help
myapp --help deploy

Example output:

myapp deploy
Deploy the application

Usage: myapp deploy <HOST> [--port <PORT>] [-l <LEVEL>] [-v]

Arguments:
  <HOST>   Target host  [env: DEPLOY_HOST]

Options:
  -p, --port <PORT>   Port number  [default: 8080]
  -l, --level <LEVEL>  Log level  [choices: debug, info, error]
  -v, --verbose        Verbose output
  -q, --quiet          Suppress output

App metadata

The app!() macro reads CARGO_PKG_NAME, CARGO_PKG_VERSION, and CARGO_PKG_DESCRIPTION from the crate's Cargo.toml at compile time. Each value is overridable via builder methods:

app!()
    .name("myapp")
    .version("1.2.0")
    .description("Does things.")
    .run();

Styling

Help text styling is controlled by the HelpStyles struct. Each field accepts either a farben markup string or an anstyle::Style value. Unspecified fields fall back to defaults via ..Default::default().

use clish::prelude::*;
use clish::help::{HelpStyles, HelpStyle};

app!()
    .styles(HelpStyles {
        header: HelpStyle::Markup("[bold cyan underline]"),
        command: HelpStyle::Markup("[bold]"),
        ..Default::default()
    })
    .run();

For projects already using anstyle:

use anstyle::{Style, AnsiColor};

app!()
    .styles(HelpStyles {
        header: HelpStyle::Anstyle(Style::new().fg_color(Some(AnsiColor::Cyan.into()))),
        command: HelpStyle::Anstyle(Style::new().bold()),
        ..Default::default()
    })
    .run();

Available fields

Crate structure

The clish-core and clish-macros crates are re-exported through clish and should not be depended on directly.

Status

Beta. The API is not yet stable.

• Positional arguments
• Named arguments
• Boolean flags
• Optional arguments
• Typed arguments via FromStr
• Short flag/option aliases (-v, -o)
• Environment variable fallback (env)
• Default values (default)
• Enum-like value constraints (choices)
• Mutual exclusion / prerequisites (conflicts_with, requires)
• Command aliases
• Hidden commands / deprecated commands
• Custom help placeholders
• Hide individual params from help
• Auto-generated help
• farben + anstyle styling
• Variadic Vec<T> in macro
• Subcommand groups
• Shell completions

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Cheers, RazkarStudio.

Copyright © 2026 RazkarStudio. All rights reserved.