Struct CliConfig 

pub struct CliConfig {

    pub name: String,
    pub short: String,
    pub long: Option<String>,
    pub build: BuildInfo,
    pub app_id: String,
    pub default_auth_provider: Option<String>,
    pub modules: Vec<Module>,
    pub commands: Vec<RuntimeCommandSpec>,
    pub auth_extra_commands: Vec<RuntimeCommandSpec>,
    pub guides: Vec<GuideEntry>,
    pub views: Vec<HumanViewDef>,
    pub auth_providers: Vec<Arc<dyn AuthProvider>>,
    pub user_agent: Option<String>,
    pub redacted_debug_headers: Vec<String>,
    pub authz: Option<Arc<dyn Authorizer>>,
    pub auditor: Option<Arc<dyn Auditor>>,
    pub activity: Option<Arc<dyn ActivityEmitter>>,
    pub init_deps: Option<InitDeps>,
    pub register_flags: Option<RegisterFlags>,
    pub apply_flags: Option<ApplyFlags>,
    pub pre_run: Option<PreRun>,
    pub meta_resolver: Option<ResolveMeta>,
    pub on_shutdown: Option<OnShutdown>,
    pub extra_search_docs: Option<ExtraSearchDocs>,
    pub root_next_actions: Option<RootNextActions>,
    pub admin_category: Option<String>,
    pub config_commands: bool,
    pub argv0_routes: BTreeMap<String, Argv0Route>,
    pub environments: Option<Arc<Environments>>,
    pub startup_args: Option<Vec<OsString>>,
    pub min_stage: Stage,
    pub feature_overrides: BTreeMap<String, Stage>,
    pub auto_interactive: bool,
}

Declarative configuration for a CLI application.

Use CliConfig::new for the common path and chain with_* methods for modules, auth providers, guides, views, and lifecycle hooks. Direct struct literals remain available for advanced setup and tests.

Fields

name: String

Root command name shown in usage output.

short: String

One-line root command description.

long: Option<String>

Optional longer root command description. Defaults to short.

build: BuildInfo

Version/build metadata for --version.

app_id: String

Application id stored in middleware and output metadata.

default_auth_provider: Option<String>

Fallback auth provider when a command does not select one explicitly.

modules: Vec<Module>

Domain modules mounted under the root command.

commands: Vec<RuntimeCommandSpec>

Additional top-level runtime commands.

auth_extra_commands: Vec<RuntimeCommandSpec>

Additional commands mounted as siblings of the built-in auth group’s login/status/logout (e.g. auth scopes). Populate via CliConfig::with_auth_extra_commands; folded in internally after the built-in group is built, so the built-ins are never lost or overwritten.

guides: Vec<GuideEntry>

Global guide entries mounted under guide.

views: Vec<HumanViewDef>

Global human output views.

auth_providers: Vec<Arc<dyn AuthProvider>>

Providers registered before command execution starts.

user_agent: Option<String>

Optional override for the process-wide outbound User-Agent. When unset, the engine derives name/version from this config. See CliConfig::user_agent_string.

redacted_debug_headers: Vec<String>

Extra HTTP header names to redact in --debug transport output, on top of the built-in sensitive set (authorization, proxy-authorization, cookie, set-cookie, x-api-key). Set CLI-specific secret-bearing headers here — e.g. a custom API-key header an auth injector adds. Populate via CliConfig::with_redacted_debug_headers.

authz: Option<Arc<dyn Authorizer>>

Optional authorization gatekeeper injected into middleware.

auditor: Option<Arc<dyn Auditor>>

Optional audit recorder injected into middleware.

activity: Option<Arc<dyn ActivityEmitter>>

Optional activity event sink injected into middleware.

init_deps: Option<InitDeps>

Optional late initializer for runtime dependencies.

register_flags: Option<RegisterFlags>

Optional hook for adding application-specific global flags.

apply_flags: Option<ApplyFlags>

Optional hook for applying parsed application-specific flags.

pre_run: Option<PreRun>

Optional hook run before executable commands and built-ins.

meta_resolver: Option<ResolveMeta>

Optional hook for global command metadata adjustments.

on_shutdown: Option<OnShutdown>

