0
# Clikt
1

2
Clikt is a multiplatform Kotlin library that makes writing command line interfaces simple and intuitive. It provides a type-safe, declarative DSL for parsing command line arguments, with support for subcommands, parameter groups, shell completion, and rich terminal output.
3

4
## Package Information
5

6
- **Package Name**: clikt-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  - Gradle: `implementation("com.github.ajalt.clikt:clikt:4.4.0")`
11
  - Maven: `<dependency><groupId>com.github.ajalt.clikt</groupId><artifactId>clikt</artifactId><version>4.4.0</version></dependency>`
12

13
## Core Imports
14

15
```kotlin
16
import com.github.ajalt.clikt.core.CliktCommand
17
import com.github.ajalt.clikt.parameters.options.*
18
import com.github.ajalt.clikt.parameters.arguments.*
19
```
20

21
For completion and advanced features:
22

23
```kotlin
24
import com.github.ajalt.clikt.completion.*
25
import com.github.ajalt.clikt.parameters.groups.*
26
import com.github.ajalt.clikt.sources.*
27
```
28

29
## Basic Usage
30

31
```kotlin
32
import com.github.ajalt.clikt.core.CliktCommand
33
import com.github.ajalt.clikt.parameters.options.option
34
import com.github.ajalt.clikt.parameters.options.required
35
import com.github.ajalt.clikt.parameters.arguments.argument
36

37
class Hello : CliktCommand() {
38
    private val greeting by option("-g", "--greeting", help="Greeting to use").required()
39
    private val name by argument(help="Name of person to greet")
40

41
    override fun run() {
42
        echo("$greeting $name!")
43
    }
44
}
45

46
fun main() = Hello().main()
47
```
48

49
## Architecture
50

51
Clikt is built around several key components:
52

53
- **CliktCommand**: Base class for all CLI commands with parameter registration and execution lifecycle
54
- **Parameter System**: Type-safe parameter parsing with delegated properties for options and arguments
55
- **Context Management**: Hierarchical context system for configuration, error handling, and state management
56
- **Transformation Pipeline**: Composable parameter processing with conversion, validation, and default value handling
57
- **Multi-platform Support**: Common API with platform-specific implementations for file handling and terminal operations
58

59
The library follows a builder pattern with method chaining, making it easy to compose complex parameter configurations while maintaining type safety and readability.
60

61
## Capabilities
62

63
### Core Commands
64

65
Foundation command classes and execution framework for building CLI applications. The CliktCommand class provides the base functionality for parameter registration, parsing, and execution.
66

67
```kotlin { .api }
68
abstract class CliktCommand(
69
    help: String = "",
70
    epilog: String = "",
71
    name: String? = null,
72
    invokeWithoutSubcommand: Boolean = false,
73
    printHelpOnEmptyArgs: Boolean = false,
74
    helpTags: Map<String, String> = emptyMap(),
75
    allowMultipleSubcommands: Boolean = false,
76
    treatUnknownOptionsAsArgs: Boolean = false,
77
    hidden: Boolean = false
78
) {
79
    abstract fun run()
80
    fun main(argv: List<String>)
81
    fun echo(message: Any?, trailingNewline: Boolean = true, err: Boolean = false)
82
}
83
```
84

85
[Core Commands](./core-commands.md)
86

87
### Options
88

89
Declarative option parsing with type conversion, validation, and default values. Options are declared as delegated properties with a fluent API for configuration.
90

91
```kotlin { .api }
92
fun CliktCommand.option(
93
    vararg names: String,
94
    help: String = "",
95
    metavar: String? = null,
96
    hidden: Boolean = false,
97
    helpTags: Map<String, String> = emptyMap(),
98
    envvar: String? = null,
99
    valueSourceKey: String? = null,
100
    completionCandidates: CompletionCandidates? = null
101
): RawOption
102

103
fun <T : Any> RawOption.convert(
104
    metavar: String,
105
    conversion: ValueConverter<String, T>
106
): NullableOption<T, T>
107
```
108

109
[Options](./options.md)
110

111
### Arguments
112

113
Positional argument parsing with type conversion and validation. Arguments are processed in order and support optional, multiple, and paired value patterns.
114

115
```kotlin { .api }
116
fun CliktCommand.argument(
117
    name: String = "",
118
    help: String = "",
119
    helpTags: Map<String, String> = emptyMap(),
120
    completionCandidates: CompletionCandidates? = null
121
): RawArgument
122

123
fun <T : Any> RawArgument.convert(
124
    conversion: ArgValueConverter<String, T>
125
): ProcessedArgument<T, T>
126
```
127

128
[Arguments](./arguments.md)
129

130
### Parameter Types
131

132
Built-in type converters for common data types including numeric types, enums, choices, and platform-specific types like files and paths.
133

134
```kotlin { .api }
135
fun RawOption.int(): NullableOption<Int, Int>
136
fun RawOption.string(): NullableOption<String, String>
137
fun RawOption.boolean(): NullableOption<Boolean, Boolean>
138
fun <T : Enum<T>> RawOption.enum(): NullableOption<T, T>
139
fun <T : Any> RawOption.choice(choices: Map<String, T>): NullableOption<T, T>
140
```
141

