Annotation Type CommandLine.Command
-
@Retention(RUNTIME) @Target({TYPE,LOCAL_VARIABLE,FIELD,PACKAGE,METHOD}) public static @interface CommandLine.CommandAnnotate your class with
@Commandwhen 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:
- [header]
- [synopsis]:
Usage: <commandName> [OPTIONS] [FILE...] - [description]
- [parameter list]:
[FILE...] Any number of input files - [option list]:
-h, --help prints this help message and exits - [exit code list]
- [footer]
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description booleanabbreviateSynopsisSpecifytrueto generate an abbreviated synopsis like"<main> [OPTIONS] [PARAMETERS...] [COMMAND]".booleanaddMethodSubcommandsSpecify whether methods annotated with@Commandshould be registered as subcommands of their enclosing@Commandclass.java.lang.String[]aliasesAlternative command names by which this subcommand is recognized on the command line.java.lang.StringcommandListHeadingSet the heading preceding the subcommands list.java.lang.String[]customSynopsisSpecify one or more custom synopsis lines to display instead of an auto-generated synopsis.java.lang.Class<? extends CommandLine.IDefaultValueProvider>defaultValueProviderClass that can provide default values dynamically at runtime.java.lang.String[]descriptionOptional text to display between the synopsis line(s) and the list of options.java.lang.StringdescriptionHeadingSet the heading preceding the description section.java.lang.String[]exitCodeListSet the values to be displayed in the exit codes section as a list of"key:value"pairs: keys are exit codes, values are descriptions.java.lang.StringexitCodeListHeadingSet the heading preceding the exit codes section, may contain"%n"line separators.intexitCodeOnExecutionExceptionExit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command.intexitCodeOnInvalidInputExit code for command line usage error.intexitCodeOnSuccessExit code for successful termination.intexitCodeOnUsageHelpExit code for successful termination after printing usage help on user request.intexitCodeOnVersionHelpExit code for successful termination after printing version help on user request.java.lang.String[]footerOptional text to display after the list of options.java.lang.StringfooterHeadingSet the heading preceding the footer section.java.lang.String[]headerOptional summary description of the command, shown before the synopsis.java.lang.StringheaderHeadingSet the heading preceding the header section.booleanhelpCommandSet this attribute totrueif this subcommand is a help command, and required options and positional parameters of the parent command should not be validated.booleanhiddenSethidden=trueif this command should not be included in the list of commands in the usage help of the parent command.booleanmixinStandardHelpOptionsAdds the standard-hand--helpusageHelp options and-Vand--versionversionHelp options to the options of this command.java.lang.Class<? extends CommandLine.IModelTransformer>modelTransformerReturns the model transformer for this command.java.lang.StringnameProgram name to show in the synopsis.java.lang.StringoptionListHeadingSet the heading preceding the options list.java.lang.StringparameterListHeadingSet the heading preceding the parameters list.java.lang.Class<? extends CommandLine.IParameterPreprocessor>preprocessorReturns the preprocessor for this command.charrequiredOptionMarkerPrefix required options with this character in the options list.java.lang.StringresourceBundleSet the base name of the ResourceBundle to find option and positional parameters descriptions, as well as usage help message sections and section headings.CommandLine.ScopeTypescopeReturns whether subcommands inherit their attributes from this parent command.java.lang.StringseparatorString that separates options from option parameters.booleanshowAtFileInUsageHelpSpecifytrueto show a[@<filename>...]entry in the synopsis and parameter list of the usage help message.booleanshowDefaultValuesSpecifytrueto show default values in the description column of the options list (except for boolean options).booleanshowEndOfOptionsDelimiterInUsageHelpSpecifytrueto show a[--]"End of options" entry in the synopsis and option list of the usage help message.booleansortOptionsSpecifyfalseto show Options in declaration order in the option list of the usage help message (or to sort options by their order index if set).booleansortSynopsisSpecifyfalseto show options in declaration order in the synopsis of the usage help message (or to sort options by their order index if set).java.lang.Class<?>[]subcommandsA list of classes to instantiate and register as subcommands.booleansubcommandsRepeatableReturns 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.java.lang.StringsynopsisHeadingSet the heading preceding the synopsis text.java.lang.StringsynopsisSubcommandLabelSpecify the String to show in the synopsis for the subcommands of this command.booleanusageHelpAutoWidthIftrue, picocli will attempt to detect the terminal width and adjust the usage help message accordingly.intusageHelpWidthSet theusage help message width.java.lang.String[]versionVersion information for this command, to print to the console when the user specifies an option to request version help.java.lang.Class<? extends CommandLine.IVersionProvider>versionProviderClass that can provide version information dynamically at runtime.
-
-
-
Element Detail
-
name
java.lang.String name
Program name to show in the synopsis. If omitted,"<main class>"is used. For declaratively added subcommands, this attribute is also used by the parser to recognize subcommands in the command line arguments.- Returns:
- the program name to show in the synopsis
- See Also:
CommandLine.Model.CommandSpec.name(),CommandLine.Help.commandName()
- Default:
- "<main class>"
-
-
-
subcommands
java.lang.Class<?>[] subcommands
A list of classes to instantiate and register as subcommands. When registering subcommands declaratively like this, you don't need to call theCommandLine.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- ahelpsubcommand that prints help on the following or preceding commandAutoComplete.GenerateCompletion- agenerate-completionsubcommand that prints a Bash/ZSH completion script for its parent command, so that clients can install autocompletion in one line by runningsource <(parent-command generate-completion)in the shell
- Returns:
- the declaratively registered subcommands of this command, or an empty array if none
- Since:
- 0.9.8
- See Also:
CommandLine.addSubcommand(String, Object),CommandLine.HelpCommand
- Default:
- {}
-
-
-
addMethodSubcommands
boolean addMethodSubcommands
Specify whether methods annotated with@Commandshould be registered as subcommands of their enclosing@Commandclass. The default istrue. 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);- Returns:
- whether methods annotated with
@Commandshould be registered as subcommands - Since:
- 3.6.0
- See Also:
CommandLine.addSubcommand(String, Object),CommandLine.getCommandMethods(Class, String),CommandLine.Model.CommandSpec.addMethodSubcommands()
- Default:
- true
-
-
-
separator
java.lang.String separator
String that separates options from option parameters. Default is"=". Spaces are also accepted.- Returns:
- the string that separates options from option parameters, used both when parsing and when generating usage help
- See Also:
CommandLine.setSeparator(String)
- Default:
- "="
-
-
-
version
java.lang.String[] version
Version information for this command, to print to the console when the user specifies an option to request version help. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.This is not part of the usage help message.
- Returns:
- a string or an array of strings with version information about this command (each string in the array is displayed on a separate line).
- Since:
- 0.9.8
- See Also:
CommandLine.printVersionHelp(PrintStream)
- Default:
- {}
-
-
-
versionProvider
java.lang.Class<? extends CommandLine.IVersionProvider> versionProvider
Class that can provide version information dynamically at runtime. An implementation may return version information obtained from the JAR manifest, a properties file or some other source.- Returns:
- a Class that can provide version information dynamically at runtime
- Since:
- 2.2
- Default:
- picocli.CommandLine.NoVersionProvider.class
-
-
-
mixinStandardHelpOptions
boolean mixinStandardHelpOptions
Adds the standard-hand--helpusageHelp options and-Vand--versionversionHelp options to the options of this command.Note that if no
version()orversionProvider()is specified, the--versionoption will not print anything.For internationalization: the help option has
descriptionKey = "mixinStandardHelpOptions.help", and the version option hasdescriptionKey = "mixinStandardHelpOptions.version".- Returns:
- whether the auto-help mixin should be added to this command
- Since:
- 3.0
- Default:
- false
-
-
-
helpCommand
boolean helpCommand
Set this attribute totrueif this subcommand is a help command, and required options and positional parameters of the parent command should not be validated. If a subcommand marked ashelpCommandis specified on the command line, picocli will not validate the parent arguments (so no "missing required option" errors) and theCommandLine.printHelpIfRequested(List, PrintStream, PrintStream, Help.Ansi)method will returntrue.- Returns:
trueif this subcommand is a help command and picocli should not check for missing required options and positional parameters on the parent command- Since:
- 3.0
- Default:
- false
-
-
-
headerHeading
java.lang.String headerHeading
Set the heading preceding the header section.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the header section
- See Also:
CommandLine.Model.UsageMessageSpec.headerHeading(),CommandLine.Help.headerHeading(Object...)
- Default:
- ""
-
-
-
header
java.lang.String[] header
Optional summary description of the command, shown before the synopsis. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- summary description of the command
- See Also:
CommandLine.Model.UsageMessageSpec.header(),CommandLine.Help.header(Object...)
- Default:
- {}
-
-
-
synopsisHeading
java.lang.String synopsisHeading
Set the heading preceding the synopsis text. The default heading is"Usage: "(without a line break between the heading and the synopsis text).May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the synopsis text
- See Also:
CommandLine.Help.synopsisHeading(Object...)
- Default:
- "Usage: "
-
-
-
abbreviateSynopsis
boolean abbreviateSynopsis
Specifytrueto generate an abbreviated synopsis like"<main> [OPTIONS] [PARAMETERS...] [COMMAND]". By default, a detailed synopsis with individual option names and parameters is generated.- Returns:
- whether the synopsis should be abbreviated
- See Also:
CommandLine.Help.abbreviatedSynopsis(),CommandLine.Help.detailedSynopsis(int, Comparator, boolean)
- Default:
- false
-
-
-
customSynopsis
java.lang.String[] customSynopsis
Specify one or more custom synopsis lines to display instead of an auto-generated synopsis. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- custom synopsis text to replace the auto-generated synopsis
- See Also:
CommandLine.Help.customSynopsis(Object...)
- Default:
- {}
-
-
-
synopsisSubcommandLabel
java.lang.String synopsisSubcommandLabel
Specify the String to show in the synopsis for the subcommands of this command. The default is"[COMMAND]". Ignored if this command has no subcommands.- Since:
- 4.0
- Default:
- "[COMMAND]"
-
-
-
descriptionHeading
java.lang.String descriptionHeading
Set the heading preceding the description section.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the description section
- See Also:
CommandLine.Help.descriptionHeading(Object...)
- Default:
- ""
-
-
-
description
java.lang.String[] description
Optional text to display between the synopsis line(s) and the list of options. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- description of this command
- See Also:
CommandLine.Help.description(Object...)
- Default:
- {}
-
-
-
parameterListHeading
java.lang.String parameterListHeading
Set the heading preceding the parameters list.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the parameters list
- See Also:
CommandLine.Help.parameterListHeading(Object...)
- Default:
- ""
-
-
-
optionListHeading
java.lang.String optionListHeading
Set the heading preceding the options list.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the options list
- See Also:
CommandLine.Help.optionListHeading(Object...)
- Default:
- ""
-
-
-
sortOptions
boolean sortOptions
Specifyfalseto 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.- Returns:
- whether options should be shown in alphabetic order.
- Default:
- true
-
-
-
sortSynopsis
boolean sortSynopsis
Specifyfalseto 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.- Returns:
- whether options in the synopsis should be shown in alphabetic order.
- Since:
- 4.7.7-SNAPSHOT
- Default:
- true
-
-
-
defaultValueProvider
java.lang.Class<? extends CommandLine.IDefaultValueProvider> defaultValueProvider
Class that can provide default values dynamically at runtime. An implementation may return default value obtained from a configuration file like a properties file or some other source.Applications may be interested in the
CommandLine.PropertiesDefaultProviderbuilt-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.- Returns:
- a Class that can provide default values dynamically at runtime
- Since:
- 3.6
- Default:
- picocli.CommandLine.NoDefaultProvider.class
-
-
-
showDefaultValues
boolean showDefaultValues
Specifytrueto 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.
- Returns:
- whether the default values for options and parameters should be shown in the description column
- Default:
- false
-
-
-
showAtFileInUsageHelp
boolean showAtFileInUsageHelp
Specifytrueto 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.)- Since:
- 4.2
- Default:
- false
-
-
-
commandListHeading
java.lang.String commandListHeading
Set the heading preceding the subcommands list. The default heading is"Commands:%n"(with a line break at the end).May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the subcommands list
- See Also:
CommandLine.Help.commandListHeading(Object...)
- Default:
- "Commands:%n"
-
-
-
footerHeading
java.lang.String footerHeading
Set the heading preceding the footer section.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- the heading preceding the footer section
- See Also:
CommandLine.Help.footerHeading(Object...)
- Default:
- ""
-
-
-
footer
java.lang.String[] footer
Optional text to display after the list of options. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.- Returns:
- text to display after the list of options
- See Also:
CommandLine.Help.footer(Object...)
- Default:
- {}
-
-
-
hidden
boolean hidden
Sethidden=trueif this command should not be included in the list of commands in the usage help of the parent command.- Returns:
- whether this command should be excluded from the usage message
- Since:
- 3.0
- Default:
- false
-
-
-
resourceBundle
java.lang.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.See
CommandLine.Model.Messagesfor more details and an example.- Returns:
- the base name of the ResourceBundle for usage help strings
- Since:
- 3.6
- See Also:
CommandLine.Model.ArgSpec.messages(),CommandLine.Model.UsageMessageSpec.messages(),CommandLine.Model.CommandSpec.resourceBundle(),CommandLine.setResourceBundle(ResourceBundle)
- Default:
- ""
-
-
-
usageHelpWidth
int usageHelpWidth
Set theusage help message width. The default is 80.- Since:
- 3.7
- See Also:
CommandLine.Model.UsageMessageSpec.width()
- Default:
- 80
-
-
-
usageHelpAutoWidth
boolean usageHelpAutoWidth
Iftrue, 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"toAUTO, and may disable this by setting this system property to a numeric value. This feature requires Java 7 or greater. The default isfalse- Since:
- 4.0
- See Also:
CommandLine.Model.UsageMessageSpec.autoWidth()
- Default:
- false
-
-
-
exitCodeOnSuccess
int exitCodeOnSuccess
Exit code for successful termination. 0 by default.- Since:
- 4.0
- See Also:
CommandLine.execute(String...)
- Default:
- 0
-
-
-
exitCodeOnUsageHelp
int exitCodeOnUsageHelp
Exit code for successful termination after printing usage help on user request. 0 by default.- Since:
- 4.0
- See Also:
CommandLine.execute(String...)
- Default:
- 0
-
-
-
exitCodeOnVersionHelp
int exitCodeOnVersionHelp
Exit code for successful termination after printing version help on user request. 0 by default.- Since:
- 4.0
- See Also:
CommandLine.execute(String...)
- Default:
- 0
-
-
-
exitCodeOnInvalidInput
int exitCodeOnInvalidInput
Exit code for command line usage error. 2 by default.- Since:
- 4.0
- See Also:
CommandLine.execute(String...)
- Default:
- 2
-
-
-
exitCodeOnExecutionException
int exitCodeOnExecutionException
Exit code signifying that an exception occurred when invoking the Runnable, Callable or Method user object of a command. 1 by default.- Since:
- 4.0
- See Also:
CommandLine.execute(String...)
- Default:
- 1
-
-
-
exitCodeListHeading
java.lang.String exitCodeListHeading
Set the heading preceding the exit codes section, may contain"%n"line separators.""(empty string) by default.- Since:
- 4.0
- See Also:
CommandLine.Help.exitCodeListHeading(Object...)
- Default:
- ""
-
-
-
exitCodeList
java.lang.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. 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."})- Since:
- 4.0
- Default:
- {}
-
-
-
scope
CommandLine.ScopeType scope
Returns whether subcommands inherit their attributes from this parent command.- Since:
- 4.6
- Default:
- picocli.CommandLine.ScopeType.LOCAL
-
-
-
modelTransformer
java.lang.Class<? extends CommandLine.IModelTransformer> modelTransformer
Returns the model transformer for this command.- Since:
- 4.6
- Default:
- picocli.CommandLine.NoOpModelTransformer.class
-
-
-
preprocessor
java.lang.Class<? extends CommandLine.IParameterPreprocessor> preprocessor
Returns the preprocessor for this command.- Since:
- 4.6
- See Also:
CommandLine.IParameterPreprocessor
- Default:
- picocli.CommandLine.NoOpParameterPreprocessor.class
-
-