Struct SpecCommand 

pub struct SpecCommand {

    pub full_cmd: Vec<String>,
    pub usage: String,
    pub subcommands: IndexMap<String, SpecCommand>,
    pub args: Vec<SpecArg>,
    pub flags: Vec<SpecFlag>,
    pub mounts: Vec<SpecMount>,
    pub groups: Vec<SpecGroup>,
    pub deprecated: Option<String>,
    pub deprecated_warn_at: Option<String>,
    pub deprecated_remove_at: Option<String>,
    pub effect: Option<SpecCommandEffect>,
    pub unknown_flags: Option<UnknownFlags>,
    pub hide: bool,
    pub help_heading: Option<String>,
    pub surface: Option<String>,
    pub available_if: Vec<String>,
    pub display_order: Option<usize>,
    pub mounted: bool,
    pub flags_from_mount: bool,
    pub subcommand_required: bool,
    pub subcommand_help_heading: Option<String>,
    pub subcommand_value_name: Option<String>,
    pub next_line_help: bool,
    pub flatten_help: bool,
    pub term_width: Option<usize>,
    pub max_term_width: Option<usize>,
    pub external_subcommand: bool,
    pub arg_required_else_help: bool,
    pub disable_help_flag: bool,
    pub disable_help_subcommand: bool,
    pub disable_version_flag: bool,
    pub dont_delimit_trailing_values: bool,
    pub args_override_self: bool,
    pub subcommand_negates_reqs: bool,
    pub args_conflicts_with_subcommands: bool,
    pub subcommand_precedence_over_arg: bool,
    pub allow_missing_positional: bool,
    pub restart_token: Option<String>,
    pub help: Option<String>,
    pub help_long: Option<String>,
    pub help_md: Option<String>,
    pub name: String,
    pub aliases: Vec<String>,
    pub hidden_aliases: Vec<String>,
    pub before_help: Option<String>,
    pub before_help_long: Option<String>,
    pub before_help_md: Option<String>,
    pub after_help: Option<String>,
    pub after_help_long: Option<String>,
    pub after_help_md: Option<String>,
    pub examples: Vec<SpecExample>,
    pub headings: Vec<SpecHeading>,
    pub outputs: Vec<SpecOutput>,
    pub select: Option<String>,
    pub exit_codes: Vec<SpecExitCode>,
    pub complete: IndexMap<String, SpecComplete>,
    /* private fields */
}

A CLI command or subcommand specification.

Commands define the structure of a CLI, including their flags, arguments, and nested subcommands. The root command represents the main CLI entry point.

Example

use usage::{SpecCommand, SpecFlag, SpecArg};

let cmd = SpecCommand::builder()
    .name("install")
    .help("Install a package")
    .alias("i")
    .flag(SpecFlag::builder().short('f').long("force").build())
    .arg(SpecArg::builder().name("package").required(true).build())
    .build();

Fields

full_cmd: Vec<String>

Full command path from root (e.g., [“git”, “remote”, “add”])

usage: String

Generated usage string

subcommands: IndexMap<String, SpecCommand>

Nested subcommands indexed by name

args: Vec<SpecArg>

Positional arguments for this command

flags: Vec<SpecFlag>

Flags/options for this command

mounts: Vec<SpecMount>

Mounted external specs

groups: Vec<SpecGroup>

Sets of flags that relate to one another as a set.

Pairwise conflicts can say everything a plain group says and cannot say required: “one of these is needed” is a statement about the set.

deprecated: Option<String>

Deprecation message if this command is deprecated

deprecated_warn_at: Option<String>

Version at which consumers should begin warning about this command.

deprecated_remove_at: Option<String>

Version at which consumers expect this command to be removed.

effect: Option<SpecCommandEffect>

What running this command does to the world: read, write or destructive. Not inherited by subcommands.

unknown_flags: Option<UnknownFlags>

What to do here with a flag-like token that names no declared flag.

Unset means “whatever encloses this command decided” — the nearest command above that set one, or failing that the spec, or failing that UnknownFlags::Value. Unlike SpecCommandEffect this is inherited, because it describes how a command line is read rather than what a command does, and a CLI that forwards options generally forwards them everywhere.

hide: bool

Whether to hide this command from help output

help_heading: Option<String>

Help section this command appears under in its parent’s command list.

surface: Option<String>

Named audience or contract surface this command belongs to. Metadata only.

available_if: Vec<String>

Descriptive conditions under which this command is available.

display_order: Option<usize>

Explicit placement within its parent’s command section.

mounted: bool

True when this command came from a SpecMount, i.e. it describes another program’s CLI that was merged in at parse time.

The flags of the commands above a mounted command belong to the mounting CLI, not to the mounted program, so they are not offered in completions once a mounted command has been reached. They stay recognized by the parser, since they may legitimately appear before the mounted command on the command line.

Runtime-only: it is derived from mount nodes and is not part of the spec syntax.

flags_from_mount: bool

True when a SpecMount brought flags of its own onto this command. A mounted spec’s root flags are merged into the command the mount sits on, replacing that command’s flags (see SpecCommand::merge), so when this is set every flag here describes the mounted program and is offered inside the mounted commands accordingly.

