Struct CommandContext 

#[non_exhaustive]
pub struct CommandContext {
    pub credential: CredentialResolver,
    pub args: ValueMap,
    pub user_args: ValueMap,
    pub command_path: String,
    pub middleware: Middleware,
    pub raw_matches: Arc<ArgMatches>,
}

Runtime context passed to advanced command handlers.

Most commands can use RuntimeCommandSpec::new and receive just the credential and effective args. Use this context when a command needs the colon path, user-supplied args, or a snapshot of middleware state.

This struct is constructed by the framework during command dispatch. Consumer code receives it in handler closures and should not construct it directly.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

credential: CredentialResolver

Lazy credential resolver.

args: ValueMap

Effective arguments, including defaults and framework-injected values.

user_args: ValueMap

Arguments explicitly supplied by the user.

command_path: String

Colon-separated command path such as project:list.

middleware: Middleware

Middleware snapshot for this invocation.

raw_matches: Arc<ArgMatches>

Raw clap matches for typed argument deserialization via derive.

Implementations

impl CommandContext

pub fn config(&self) -> &ConfigFile

Returns the per-application config file as loaded at startup.

Read a consumer-owned section with ConfigFile::section, for example ctx.config().section::<DeployConfig>("deploy")?. Engine-reserved settings are available via ConfigFile::engine.

Snapshot semantics: this is the config loaded once when crate::cli::Cli::new was called. Changes made by config set during the same process invocation (e.g. from a previous Cli::run) are not reflected here; restart the CLI (a new Cli::new) to pick them up. For a one-shot CLI process this is always the current on-disk state.

pub fn dry_run(&self) -> bool

Returns whether --dry-run was passed for this invocation.

Only meaningful for commands that opted in via CommandSpec::handles_dry_run — other mutating commands never reach their handler under --dry-run at all, so there’s nothing to branch on. An opted-in handler should run its real validation unconditionally and use this only to skip the actual mutating I/O, returning a preview result tagged with CommandResult::with_dry_run.

pub fn is_interactive(&self) -> bool

Returns the resolved interactivity mode for this invocation.

Use this to decide whether to prompt for missing inputs, show progress spinners, or offer interactive choices. When false, the command should fail with a descriptive error if required inputs are missing.

pub fn interactivity_mode(&self) -> InteractivityMode

Returns the resolved InteractivityMode.

Equivalent to is_interactive but returns the enum for pattern matching.

pub fn environment(&self) -> Result<EnvSource>

Resolves the active environment’s merged TOML table for this invocation, as an EnvSource.

The active environment name is self.middleware.env, seeded at startup from the persisted active environment or configured default and overridden per invocation by the global --env flag. Resolution merges the compiled-in table and the environments.toml file layer (file wins). Use this for generic introspection (see the built-in env info command); for a typed section with the app-scoped environment-variable override tier applied, use environment_config instead.

Blocking

When the environments.toml file layer is enabled, this performs synchronous filesystem I/O via Environments::source. Call it once per invocation and reuse the result rather than calling it repeatedly inside an async handler on a latency-sensitive path.

Errors

Returns an error if no environment system was registered via CliConfig::with_environments or if the active name does not resolve to a known environment.

pub fn environment_config<T: EnvConfig>(&self) -> Result<T, EnvConfigError>

Resolves the active environment into a typed EnvConfig section, with the app-scoped environment-variable override tier applied (see Environments::resolve).

Blocking

See environment.

Errors

Returns an error under the same conditions as environment, or when a field’s present value fails to convert to its type, or a required field has no value in any source and no default.

pub fn typed_args<T: FromArgMatches>(&self) -> Result<T>

Deserializes the raw argument matches into a typed args struct.

Use this with #[derive(clap::Args)] structs to get type-safe access to command arguments instead of working with the ValueMap directly.

Errors

Returns an error if the matches cannot be deserialized into T.

pub async fn credential(&self) -> Result<Credential>

Resolves the credential for this command, triggering the auth flow on first use and memoizing the result.

Convenience wrapper over self.credential.resolve().

Errors

Returns an error when the command is marked no_auth, or when the auth provider fails to produce a credential.

pub async fn try_credential(&self) -> Result<Option<Credential>>

Resolves the credential when one is available, returning Ok(None) for no-auth commands.

Convenience wrapper over self.credential.try_resolve().

Errors

Propagates the auth provider error when resolution is attempted and fails.

pub async fn credential_with_scopes( &self, extra: &[String], ) -> Result<Credential>

Resolves a credential that additionally covers extra scopes, on top of the command’s declared scopes.

Use this when the required scopes are only known at runtime (for example a generic API caller that derives scopes from the target endpoint). A scope-aware auth provider re-authenticates when the cached token does not already cover the requested set.

Convenience wrapper over self.credential.resolve_with_scopes().

If the handler also issues HTTP requests through the transport bearer injector, call this before the first request: the injector resolves and caches a scope-unaware token, so stepping up afterwards would not affect requests it already authorized. See CredentialResolver::resolve_with_scopes for the full ordering note.

Errors

Returns an error when the command is marked no_auth, or when the auth provider fails to produce a credential.

Trait Implementations

impl Clone for CommandContext

fn clone(&self) -> CommandContext

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CommandContext

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

Formats the value using the given formatter.