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 guides: Vec<GuideEntry>,
    pub views: Vec<HumanViewDef>,
    pub auth_providers: Vec<Arc<dyn AuthProvider>>,
    pub user_agent: Option<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>>,
}

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.

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.

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.

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_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 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.

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

Adds several domain modules.

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

Adds a top-level runtime command outside a module.

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.