Customizing Help for Commands
Define your command’s abstract, extended discussion, or usage string, and set the flags used to invoke the help display.
CustomizingCommandHelp.mdOverview
In addition to configuring the command name and subcommands, as described in Defining Commands and Subcommands, you can also configure a command’s help text by providing an abstract, discussion, or custom usage string.
struct Repeat: ParsableCommand {
static let configuration = CommandConfiguration(
abstract: "Repeats your input phrase.",
usage: """
repeat <phrase>
repeat --count <count> <phrase>
""",
discussion: """
Prints to stdout forever, or until you halt the program.
""")
@Argument(help: "The phrase to repeat.")
var phrase: String
@Option(help: "How many times to repeat.")
var count: Int? = nil
mutating func run() throws {
for _ in 0..<(count ?? 2) {
print(phrase)
}
}
}
The customized components now appear in the generated help screen:
% repeat --help
OVERVIEW: Repeats your input phrase.
Prints to stdout forever, or until you halt the program.
USAGE: repeat <phrase>
repeat --count <count> <phrase>
ARGUMENTS:
<phrase> The phrase to repeat.
OPTIONS:
-h, --help Show help information.
% repeat hello!
hello!
hello!
hello!
hello!
hello!
hello!
...
Modifying the Help Flag Names
Users can see the help screen for a command by passing either the -h
or the --help
flag, by default. If you need to use one of those flags for another purpose, you can provide alternative names when configuring a root command.
struct Example: ParsableCommand {
static let configuration = CommandConfiguration(
helpNames: [.long, .customShort("?")])
@Option(name: .shortAndLong, help: "The number of history entries to show.")
var historyDepth: Int
mutating func run() throws {
printHistory(depth: historyDepth)
}
}
When running the command, -h
matches the short name of the historyDepth
property, and -?
displays the help screen.
% example -h 3
nmap -v -sS -O 10.2.2.2
sshnuke 10.2.2.2 -rootpw="Z1ON0101"
ssh 10.2.2.2 -l root
% example -?
USAGE: example --history-depth <history-depth>
ARGUMENTS:
<phrase> The phrase to repeat.
OPTIONS:
-h, --history-depth The number of history entries to show.
-?, --help Show help information.
When not overridden, custom help names are inherited by subcommands. In this example, the parent command defines --help
and -?
as its help names:
struct Parent: ParsableCommand {
static let configuration = CommandConfiguration(
subcommands: [Child.self],
helpNames: [.long, .customShort("?")])
struct Child: ParsableCommand {
@Option(name: .shortAndLong, help: "The host the server will run on.")
var host: String
}
}
The child
subcommand inherits the parent’s help names, allowing the user to distinguish between the host argument (-h
) and help (-?
).
% parent child -h 192.0.0.0
...
% parent child -?
USAGE: parent child --host <host>
OPTIONS:
-h, --host <host> The host the server will run on.
-?, --help Show help information.
Hiding Commands
You may not want to show every one of your command as part of your command-line interface. To render a command invisible (but still usable), pass shouldDisplay: false
to the CommandConfiguration
initializer.
Generating Help Text Programmatically
The help screen is automatically shown to users when they call your command with the help flag. You can generate the same text from within your program by calling the helpMessage()
method.
let help = Repeat.helpMessage()
// `help` matches the output above
let fortyColumnHelp = Repeat.helpMessage(columns: 40)
// `fortyColumnHelp` is the same help screen, but wrapped to 40 columns
When generating help text for a subcommand, call helpMessage(for:)
on the ParsableCommand
type that represents the root of the command tree and pass the subcommand type as a parameter to ensure the correct display.
See also
Defining Commands and Subcommands
Break complex command-line tools into a tree of subcommands.
Read More