142
[Parameter Types](./parameter-types.md)
143

144
### Parameter Groups
145

146
Organize related parameters into groups with mutual exclusion, co-occurrence, and choice-based selection patterns.
147

148
```kotlin { .api }
149
open class OptionGroup(name: String? = null, help: String? = null)
150

151
fun ParameterHolder.mutuallyExclusiveOptions(
152
    vararg options: OptionDelegate<*>
153
): MutuallyExclusiveOptions
154

155
fun <T : Any> CliktCommand.groupChoice(
156
    vararg choices: Pair<String, T>
157
): ParameterGroupDelegate<T?>
158
```
159

160
[Parameter Groups](./parameter-groups.md)
161

162
### Shell Completion
163

164
Generate shell completion scripts for Bash and Fish, with support for dynamic completion candidates including files, hostnames, and custom completions.
165

166
```kotlin { .api }
167
sealed class CompletionCandidates {
168
    object None : CompletionCandidates()
169
    object Path : CompletionCandidates()
170
    object Hostname : CompletionCandidates()
171
    object Username : CompletionCandidates()
172
    data class Fixed(val candidates: Set<String>) : CompletionCandidates()
173
    data class Custom(val generator: (ShellType) -> String?) : CompletionCandidates()
174
}
175

176
interface CompletionGenerator {
177
    fun generateScript(commandName: String, command: CliktCommand): String
178
}
179
```
180

181
[Shell Completion](./shell-completion.md)
182

183
### Configuration Sources
184

185
Load parameter values from external sources including environment variables, configuration files, and custom value providers with priority chaining.
186

187
```kotlin { .api }
188
interface ValueSource {
189
    data class Invocation(val values: List<String>)
190
    fun getValues(context: Context, option: Option): List<Invocation>
191
}
192

193
class MapValueSource(private val map: Map<String, String>) : ValueSource
194
class ChainedValueSource(private val sources: List<ValueSource>) : ValueSource
195
```
196

197
[Configuration Sources](./configuration-sources.md)
198

199
### Error Handling
200

201
Comprehensive exception hierarchy for different types of CLI errors and command execution failures. All exceptions provide structured error information for proper error handling and user feedback.
202

203
```kotlin { .api }
204
open class CliktError(
205
    message: String?,
206
    cause: Exception? = null,
207
    val statusCode: Int = 1,
208
    val printError: Boolean = true
209
) : RuntimeException(message, cause)
210

211
open class UsageError(
212
    message: String? = null,
213
    val paramName: String? = null,
214
    statusCode: Int = 1
215
) : CliktError(message, null, statusCode)
216

217
class BadParameterValue(
218
    message: String,
219
    paramName: String? = null,
220
    statusCode: Int = 1
221
) : UsageError(message, paramName, statusCode)
222
```
223

224
[Error Handling](./exceptions.md)
225

226
### Testing Utilities
227

228
Test command execution with controlled input/output, environment variables, and terminal settings for comprehensive CLI testing.
229

230
```kotlin { .api }
231
data class CliktCommandTestResult(
232
    val stdout: String,
233
    val stderr: String,
234
    val output: String,
235
    val statusCode: Int
236
)
237

238
fun CliktCommand.test(
239
    argv: String,
240
    stdin: String = "",
241
    envvars: Map<String, String> = emptyMap(),
242
    includeSystemEnvvars: Boolean = false,
243
    ansiLevel: AnsiLevel = AnsiLevel.NONE,
244
    width: Int = 79,
245
    height: Int = 24
246
): CliktCommandTestResult
247
```
248

249
[Testing Utilities](./testing-utilities.md)
250

251
## Types
252

253
### Core Types
254

255
```kotlin { .api }
256
abstract class CliktCommand(/* constructor parameters */)
257

258
class Context(
259
    val parent: Context?,
260
    val command: CliktCommand,
261
    val allowInterspersedArgs: Boolean = true,
262
    val allowGroupedShortOptions: Boolean = true,
263
    val autoEnvvarPrefix: String? = null,
264
    val printExtraMessages: Boolean = true,
265
    val helpOptionNames: Set<String> = setOf("-h", "--help"),
266
    val terminal: Terminal,
267
    val valueSource: ValueSource? = null,
268
    val localization: Localization = defaultLocalization,
269
    val obj: Any? = null
270
)
271

272
interface Option
273
interface Argument
274
interface ParameterGroup
275
```
276

277

278
### Type Aliases
279

280
```kotlin { .api }
281
typealias ValueConverter<InT, ValueT> = OptionTransformContext.(InT) -> ValueT
282
typealias ArgValueConverter<InT, ValueT> = ArgumentTransformContext.(InT) -> ValueT
283
typealias OptionValidator<T> = OptionTransformContext.(T) -> Unit
284
typealias ArgValidator<T> = ArgumentTransformContext.(T) -> Unit
285
```