@Retention(value=RUNTIME) @Target(value={TYPE,LOCAL_VARIABLE,FIELD,PACKAGE,METHOD}) public static @interface CommandLine.Command
Annotate your class with @Command
when you want more control over the format of the generated help
message. From 3.6, methods can also be annotated with @Command
, where the method parameters define the
command options and positional parameters.
@Command(name = "Encrypt", mixinStandardHelpOptions = true, description = "Encrypt FILE(s), or standard input, to standard output or to the output file.", version = "Encrypt version 1.0", footer = "Copyright (c) 2017", exitCodeListHeading = "Exit Codes:%n", exitCodeList = { " 0:Successful program execution.", "64:Invalid input: an unknown option or invalid parameter was specified.", "70:Execution exception: an exception occurred while executing the business logic."} ) public class Encrypt { @Parameters(paramLabel = "FILE", description = "Any number of input files") private List<File> files = new ArrayList<File>(); @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)") private File outputFile; @Option(names = { "-v", "--verbose"}, description = "Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity.") private boolean[] verbose; }
The structure of a help message looks like this:
Usage: <commandName> [OPTIONS] [FILE...]
[FILE...] Any number of input files
-h, --help prints this help message and exits
Modifier and Type | Optional Element and Description |
---|---|
boolean |
abbreviateSynopsis
Specify
true to generate an abbreviated synopsis like "<main> [OPTIONS] [PARAMETERS...] [COMMAND]" . |
boolean |
addMethodSubcommands
Specify whether methods annotated with
@Command should be registered as subcommands of their
enclosing @Command class. |
String[] |
aliases
Alternative command names by which this subcommand is recognized on the command line.
|
String |
commandListHeading
Set the heading preceding the subcommands list.
|
String[] |
customSynopsis
Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.
|
Class<? extends CommandLine.IDefaultValueProvider> |
defaultValueProvider
Class that can provide default values dynamically at runtime.
|
String[] |
description
Optional text to display between the synopsis line(s) and the list of options.
|
String |
descriptionHeading
Set the heading preceding the description section.
|
String[] |
exitCodeList
Set the values to be displayed in the exit codes section as a list of
"key:value" pairs:
keys are exit codes, values are descriptions. |
String |
exitCodeListHeading
Set the heading preceding the exit codes section, may contain
"%n" line separators. |
int |
exitCodeOnExecutionException
Exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command.
|
int |
exitCodeOnInvalidInput
Exit code for command line usage error.
|
int |
exitCodeOnSuccess
Exit code for successful termination.
|
int |
exitCodeOnUsageHelp
Exit code for successful termination after printing usage help on user request.
|
int |
exitCodeOnVersionHelp
Exit code for successful termination after printing version help on user request.
|
String[] |
footer
Optional text to display after the list of options.
|
String |
footerHeading
Set the heading preceding the footer section.
|
String[] |
header
Optional summary description of the command, shown before the synopsis.
|
String |
headerHeading
Set the heading preceding the header section.
|
boolean |
helpCommand
Set this attribute to
true if this subcommand is a help command, and required options and positional
parameters of the parent command should not be validated. |
boolean |
hidden
Set
hidden=true if this command should not be included in the list of commands in the usage help of the parent command. |
boolean |
mixinStandardHelpOptions
Adds the standard
-h and --help usageHelp options and -V
and --version versionHelp options to the options of this command. |
Class<? extends CommandLine.IModelTransformer> |
modelTransformer
Returns the model transformer for this command.
|
String |
name
Program name to show in the synopsis.
|
String |
optionListHeading
Set the heading preceding the options list.
|
String |
parameterListHeading
Set the heading preceding the parameters list.
|
Class<? extends CommandLine.IParameterPreprocessor> |
preprocessor
Returns the preprocessor for this command.
|
char |
requiredOptionMarker
Prefix required options with this character in the options list.
|
String |
resourceBundle
Set the base name of the ResourceBundle to find option and positional parameters descriptions, as well as
usage help message sections and section headings.
|
CommandLine.ScopeType |
scope
Returns whether subcommands inherit their attributes from this parent command.
|
String |
separator
String that separates options from option parameters.
|
boolean |
showAtFileInUsageHelp
Specify
true to show a [@<filename>...] entry
in the synopsis and parameter list of the usage help message. |
boolean |
showDefaultValues
Specify
true to show default values in the description column of the options list (except for
boolean options). |
boolean |
showEndOfOptionsDelimiterInUsageHelp
Specify
true to show a [--] "End of options" entry
in the synopsis and option list of the usage help message. |
boolean |
sortOptions
Specify
false to show Options in declaration order in the option list of the usage help message (or to sort options by their order index if set). |
boolean |
sortSynopsis
Specify
false to show options in declaration order in the synopsis of the usage help message (or to sort options by their order index if set). |
Class<?>[] |
subcommands
A list of classes to instantiate and register as subcommands.
|
boolean |
subcommandsRepeatable
Returns whether the subcommands of this command are repeatable, that is, whether such subcommands can
occur multiple times and may be followed by sibling commands instead of only by child commands of the subcommand.
|
String |
synopsisHeading
Set the heading preceding the synopsis text.
|
String |
synopsisSubcommandLabel
Specify the String to show in the synopsis for the subcommands of this command.
|
boolean |
usageHelpAutoWidth
If
true , picocli will attempt to detect the terminal width and adjust the usage help message accordingly. |
int |
usageHelpWidth
Set the
usage help message width . |
String[] |
version
Version information for this command, to print to the console when the user specifies an
option to request version help.
|
Class<? extends CommandLine.IVersionProvider> |
versionProvider
Class that can provide version information dynamically at runtime.
|
public abstract String name
"<main class>"
is used.
For declaratively added subcommands, this attribute is also used
by the parser to recognize subcommands in the command line arguments.CommandLine.Model.CommandSpec.name()
,
CommandLine.Help.commandName()
public abstract String[] aliases
public abstract Class<?>[] subcommands
CommandLine.addSubcommand(String, Object)
method. For example, this:
@Command(subcommands = { GitStatus.class, GitCommit.class, GitBranch.class }) public class Git { ... } CommandLine commandLine = new CommandLine(new Git());is equivalent to this:
// alternative: programmatically add subcommands. // NOTE: in this case there should be no `subcommands` attribute on the @Command annotation. @Command public class Git { ... } CommandLine commandLine = new CommandLine(new Git()) .addSubcommand("status", new GitStatus()) .addSubcommand("commit", new GitCommit()) .addSubcommand("branch", new GitBranch());Applications may be interested in the following built-in commands in picocli that can be used as subcommands:
CommandLine.HelpCommand
- a help
subcommand that prints help on the following or preceding commandAutoComplete.GenerateCompletion
- a generate-completion
subcommand that prints a Bash/ZSH completion script for its parent command, so that clients can install autocompletion in one line by running source <(parent-command generate-completion)
in the shellCommandLine.addSubcommand(String, Object)
,
CommandLine.HelpCommand
public abstract boolean subcommandsRepeatable
public abstract boolean addMethodSubcommands
@Command
should be registered as subcommands of their
enclosing @Command
class.
The default is true
. For example:
@Command public class Git { @Command void status() { ... } } CommandLine git = new CommandLine(new Git());is equivalent to this:
// don't add command methods as subcommands automatically @Command(addMethodSubcommands = false) public class Git { @Command void status() { ... } } // add command methods as subcommands programmatically CommandLine git = new CommandLine(new Git()); CommandLine status = new CommandLine(CommandLine.getCommandMethods(Git.class, "status").get(0)); git.addSubcommand("status", status);
@Command
should be registered as subcommandsCommandLine.addSubcommand(String, Object)
,
CommandLine.getCommandMethods(Class, String)
,
CommandLine.Model.CommandSpec.addMethodSubcommands()
public abstract String separator
"="
. Spaces are also accepted.CommandLine.setSeparator(String)
public abstract String[] version
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
This is not part of the usage help message.
CommandLine.printVersionHelp(PrintStream)
public abstract Class<? extends CommandLine.IVersionProvider> versionProvider
public abstract boolean mixinStandardHelpOptions
-h
and --help
usageHelp options and -V
and --version
versionHelp options to the options of this command.
Note that if no version()
or versionProvider()
is specified, the --version
option will not print anything.
For internationalization: the help option has descriptionKey = "mixinStandardHelpOptions.help"
,
and the version option has descriptionKey = "mixinStandardHelpOptions.version"
.
public abstract boolean helpCommand
true
if this subcommand is a help command, and required options and positional
parameters of the parent command should not be validated. If a subcommand marked as helpCommand
is
specified on the command line, picocli will not validate the parent arguments (so no "missing required
option" errors) and the CommandLine.printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi)
method will return true
.true
if this subcommand is a help command and picocli should not check for missing required
options and positional parameters on the parent commandpublic abstract String headerHeading
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Model.UsageMessageSpec.headerHeading()
,
CommandLine.Help.headerHeading(Object...)
public abstract String[] header
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Model.UsageMessageSpec.header()
,
CommandLine.Help.header(Object...)
public abstract String synopsisHeading
"Usage: "
(without a line break between the heading and the synopsis text).
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.synopsisHeading(Object...)
public abstract boolean abbreviateSynopsis
true
to generate an abbreviated synopsis like "<main> [OPTIONS] [PARAMETERS...] [COMMAND]"
.
By default, a detailed synopsis with individual option names and parameters is generated.CommandLine.Help.abbreviatedSynopsis()
,
CommandLine.Help.detailedSynopsis(int, Comparator, boolean)
public abstract String[] customSynopsis
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.customSynopsis(Object...)
public abstract String synopsisSubcommandLabel
"[COMMAND]"
. Ignored if this command has no subcommands.public abstract String descriptionHeading
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.descriptionHeading(Object...)
public abstract String[] description
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.description(Object...)
public abstract String parameterListHeading
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.parameterListHeading(Object...)
public abstract String optionListHeading
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.optionListHeading(Object...)
public abstract boolean sortOptions
false
to show Options in declaration order in the option list of the usage help message (or to sort options by their order index if set).
Note that picocli cannot reliably detect declaration order in commands that have both @Option
-annotated methods and @Option
-annotated fields.
The default (true
) is to sort alphabetically.public abstract boolean sortSynopsis
false
to show options in declaration order in the synopsis of the usage help message (or to sort options by their order index if set).
Note that picocli cannot reliably detect declaration order in commands that have both @Option
-annotated methods and @Option
-annotated fields.
The default (true
) is to sort alphabetically.public abstract char requiredOptionMarker
public abstract Class<? extends CommandLine.IDefaultValueProvider> defaultValueProvider
Applications may be interested in the CommandLine.PropertiesDefaultProvider
built-in default provider
that allows end users to maintain their own default values for options and positional parameters,
which may override the defaults that are hard-coded in the application.
public abstract boolean showDefaultValues
true
to show default values in the description column of the options list (except for
boolean options). False by default.
Note that picocli 3.2 allows embedding default values anywhere in the option or positional parameter description that ignores this setting.
public abstract boolean showAtFileInUsageHelp
true
to show a [@<filename>...]
entry
in the synopsis and parameter list of the usage help message.
(The entry is not shown if expanding parameter files is disabled.)public abstract boolean showEndOfOptionsDelimiterInUsageHelp
true
to show a [--]
"End of options" entry
in the synopsis and option list of the usage help message.public abstract String commandListHeading
"Commands:%n"
(with a line break at the end).
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.commandListHeading(Object...)
public abstract String footerHeading
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.footerHeading(Object...)
public abstract String[] footer
May contain embedded format specifiers like %n
line separators. Literal percent '%'
characters must be escaped with another %
.
CommandLine.Help.footer(Object...)
public abstract boolean hidden
hidden=true
if this command should not be included in the list of commands in the usage help of the parent command.public abstract String resourceBundle
See CommandLine.Model.Messages
for more details and an example.
CommandLine.Model.ArgSpec.messages()
,
CommandLine.Model.UsageMessageSpec.messages()
,
CommandLine.Model.CommandSpec.resourceBundle()
,
CommandLine.setResourceBundle(ResourceBundle)
public abstract int usageHelpWidth
usage help message width
. The default is 80.CommandLine.Model.UsageMessageSpec.width()
public abstract boolean usageHelpAutoWidth
true
, picocli will attempt to detect the terminal width and adjust the usage help message accordingly.
End users may enable this by setting system property "picocli.usage.width"
to AUTO
,
and may disable this by setting this system property to a numeric value.
This feature requires Java 7 or greater. The default is false
CommandLine.Model.UsageMessageSpec.autoWidth()
public abstract int exitCodeOnSuccess
CommandLine.execute(String...)
public abstract int exitCodeOnUsageHelp
CommandLine.execute(String...)
public abstract int exitCodeOnVersionHelp
CommandLine.execute(String...)
public abstract int exitCodeOnInvalidInput
CommandLine.execute(String...)
public abstract int exitCodeOnExecutionException
CommandLine.execute(String...)
public abstract String exitCodeListHeading
"%n"
line separators. ""
(empty string) by default.CommandLine.Help.exitCodeListHeading(Object...)
public abstract String[] exitCodeList
"key:value"
pairs:
keys are exit codes, values are descriptions. Descriptions may contain "%n"
line separators.
For example:
@Command(exitCodeListHeading = "Exit Codes:%n", exitCodeList = { " 0:Successful program execution.", "64:Invalid input: an unknown option or invalid parameter was specified.", "70:Execution exception: an exception occurred while executing the business logic."})
public abstract CommandLine.ScopeType scope
public abstract Class<? extends CommandLine.IModelTransformer> modelTransformer
public abstract Class<? extends CommandLine.IParameterPreprocessor> preprocessor
CommandLine.IParameterPreprocessor