cli-engine 0.3.2

Rust CLI framework for consistent command modules
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

//! 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
//!
//! ```no_run
//! 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.

/// Auth provider traits, dispatch, and built-in provider commands.
pub mod auth;
/// CLI application assembly and execution.
pub mod cli;
/// Command and command-group specifications.
pub mod command;
/// Engine config file and credential-storage selection.
pub mod config;
/// Built-in `config` command group.
pub mod config_commands;
/// Built-in `env` command group (private; only `cli.rs` consumes it).
mod env_commands;
/// First-class environment definitions and layered resolution.
pub mod environments;
/// Shared error type and error traits.
pub mod error;
/// Global framework flags and flag-extraction helpers.
pub mod flags;
/// Filesystem and path utilities (base dir, path-component safety, atomic write).
pub mod fs;
/// Embedded or file-backed guide parsing.
pub mod guide;
/// Cross-cutting command execution middleware.
pub mod middleware;
/// Domain module registration helpers.
pub mod module;
/// Structured output envelopes, renderers, schemas, and field projection.
pub mod output;
/// Search indexing for commands, guides, and extra documents.
pub mod search;
/// Command risk tiers used by authentication, authorization, and dry-run.
pub mod tier;
/// HTTP transport client and auth injectors.
pub mod transport;
/// Command tree data model and human rendering.
pub mod tree;

#[cfg(feature = "pkce-auth")]
pub use auth::storage::{AutoStorage, KeyringStorage};
pub use auth::storage::{
    CredentialKey, CredentialStorage, FileStorage, default_storage, storage_for,
};
pub use auth::{
    AuthLoginResult, AuthProvider, AuthStatusEntry, CACHE_TTL, Credential, CredentialRequest,
    Dispatcher, SingleProvider, StatusEntry, auth_command_group, login_and_build,
    login_and_build_with_scopes, logout_result, status_result, to_status_entry,
};
pub use cli::{
    ApplyFlags, Argv0LinkMethod, Argv0Route, BuildInfo, Cli, CliConfig, CliRunOutput,
    ExtraSearchDocs, InitDeps, ModuleHelpEntry, OnShutdown, PreRun, RegisterFlags, ResolveMeta,
    RootNextActions, build_root_long,
};
pub use command::{
    CommandContext, CommandFuture, CommandHandler, CommandResult, CommandResultMetadata,
    CommandSpec, GroupSpec, RuntimeCommandSpec, RuntimeGroupSpec, StreamSender,
    StreamingCommandFuture, StreamingCommandHandler, command_args_from_matches,
    command_path_from_matches, command_path_from_parts, leaf_matches,
};
pub use config::{
    ConfigFile, CredentialStore, CredentialsConfig, EngineConfig, ParseCredentialStoreError,
    credential_store_env_var, resolve_credential_store, resolve_credential_store_with,
};
pub use config_commands::config_command_group;
pub use environments::{Environment, EnvironmentDef, Environments, OAuthConfig};
pub use error::{
    CliCoreError, DetailedError, ExitCoder, Result, exit_code_for_error, exit_code_for_exit_coder,
};
pub use flags::{
    GlobalFlags, app_id_env_prefix, debug_component_enabled, default_output_format,
    derive_bool_flags, derive_value_flags, extract_command_path, extract_output_format,
    extract_search_query, global_flags_from_matches, has_true_schema_flag, output_env_var,
    register_global_flags, resolve_default_output_format,
};
pub use guide::{GuideEntry, parse_guides, parse_guides_from_markdown};
pub use middleware::{
    ActivityEmitter, ActivityEvent, Auditor, AuthRequirement, Authorizer, CommandMeta,
    CredentialResolver, Middleware, MiddlewareOutput, MiddlewareRequest,
};
pub use module::{CommandModule, Module, ModuleContext, ModuleRegister};
pub use output::{
    Envelope, ErrorEnvelope, FieldInfo, HumanViewDef, HumanViewFn, HumanViewRegistry,
    HumanViewRenderer, Metadata, NextAction, NextActionParam, OutputField, OutputFormat,
    OutputSchema, PaginationMeta, PipelineOpts, RendererFactory, SchemaInfo, SchemaRegistry,
    TableColumn, apply_pipeline, build_detailed_error_envelope, build_error_envelope, fields_for,
    fields_from_json_schema, filter_fields, format_help_section, get_global_schema_by_path,
    global_human_view_registry_snapshot, global_schema_registry_snapshot, is_valid_output_format,
    json_schema_for, json_schema_info, lookup_global_human_view_columns,
    lookup_global_human_view_func, parse_fields, register_global_human_view,
    register_global_human_view_func, register_global_json_schema, register_global_schema,
    register_global_schema_fields, register_global_schema_info, render, render_data,
    render_data_format, render_detailed_error, render_detailed_error_format, render_error,
    render_error_format, render_format, render_human, render_human_with_registry,
    render_human_with_registry_for_schema, render_human_with_registry_selected,
    render_human_with_view, render_json, render_toon, write_render,
};
pub use search::{SearchDocument, SearchResult};
pub use tier::Tier;
pub use tree::{TreeNode, build_tree_from_clap, build_tree_from_parts, render_tree_human};