cli-engine

cli-engine is a Rust library for building consistent, domain-oriented CLI applications. It provides shared framework pieces for command registration, authentication, authorization hooks, middleware, structured output, schemas, guides, search, command tree rendering, and HTTP transport.

Consumer CLIs bring their own binary entrypoint and domain modules. cli-engine owns the common execution pipeline so teams can add commands by copying a nearby command and filling in the domain-specific details.

Quick Start

use std::process::ExitCode;

use clap::Arg;
use cli_engine::{
    BuildInfo, Cli, CliConfig, CommandResult, CommandSpec, GroupSpec, Module, RuntimeCommandSpec,
    RuntimeGroupSpec,
};
use serde_json::json;

#[tokio::main]
async fn main() -> ExitCode {
    let list = RuntimeCommandSpec::new(
        CommandSpec::new("list", "List projects")
            .with_system("projects-api")
            .with_default_fields("id,name,status")
            .with_arg(Arg::new("team").long("team").required(true))
            .no_auth(true),
        async |_credential, args| {
            let team = args
                .get("team")
                .and_then(|value| value.as_str())
                .unwrap_or_default();

            Ok(CommandResult::new(json!([
                { "id": "project-1", "name": "Portal", "status": "active", "team": team }
            ])))
        },
    );

    let module = Module::new("Platform Systems", move |_context| {
        RuntimeGroupSpec::new(GroupSpec::new("project", "Manage projects"))
            .with_command(list.clone())
    });

    let cli = Cli::new(
        CliConfig::new("example", "Example cli-engine application", "example")
            .with_build(BuildInfo::new(env!("CARGO_PKG_VERSION")))
            .with_module(module),
    );

    cli.execute().await
}

Command paths are colon-separated, such as project:list, for policy, schema, audit, activity, and authorization metadata.

Guide Embedding

Guide markdown can be read from disk during development with parse_guides("guides"), or embedded in the consumer CLI binary with standard Rust compile-time embedding:

use cli_engine::Module;

let module = Module::new("Platform Systems", register).with_guides_from_markdown([
    ("guides/deploy.md", include_bytes!("../guides/deploy.md").as_slice()),
    ("guides/operate.md", include_bytes!("../guides/operate.md").as_slice()),
]);

For large guide directories, applications can use an embedding crate or a build.rs generated manifest that produces the same (path, bytes) pairs.

Documentation

Cargo Features

Feature	Description
`pkce-auth`	Enables `auth::pkce::PkceAuthProvider`, a built-in browser-based OAuth 2.0 PKCE flow with system keychain storage via the `keyring` crate. Adds optional dependencies: `keyring`, `open`, `rand`, `sha2`, `url`.

Verification