Optional hook called after each run.

extra_search_docs: Option<ExtraSearchDocs>

Optional root-scope search document provider.

root_next_actions: Option<RootNextActions>

Optional provider for the bare-root suggested next actions.

admin_category: Option<String>

Name of the admin help category. The engine files its built-in auth command under this heading; apps should use the same name for their own admin modules (e.g. godaddy’s env). When unset, defaults to "Admin"; set it to match a consumer’s own taxonomy (e.g. gdx’s “Administration”).

config_commands: bool

Whether to mount the built-in config command group (config get/set/path/list). Off by default to avoid colliding with a consumer’s own config noun. Enable via CliConfig::with_config_commands.

argv0_routes: BTreeMap<String, Argv0Route>

Alternative argv[0] names this binary may be invoked as, mapped to the behavior the engine should take (busybox/git-style multi-call dispatch).

Keyed by the bare alternative name (no path, no extension). Empty by default, in which case argv0 dispatch is inert and behavior is identical to a binary that never opted in. Populate via CliConfig::with_argv0_alias and CliConfig::with_argv0_personality.

environments: Option<Arc<Environments>>

Optional first-class environment system.

Registered via CliConfig::with_environments. When set, the engine registers a global --env flag, seeds the active environment into middleware, and exposes it to handlers through CommandContext::environment.

startup_args: Option<Vec<OsString>>

Explicit argv override for Cli::new’s startup --env prescan, mainly used to make tests hermetic.

min_stage: Stage

Minimum feature stage required for a flagged command, group, or module to remain mounted.

Defaults to Stage::Ga via Stage’s own Default, which combined with an empty feature_overrides is the zero-config behavior: nothing is gated unless a command/group/module opts in with .with_feature_flag(...), and even then it stays visible until this is lowered. Lower it (e.g. to Stage::Beta or Stage::Experimental) to opt a build or environment into pre-release commands. Set via CliConfig::with_min_stage.

feature_overrides: BTreeMap<String, Stage>

Per-key stage overrides that substitute a forced stage for a flag key’s own declared stage before comparing against min_stage.

Empty by default. Populate via CliConfig::with_feature_override to force one named flag to a specific effective stage — e.g. forcing a single flag to Stage::Ga to turn it on for internal testing without lowering min_stage for every other flagged command, or forcing it to Stage::Experimental to disable it even under a permissive min_stage. See FlagPolicy::visible for the exact comparison.

auto_interactive: bool

Whether to auto-enable interactive mode when a TTY is detected.

When false (the default), commands only run interactively if the user passes --interactive explicitly. When true, the engine auto-detects a TTY (stdin + stderr) and defaults to interactive mode — meaning missing required arguments will be prompted for instead of erroring.

Set via CliConfig::with_auto_interactive. Start with false for backwards compatibility; flip to true once the CLI’s commands have been tested under interactive prompting.

Implementations

impl CliConfig

pub fn new( name: impl Into<String>, short: impl Into<String>, app_id: impl Into<String>, ) -> Self

Creates the minimum useful CLI configuration.

pub fn with_long(self, long: impl Into<String>) -> Self

Sets root long help text.

pub fn with_build(self, build: BuildInfo) -> Self

Sets build metadata used by --version.

pub fn with_default_auth_provider(self, provider: impl Into<String>) -> Self

Sets the fallback auth provider for commands that do not name one.

pub fn with_environments(self, environments: Arc<Environments>) -> Self

Registers a first-class environment system.

When set, Cli::new registers a global --env flag, seeds the active environment into middleware (explicit --env > persisted active > configured default), and exposes the resolved environment to handlers via CommandContext::environment.

The Environments is stored as-is, so the consumer is responsible for configuring it before wrapping it in an Arc:

• Call Environments::with_app_id with the same app_id passed to CliConfig::new, so the config file and active-environment persistence resolve to the application’s config directory. (An empty app_id makes Environments::config_file_path return None, silently disabling the environments.toml file layer.)
• Call Environments::with_config_file(true) if the application loads a user-editable environments.toml.
• Share the same Arc with any PkceAuthProvider::with_environments (available with the pkce-auth feature): the provider’s OAuth file layer and active-environment persistence must resolve against the identical, app_id-stamped instance the engine sees, or a file-defined environment (or a file override of a compiled environment’s client_id) will be visible to env info yet invisible to the actual OAuth login.

