Struct CommandSpec 

pub struct CommandSpec {

    pub name: String,
    pub short: String,
    pub long: Option<String>,
    pub aliases: Vec<String>,
    pub hidden: bool,
    pub system: Option<String>,
    pub default_fields: Option<String>,
    pub auth: AuthRequirement,
    pub auth_provider: Option<String>,
    pub tier: Option<Tier>,
    pub mutates: bool,
    pub auth_metadata: BTreeMap<String, String>,
    pub args: Vec<Arg>,
    pub output_schema: Option<SchemaInfo>,
}

Declarative leaf command metadata and parser arguments.

CommandSpec intentionally keeps command metadata next to the command’s handler. This is the primary copy/paste surface for teams adding commands.

Fields

name: String

Leaf command name.

short: String

One-line command description.

long: Option<String>

Optional long help text.

aliases: Vec<String>

Alternate command names accepted by the parser.

hidden: bool

Whether the command runs but is hidden from help, tree, and search.

system: Option<String>

Backend/system id used in output metadata and generic error envelopes.

default_fields: Option<String>

Default comma-separated field projection.

auth: AuthRequirement

Authentication requirement enforced by the engine for this command.

Defaults to AuthRequirement::Required (fail-closed). Use auth_optional for commands that should run logged out, or no_auth for commands that never authenticate.

auth_provider: Option<String>

Auth provider name for this command.

tier: Option<Tier>

Risk tier used by authentication, authorization, and dry-run.

mutates: bool

Explicit dry-run prompt marker for commands without a tier.

auth_metadata: BTreeMap<String, String>

Provider-specific auth metadata.

args: Vec<Arg>

Command-specific clap arguments.

output_schema: Option<SchemaInfo>

Optional output schema published through --schema and help.

Implementations

impl CommandSpec

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

Creates a command spec with the required name and one-line help.

pub fn from_args<T: Args>( name: impl Into<String>, short: impl Into<String>, ) -> Self

Creates a command spec from a #[derive(clap::Args)] struct.

Extracts the argument definitions from the derive type and populates the spec’s args list. The command name and help text are still required since Args types do not carry those.

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

Sets expanded command help.

pub fn with_alias(self, alias: impl Into<String>) -> Self

Adds one command alias.

pub fn hidden(self, hidden: bool) -> Self

Hides or shows this command in discovery output.

pub fn with_system(self, system: impl Into<String>) -> Self

Sets the backend/system id for output metadata and error attribution.

pub fn with_default_fields(self, default_fields: impl Into<String>) -> Self

Sets the default field projection used when --fields is absent.

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

Selects the auth provider for this command.

pub fn no_auth(self, no_auth: bool) -> Self

Marks the command as no-auth.

no_auth(true) sets AuthRequirement::None: the command never resolves a credential and default-env injection is suppressed. no_auth(false) restores the default AuthRequirement::Required.

pub fn auth(self, requirement: AuthRequirement) -> Self

Sets the command’s AuthRequirement explicitly.

pub fn auth_optional(self) -> Self

Marks authentication as optional (AuthRequirement::Optional).

The engine does not resolve a credential before the handler runs; the handler triggers the auth flow only by calling CredentialResolver::resolve/try_resolve. Use for commands that should still run when the user is logged out.

pub fn with_tier(self, tier: Tier) -> Self

Sets the command risk tier.

pub fn with_auth_metadata( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Adds provider-specific auth metadata.

pub fn with_scopes(self, scopes: &[impl AsRef<str>]) -> Self

Declares the OAuth scopes this command requires.

Sugar over with_auth_metadata with the "scopes" key (whitespace-joined). The scopes surface on CommandMeta::scopes and reach the auth provider via CredentialRequest; a provider that supports scope step-up re-authenticates when the cached token lacks them.

pub fn with_arg(self, arg: Arg) -> Self

Adds a clap argument or option to this command.

pub fn with_flag(self, flag: Arg) -> Self

Adds a clap flag or option to this command.

pub fn with_output_schema<T: OutputSchema>(self) -> Self

Registers a compact framework schema from an OutputSchema type.

pub fn with_json_schema<T: JsonSchema>(self) -> Self

Registers JSON Schema generated from a Rust type with schemars.

pub fn mutates(self, mutates: bool) -> Self

Marks whether the command should short-circuit under --dry-run.

pub fn metadata(&self) -> CommandMeta

Builds middleware metadata from the spec.

pub fn clap_command(&self) -> Command

Builds the clap command for parser registration.

Trait Implementations

impl Clone for CommandSpec

fn clone(&self) -> CommandSpec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CommandSpec

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

Formats the value using the given formatter.

impl Default for CommandSpec

fn default() -> CommandSpec

Returns the “default value” for a type.