Skip to content

clikt / com.github.ajalt.clikt.core / CliktCommand

CliktCommand

abstract class CliktCommand : ParameterHolder

The CliktCommand is the core of command line interfaces in Clikt.

Command line interfaces created by creating a subclass of CliktCommand with properties defined with option and argument. You can then parse argv by calling main, which will take care of printing errors and help to the user. If you want to handle output yourself, you can use parse instead.

Once the command line has been parsed and all of the parameters are populated, run is called.

Parameters

help - The help for this command. The first line is used in the usage string, and the entire string is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.

epilog - Text to display at the end of the full help output. It is automatically re-wrapped to the terminal width.

name - The name of the program to use in the help output. If not given, it is inferred from the class name.

invokeWithoutSubcommand - Used when this command has subcommands, and this command is called without a subcommand. If true, run will be called. By default, a PrintHelpMessage is thrown instead.

printHelpOnEmptyArgs - If this command is called with no values on the command line, print a help message (by throwing PrintHelpMessage) if this is true, otherwise run normally.

helpTags - Extra information about this option to pass to the help formatter.

autoCompleteEnvvar - The envvar to use to enable shell autocomplete script generation. Set to null to disable generation.

allowMultipleSubcommands - If true, allow multiple of this command’s subcommands to be called sequentially. This will disable allowInterspersedArgs on the context of this command an its descendants. This functionality is experimental, and may change in a future release.

treatUnknownOptionsAsArgs - If true, any options on the command line whose names aren’t valid will be parsed as an argument rather than reporting an error. You’ll need to define an argument().multiple() to collect these options, or an error will still be reported. Unknown short option flags grouped with other flags on the command line will always be reported as errors.

Constructors

Name Summary
<init> The CliktCommand is the core of command line interfaces in Clikt.CliktCommand(help:String= "", epilog:String= "", name:String? = null, invokeWithoutSubcommand:Boolean= false, printHelpOnEmptyArgs:Boolean= false, helpTags:Map<String,String> = emptyMap(), autoCompleteEnvvar:String? = "", allowMultipleSubcommands:Boolean= false, treatUnknownOptionsAsArgs:Boolean= false)

Properties

Name Summary
commandHelp The help text for this command.open val commandHelp:String
commandHelpEpilog Help text to display at the end of the help output, after any parameters.open val commandHelpEpilog:String
commandName The name of this command, used in help output.val commandName:String
currentContext This command’s context.val currentContext:Context
helpTags Extra information about this option to pass to the help formatter.val helpTags:Map<String,String>
invokeWithoutSubcommand Used when this command has subcommands, and this command is called without a subcommand. If true, run will be called. By default, a PrintHelpMessage is thrown instead.val invokeWithoutSubcommand:Boolean
messages All messages issued during parsing.val messages:List<String>
printHelpOnEmptyArgs If this command is called with no values on the command line, print a help message (by throwing PrintHelpMessage) if this is true, otherwise run normally.val printHelpOnEmptyArgs:Boolean

Functions

