cli_engine/
lib.rs

1//! Build consistent, domain-oriented CLIs with a small amount of Rust.
2//!
3//! `cli_engine` provides the shared pieces that most CLI tools need:
4//! command registration, authentication provider routing, authorization hooks,
5//! audit and activity hooks, structured output, output schemas, guides, search,
6//! command tree rendering, busybox-style multi-call (`argv[0]`) dispatch, and
7//! authenticated HTTP transport helpers.
8//!
9//! The intended shape is:
10//!
11//! 1. Each team owns one or more [`Module`] values.
12//! 2. A module registers noun-based [`GroupSpec`] groups.
13//! 3. Groups contain verb-like [`CommandSpec`] leaf commands.
14//! 4. Command handlers stay focused on domain behavior while [`Middleware`]
15//!    handles authentication, dry-run, audit, activity, output, and errors.
16//!
17//! # Quick Start
18//!
19//! ```no_run
20//! use clap::Arg;
21//! use cli_engine::{
22//!     BuildInfo, Cli, CliConfig, CommandSpec, GroupSpec, Module,
23//!     RuntimeCommandSpec, RuntimeGroupSpec,
24//! };
25//! use serde_json::json;
26//!
27//! #[tokio::main]
28//! async fn main() -> std::process::ExitCode {
29//!     let list = RuntimeCommandSpec::new(
30//!         CommandSpec::new("list", "List projects")
31//!             .with_system("projects-api")
32//!             .with_default_fields("id,name,status")
33//!             .with_arg(Arg::new("team").long("team").required(true))
34//!             .no_auth(true),
35//!         async |_credential, args| {
36//!             let team = args
37//!                 .get("team")
38//!                 .and_then(|value| value.as_str())
39//!                 .unwrap_or_default();
40//!             Ok(cli_engine::CommandResult::new(json!([
41//!                 { "id": "p1", "name": "Portal", "status": "active", "team": team }
42//!             ])))
43//!         },
44//!     );
45//!
46//!     let module = Module::new("Platform Systems", move |_context| {
47//!         RuntimeGroupSpec::new(GroupSpec::new("project", "Manage projects"))
48//!             .with_command(list.clone())
49//!     });
50//!
51//!     let cli = Cli::new(
52//!         CliConfig::new("example", "Example cli-engine application", "example")
53//!             .with_build(BuildInfo::new(env!("CARGO_PKG_VERSION")))
54//!             .with_module(module),
55//!     );
56//!
57//!     cli.execute().await
58//! }
59//! ```
60//!
61//! Command paths are colon-separated (`project:list`) for policy, audit,
62//! schema, and authorization compatibility with existing CLI ecosystems.
63
64/// Auth provider traits, dispatch, and built-in provider commands.
65pub mod auth;
66/// CLI application assembly and execution.
67pub mod cli;
68/// Command and command-group specifications.
69pub mod command;
70/// Engine config file and credential-storage selection.
71pub mod config;
72/// Built-in `config` command group.
73pub mod config_commands;
74/// Built-in `env` command group (private; only `cli.rs` consumes it).
75mod env_commands;
76/// First-class environment definitions and layered resolution.
77pub mod environments;
78/// Shared error type and error traits.
79pub mod error;
80/// Global framework flags and flag-extraction helpers.
81pub mod flags;
82/// Filesystem and path utilities (base dir, path-component safety, atomic write).
83pub mod fs;
84/// Embedded or file-backed guide parsing.
85pub mod guide;
86/// Cross-cutting command execution middleware.
87pub mod middleware;
88/// Domain module registration helpers.
89pub mod module;
90/// Structured output envelopes, renderers, schemas, and field projection.
91pub mod output;
92/// Search indexing for commands, guides, and extra documents.
93pub mod search;
94/// Command risk tiers used by authentication, authorization, and dry-run.
95pub mod tier;
96/// HTTP transport client and auth injectors.
97pub mod transport;
98/// Command tree data model and human rendering.
99pub mod tree;
100
101#[cfg(feature = "pkce-auth")]
102pub use auth::storage::{AutoStorage, KeyringStorage};
103pub use auth::storage::{
104    CredentialKey, CredentialStorage, FileStorage, default_storage, storage_for,
105};
106pub use auth::{
107    AuthLoginResult, AuthProvider, AuthStatusEntry, CACHE_TTL, Credential, CredentialRequest,
108    Dispatcher, SingleProvider, StatusEntry, auth_command_group, login_and_build,
109    login_and_build_with_scopes, logout_result, status_result, to_status_entry,
110};
111pub use cli::{
112    ApplyFlags, Argv0LinkMethod, Argv0Route, BuildInfo, Cli, CliConfig, CliRunOutput,
113    ExtraSearchDocs, InitDeps, ModuleHelpEntry, OnShutdown, PreRun, RegisterFlags, ResolveMeta,
114    RootNextActions, build_root_long,
115};
116pub use command::{
117    CommandContext, CommandFuture, CommandHandler, CommandResult, CommandResultMetadata,
118    CommandSpec, GroupSpec, RuntimeCommandSpec, RuntimeGroupSpec, StreamSender,
119    StreamingCommandFuture, StreamingCommandHandler, command_args_from_matches,
120    command_path_from_matches, command_path_from_parts, leaf_matches,
121};
122pub use config::{
123    ConfigFile, CredentialStore, CredentialsConfig, EngineConfig, ParseCredentialStoreError,
124    credential_store_env_var, resolve_credential_store, resolve_credential_store_with,
125};
126pub use config_commands::config_command_group;
127pub use environments::{Environment, EnvironmentDef, Environments, OAuthConfig};
128pub use error::{
129    CliCoreError, DetailedError, ExitCoder, Result, exit_code_for_error, exit_code_for_exit_coder,
130};
131pub use flags::{
132    GlobalFlags, app_id_env_prefix, debug_component_enabled, default_output_format,
133    derive_bool_flags, derive_value_flags, extract_command_path, extract_output_format,
134    extract_search_query, global_flags_from_matches, has_true_schema_flag, output_env_var,
135    register_global_flags, resolve_default_output_format,
136};
137pub use guide::{GuideEntry, parse_guides, parse_guides_from_markdown};
138pub use middleware::{
139    ActivityEmitter, ActivityEvent, Auditor, AuthRequirement, Authorizer, CommandMeta,
140    CredentialResolver, Middleware, MiddlewareOutput, MiddlewareRequest,
141};
142pub use module::{CommandModule, Module, ModuleContext, ModuleRegister};
143pub use output::{
144    Envelope, ErrorEnvelope, FieldInfo, HumanViewDef, HumanViewFn, HumanViewRegistry,
145    HumanViewRenderer, Metadata, NextAction, NextActionParam, OutputField, OutputFormat,
146    OutputSchema, PaginationMeta, PipelineOpts, RendererFactory, SchemaInfo, SchemaRegistry,
147    TableColumn, apply_pipeline, build_detailed_error_envelope, build_error_envelope, fields_for,
148    fields_from_json_schema, filter_fields, format_help_section, get_global_schema_by_path,
149    global_human_view_registry_snapshot, global_schema_registry_snapshot, is_valid_output_format,
150    json_schema_for, json_schema_info, lookup_global_human_view_columns,
151    lookup_global_human_view_func, parse_fields, register_global_human_view,
152    register_global_human_view_func, register_global_json_schema, register_global_schema,
153    register_global_schema_fields, register_global_schema_info, render, render_data,
154    render_data_format, render_detailed_error, render_detailed_error_format, render_error,
155    render_error_format, render_format, render_human, render_human_with_registry,
156    render_human_with_registry_for_schema, render_human_with_registry_selected,
157    render_human_with_view, render_json, render_toon, write_render,
158};
159pub use search::{SearchDocument, SearchResult};
160pub use tier::Tier;
161pub use tree::{TreeNode, build_tree_from_clap, build_tree_from_parts, render_tree_human};
cli_engine/lib.rs

cli_engine/
lib.rs
