Annotation Type CommandLine.Command


  • @Retention(RUNTIME)
    @Target({TYPE,LOCAL_VARIABLE,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",
            description = "Encrypt FILE(s), or standard input, to standard output or to the output file.",
            footer      = "Copyright (c) 2017")
     public class Encrypt {
         @Parameters(paramLabel = "FILE", type = File.class, 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;
     }

    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 Description
      boolean abbreviateSynopsis
      Specify true to generate an abbreviated synopsis like "<main> [OPTIONS] [PARAMETERS...]".
      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.
      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.
    • 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.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 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)
        Default:
        {}
      • 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.Help.separator, 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. This is not part of the usage help message.
        Returns:
        a string or an array of strings with version information about this command.
        Since:
        0.9.8
        See Also:
        CommandLine.printVersionHelp(PrintStream)
        Default:
        {}
      • headerHeading

        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.Help.headerHeading(Object...)
        Default:
        ""
      • synopsisHeading

        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: "
      • descriptionHeading

        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:
        ""
      • parameterListHeading

        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

        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

        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.
        See Also:
        CommandLine.Help.sortOptions
        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
        See Also:
        CommandLine.Help.requiredOptionMarker
        Default:
        ' '
      • showDefaultValues

        boolean showDefaultValues
        Specify true to show default values in the description column of the options list (except for boolean options). False by default.
        Returns:
        whether the default values for options and parameters should be shown in the description column
        See Also:
        CommandLine.Help.showDefaultValues
        Default:
        false
      • commandListHeading

        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

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