Name Summary
aliases A list of command aliases.open fun aliases():Map<String,List<String>>
confirm Prompt for user confirmation.fun confirm(text:String, default:Boolean= false, abort:Boolean= false, promptSuffix:String= ": ", showDefault:Boolean= true):Boolean?
echo Print the default line separator to stdout``fun echo():Unit
Print the message to the screen.fun echo(message:Any?, trailingNewline:Boolean= true, err:Boolean= false, lineSeparator:String= currentContext.console.lineSeparator):Unit
getFormattedHelp Return the full help string for this command.open fun getFormattedHelp():String
getFormattedUsage Return the usage string for this command.open fun getFormattedUsage():String
issueMessage Add a message to be printed after parsingfun issueMessage(message:String):Unit
main Parse the command line and print helpful output if any errors occur.fun main(argv:List<String>):Unitfun main(argv:Array<outString>):Unit
parse Parse the command line and throw an exception if parsing fails.fun parse(argv:List<String>, parentContext:Context? = null):Unitfun parse(argv:Array<String>, parentContext:Context? = null):Unit
prompt Prompt a user for text input.fun prompt(text:String, default:String? = null, hideInput:Boolean= false, requireConfirmation:Boolean= false, confirmationPrompt:String= "Repeat for confirmation: ", promptSuffix:String= ": ", showDefault:Boolean= true):String?
Prompt a user for text input and convert the result.fun <T> prompt(text:String, default:String? = null, hideInput:Boolean= false, requireConfirmation:Boolean= false, confirmationPrompt:String= "Repeat for confirmation: ", promptSuffix:String= ": ", showDefault:Boolean= true, convert: (String) -> T): T?
registerArgument Register an argument with this command.fun registerArgument(argument:Argument):Unit
registeredArguments Get a read-only list of arguments registered in this command (e.g. via registerArgument or an argument delegate)fun registeredArguments():List<Argument>
registeredOptions Get a read-only list of options registered in this command (e.g. via registerOption or an option delegate)fun registeredOptions():List<Option>
registeredParameterGroups Get a read-only list of groups registered in this command (e.g. via registerOptionGroup or an OptionGroup delegate)fun registeredParameterGroups():List<ParameterGroup>
registeredSubcommandNames The names of all direct children of this commandfun registeredSubcommandNames():List<String>
registeredSubcommands Get a read-only list of commands registered as subcommands of this command.fun registeredSubcommands():List<CliktCommand>
registerOption Register an option with this command.fun registerOption(option:Option):Unit
Register an option with this command or group.open fun registerOption(option:GroupableOption):Unit
registerOptionGroup Register a group with this command.fun registerOptionGroup(group:ParameterGroup):Unit
run Perform actions after parsing is complete and this command is invoked.abstract fun run():Unit
shortHelp The help displayed in the commands list when this command is used as a subcommand.fun shortHelp():String
toString open fun toString():String

Extension Functions

Name Summary
argument Create a property delegate argument.funCliktCommand.argument(name:String= "", help:String= "", helpTags:Map<String,String> = emptyMap(), completionCandidates:CompletionCandidates? = null):RawArgument
context Configure this command’s Context.fun <T :CliktCommand> T.context(block: Builder.() ->Unit): T
eagerOption Add an eager option to this command that, when invoked, runs action.fun <T :CliktCommand> T.eagerOption(name:String, vararg additionalNames:String, help:String= "", hidden:Boolean= false, helpTags:Map<String,String> = emptyMap(), groupName:String? = null, action:OptionTransformContext.() ->Unit): T
fun <T :CliktCommand> T.eagerOption(names:Collection<String>, help:String= "", hidden:Boolean= false, helpTags:Map<String,String> = emptyMap(), groupName:String? = null, action:OptionTransformContext.() ->Unit): T
findObject Find the closest object of type T, or nullfun <T :Any>CliktCommand.findObject():ReadOnlyProperty<CliktCommand, T?>
findOrSetObject Find the closest object of type T, setting context.obj if one is not found.fun <T :Any>CliktCommand.findOrSetObject(default: () -> T):ReadOnlyProperty<CliktCommand, T>
mutuallyExclusiveOptions Declare a set of two or more mutually exclusive options.fun <T :Any>ParameterHolder.mutuallyExclusiveOptions(option1:OptionDelegate<T?>, option2:OptionDelegate<T?>, vararg options:OptionDelegate<T?>, name:String? = null, help:String? = null):MutuallyExclusiveOptions<T, T?>
option Create a property delegate option.funParameterHolder.option(vararg names:String, help:String= "", metavar:String? = null, hidden:Boolean= false, envvar:String? = null, helpTags:Map<String,String> = emptyMap(), completionCandidates:CompletionCandidates? = null, valueSourceKey:String? = null):RawOption
requireObject Find the closest object of type T, or throw a NullPointerExceptionfun <T :Any>CliktCommand.requireObject():ReadOnlyProperty<CliktCommand, T>
subcommands Add the given commands as a subcommand of this command.fun <T :CliktCommand> T.subcommands(commands:Iterable<CliktCommand>): T
fun <T :CliktCommand> T.subcommands(vararg commands:CliktCommand): T
versionOption Add an eager option to this command that, when invoked, prints a version message and exits.fun <T :CliktCommand> T.versionOption(version:String, help:String= "Show the version and exit", names:Set<String> = setOf("--version"), message: (String) ->String= { "$commandName version $it" }): T

Inheritors

Name Summary
NoOpCliktCommand A CliktCommand that has a default implementation of CliktCommand.run that is a no-op.open class NoOpCliktCommand :CliktCommand