Upgrading to Newer Releases¶

See the changelog for a full list of changes in each release. This guide contains information on the most significant changes that may require updating to your code.

Upgrading to 5.0¶

some methods like `main` are now extensions¶

The CliktCommand.main and CliktCommand.parse methods are now extension functions, so you’ll need to import them.

+ import com.github.ajalt.clikt.core.main
fun main(args: Array<String>) = MyCommand().main(args)

Context.obj and Context.terminal, and OptionTransformContext.terminal are also now extensions.

+ import com.github.ajalt.clikt.core.obj
+ import com.github.ajalt.clikt.core.terminal

fun main() {
    val ctx = MyCommand().currentContext
    ctx.terminal.info(ctx.obj)
}

`CliktCommand` constructor no longer takes most parameters¶

All parameters of the CliktCommand except for name have been moved to open properties.

In 5.0In 4.0

class MyCommand : CliktCommand(name="mycommand") {
    override fun help(context: Context) = "command help"
    override fun helpEpilog(context: Context) = "command epilog"
    override val invokeWithoutSubcommand = true
    override val printHelpOnEmptyArgs = true
    override val helpTags = mapOf("tag" to "value")
    override val autoCompleteEnvvar = "MYCOMMAND_COMPLETE"
    override val allowMultipleSubcommands = true
    override val treatUnknownOptionsAsArgs = true
    override val hiddenFromHelp = true
}

class MyCommand : CliktCommand(
    name = "mycommand",
    help = "command help",
    helpEpilog = "command epilog",
    invokeWithoutSubcommand = true,
    printHelpOnEmptyArgs = true,
    helpTags = mapOf("tag" to "value"),
    autoCompleteEnvvar = "MYCOMMAND_COMPLETE",
    allowMultipleSubcommands = true,
    treatUnknownOptionsAsArgs = true,
    hiddenFromHelp = true,
) {
}

The full list of moved parameters:

removed parameter	new 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`

Markdown moved to a separate module¶

In order to reduce executable size, the Markdown rendering functionality has been moved to a separate module.

To use Markdown rendering first, add the :clitk-markdown dependency to your project:

dependencies {
   implementation("com.github.ajalt.clikt:clikt-markdown:$cliktVersion")
}

Then install the markdown help formatter on your command:

val command = MyCommand().installMordantMarkdown()

`Context` builder properties renamed¶

Some of the properties on Context and its builder have been renamed to be more consistent:

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

The old names are still available as deprecated properties.

Removed `TermUi`¶

The remaining methods in TermUi have been removed. If you were using it, you can open an editor manually with ProcessBuilder or similar.

Upgrading to 4.0¶

Help formatting¶

The CliktHelpFormatter class has been removed and replaced with the MordantHelpFormatter. The MordantHelpFormatter constructor takes a Context instead of a Localization, and the parameters controlling size and spacing have been removed. See the documentation for details on how to set the help formatter on the Context.

If you were subclassing CliktHelpFormatter, MordantHelpFormatter’s open methods are different. See the helpformat sample for an example of how to use the new formatter.

Prompting¶

The CliktConsole class has been removed. If you were using it, use your command’s Mordant terminal instead.

The prompt and confirm methods now use Mordant’s prompting functionality, and some of their arguments have changed. In particular, conversion lambdas now return a ConversionResult instead of throwing an exception.

In 4.0In 3.0

val input = prompt("Enter a number") {
    it.toIntOrNull()
        ?.let { ConversionResult.Valid(it) }
        ?: ConversionResult.Invalid("$it is not a valid integer")
}

val input = prompt("Enter a number") {
    it.toIntOrNull() ?: throw BadParameterValue("$it is not a valid integer")
}

Upgrading to 3.0¶

Maven Coordinates¶

Clikt’s Maven groupId changed from com.github.ajalt to com.github.ajalt.clikt. So the full coordinate is now com.github.ajalt.clikt:clikt:3.0.0.

With the new Multiplatform plugin in Kotlin 1.4, there is no longer a separate clikt-multiplatform artifact. You can use com.github.ajalt.clikt:clikt:3.0.0 for both JVM-only and Multiplatform projects.

Environment variable splitting¶

There used to be an envvarSplit parameter to option() and its convert() that would split values coming from an environment variable. This parameter is removed, and values from environment variables are no longer split automatically.

If you still want to split option values, you can do so explicitly with split().

Experimental APIs¶

The Value Source API and Completion Generation APIs no longer require opt-in. You can use these APIs without needing the ExperimentalValueSourceApi or ExperimentalCompletionCandidates annotations.

Localization¶

By default, all strings are defined in the Localization object set on your context.

This means that string parameters like usageTitle in the constructor for CliktHelpFormatter have been removed in favor of functions like Localization.usageTitle().

Context.helpOptionMessage has also been removed in favor of Localization.helpOptionMessage(). See Help Option Customization for an example.