CommandLine.Command (picocli 3.5.0 API)

@Retention(value=RUNTIME)
 @Target(value={TYPE,LOCAL_VARIABLE,FIELD,PACKAGE})
public static @interface CommandLine.Command

Annotate your class with @Command when you want more control over the format of the generated help message.

 @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")
 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
[footer]

Optional Element Summary

Optional Elements
Modifier and Type	Optional Element and Description
`boolean`	`abbreviateSynopsis` Specify `true` to generate an abbreviated synopsis like `"<main> [OPTIONS] [PARAMETERS...]"`.
`java.lang.String[]`	`aliases` Alternative command names by which this subcommand is recognized on the command line.
`java.lang.String`	`commandListHeading` Set the heading preceding the subcommands list.
`java.lang.String[]`	`customSynopsis` Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.
`java.lang.String[]`	`description` Optional text to display between the synopsis line(s) and the list of options.
`java.lang.String`	`descriptionHeading` Set the heading preceding the description section.
`java.lang.String[]`	`footer` Optional text to display after the list of options.
`java.lang.String`	`footerHeading` Set the heading preceding the footer section.
`java.lang.String[]`	`header` Optional summary description of the command, shown before the synopsis.
`java.lang.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.
`java.lang.String`	`name` Program name to show in the synopsis.
`java.lang.String`	`optionListHeading` Set the heading preceding the options list.
`java.lang.String`	`parameterListHeading` Set the heading preceding the parameters list.
`char`	`requiredOptionMarker` Prefix required options with this character in the options list.
`java.lang.String`	`separator` String that separates options from option parameters.
`boolean`	`showDefaultValues` Specify `true` to show default values in the description column of the options list (except for boolean options).
`boolean`	`sortOptions` Specify `false` to show Options in declaration order.
`java.lang.Class<?>[]`	`subcommands` A list of classes to instantiate and register as subcommands.
`java.lang.String`	`synopsisHeading` Set the heading preceding the synopsis text.
`java.lang.String[]`	`version` Version 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>`	`versionProvider` Class that can provide version information dynamically at runtime.

- Element Detail
  - name
```
public abstract 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>"
- - aliases
```
public abstract java.lang.String[] aliases
```
    Alternative command names by which this subcommand is recognized on the command line.
    
    Returns:
    
    one or more alternative command names
    
    Since:
    
    3.1
    
    Default:
    
    {}
- - subcommands
```
public abstract 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 the 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());
 
```
    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:
    
    {}
- - separator
```
public abstract 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
```
public abstract java.lang.String[] version
```
    Version information for this command, to print to the console when the user specifies an option to request version help. 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
```
public abstract 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
```
public abstract boolean mixinStandardHelpOptions
```
    Adds the standard -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.
    
    Returns:
    
    whether the auto-help mixin should be added to this command
    
    Since:
    
    3.0
    
    Default:
    
    false
- - helpCommand
```
public abstract 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. 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.
    
    Returns:
    
    true if 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
```
public abstract java.lang.String headerHeading
```
    Set the heading preceding the header section. May contain embedded format specifiers.
    
    Returns:
    
    the heading preceding the header section
    
    See Also:
    
    CommandLine.Model.UsageMessageSpec.headerHeading(), CommandLine.Help.headerHeading(Object...)
    
    Default:
    
    ""
- - header
```
public abstract java.lang.String[] header
```
    Optional summary description of the command, shown before the synopsis.
    
    Returns:
    
    summary description of the command
    
    See Also:
    
    CommandLine.Model.UsageMessageSpec.header(), CommandLine.Help.header(Object...)
    
    Default:
    
    {}
- - synopsisHeading
```
public abstract java.lang.String synopsisHeading
```
    Set the heading preceding the synopsis text. May contain embedded format specifiers. The default heading is "Usage: " (without a line break between the heading and the synopsis text).
    
    Returns:
    
    the heading preceding the synopsis text
    
    See Also:
    
    CommandLine.Help.synopsisHeading(Object...)
    
    Default:
    
    "Usage: "
