For user convenience, it might make sense to allow passing global options as if they were sub-command options. For example, instead of requiring the user to write

command --root-option subcommand --sub-option

clikt could allow to write

command subcommand --root-option --sub-option

This would work unless there is an option name clash between the global command and the sub-command, in which case the sub-command-specific option should take precedence.

AFAIK there's currently no elegant way to achieve this in clikt, so maybe it makes sense to implement this as a core feature toggle on the context, like subcommandsInheritGlobalOptions or allowGlobalOptionsForSubcommands.

Not an issue, rather a question:

Example

CliktCommand(help = "Sentence1.\nSentence2.")

Will generate help text without the newline characters. I have tried \n and \r. Am I asking for the impossible (im not familiar with cli low lvl impl) or am I doing something wrong?

I am trying this with gitbash on Windows.

Following version 2.40, it appears the releases of Clikt on JCenter haven't been kept up-to-date. Would it be possible to make the last few releases available?

I'm always having trouble remembering what checks exactly are performed for the different parameters to file(). For example, does exists = false check whether the file does not exist and fail otherwise? (No, it does not.) While that's part of the documentation, I believe this could be made more clear by renaming parameters. How about:

• exists -> verifyExists
• fileOkay -> canBeFile
• folderOkay -> canBeDir
• writable -> mustBeWritable
• readable -> mustBeReadable

file() currently fails for a path like ~/my-file.txt as ~ is not expanded. It would be great if ~ would be expanded when running on shells that support it similar to like we do here, maybe by introducing an expandTilde parameter to file() which defaults to true.

Currently the NonInteractiveCliktConsole only reads in the first line of any input file passed as the input stream.

This can be fixed by caching the buffered reader like I have below.

class NonInteractiveCliktConsole : CliktConsole {
    private val bufferedReader by lazy {
        System.`in`.bufferedReader()
    }

    override fun promptForLine(prompt: String, hideInput: Boolean) = try {
        print(prompt, false)
        bufferedReader.readLine()
    } catch (err: IOException) {
        null
    }

    override fun print(text: String, error: Boolean) {
        if (error) {
            System.err
        } else {
            System.out
        }.print(text)
    }

    override val lineSeparator: String get() = System.lineSeparator()
}

I'm using version 1.5.0.

Am I doing something wrong or do I need to specify options before arguments in command? And if so, is it somewhere in the documentation and I am just blind?

Example code:

private val files by argument().file().pair()
private val offsets by argument().int().pair()
private val length by argument().int()    // should be optional integer
private val display by option().switch("-f" to First, "-l" to Largest).default(None)

The idea is to be able to do cmd path1 path2 0 0 1024 -f or cmd path1 path2 0 0 -f but it doesn't seem to work unless I put the flag in the front: cmd -f path1 path2 0 0 1024.

If this is some limitation of the parser it should be stated clearly in the docs. If this should work, can anyone point me in the right direction?

I thing something is wrong between Kotest 4.2.4 and Clikt 3.0.1

Then I'm wrtiting this class in the test sources directory:

class ATestCommand : CliktCommand() {
    private val environment: String? by option("-e", "--env")
    override fun run() {
        println("Env: $environment")
    }
}

gives an intellj error on option:

Overload resolution ambiguity: 
public fun ParameterHolder.option(vararg names: String, help: String = ..., metavar: String? = ..., hidden: Boolean = ..., envvar: String? = ..., helpTags: Map<String, String> = ..., completionCandidates: CompletionCandidates? = ..., valueSourceKey: String? = ...): RawOption /* = OptionWithValues<String?, String, String> */ defined in com.github.ajalt.clikt.parameters.options
public fun ParameterHolder.option(vararg names: String, help: String = ..., metavar: String? = ..., hidden: Boolean = ..., envvar: String? = ..., envvarSplit: Regex? = ..., helpTags: Map<String, String> = ..., completionCandidates: CompletionCandidates? = ...): RawOption /* = OptionWithValues<String?, String, String> */ defined in com.github.ajalt.clikt.parameters.options

Same class in source no problem.

Noticed that while was trying to figure out why I can't run any test on a command.

when I run the test:

class ATestCommandTest() : FunSpec({
    test("test should run without throwing NoSuchMethodError") {
        ATestCommand().parse(emptyArray())
    }
})

I got the error:

'com.github.ajalt.clikt.parameters.options.OptionWithValues com.github.ajalt.clikt.parameters.options.OptionWithValuesKt.option$default(com.github.ajalt.clikt.core.ParameterHolder, java.lang.String[], java.lang.String, java.lang.String, boolean, java.lang.String, java.util.Map, com.github.ajalt.clikt.completion.CompletionCandidates, java.lang.String, int, java.lang.Object)'
java.lang.NoSuchMethodError: 'com.github.ajalt.clikt.parameters.options.OptionWithValues com.github.ajalt.clikt.parameters.options.OptionWithValuesKt.option$default(com.github.ajalt.clikt.core.ParameterHolder, java.lang.String[], java.lang.String, java.lang.String, boolean, java.lang.String, java.util.Map, com.github.ajalt.clikt.completion.CompletionCandidates, java.lang.String, int, java.lang.Object)'

This does not happen if I use JUnit 5 in place of Kotest.

My build.gradle.kts (useful parts)

plugins {
    application
    kotlin("jvm") version "1.4.10"
}
// ...
dependencies {
    implementation("com.github.ajalt.clikt:clikt:3.0.1")
    implementation("com.typesafe:config:1.4.0")

    testImplementation("io.kotest:kotest-runner-junit5:4.2.4") // for kotest framework
    testImplementation("io.kotest:kotest-assertions-core:4.2.4") // for kotest core jvm assertions
    testImplementation("io.kotest:kotest-property:4.2.4") // for kotest property test
    testImplementation("io.mockk:mockk:1.10.0")
}
// ...
tasks.withType<KotlinCompile>() {
    kotlinOptions.jvmTarget = "11"
}

tasks.withType<Test>() {
    useJUnitPlatform()
}
// ...

Thanks

Here's my first stab at supporting i18n of Clikt output.

All exceptions and conversions now pull their strings from a Localization object configured on the current context. Right now, that object is an interface with all default methods. This should allow me to add strings in the future without breaking ABI compatibility. I kept all logic other than simple string interpolation out of the Localization implementation, although that leads to some weirdness when dealing with plurals and lists values.

For example, the error message when too many arguments are present is currently split into two:

fun extraArgumentOne(name: String) = "Got unexpected extra argument $name"
fun extraArgumentMany(name: String, count: Int) = "Got unexpected extra arguments $name"

But languages that pluralize differently than english will need to add some logic to extraArgumentMany anyway, so maybe it's better to combine those two functions.

Joining sentences together is also introduces some redundancy. For example, the error when you type an option that doesn't exist might include typo corrections. Right now, there are two functions:

fun noSuchOption(name: String) = "no such option: $name"
fun noSuchOption(name: String, suggestion: String) = "no such option: $name. $suggestion"

Maybe it would be better to make the suggestion parameter nullable and let the implementations deal with it?

The last problem is when joining lists. For example, the suggestions for typo correction are a list of names. Right now the prefix and postfix are separate strings, and the caller joins them:

fun possibleOptionsPrefix() = "(Possible options: "
fun possibleParameterPostfix() = ")"

That feels clunky. Maybe it would be better to just pass in the list of items and have the implementation join them?

Finally, there are a couple of places that define strings that aren't in the Localization. The CliktHelpFormatter has a few constructor parameters for things like the usageTitle. We could read those from Localization, but other help formatters might not need those strings, so maybe it's better to leave them separate.

The other place that doesn't read from Localization is the metavar parameters to option() and convert(). There's no context at the time options are defined, so I'm not sure what to do here. We could change the parameter from String to (Context) -> String, although that's kind of clunky. As-is, you'll have to manually specify the metavar for every option if you want it localized.

Fixes #227

Hi,

any chance of supporting the browser target, even with reduced functionality?

Would be very handy for me because I like to have a small shell in my SPA-s so I can issue commands manually, no need to build a whole interface. It is very similar to a terminal.

I've checked kotlinx.cli and it is very "noisy".

Thanks in advance, tiz

Thanks for writing this library. I was wondering if you have / would consider making it possible to test error handling and custom return codes?

The idea is when implementing a CliktComand or including it into another library / framework for their users would want to do the following:

• Provide a facility for custom exit codes, making it easier for automation down the road to use that to make decisions, for instance some errors might be worth retrying
• Test that error messages and codes are being generated correctly, this is mostly checking exception logic

Challenges & Possible Solutions

Challenges I've encountered so far and some thoughts towards a solution, but those solutions themselves have accompanying issues:

• main functions in CliktCommand are final making it hard
• main(List), parse, and run do not return numbers so exit codes can't be seamlessly passed through
• CliktError, Abort, and friends don't accept return codes -- these should probably be optional parameters (defaulted to current codes)
• main(List) calls exitProcess making the logic not testable indirectly (less of a concern for library consumers) but going down a path of an extensible and testable strategy it might be worth returning the exit code to main(Array) and it having a single exitProcess:

fun main(argv: List<String>): Int { /* snip */ }

fun main(argv: Array<String>) = exitProcess(main(argv.asList()))

I can completely understanding being hesitant about adding return parameters to these functions as they're the entry point everyone uses, but the breakage should be very easy to fix. I can create a speculative pull request if you want to see what a possible set of changes might look like and we can see what options there might be.

What I've Tried

Below is an example where I've done it from as a consumer of the library, this is within the broader context of me creating a tiny web framework mimicking Dropwizard's single fat jar which allows you to run migrations, start an application server, add custom sub-commands, etc...

import com.github.ajalt.clikt.core.CliktCommand
import kotlin.system.exitProcess

abstract class Command (
        help: String = "",
        epilog: String = "",
        name: String? = null,
        invokeWithoutSubcommand: Boolean = false
    ): CliktCommand(
        help = help,
        epilog = epilog,
        name = name,
        invokeWithoutSubcommand = invokeWithoutSubcommand) {

    companion object {
        const val SUCCESS = 0
        const val COMMAND_PARSING_ERROR = 1 // used by Clikt
        const val ERROR_WHILE_COMMAND_RUNNING = 2
    }

    /**
     * Implement [doRun] and don't use [main]
     */
    final override fun run() {
        val exitCode = try {
            doRun()
        } catch (e: Exception) {
            exceptionHandler(e)
        }

        exitProcess(exitCode)
    }
    
    abstract fun doRun(): Int
    
    open fun exceptionHandler(e: Exception) = ERROR_WHILE_COMMAND_RUNNING
}

In JS, the file execution never returns after the prompt() call back to the main thread where it was called from.

(some internal await / callback issue maybe)

When I create a CliktCommand with printHelpOnEmptyArgs set to true, with an option, if I launch my program without any option but with environment variables, they are not considered by the parser and the help message is printed.

Expected : if environment variables matching defined options exist, they should be considered to don't print the help message (as corresponding options can be filled)

When I try the autocomplete feature in bash with file names that contain spaces, the completion fails, because the parts of the name are treated separately.

So if I have a file named file with spaces.txt and type fi, then nothing happens on first TAB (despite no other file matches fi), and on the second TAB I get the list: file spaces.txt with as possible completions, which is the correctly found filename, but the parts sorted alphabetically.

It looks for me like the result of some missing quotes or something like that, but I know very few of bash autocompletion, so I don't know how to fix it.

I think there is a design issue in Clikt, It tries todo too much.

Ideally I just want to have an argument parser, and use that where-ever its needed. (Command line tools for example).

But Clikt really requires you to use inheritance and not composition. Composition allows for plug and play of the argument parser, like https://github.com/Kotlin/kotlinx-cli does.

I actually tried using Clikt initially, but found issues where clikt already defines the main function so I cannot use it directly. Next to that, it requires subclassing, so i cant use clikt in a class that already is subclassing an abstract class.

All in all, this makes clikt less usable/pluggable. It would be nice if clikt could be use without subclassing. And just as an argument parser tool, not as a command runner tool.

Hi there! Big fan of clikt, this project is awesome. We have made a practice of extending certain clikt classes including CliktCommand to get additional or supportive functionality we've desired.

One capability we desire is to extend OptionGroup so our CLI can debug log the assigned values passed to all options. Our CLI has a DEBUG flag, and an increasing number of options. It would help greatly with debugging and maintainability to report all assigned settings passed into the OptionGroup.

https://github.com/ajalt/clikt/blob/master/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt#L76

We don't have a slick way of doing this currently, because access to OptionGroup.options is marked as internal. Any reason this field cannot be made protected instead, so advanced users can access all options in a group dynamically? This is a small change, but it would be a huge help.

The mkdocs website (https://ajalt.github.io/clikt/) currently shows "3.4.0" while the GitHub sources shows "3.5.0".

Not a huge deal but automating that process would make sure both pages stay in sync.