pub fn with_startup_args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<OsString>,

Overrides the argv Cli::new prescans for --env before pruning the command tree, instead of the real process argv.

Only meaningful alongside with_environments — otherwise Cli::new never registers --env or does the prescan at all, so this is silently unused. Element 0 is treated as the program name and skipped, the same convention Cli::run/Cli::execute_from use for their own args parameter.

This matters beyond tests: tree pruning is decided once, at Cli::new time, from either this override or real process argv — never from the args a later Cli::run/Cli::execute_from call receives. Any caller that builds the Cli once and later runs it with a synthetic argv (e.g. a wrapper binary invoking it programmatically, or a fixed argument list unrelated to std::env::args_os()) should pass the same --env here too, or an environment named only in the later call’s argv won’t have been consulted for pruning, and a flagged command that environment would reveal (or hide) can disagree with what actually dispatches. A test that configures with_environments should call this (even with an empty iterator) to keep construction hermetic; without it, Cli::new reads whatever real argv the test binary itself was invoked with.

pub fn with_min_stage(self, stage: Stage) -> Self

Sets the minimum feature stage required for a flagged command, group, or module to remain mounted.

See min_stage for the default and FlagPolicy for how it combines with feature_overrides during command-tree pruning.

pub fn with_auto_interactive(self, enabled: bool) -> Self

Enables auto-interactive mode: when a TTY is detected, the CLI defaults to interactive prompting for missing required arguments.

Off by default for backwards compatibility. Enable once commands have been tested under interactive prompting. --interactive still works as an explicit override regardless of this setting.

pub fn with_feature_override(self, key: impl Into<String>, stage: Stage) -> Self

Adds (or replaces) a per-key feature-flag stage override.

See feature_overrides for how the override participates in the FlagPolicy::visible comparison.

pub fn with_user_agent(self, user_agent: impl Into<String>) -> Self

Overrides the outbound User-Agent string for all HTTP traffic.

When unset, the engine derives name/version from this config (see CliConfig::user_agent_string). Set this when the upstream APIs expect a specific product token. The resolved value is applied process-wide on execution via crate::transport::set_default_user_agent, so it reaches both command HttpClients and the engine’s own OAuth token requests.

