Loading pageā¦
Rust walkthroughs
Loading pageā¦
clap::Arg::short and clap::Arg::short_aliases for command-line argument abbreviation?clap::Arg::short defines the primary short flag for an argument using a single character that appears in help text and is the canonical way to specify that argument. clap::Arg::short_aliases defines additional alternative short flags that are accepted as synonyms but don't appear in the main help outputāthey're hidden conveniences for common misspellings, historical aliases, or migration from other tools. The key difference is visibility: short is documented and user-facing while short_aliases are invisible shortcuts that work identically to the primary flag but won't clutter help output or confuse users about which flag to use.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("myapp")
.arg(
Arg::new("verbose")
.short('v') // Primary short flag
.long("verbose")
.help("Enable verbose output")
)
.get_matches();
if matches.get_flag("verbose") {
println!("Verbose mode enabled");
}
}The short method defines the canonical short form shown in --help.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("myapp")
.arg(
Arg::new("verbose")
.short('v')
.long("verbose")
.short_aliases(['V', 'd']) // Hidden aliases
.help("Enable verbose output")
)
.get_matches_from(vec!["myapp", "-V"]);
if matches.get_flag("verbose") {
println!("Verbose mode enabled via -V alias");
}
}short_aliases accepts additional characters that work identically to the primary.
use clap::{Arg, Command};
fn main() {
let cmd = Command::new("example")
.arg(
Arg::new("force")
.short('f')
.long("force")
.short_aliases(['F']) // Alias won't show in help
.help("Force overwrite")
)
.arg(
Arg::new("quiet")
.short('q')
.long("quiet")
.help("Suppress output")
);
// Help shows only primary short flags
cmd.clone().get_matches_from(vec!["example", "--help"]);
// Output shows:
// -f, --force Force overwrite
// -q, --quiet Suppress output
// Note: -F alias is NOT shown
}Aliases are functional but invisible in documentation.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("tool")
.arg(
Arg::new("output")
.short('o')
.long("output")
.short_aliases(['O']) // Uppercase variant
.help("Output file")
)
.arg(
Arg::new("recursive")
.short('r')
.long("recursive")
.short_aliases(['R']) // Common capital variant
.help("Process directories recursively")
)
.get_matches_from(vec!["tool", "-R", "-O", "file.txt"]);
println!("Recursive: {}", matches.get_flag("recursive"));
println!("Output: {:?}", matches.get_one::<String>("output"));
}Aliases handle case variations that users commonly type.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("modern-tool")
.arg(
Arg::new("verbose")
.short('v')
.long("verbose")
.short_aliases(['d']) // Legacy: -d for "debug/verbose"
.help("Enable verbose output")
)
.arg(
Arg::new("config")
.short('c')
.long("config")
.short_aliases(['C', 'f']) // Multiple compatibility aliases
.help("Configuration file")
)
.get_matches_from(vec!["modern-tool", "-d", "-C", "settings.cfg"]);
// Both aliases work
println!("Verbose: {}", matches.get_flag("verbose"));
println!("Config: {:?}", matches.get_one::<String>("config"));
}Use aliases when migrating from tools with different flag conventions.
use clap::{Arg, Command};
fn print_help() {
let cmd = Command::new("app")
.arg(
Arg::new("all")
.short('a')
.long("all")
.short_aliases(['A', 'x', 'y']) // None visible
.help("Select all items")
)
.arg(
Arg::new("input")
.short('i')
.long("input")
.help("Input file")
);
cmd.get_matches_from(vec!["app", "--help"]);
// Shows: -a, --all Select all items
// Shows: -i, --input Input file
// -A, -x, -y are invisible but functional
}Documentation remains clean while accepting alternative flags.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("test")
.arg(
Arg::new("option")
.short('o')
.long("option")
.short_aliases(['O', 'p', 'P'])
.help("An option")
)
.try_get_matches_from(vec!["test", "-o"]);
// All these would match the same argument:
// -o (primary)
// -O (alias)
// -p (alias)
// -P (alias)
// --option (long)
println!("Matched: {}", matches.unwrap().get_flag("option"));
}All aliases and the primary flag access the same argument value.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("app")
.arg(
Arg::new("level")
.short('l')
.long("level")
.short_aliases(['L'])
.value_name("N")
.help("Set level")
)
.get_matches_from(vec!["app", "-L", "5"]);
let level: i32 = matches.get_one::<i32>("level")
.copied()
.unwrap_or(0);
println!("Level: {}", level); // Works with alias -L
}Aliases work identically for flags with values.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("tool")
.arg(
Arg::new("verbose")
.short('v')
.long("verbose")
.short_aliases(['V'])
)
.arg(
Arg::new("quiet")
.short('q')
.long("quiet")
.short_aliases(['Q'])
)
.get_matches_from(vec!["tool", "-vQ"]); // Combined flags
// Both work, including aliases in combined form
println!("Verbose: {}", matches.get_flag("verbose"));
println!("Quiet: {}", matches.get_flag("quiet"));
}Aliases work in combined short flag syntax like -vQ.
use clap::{Arg, Command};
fn main() {
let cmd = Command::new("app")
.arg(
Arg::new("verbose")
.short('v')
.long("verbose")
.visible_short_aliases(['V']) // Visible in help!
.help("Enable verbose output")
);
cmd.clone().get_matches_from(vec!["app", "--help"]);
// Help shows both:
// -v, -V, --verbose Enable verbose output
}Use visible_short_aliases when you want aliases documented.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("app")
.arg(
Arg::new("output")
.short('o')
.long("output")
.short_aliases(['O']) // Short aliases
.aliases(["out", "outfile"]) // Long aliases (hidden)
.help("Output file")
)
.get_matches_from(vec!["app", "-O", "file.txt"]);
// Short and long aliases both exist
// All reference the same argument
println!("Output: {:?}", matches.get_one::<String>("output"));
}short_aliases is to short flags what aliases is to long flags.
use clap::{Arg, Command};
fn main() {
let result = Command::new("app")
.arg(
Arg::new("file")
.short('f')
.long("file")
.short_aliases(['F'])
.help("Input file")
)
.try_get_matches_from(vec!["app", "-F"]); // Using alias
match result {
Ok(matches) => {
println!("File flag: {}", matches.get_flag("file"));
}
Err(e) => {
// Error messages reference the primary flag
println!("Error: {}", e);
}
}
}Error messages typically reference primary flags, not aliases.
use clap::{Arg, Command};
fn main() {
let matches = Command::new("git-style")
.arg(
Arg::new("all")
.short('a')
.long("all")
.short_aliases(['A']) // Git users expect -A
.help("Stage all changes")
)
.arg(
Arg::new("force")
.short('f')
.long("force")
.short_aliases(['F']) // Common uppercase variant
.help("Force operation")
)
.arg(
Arg::new("dry-run")
.short('n')
.long("dry-run")
.short_aliases(['N']) // Alternative form
.help("Perform a trial run")
)
.get_matches();
// Users can use -a or -A, -f or -F, etc.
if matches.get_flag("all") {
println!("Stage all changes");
}
}Use aliases for tool compatibility and common user expectations.
Core distinction:
short('c') defines the primary, documented short flagshort_aliases(['x', 'y']) defines hidden alternative flagsVisibility:
short appears in help outputshort_aliases are invisible but functionalvisible_short_aliases to show them in helpCommon patterns:
-v with alias -V-l with alias -LKey insight: The distinction between short and short_aliases is purely about documentation and user communication, not runtime behavior. All aliases work identically to the primary flag, but hidden aliases keep help output clean while accepting alternative user inputs. This is especially valuable when migrating from tools with different conventions, supporting case-insensitive users, or maintaining backwards compatibility while evolving your CLI interface. The primary flag should be the one you want users to remember and document; aliases are conveniences that don't clutter the mental model or help text.