5.0.1

Added

• Added completion commands for suspending and chained commands. (#553)
• Added no-op suspending commands. (#554)

Changed

• Unknown option errors and missing argument errors that occur at the same time will now both be reported. (#553)

5.0.0

This release splits the package into separate modules to help produce smaller binaries. Parsing and running commands are now separated, which allows for custom run types. This release includes the SuspendingCliktCommand and the ChainedCliktCommand, and it's easy to define your own.

See the migration guide for details on upgrading to Clikt 5.0.

Added

• Publish iosArm64 and iosX64 targets.
• Added NoSuchArgument exception that is thrown when too many arguments were given on the command line. Previously, a less specific UsageError was thrown instead.
• Added CommandLineParser.tokenize that splits a string into argv tokens.
• Added CommandLineParser that provides functions for parsing and finalizing commands manually for more control.
• Added Context.invokedSubcommands that contains all subcommands of the current command that are going to be invoked when allowMultipleSubcommands is true.
• Added SuspendingCliktCommand that has a suspend fun run method, allowing you to use coroutines in your commands.
• Added ChainedCliktCommand that allows you to return a value from your run method and pass it to the next command in the chain.
• Added Context.data as an alternative to obj that allows you to store more than one object in the context.
• Added Context.echoer to customize how echo messages are printed.
• Added CompletionGenerator to manually generate completions for a command.
• Added Context.exitProcess which you can use to prevent the process from exiting during tests.
• Added core module that supports watchOS, tvOS, and wasmWasi targets and has no dependencies.
• Added more options to CliktCommand.test to control the terminal interactivity. (#517)
• Added associate{}, associateBy{}, and associateWith{} transforms for options that allow you to convert the keys and values of the map. (#529)
• Added support for aliasing options to other options. (#535)
• Added limit and ignoreCase parameters to option().split(). (#541)
• Support calling --help on subcommands when parents have required parameters.

Changed

• In a subcommand with and an argument() with multiple() or optional(), the behavior is now the same regardless of the value of allowMultipleSubcommands: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.

• Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.

• Breaking Change: Moved the following parameters from CliktCommand's constructor; override the corresponding properties instead:

  removed parameter	replacement property
  help	fun help
  epilog	fun helpEpilog
  invokeWithoutSubcommand	val invokeWithoutSubcommand
  printHelpOnEmptyArgs	val printHelpOnEmptyArgs
  helpTags	val helpTags
  autoCompleteEnvvar	val autoCompleteEnvvar
  allowMultipleSubcommands	val allowMultipleSubcommands
  treatUnknownOptionsAsArgs	val treatUnknownOptionsAsArgs
  hidden	val hiddenFromHelp

• The following methods on CliktCommand have been renamed: commandHelp -> help, commandHelpEpilog -> epilog. The old names are deprecated.

• Breaking Change: CliktCommand.main and CliktCommand.parse are now extension functions rather than methods.

• Breaking Change: Context.obj and Context.terminal, and OptionTransformContext.terminal are now extension functions rather than properties.

• Breaking Change: The RenderedSection and DefinitionRow classes have moved to AbstractHelpFormatter.

• Markdown support in the help formatter is no longer included by default. To enable it, include the :clikt-markdown dependency and call yourCommand.installMordantMarkdown() before parsing.

• Updated Kotlin to 2.0.0

Fixed

• Fixed excess arguments not being reported when allowMultipleSubcommands=true and a subcommand has excess arguments followed by another subcommand.
• Commands with printHelpOnEmptyArgs=true will no longer print help if an option has a value from an environment variable or value source. (#382)

Deprecated

• Deprecated Context.originalArgv. It will now always return an empty list. If your commands need an argv, you can pass it to them before you run them, or set in on the new Context.data map.
• Deprecated Context.expandArgumentFiles. Use Context.argumentFileReader instead.
• Renamed the following Context fields to be more consistent. The old names are deprecated.

old name	new name
Context.envvarReader	Context.readEnvvar
Context.correctionSuggestor	Context.suggestTypoCorrection
Context.argumentFileReader	Context.readArgumentFile
Context.tokenTransformer	Context.transformToken

Removed

• Removed previously deprecated experimental annotations.
• Removed MordantHelpFormatter.graphemeLength
• Removed TermUi

4.4.0

This release adds support for linuxArm64 and wasmJs targets.

4.3.0

Added

• Added 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)
• Added Context.registerClosable and Context.callOnClose to allow you to register cleanup actions that will be called when the command exits. (#395)

Fixed

• Fixed unrecognized modifier 'i' that happened on tab-completion when using sub command aliases. Thanks to @hick209 for the contribution. (#500)
• Make sure auto complete script works on zsh, fixing the error complete:13: command not found: compdef. Thanks to @hick209 for the contribution. (#499)

4.2.2

Changed

• Options and arguments can now reference option groups in their defaultLazy and other finalization blocks. They can also freely reference each other, including though chains of references. (#473)
• Updated Kotlin to 1.9.21 (#472)

4.2.1

Added

• Added toString implementations to options and arguments. (#434)
• Added CliktCommand.test overload that takes a vararg of Strings as the command line arguments. Thanks to @sschuberth for the contribution (#451)

Fixed

• Update Mordant dependency to fix crashes on native targets and GraalVM (#447)

4.2.0

Added

• Added requireConfirmation parameter to option().prompt() (#426)
• Added CliktCommand.terminal extension for accessing the terminal from a command.
• Added includeSystemEnvvars, ansiLevel, width, and height parameters to all CliktCommand.test overloads.

Deprecated

• Deprecated CliktCommand.prompt, use CliktCommand.terminal.prompt or Prompt instead.
• Deprecated CliktCommand.confirm, use YesNoPrompt instead.

4.1.0

Added

• Added 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)
• Added option().optionalValueLazy{}, which work like optionalValue() but the default value is computed lazily. (#381)

Changed

• Updated Kotlin to 1.9.0
• PrintMessage, PrintHelpMessage and PrintCompletionMessage now default to exiting with a status code 0, which is the behavior they had in 3.x. (#419)

4.0.0

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.

Highlights

Here are some of the highlights of this release. See CHANGELOG.md for a detailed list of changes.

Colors and Markdown in help output

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") }

Optional and vararg values for options

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.

Streamlined error handling

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)
    }
}

4.0.0-RC

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.

Highlights

Here are some of the highlights of this release. See CHANGELOG.md for a detailed list of changes.

Colors and Markdown in help output

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    │
└───────────┴────────┴──────┴────────┘

Optional and vararg values for options

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.

Streamlined error handling

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)
    }
}