Runtime-only, like SpecCommand::mounted.

subcommand_required: bool

Whether a subcommand must be provided

subcommand_help_heading: Option<String>

Heading used for this command’s subcommand section.

subcommand_value_name: Option<String>

Placeholder used for subcommands in the synopsis.

next_line_help: bool

Put each argument, flag, and subcommand description on the following line.

flatten_help: bool

Expand each visible subcommand’s summary and arguments into this command’s help page.

term_width: Option<usize>

Fixed help width. Zero disables wrapping.

max_term_width: Option<usize>

Maximum detected terminal width when term_width is unset. Zero disables the cap.

external_subcommand: bool

Whether an unmatched word is forwarded as an external command plus the rest of argv.

clap’s allow_external_subcommands / #[command(external_subcommand)]. Known subcommands still win; a default_subcommand still catches first. Once the unmatched word is taken, remaining tokens — including --help — are not parsed as this command’s flags.

arg_required_else_help: bool

Whether a bare invocation of this command shows its help.

disable_help_flag: bool

disable_help_subcommand: bool

disable_version_flag: bool

dont_delimit_trailing_values: bool

Whether delimiter splitting is disabled after -- or for an automatic trailing arg.

args_override_self: bool

Whether a later occurrence of a single-valued argument replaces the earlier one. Permissive by default; set false to report duplicates.

subcommand_negates_reqs: bool

Whether selecting a subcommand satisfies this command’s required arguments.

args_conflicts_with_subcommands: bool

Whether binding an argument prevents selecting a later subcommand.

subcommand_precedence_over_arg: bool

allow_missing_positional: bool

Allow required positionals after optional positionals to claim the remaining words.

restart_token: Option<String>

Token that resets argument parsing, allowing multiple command invocations. e.g., mise run lint ::: test ::: check with restart_token=“:::”

help: Option<String>

Short help text shown in command listings

help_long: Option<String>

Extended help text shown with –help

help_md: Option<String>

Markdown-formatted help text

name: String

Command name (e.g., “install”)

aliases: Vec<String>

Alternative names for this command

hidden_aliases: Vec<String>

Hidden alternative names (not shown in help)

before_help: Option<String>

Text displayed before the help content

before_help_long: Option<String>

Extended text displayed before help content

before_help_md: Option<String>

Markdown text displayed before help content

after_help: Option<String>

Text displayed after the help content

after_help_long: Option<String>

Extended text displayed after help content

after_help_md: Option<String>

Markdown text displayed after help content

examples: Vec<SpecExample>

Usage examples for this command

headings: Vec<SpecHeading>

Prose introducing this command’s help sections, by heading title.

outputs: Vec<SpecOutput>

What this command writes, and how a consumer should read it.

Folded with the spec’s CLI-wide outputs on read rather than here — see effective_outputs.

select: Option<String>

The flag whose value picks among Self::outputs, e.g. --format.

The other spelling — a boolean flag picking one output — lives on the output itself, because that is where it is scoped.

exit_codes: Vec<SpecExitCode>

What this command’s exit statuses mean.

complete: IndexMap<String, SpecComplete>

Custom completers for arguments

Implementations

impl SpecCommand

pub fn builder() -> SpecCommandBuilder

Create a new builder for SpecCommand

pub fn usage(&self) -> String

pub fn all_subcommands(&self) -> Vec<&SpecCommand>

pub fn find_subcommand(&self, name: &str) -> Option<&SpecCommand>

impl SpecCommand

pub fn effect_of<'a>( &self, flags: impl IntoIterator<Item = &'a SpecFlag>, args: impl IntoIterator<Item = &'a SpecArg>, ) -> Option<SpecCommandEffect>

The effect of running this command with flags and args supplied, as the maximum of the command’s own effect and theirs.

A flag contributes both its own effect and that of its value argument, so --output <file> can declare the danger on either.

Pass only what the command line actually supplied. Feeding in values that came from defaults or the environment is safe — the result can only be too high, never too low — but it will over-report.

Returns None when nothing involved declares an effect, which means “unknown” — consumers should treat that as “ask”, not as safe.

pub fn max_effect(&self) -> Option<SpecCommandEffect>

The worst effect any invocation of this command could have: its own effect combined with every flag and argument it declares.

This is the safe fallback for a consumer that has a spec but not a parsed command line.

Trait Implementations

impl Clone for SpecCommand

fn clone(&self) -> SpecCommand

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SpecCommand

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

Formats the value using the given formatter.

impl Default for SpecCommand

fn default() -> Self

Returns the “default value” for a type.

impl From<SpecCommand> for Spec

A spec wrapping one command, for command trees built in Rust rather than parsed from KDL.

The command’s own name becomes the spec’s name and bin, and its help becomes the spec’s about — the same correspondence usage-dynamic applies in the other direction when it grafts a spec into a host as a command.

fn from(cmd: SpecCommand) -> Self

Converts to this type from the input type.

impl Serialize for SpecCommand

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.