Skip to content

Welcome to clish

Beta

clish is under active development. The API is not yet stable.

What is clish?

clish is a CLI framework for Rust. Instead of manually wiring together argument parsers, you annotate regular Rust functions with #[command] and the macro figures out the rest. Argument parsing, help text, error handling, and validation all happen automatically.

Think of it like this: if you can write a function, you can write a CLI command.

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();
}

Run it:

myapp deploy production --env prod --force

That is it. No builder chains, no manual argument definitions, no separate parser setup. Just a function.

Installation

Add clish to your project:

cargo add clish

Or edit Cargo.toml directly:

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

To use the latest development version:

[dependencies]
clish = { git = "https://codeberg.org/razkar/clish" }

How it works

clish works in two layers:

  1. The #[command] macro reads your function signature at compile time. It looks at each parameter type and generates the code needed to parse command-line arguments into those types.

  2. The runtime collects all registered commands, matches the user input against them, and dispatches to the right function. If anything goes wrong, it prints a styled error message and exits.

You do not need to think about the runtime. Just write functions and annotate them.

What you will learn in this guide

The user guide walks you through everything you need to build a real CLI application:

  • Arguments tells you how to declare positional arguments, named options, and flags, plus how to make them optional or repeatable.
  • Commands covers command metadata like aliases, hidden commands, deprecation, and per-parameter configuration.
  • Oneshot Mode explains single-command CLIs that skip subcommand dispatch entirely.
  • Value Resolution details the CLI > env > default > error pipeline that every parameter follows.
  • Validation covers choices, conflicts, prerequisites, and compile-time type constraints.
  • Help and Style shows you how the built-in help system works and how to customize the look of your CLI.
  • Architecture explains how the three crates work together, the parsing pipeline, and the inventory system.

After the user guide, the Cookbook gives you a complete reference with tables for every attribute, type, and style option. Use it when you need to look up a specific detail.

Imports

Always import clish::prelude::*. This gives you App, Pos, Named, Flag, command, and app!. Do not use clish::* directly. The glob import exposes internal types that you do not need.

Next step

Ready to write your first command? Head over to Arguments.