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 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 argv0_routes: BTreeMap<String, Argv0Route>,
}

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.

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”).

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.

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