Skip to content

Exception Handling

Clikt uses exceptions internally to signal that processing has ended early for any reason. This includes incorrect command line usage, or printing a help page.

Where are Exceptions Handled?

When you call CliktCommand.main, it will parse the command line and catch any CliktError exceptions. If it catches one, it will then print out the error’s message and exit the process with the error’s statusCode. The message is printed to stderr or stdout depending on the error’s printError property.

For exceptions raised by Clikt, PrintMessage and PrintHelpMessage have a statusCode of 0 and print to stdout. Other exceptions have a statusCode of 1 and print to stderr.

Any other types of exceptions indicate a programming error, and are not caught by main. However, convert and the other parameter transformations will wrap exceptions thrown inside them in a UsageError, so if you define a custom transformation, you don’t have to worry about an exception escaping to the user.

Handling Exceptions Manually

CliktCommand.main is just a try/catch block surrounding CliktCommand.parse, so if you don’t want exceptions to be caught, you can call parse wherever you would normally call main.

Tip

You can use echoFormattedHelp to print the help or error message to any exception, or getFormattedHelp to get the help message as a string.

fun main(args: Array<String>) {
    val cli = Cli()
    try {
        cli.parse(args)
    } catch (e: CliktError) {
        cli.echoFormattedHelp(e)
        exitProcess(e.statusCode)
    }
}

Which Exceptions Exist?

All exceptions thrown by Clikt are subclasses of CliktError.

The following subclasses exist:

  • Abort : The command should exit immediately with the given statusCode without printing any messages.
  • PrintMessage : The exception’s message should be printed.
  • PrintHelpMessage : The help page for the exception’s command should be printed.
  • PrintCompletionMessage : Shell completion code for the command should be printed.
  • UsageError : The command line was incorrect in some way. All the following exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.
  • MultiUsageError : Multiple UsageErrors occurred. The errors property contains the list of the errors.
  • ProgramResult : The program should exit with the statusCode from this exception.
  • BadParameterValue : A parameter was given the correct number of values, but of invalid format or type.
  • MissingOption and MissingArgument: A required parameter was not provided.
  • NoSuchOption : An option was provided that does not exist.
  • NoSuchSubcommand : A subcommand was called that does not exist.
  • IncorrectOptionValueCount : An option was supplied but the number of values supplied to the option was incorrect.
  • IncorrectArgumentValueCount : An argument was supplied but the number of values supplied was incorrect.
  • MutuallyExclusiveGroupException : Multiple options in a mutually exclusive group were supplied when the group is restricted to a single value.
  • FileNotFound : A required configuration file or @-file was not found.
  • InvalidFileFormat : A configuration file or @-file failed to parse correctly.