- - abbreviateSynopsis
```
public abstract boolean abbreviateSynopsis
```
    Specify true to generate an abbreviated synopsis like "<main> [OPTIONS] [PARAMETERS...]". 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(Comparator, boolean)
    
    Default:
    
    false
- - customSynopsis
```
public abstract java.lang.String[] customSynopsis
```
    Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.
    
    Returns:
    
    custom synopsis text to replace the auto-generated synopsis
    
    See Also:
    
    CommandLine.Help.customSynopsis(Object...)
    
    Default:
    
    {}
- - descriptionHeading
```
public abstract java.lang.String descriptionHeading
```
    Set the heading preceding the description section. May contain embedded format specifiers.
    
    Returns:
    
    the heading preceding the description section
    
    See Also:
    
    CommandLine.Help.descriptionHeading(Object...)
    
    Default:
    
    ""
- - description
```
public abstract java.lang.String[] description
```
    Optional text to display between the synopsis line(s) and the list of options.
    
    Returns:
    
    description of this command
    
    See Also:
    
    CommandLine.Help.description(Object...)
    
    Default:
    
    {}
- - parameterListHeading
```
public abstract java.lang.String parameterListHeading
```
    Set the heading preceding the parameters list. May contain embedded format specifiers.
    
    Returns:
    
    the heading preceding the parameters list
    
    See Also:
    
    CommandLine.Help.parameterListHeading(Object...)
    
    Default:
    
    ""
- - optionListHeading
```
public abstract java.lang.String optionListHeading
```
    Set the heading preceding the options list. May contain embedded format specifiers.
    
    Returns:
    
    the heading preceding the options list
    
    See Also:
    
    CommandLine.Help.optionListHeading(Object...)
    
    Default:
    
    ""
- - sortOptions
```
public abstract boolean sortOptions
```
    Specify false to show Options in declaration order. The default is to sort alphabetically.
    
    Returns:
    
    whether options should be shown in alphabetic order.
    
    Default:
    
    true
- - requiredOptionMarker
```
public abstract char requiredOptionMarker
```
    Prefix required options with this character in the options list. The default is no marker: the synopsis indicates which options and parameters are required.
    
    Returns:
    
    the character to show in the options list to mark required options
    
    Default:
    
    32
- - showDefaultValues
```
public abstract boolean showDefaultValues
```
    Specify 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.
    
    Returns:
    
    whether the default values for options and parameters should be shown in the description column
    
    Default:
    
    false
- - commandListHeading
```
public abstract java.lang.String commandListHeading
```
    Set the heading preceding the subcommands list. May contain embedded format specifiers. The default heading is "Commands:%n" (with a line break at the end).
    
    Returns:
    
    the heading preceding the subcommands list
    
    See Also:
    
    CommandLine.Help.commandListHeading(Object...)
    
    Default:
    
    "Commands:%n"
- - footerHeading
```
public abstract java.lang.String footerHeading
```
    Set the heading preceding the footer section. May contain embedded format specifiers.
    
    Returns:
    
    the heading preceding the footer section
    
    See Also:
    
    CommandLine.Help.footerHeading(Object...)
    
    Default:
    
    ""
- - footer
```
public abstract java.lang.String[] footer
```
    Optional text to display after the list of options.
    
    Returns:
    
    text to display after the list of options
    
    See Also:
    
    CommandLine.Help.footer(Object...)
    
    Default:
    
    {}
- - hidden
```
public abstract 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.
    
    Returns:
    
    whether this command should be excluded from the usage message
    
    Since:
    
    3.0
    
    Default:
    
    false

Annotation Type CommandLine.Command

Optional Element Summary

Element Detail

name

aliases

subcommands

separator

version

versionProvider

mixinStandardHelpOptions

helpCommand

headerHeading

header

synopsisHeading

abbreviateSynopsis

customSynopsis

descriptionHeading

description

parameterListHeading

optionListHeading

sortOptions

requiredOptionMarker

showDefaultValues

commandListHeading

footerHeading

footer

hidden