Skip to main content

Crate clawless

Crate clawless 

Source
Expand description

§🦦 Clawless

clawless is an opinionated, batteries-included framework for building command-line applications with Rust. It features low-level building blocks and high-level abstractions that can be used to build stateless CLIs or stateful TUI applications.

This crate is the facade of the framework. It re-exports clawless-core, clawless-cli, and clawless-tui, along with the macros from clawless-derive, so that applications need only a single dependency. The full documentation and guides are available at clawless.rs.

§Usage

The quickest way to create a new project is the scaffolding tool:

cargo install cargo-clawless
cargo clawless new my-cli

To set up a project manually instead, create a new binary crate with cargo new --bin <name>. Then add clawless as a dependency. Inside the crate, open src/main.rs and replace the generated contents with the following snippet:

ⓘ
mod commands;

clawless::main!();

Next, create src/commands.rs to set up your commands module:

ⓘ
clawless::commands!();

You can now start creating commands for your application. Commands should be defined in modules under the commands module. For example, create src/commands/greet.rs:

use clawless::prelude::*;

#[derive(Debug, Args)]
pub struct GreetArgs {
    #[arg(short, long)]
    name: String,
}

#[command]
pub async fn greet(args: GreetArgs, context: Context) -> CommandResult {
    message!("Hello, {}!", args.name);
    Ok(())
}

Don’t forget to declare the module in src/commands.rs:

ⓘ
mod greet;

clawless::commands!();

You can execute the command by calling your command-line application:

cargo run -- greet --name World

§Organizing Commands

For larger applications, you can organize commands into nested modules. The module hierarchy naturally maps to subcommand groups:

src/
├── main.rs
├── commands.rs
└── commands/
    ├── greet.rs
    ├── db.rs
    └── db/
        ├── migrate.rs
        └── seed.rs

With this structure:

  • cargo run -- greet runs the greet command
  • cargo run -- db migrate runs the db::migrate command
  • cargo run -- db seed runs the db::seed command

Parent modules declare their children, so src/commands/db.rs contains mod migrate; and mod seed;.

§License

Licensed under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules§

cancellation
Cooperative shutdown
context
Context for Clawless commands
event
Event types for structured command output
output
CLI flag configuration and output types
prelude
A prelude module to easily import Clawless essentials
presenter
Output port for rendering command output
resolved_leaf
Resolved subcommand leaf
runner
CLI command runner
tui
TUI presentation layer re-exports

Macros§

artifact
Writes an artifact value via the Output on Context
commands
Set up the commands module for a Clawless application
detail
Writes a supplementary detail via the Output on Context
main
Initialize and run a Clawless application
message
Writes an informational message via the Output on Context

Structs§

Error
The Error type, a wrapper around a dynamic error type.

Traits§

ErrorContext
Provides the context method for Result.

Type Aliases§

CommandResult
Result type for Clawless commands

Attribute Macros§

application
Add a TUI application to a Clawless project
command
Add a command to a Clawless application