Crate cli_engine 

Build consistent, domain-oriented CLIs with a small amount of Rust.

cli_engine provides the shared pieces that most CLI tools need: command registration, authentication provider routing, authorization hooks, audit and activity hooks, structured output, output schemas, guides, search, command tree rendering, busybox-style multi-call (argv[0]) dispatch, and authenticated HTTP transport helpers.

The intended shape is:

1. Each team owns one or more Module values.
2. A module registers noun-based GroupSpec groups.
3. Groups contain verb-like CommandSpec leaf commands.
4. Command handlers stay focused on domain behavior while Middleware handles authentication, dry-run, audit, activity, output, and errors.

Quick Start

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

#[tokio::main]
async fn main() -> std::process::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(cli_engine::CommandResult::new(json!([
                { "id": "p1", "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 (project:list) for policy, audit, schema, and authorization compatibility with existing CLI ecosystems.

Re-exports

pub use auth::AuthLoginResult;

pub use auth::AuthProvider;

pub use auth::AuthStatusEntry;

pub use auth::CACHE_TTL;

pub use auth::Credential;

pub use auth::CredentialRequest;

pub use auth::Dispatcher;

pub use auth::SingleProvider;

pub use auth::StatusEntry;

pub use auth::auth_command_group;

pub use auth::login_and_build;

pub use auth::login_and_build_with_scopes;

pub use auth::logout_result;

pub use auth::status_result;

pub use auth::to_status_entry;

pub use cli::ApplyFlags;

pub use cli::Argv0LinkMethod;

pub use cli::Argv0Route;

pub use cli::BuildInfo;

pub use cli::Cli;

pub use cli::CliConfig;

pub use cli::CliRunOutput;

pub use cli::ExtraSearchDocs;

pub use cli::InitDeps;

pub use cli::ModuleHelpEntry;

pub use cli::OnShutdown;

pub use cli::PreRun;

pub use cli::RegisterFlags;

pub use cli::ResolveMeta;

pub use cli::RootNextActions;

pub use cli::build_root_long;

pub use command::CommandContext;

pub use command::CommandFuture;

pub use command::CommandHandler;

pub use command::CommandResult;

pub use command::CommandResultMetadata;

pub use command::CommandSpec;

pub use command::GroupSpec;

pub use command::RuntimeCommandSpec;

pub use command::RuntimeGroupSpec;

pub use command::StreamSender;

pub use command::StreamingCommandFuture;

pub use command::StreamingCommandHandler;

pub use command::command_args_from_matches;

pub use command::command_path_from_matches;

pub use command::command_path_from_parts;

pub use command::leaf_matches;

pub use error::CliCoreError;

pub use error::DetailedError;

pub use error::ExitCoder;

pub use error::Result;

pub use error::exit_code_for_error;

pub use error::exit_code_for_exit_coder;

pub use flags::GlobalFlags;

pub use flags::default_output_format;

pub use flags::derive_bool_flags;

pub use flags::derive_value_flags;

pub use flags::extract_command_path;

pub use flags::extract_output_format;

pub use flags::extract_search_query;

pub use flags::global_flags_from_matches;

pub use flags::has_true_schema_flag;

pub use flags::output_env_var;

pub use flags::register_global_flags;

pub use flags::resolve_default_output_format;

pub use guide::GuideEntry;

pub use guide::parse_guides;

pub use guide::parse_guides_from_markdown;

pub use middleware::ActivityEmitter;

pub use middleware::ActivityEvent;

pub use middleware::Auditor;

pub use middleware::AuthRequirement;

pub use middleware::Authorizer;

pub use middleware::CommandMeta;

pub use middleware::CredentialResolver;

pub use middleware::Middleware;

pub use middleware::MiddlewareOutput;

pub use middleware::MiddlewareRequest;

pub use module::CommandModule;

pub use module::Module;

pub use module::ModuleContext;

pub use module::ModuleRegister;

pub use output::Envelope;

pub use output::ErrorEnvelope;

pub use output::FieldInfo;

pub use output::HumanViewDef;

pub use output::HumanViewFn;

pub use output::HumanViewRegistry;

pub use output::HumanViewRenderer;

pub use output::Metadata;

pub use output::NextAction;

pub use output::NextActionParam;

pub use output::OutputField;

pub use output::OutputFormat;

pub use output::OutputSchema;

pub use output::PaginationMeta;

pub use output::PipelineOpts;

pub use output::RendererFactory;

pub use output::SchemaInfo;

pub use output::SchemaRegistry;

pub use output::TableColumn;

pub use output::apply_pipeline;

pub use output::build_detailed_error_envelope;

pub use output::build_error_envelope;

pub use output::fields_for;

pub use output::fields_from_json_schema;

pub use output::filter_fields;

pub use output::format_help_section;

pub use output::get_global_schema_by_path;

pub use output::global_human_view_registry_snapshot;

pub use output::global_schema_registry_snapshot;

pub use output::is_valid_output_format;

pub use output::json_schema_for;

pub use output::json_schema_info;

pub use output::lookup_global_human_view_columns;

pub use output::lookup_global_human_view_func;

pub use output::parse_fields;

pub use output::register_global_human_view;

pub use output::register_global_human_view_func;

pub use output::register_global_json_schema;

pub use output::register_global_schema;

pub use output::register_global_schema_fields;

pub use output::register_global_schema_info;

pub use output::render;

pub use output::render_data;

pub use output::render_data_format;

pub use output::render_detailed_error;

pub use output::render_detailed_error_format;

pub use output::render_error;

pub use output::render_error_format;

pub use output::render_format;

pub use output::render_human;

pub use output::render_human_with_registry;

pub use output::render_human_with_registry_for_schema;

pub use output::render_human_with_view;

pub use output::render_json;

pub use output::render_toon;

pub use output::write_render;

pub use search::SearchDocument;

pub use search::SearchResult;

pub use tier::Tier;

pub use tree::TreeNode;

pub use tree::build_tree_from_clap;

pub use tree::build_tree_from_parts;

pub use tree::render_tree_human;

Modules

auth

Auth provider traits, dispatch, and built-in provider commands. Auth provider abstraction and built-in auth helpers.

cli

CLI application assembly and execution.

command

Command and command-group specifications.

error

Shared error type and error traits.

flags

Global framework flags and flag-extraction helpers.

guide

Embedded or file-backed guide parsing.

middleware

Cross-cutting command execution middleware.

module

Domain module registration helpers.

output

Structured output envelopes, renderers, schemas, and field projection. Structured output envelopes and renderers.

search

Search indexing for commands, guides, and extra documents.

tier

Command risk tiers used by authentication, authorization, and dry-run.

transport

HTTP transport client and auth injectors. HTTP transport helpers for command implementations.

tree

Command tree data model and human rendering.