Struct CommandSpec 

#[non_exhaustive]
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 handles_dry_run: bool,
    pub raw_output: bool,
    pub auth_metadata: BTreeMap<String, String>,
    pub args: Vec<Arg>,
    pub arg_groups: Vec<ArgGroup>,
    pub output_schema: Option<SchemaInfo>,
    pub view_columns: Vec<TableColumn>,
    pub view_id: Option<String>,
    pub feature_flag: Option<FeatureFlag>,
    pub pagination: Option<PaginationConfig>,
}

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.

Construct with CommandSpec::new or CommandSpec::from_args, then configure with the with_* builder methods — never as a struct literal. #[non_exhaustive] enforces this so the engine can add fields (as it did for arg_groups) without a breaking release.

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.

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.

handles_dry_run: bool

Opts this command into handler-driven --dry-run.

Set with handles_dry_run. When true, the engine skips its generic --dry-run short-circuit for this command and invokes the handler as normal (still respecting the command’s AuthRequirement). The handler is responsible for running its real validation unconditionally, checking CommandContext::dry_run to skip only the mutating I/O, and tagging its preview result with CommandResult::with_dry_run.

Requires a context-aware handler. Only handlers built with RuntimeCommandSpec::new_with_context, new_streaming, new_typed_with_context, or new_typed_streaming receive a CommandContext and can call CommandContext::dry_run. A handler built with RuntimeCommandSpec::new/new_typed only receives (CredentialResolver, args) — it has no way to observe --dry-run at all, so opting it into handles_dry_run would silently execute the handler’s real side effects under --dry-run instead of skipping them. RuntimeCommandSpec::new/new_typed debug-assert against this misuse; release builds do not, so treat the assert as a development-time safety net, not the actual guarantee — only pair this field with one of the four context-aware constructors above.

raw_output: bool

Forces this command’s successful output to print verbatim to stdout.

auth_metadata: BTreeMap<String, String>

Provider-specific auth metadata.

args: Vec<Arg>

Command-specific clap arguments.

arg_groups: Vec<ArgGroup>

Argument relations (mutually-exclusive or “at least one of” groups).

Set with with_arg_group, or captured automatically by from_args from a #[derive(clap::Args)] struct’s #[group(...)] attribute.

output_schema: Option<SchemaInfo>

Optional output schema published through --schema and help.

view_columns: Vec<TableColumn>

Inline human-output table columns assigned directly to this command.

Set with with_view. When present (and view_id is unset), the engine registers these columns under the command’s own path so human output renders them.

view_id: Option<String>

Id of a shared human view this command should use.

Set with with_view_id. Names a HumanViewDef registered with with_view on the module or CLI, so several commands can share one table. Takes precedence over inline view_columns.

feature_flag: Option<FeatureFlag>

This command’s own feature-flag declaration, if any.

None means the command has no explicit stage declaration of its own, in which case it inherits its effective stage from its nearest ancestor (nested group, then enclosing group, then module — nearest declaration wins), implicitly resolving to Stage::Ga if nothing in the ancestor chain declares a flag either; see Stage’s documentation for why that is its default. Set with with_feature_flag. This field only records the command’s own declaration; cascading resolution against the ancestor chain happens when a Cli mounts the enclosing module or group.

pagination: Option<PaginationConfig>

This command’s opt-in pagination policy, if any.

None (the default) means the command does not paginate: --limit/ --offset are not registered for it, so they neither show up in its --help nor parse on its command line. Set with with_pagination.

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. Also captures any ArgGroups the derive macro registers (via a struct-level #[group(...)] attribute) into arg_groups.

Flatten caveat: clap_derive empties a struct’s own implicit group’s member list when the struct also has a #[command(flatten)] field, so a #[group(required = true)] on such a struct silently enforces nothing. This is debug-asserted against below; treat it as a development-time safety net, not the actual guarantee.

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_view(self, columns: impl Into<Vec<TableColumn>>) -> Self

Assigns an inline human-output table view to this command.

The columns are registered under the command’s own path, so human output renders this table directly. Field selection still applies: --fields (defaulting to default_fields) narrows which of these columns show. Use with_view_id instead to point at a shared view registered with with_view on the module or CLI.

pub fn with_view_id(self, id: impl Into<String>) -> Self

Points this command at a shared human view by id.

The id must match a HumanViewDef registered with with_view on the module or CLI, letting several commands share one table. Takes precedence over inline with_view columns.

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_feature_flag(self, key: impl Into<String>, stage: Stage) -> Self

Declares this command’s own feature flag: the key used for policy overrides and introspection, and the stage at which it becomes visible.

pub fn with_pagination(self, config: PaginationConfig) -> Self

Opts this command into paginated list output.

Registers --limit/--offset for this command only — a command that never calls this does not get those flags at all, in --help or on the command line. When the user passes neither flag, config.default_limit applies instead of the framework’s “pagination disabled” default of unlimited; an explicit --limit above config.max_limit (when set) is rejected before the command runs. See PaginationConfig.

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_arg_group(self, group: ArgGroup) -> Self

Adds an argument relation (an ArgGroup) to this command, e.g. to express “at least one of” or mutually-exclusive relationships between arguments added with with_arg/with_flag.

The group’s ArgGroup::args([...]) ids must reference args already (or later) added to this spec, matching clap’s own requirement that referenced arg ids exist on the built Command. This replaces hand-rolled required_unless_present_any/conflicts_with chains with a single declarative relation.

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 handles_dry_run(self, handles: bool) -> Self

Opts this command into handler-driven --dry-run instead of the engine’s generic short-circuit.

See handles_dry_run (the field) for the contract a handler must follow once it opts in — in particular, only use this with a context-aware handler (RuntimeCommandSpec::new_with_context, new_streaming, new_typed_with_context, or new_typed_streaming); a new/new_typed handler can’t observe --dry-run and would execute its real side effects under it regardless of this flag.

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

Forces this command’s successful output to print verbatim to stdout.

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.