Upgrading to Newer Releases¶

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.