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

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

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 KdlNode

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.