Package picocli

Annotation Type CommandLine.Command

  • @Retention(RUNTIME)
@Target({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")
 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]

      • aliases

        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

        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:
        {}

      • addMethodSubcommands

        boolean addMethodSubcommands
        Specify whether methods annotated with @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);
        Returns:
        whether methods annotated with @Command should 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

        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

        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 %n line 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

        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 -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".

        Returns:
        whether the auto-help mixin should be added to this command
        Since:
        3.0
        Default:
        false

      • helpCommand

        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

      • synopsisHeading

        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 %n line separators. Literal percent '%' characters must be escaped with another %.

        Returns:
        the heading preceding the synopsis text
        See Also:
        CommandLine.Help.synopsisHeading(Object...)
        Default:
        "Usage: "

      • customSynopsis

        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 %n line 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:
        {}

      • description

        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 %n line separators. Literal percent '%' characters must be escaped with another %.

        Returns:
        description of this command
        See Also:
        CommandLine.Help.description(Object...)
        Default:
        {}

      • sortOptions

        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

        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:
        ' '

      • defaultValueProvider

        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.
        Returns:
        a Class that can provide default values dynamically at runtime
        Since:
        3.6
        Default:
        picocli.CommandLine.NoDefaultProvider.class

      • showDefaultValues

        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

        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 %n line 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"

      • footer

        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 %n line 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
        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