Documenting Scripts¶
Clikt takes care of creating formatted help messages for commands.
There are a number of ways to customize the default behavior.
You can also implement your own HelpFormatter
and set it on the command’s context.
Help Texts¶
Commands and parameters accept a help argument. Commands also accept an epilog
argument, which is printed after the parameters and commands on the help page. All text is
automatically trimmed of leading indentation and re-wrapped to the terminal width.
As an alternative to passing your help strings as function arguments, you can also use the help()
extensions for your options, and override commandHelp and commandHelpEpilog on your commands.
These methods can access the terminal theme on the context to add color to your help text.
class Hello : CliktCommand(help = """
This script prints <name> <count> times.
<count> must be a positive number, and defaults to 1.
"""
) {
val count by option("-c", "--count", metavar="count", help = "number of greetings").int().default(1)
val name by argument()
override fun run() = repeat(count) { echo("Hello $name!") }
}
class Hello : CliktCommand() {
override fun commandHelp(context: Context): String {
val style = context.theme.info
return """
This script prints ${style("<name>")} ${style("<count>")} times.
${style("<count>")} must be a positive number, and defaults to 1.
""".trimIndent()
}
val count by option("-c", "--count", metavar="count").int().default(1)
.help { theme.success("number of greetings") }
val name by argument()
override fun run() = repeat(count) { echo("Hello $name!") }
}
$ ./hello --help
Usage: hello [<options>] <name>
This script prints <name> <count> times.
<count> must be a positive number, and defaults to 1.
Options:
-c, --count <count> number of greetings
-h, --help Show this message and exit
Option names and metavars will appear in help output even if no help string is specified for them. On the other hand, arguments only appear in the usage string. It is possible to add a help string to arguments which will be added to the help page, but the Unix convention is to just describe arguments in the command help.
Markdown in help texts¶
All help texts use Mordant to render Markdown. You can use all the normal markdown features, such as lists, tables, and even hyperlinks if your terminal supports them.
class Tool : NoOpCliktCommand() {
val option by option().help {
"""
| This | is | a | table |
| ---- | -- | - | ----- |
| 1 | 2 | 3 | 4 |
- This is
- a list
```
You can
use code blocks
```
""".trimIndent()
}
}
Usage: tool [<options>]
Options:
--option=<text> ┌──────┬────┬───┬───────┐
│ This │ is │ a │ table │
╞══════╪════╪═══╪═══════╡
│ 1 │ 2 │ 3 │ 4 │
└──────┴────┴───┴───────┘
• This is
• a list
╭───────────────────╮
│You can │
│ use code blocks│
╰───────────────────╯
-h, --help Show this message and exit
Manual Line Breaks¶
If you want to insert a line break manually without preformatting the entire paragraph, you can use
the Unicode Next Line (NEL) character. You can type a NEL with the unicode literal \u0085.
Clikt will treat NEL similarly to how <br> behaves in HTML: The NEL will be replaced with a line
break in the output, and the paragraph will still be wrapped to the terminal width.
class Tool : NoOpCliktCommand() {
val option by option()
.help("This help will be at least two lines.\u0085(this will start a new line)")
}
Usage: tool
Options:
--option This help will be at least
two lines.
(this will start a new
line)
-h, --help Show this message and exit
Tip
In raw multiline strings (which do not parse escape sequences),
you’ll need to insert the NEL with a string template such as ${"\u0085"}.
Subcommand Short Help¶
Subcommands are listed in the help page based on their name. They have a short help string which is the first line of their help.
class Tool : NoOpCliktCommand()
class Execute : NoOpCliktCommand(help = """
Execute the command.
The command will be executed.
""")
class Abort : NoOpCliktCommand(help="Kill any running commands.")
$ ./tool --help
Usage: tool [<options>] <command> [<args>]...
Options:
-h, --help Show this message and exit
Commands:
execute Execute the command.
abort Kill any running commands.
Help Option Customization¶
Clikt handles the help option is specially. It is added automatically to every command. Any help option name that conflicts with another option is not used for the help option. If the help option has no unique names, it is not added.
You can change the help option’s name and help message on the command’s context:
class HelpLocalization: Localization {
override fun helpOptionMessage(): String = "show the help"
}
class Tool : NoOpCliktCommand() {
init {
context {
helpOptionNames = setOf("/help")
localization = HelpLocalization()
}
}
}
$ ./tool /help
Usage: tool [<options>]
Options:
/help show the help
If you don’t want a help option to be added, you can set
helpOptionNames = emptySet()
Default Values in Help¶
You can configure the help formatter to show default values in the help output by passing
showDefaultValues = true to the MordantHelpFormatter. By default, the string value of the
default value will be shown. You can show a different value by passing the value you want to show to
the defaultForHelp parameter of default.
class Tool : NoOpCliktCommand() {
init {
context {
helpFormatter = { MordantHelpFormatter(it, showDefaultValues = true) }
}
}
val a by option(help = "this is optional").default("value")
val b by option(help = "this is also optional").default("value", defaultForHelp="chosen for you")
}
$ ./tool --help
Usage: tool [<options>]
Options:
--a <text> this is optional (default: value)
--b <text> this is also optional (default: chosen for you)
Required Options in Help¶
By default, required options are displayed the same way as other options. The help
formatter includes two different ways to show that an option is required.
Required Option Marker¶
You can pass a character to the requiredOptionMarker argument of the MordantHelpFormatter.
class Tool : NoOpCliktCommand() {
init {
context {
helpFormatter = { MordantHelpFormatter(it, requiredOptionMarker = "*") }
}
}
val option by option(help = "this is optional")
val required by option(help = "this is required").required()
}
$ ./tool --help
Usage: tool [<options>]
Options:
--option <text> this is optional
* --required <text> this is required
-h, --help Show this message and exit
Required Option Tag¶
You can also show a tag for required options by passing showRequiredTag = true to the
MordantHelpFormatter.
class Tool : CliktCommand() {
init {
context {
helpFormatter = { MordantHelpFormatter(it, showRequiredTag = true) }
}
}
val option by option(help = "this is optional")
val required by option(help = "this is required").required()
}
$ ./tool --help
Usage: tool [<options>]
Options:
--option <text> this is optional
--required <text> this is required (required)
-h, --help Show this message and exit
Grouping Options in Help¶
You can group options into separate help sections by using OptionGroup and importing groups.provideDelegate. The name of the group will be shown in the output. You can also add an extra help message to be shown with the group. Groups can’t be nested.
import com.github.ajalt.clikt.parameters.groups.provideDelegate
class UserOptions : OptionGroup(
name = "User Options",
help = "Options controlling the user"
) {
val name by option(help = "user name")
val age by option(help = "user age").int()
}
class Tool : NoOpCliktCommand() {
val userOptions by UserOptions()
}
$ ./tool --help
Usage: cli [<options>]
User Options:
Options controlling the user
--name <text> user name
--age <int> user age
Options:
-h, --help Show this message and exit
Suggesting Corrections for Mistyped Parameters¶
When an option or subcommand is mistyped, Clikt will suggest corrections that are similar to the typed value.
$ ./cli --sise=5
Error: no such option: "--sise". Did you mean "--size"?
$ ./cli building
Usage: cli [<options>] <command> [<args>]...
Error: no such subcommand: "building". Did you mean "build"?
By default, Clikt will suggest corrections of any similar option or subcommand name based on a
similarity metric. You can customize the suggestions by setting a correctionSuggestor on your
command’s context.
class Cli : NoOpCliktCommand() {
init {
context {
// Only suggest corrections that start with the entered value
correctionSuggestor = { enteredValue, possibleValues ->
possibleValues.filter { it.startsWith(enteredValue) }
}
}
}
}
Localization¶
You can localize error messages by implementing Localization and setting the
localization property on your context.
class CursiveLocalization : Localization {
override fun usageTitle() = "𝒰𝓈𝒶𝑔𝑒:"
override fun optionsTitle() = "𝒪𝓅𝓉𝒾𝑜𝓃𝓈"
override fun optionsMetavar() = "𝑜𝓅𝓉𝒾𝑜𝓃𝓈"
override fun helpOptionMessage() = "𝒮𝒽𝑜𝓌 𝓉𝒽𝒾𝓈 𝓂𝑒𝓈𝓈𝒶𝑔𝑒 𝒶𝓃𝒹 𝑒𝓍𝒾𝓉"
// ... override the rest of the strings here
}
class I18NTool : NoOpCliktCommand(help = "𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒") {
init {
context { localization = CursiveLocalization() }
}
}
$ ./i18ntool --help
𝒰𝓈𝒶𝑔𝑒: i18ntool [<𝑜𝓅𝓉𝒾𝑜𝓃𝓈>]
𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒
𝒪𝓅𝓉𝒾𝑜𝓃𝓈:
-h, --help 𝒮𝒽𝑜𝓌 𝓉𝒽𝒾𝓈 𝓂𝑒𝓈𝓈𝒶𝑔𝑒 𝒶𝓃𝒹 𝑒𝓍𝒾𝓉