Crate sen 

SEN: Script to System CLI Engine

A type-safe, macro-powered CLI framework inspired by Axum’s ergonomics.

Core Principles

• Compile-time safety: Enum-based routing with exhaustiveness checking
• Zero boilerplate: Derive macros generate all wiring code
• Type-driven DI: Handler parameters are injected based on type signature
• Fixed workflows: Predictable behavior for humans and AI agents

Quick Start

use sen::{CliResult, State, SenRouter};

// Define application state
pub struct AppState {
    pub config: Config,
}

// Define commands with derive macro
#[derive(SenRouter)]
#[sen(state = AppState)]
enum Commands {
    #[sen(handler = handlers::status)]
    Status,

    #[sen(handler = handlers::build)]
    Build(BuildArgs),
}

// Implement handlers as async functions
mod handlers {
    use super::*;

    pub async fn status(state: State<AppState>) -> CliResult<String> {
        let app = state.read().await;
        Ok("Status: OK".to_string())
    }

    pub async fn build(state: State<AppState>, args: BuildArgs) -> CliResult<()> {
        // Build logic here (can use async DB, API calls, etc.)
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    let state = State::new(AppState { config: Config::load() });
    let cmd = Commands::parse();
    let response = cmd.execute(state).await;

    if !response.output.is_empty() {
        println!("{}", response.output);
    }
    std::process::exit(response.exit_code);
}

Re-exports

pub use tracing_support::init_subscriber;

pub use tracing_support::init_subscriber_with_config;

pub use tracing_support::TracingConfig;

pub use tracing_support::TracingFormat;

pub use build_info::version_info;

pub use build_info::version_short;

pub use sensors::GitSensor;

pub use sensors::SensorData;

pub use sensors::Sensors;

pub use tracing_support::tracing;

Modules

build_info

Build information module.

instrument

Attach a span to a std::future::Future.

sensors

Sensor system for environment context injection.

tracing_support

Tracing and logging support.

Macros

debug

Constructs an event at the debug level.

error

Constructs an event at the error level.

info

Constructs an event at the info level.

trace

Constructs an event at the trace level.

warn

Constructs an event at the warn level.

Structs

Args

Extractor for command-line arguments.

GlobalOptions

Global options wrapper for CLI-wide flags.

HandlerMetadata

Metadata for individual command handlers.

HandlerWithMeta

Wrapper that attaches metadata to a handler.

Response

Response returned by handlers after execution.

ResponseMetadata

Metadata attached to Response for AI agents.

RouteMetadata

Metadata for a specific route in the router.

Router

Router for CLI commands.

RouterMetadata

Metadata for CLI application and commands.

State

Shared application state wrapper with async-safe interior mutability.

Enums

CliError

Top-level error type for CLI operations.

Output

Output type for responses.

SystemError

System-level failures (exit code 101).

Tier

Safety tier for CLI commands.

UserError

User-fixable errors (exit code 1).

Traits

FromArgs

Trait for parsing command-line arguments into a type.

FromGlobalArgs

Trait for parsing global options from command-line arguments.

Handler

Handler trait - allows functions with various signatures to be used as handlers.

IntoResponse

Trait for converting handler return values into responses.

Type Aliases

CliResult

CLI result type.

Attribute Macros

handler

Attribute macro for handler functions to attach metadata.

instrument

Instruments a function to create and enter a tracing span every time the function is called.

sen

Attribute macro for Router functions to attach CLI metadata.

Derive Macros

SenRouter

Derives the SenRouter trait for an enum, generating the execute() method.