Multiplatform command line interface parsing for Kotlin
This release adds support for linuxArm64
and wasmJs
targets.
limit
parameter to option().counted()
to limit the number of times the option can be used. You can either clamp the value to the limit, or throw an error if the limit is exceeded. (#483)Context.registerClosable
and Context.callOnClose
to allow you to register cleanup actions that will be called when the command exits. (#395)requireConfirmation
parameter to option().prompt()
(#426)CliktCommand.terminal
extension for accessing the terminal from a command.includeSystemEnvvars
, ansiLevel
, width
, and height
parameters to all CliktCommand.test
overloads.CliktCommand.prompt
, use CliktCommand.terminal.prompt
or Prompt
instead.CliktCommand.confirm
, use YesNoPrompt
instead.MordantHelpFormatter.renderAttachedOptionValue
that you can override to change how option values are shown, e.g. if you want option to show as --option <value>
instead of --option=<value>
. (#416)option().optionalValueLazy{}
, which work like optionalValue()
but the default value is computed lazily. (#381)PrintMessage
, PrintHelpMessage
and PrintCompletionMessage
now default to exiting with a status code 0, which is the behavior they had in 3.x. (#419)Clikt 4.0 is a major release that uses the Mordant library for help formatting. If you aren't customizing help output, this upgrade will probably be source compatible.
Here are some of the highlights of this release. See CHANGELOG.md
for a detailed list of changes.
All help strings now support markdown, including tables and lists. On terminals that support it, help and error messages will be colored.
class Command : CliktCommand(
help="""
## This command uses markdown for its help text
- You can use lists
- You can use **bold** and *italic* text
- You can even use [links](https://example.com) on terminals that support them
| You | can | use | tables |
|-----------|--------|------|--------|
| and | they | will | be |
| formatted | nicely | for | you |
""".trimIndent()
)
$ ./command --help
Usage: command [<options>]
───── This command uses markdown for its help text ─────
• You can use lists
• You can use bold and italic text
• You can even use links on terminals that support them
┌───────────┬────────┬──────┬────────┐
│ You │ can │ use │ tables │
╞═══════════╪════════╪══════╪════════╡
│ and │ they │ will │ be │
├───────────┼────────┼──────┼────────┤
│ formatted │ nicely │ for │ you │
└───────────┴────────┴──────┴────────┘
There are new lazy extensions for setting paramter help that you can use to add color to parameter help text:
option().help { theme.info("this text will use the theme color") }
You can now use optionalValue()
to create an option that can be used as a flag or with a value
val log by option().optionalValue("verbose").default("none")
> ./tool --log=debug
log level == debug
> ./tool --log
log level == verbose
> ./tool
log level == none
You can also use varargValues()
to create an option that accepts a variable number of values.
Clikt's exceptions now all inherit from CliktError
, and the CliktCommand.getFormattedHelp
method renders them into strings for you. This makes customizing main
much easier. The default
implementation is now just:
fun main(argv: List<String>) {
try {
parse(argv)
} catch (e: CliktError) {
echoFormattedHelp(e)
exitProcess(e.statusCode)
}
}
Clikt 4.0 is a major release that uses the Mordant library for help formatting. If you aren't customizing help output, this upgrade will probably be source compatible.
Here are some of the highlights of this release. See CHANGELOG.md
for a detailed list of changes.
All help strings now support markdown, including tables and lists. On terminals that support it, help and error messages will be colored.
class Command : CliktCommand(
help="""
## This command uses markdown for its help text
- You can use lists
- You can use **bold** and *italic* text
- You can even use [links](https://example.com) on terminals that support them
| You | can | use | tables |
|-----------|--------|------|--------|
| and | they | will | be |
| formatted | nicely | for | you |
""".trimIndent()
)
$ ./command --help
Usage: command [<options>]
───── This command uses markdown for its help text ─────
• You can use lists
• You can use bold and italic text
• You can even use links on terminals that support them
┌───────────┬────────┬──────┬────────┐
│ You │ can │ use │ tables │
╞═══════════╪════════╪══════╪════════╡
│ and │ they │ will │ be │
├───────────┼────────┼──────┼────────┤
│ formatted │ nicely │ for │ you │
└───────────┴────────┴──────┴────────┘
You can now use optionalValue()
to create an option that can be used as a flag or with a value
val log by option().optionalValue("verbose").default("none")
> ./tool --log=debug
log level == debug
> ./tool --log
log level == verbose
> ./tool
log level == none
You can also use varargValues()
to create an option that accepts a variable number of values.
Clikt's exceptions now all inherit from CliktError
, and the CliktCommand.getFormattedHelp
method renders them into strings for you. This makes customizing main
much easier. The default
implementation is now just:
fun main(argv: List<String>) {
try {
parse(argv)
} catch (e: CliktError) {
echoFormattedHelp(e)
exitProcess(e.statusCode)
}
}
treatUnknownOptionsAsArgs
is true, grouped unknown short options will now be treated as arguments rather than reporting an error.