pub fn with_redacted_debug_headers( self, names: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Adds HTTP header names to redact in --debug transport output, on top of the built-in sensitive set.

Use this for CLI-specific secret-bearing headers that are not standard auth headers — for example a custom API-key header that an AuthInjector sets. Matching is case-insensitive and additive: the built-in set is always redacted. Calls accumulate. Names are trimmed and empty entries are dropped, so a mistyped value with stray whitespace cannot silently disable redaction.

pub fn user_agent_string(&self) -> String

Returns the outbound User-Agent string the CLI presents on HTTP requests.

Resolution order:

1. an explicit with_user_agent override;
2. otherwise name/version (for example gdx/1.2.3);
3. otherwise just name when no build version is set.

pub fn with_module(self, module: Module) -> Self

Adds one domain module.

Reserved group names

The top-level group names help, guide, tree, and completion are reserved by the engine. A module whose root group uses one of these names will be rejected at registration time (logged as a warning) so the engine’s own built-in always takes precedence in the command tree.

pub fn with_modules(self, modules: impl IntoIterator<Item = Module>) -> Self

Adds several domain modules.

See with_module for the list of reserved group names.

pub fn with_command(self, command: RuntimeCommandSpec) -> Self

Adds a top-level runtime command outside a module.

pub fn with_auth_extra_commands( self, commands: impl IntoIterator<Item = RuntimeCommandSpec>, ) -> Self

Adds commands mounted as siblings of the built-in auth group’s login/status/logout.

Use this to extend auth with consumer-specific subcommands (e.g. auth scopes) without losing or duplicating the built-ins — unlike pre-registering an auth Module, which either drops the built-ins entirely or has them silently overwrite any extra command added this way, these are folded in additively after building the built-in group.

pub fn with_guide(self, guide: GuideEntry) -> Self

Adds one global guide.

pub fn with_guides(self, guides: impl IntoIterator<Item = GuideEntry>) -> Self

Adds several global guides.

pub fn with_view(self, view: HumanViewDef) -> Self

Adds one global human view.

pub fn with_auth_provider(self, provider: Arc<dyn AuthProvider>) -> Self

Registers one auth provider.

pub fn with_authz(self, authz: Arc<dyn Authorizer>) -> Self

Sets the authorization gatekeeper.

pub fn with_auditor(self, auditor: Arc<dyn Auditor>) -> Self

Sets the audit recorder.

pub fn with_activity(self, activity: Arc<dyn ActivityEmitter>) -> Self

Sets the activity event sink.

pub fn with_init_deps(self, init_deps: InitDeps) -> Self

Sets the late dependency initializer.

pub fn with_register_flags(self, register_flags: RegisterFlags) -> Self

Sets the application-specific global flag registration hook.

pub fn with_apply_flags(self, apply_flags: ApplyFlags) -> Self

Sets the application-specific parsed flag application hook.

pub fn with_pre_run(self, pre_run: PreRun) -> Self

Sets the pre-run hook.

pub fn with_meta_resolver(self, meta_resolver: ResolveMeta) -> Self

Sets the command metadata resolver hook.

pub fn with_on_shutdown(self, on_shutdown: OnShutdown) -> Self

Sets the shutdown hook.

pub fn with_extra_search_docs(self, extra_search_docs: ExtraSearchDocs) -> Self

Sets the provider for additional root-scope search documents.

pub fn with_root_next_actions(self, root_next_actions: RootNextActions) -> Self

Sets the provider for the bare-root suggested next actions.

pub fn with_admin_category(self, category: impl Into<String>) -> Self

Sets the name of the admin help category. The engine files the built-in auth command there; apps should use the same name for their own admin modules (e.g. godaddy’s env). Optional: defaults to "Admin".

pub fn with_config_commands(self) -> Self

Mounts the built-in config command group (config get/set/path/ list) for reading and writing the per-application config file.

Off by default so it never collides with a consumer’s own config noun; the group is filed under the admin help category when enabled.

pub fn with_argv0_alias( self, name: impl Into<String>, command_path: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Registers an alternative argv[0] name that acts as a shortcut to a command path on this same CLI.

When the binary is invoked under name (via symlink, hardlink, copy, or the hidden argv0 command), the engine behaves as if the user had typed command_path followed by the real argument tail, routed through the normal command tree. For example:

use cli_engine::CliConfig;

// Invoking the binary as `pl --team platform` runs `project list --team platform`.
let config = CliConfig::new("my-cli", "Team CLI", "my-cli")
    .with_argv0_alias("pl", ["project", "list"]);

name must be a simple token: non-empty and composed only of ASCII letters, digits, -, or _ (no dots, spaces, path separators, or shell metacharacters), and it must differ from the CLI’s own name. These are debug-asserted. The restriction keeps the name usable as a link/shim filename and an argv[0] basename (which is matched with its extension stripped, so a dot would break matching).

pub fn with_argv0_personality( self, name: impl Into<String>, build: impl Fn() -> CliConfig + Send + Sync + 'static, ) -> Self

Registers an alternative argv[0] name that runs an entirely separate CLI application.

When the binary is invoked under name, the engine builds a fresh CliConfig from build and runs that application instead — its own root name, commands, flags, and auth. The closure runs lazily, only when the route is dispatched, so unused personalities cost nothing. The personality presents the name from its own CliConfig in help and usage output.

use cli_engine::CliConfig;

let config = CliConfig::new("my-cli", "Team CLI", "my-cli")
    .with_argv0_personality("legacy-tool", || {
        CliConfig::new("legacy-tool", "Legacy compatibility shim", "legacy-tool")
    });

name follows the same contract as CliConfig::with_argv0_alias: a simple [A-Za-z0-9_-] token, differing from the CLI’s own name (debug-asserted).

Trait Implementations

impl Clone for CliConfig

fn clone(&self) -> CliConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CliConfig

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CliConfig

fn default() -> CliConfig

Returns the “default value” for a type.