Arguments API Reference¶

abstract class Arguments {
    // DSL methods for defining options
    fun option(vararg switches: String): OptionBuilder<String?>
    fun positional(name: String): PositionalBuilder<String?>
    fun domain(id: String?): DomainBuilder

    // Parsing methods
    fun parse(args: Array<String>): ParseResult
    fun parseOrExit(args: Array<String>): ParseResult.Success

    // Information methods
    fun selectedDomain(): String?
    fun terminal(): Terminal

    // Configuration
    fun settings(block: SettingsBuilder.() -> Unit)
    fun constraints(block: ConstraintsBuilder.() -> Unit)
}

class MyApp : Arguments() {
    // Define your options here
    val verbose by option("--verbose", "-v")
    val inputFile by positional("input")

    init {
        settings {
            appName = "myapp"
            appDescription = "My awesome CLI application"
        }
    }
}

// The property name becomes the internal identifier
val verbose by option("--verbose", "-v")
//  ^^^^^^^
//  This name is used for validation rules and error messages

// You can access the parsed value after calling parse()
if (verbose) {
    println("Verbose mode enabled")
}

fun main(args: Array<String>) {
    val app = MyApp()

    when (val result = app.parse(args)) {
        is Arguments.ParseResult.Success -> {
            // Arguments parsed successfully
            println("Input: ${app.inputFile}")
        }
        is Arguments.ParseResult.Help -> {
            // User requested help (--help)
            // Help has already been printed
        }
        is Arguments.ParseResult.Error -> {
            // Parsing failed
            // Error message has already been printed
            kotlin.system.exitProcess(1)
        }
    }
}

fun main(args: Array<String>) {
    val app = MyApp()

    // This will automatically:
    // - Print help and exit(0) if --help is used
    // - Print error and exit(1) if parsing fails
    // - Return only on successful parsing
    when (val result = app.parseOrExit(args)) {
        is Arguments.ParseResult.Success -> {
            // Always successful - no other cases to handle
            runApplication(app)
        }
    }
}

sealed class ParseResult {
    object Success : ParseResult()
    object Help : ParseResult()
    object Error : ParseResult()
}

init {
    settings {
        appName = "myapp"                    // Used in help text and error messages
        appDescription = "Description here"  // Shown in help header
        defaultLongPrefix = "--"             // Default prefix for long options
        defaultShortPrefix = "-"             // Default prefix for short options
        allowUnknownOptions = false          // Whether to allow undefined options
        stopAtFirstPositional = false       // Stop parsing at first positional arg
        terminal = ANSITerminal()            // Terminal implementation to use
    }
}

class GitApp : Arguments() {
    val commit by domain("commit")
    val push by domain("push")

    init {
        settings { appName = "git" }
    }
}

fun main(args: Array<String>) {
    val app = GitApp()
    app.parseOrExit(args)

    when (app.selectedDomain()) {
        "commit" -> handleCommit()
        "push" -> handlePush()
        null -> println("No subcommand selected")
    }
}

val app = MyApp()
val terminal = app.terminal()

// Use for custom output
terminal.emitStrong("Important: ")
terminal.emitPlain("This is a message")
terminal.emitNewLine()

// If user provides: --count invalid
// Error output:
❌ Error: Invalid value 'invalid' for --count (expected an integer)

// If required option is missing:
❌ Error: Missing required option --input-file

// If constraint violation:
❌ Error: Option --count must be at least 1 (got 0)

constraints {
    "port" requiredMin 1024 message "Port must be >= 1024 (ports below 1024 require root privileges)"
    "threads" requiredMax 16 message "Maximum 16 threads supported on this system"
}

init {
    constraints {
        custom("file-exists") { args ->
            val file = java.io.File(args.inputFile)
            if (!file.exists()) {
                "Input file '${args.inputFile}' does not exist"
            } else null
        }
    }
}

val port by option("--port")
    .int()
    .fromEnv("SERVER_PORT")  // Read from environment variable if not provided
    .default(8080)

val configFile by option("--config")
    .map { it?.let(::java.io.File) }

init {
    // Load configuration after parsing
    configFile?.let { file ->
        if (file.exists()) {
            loadConfiguration(file)
        }
    }
}

// Good: Clear what this option does
val maxRetries by option("--max-retries").int().default(3)

// Avoid: Unclear abbreviations
val mr by option("--mr").int().default(3)

val timeout by option("--timeout")
    .int()
    .default(30)
    .help("Connection timeout in seconds")

val threads by option("--threads")
    .int()
    .default(Runtime.getRuntime().availableProcessors())
    .help("Number of worker threads")

// Group networking options together
val host by option("--host").default("localhost")
val port by option("--port").int().default(8080)
val timeout by option("--timeout").int().default(30)

// Group output options together
val output by option("--output")
val format by option("--format").oneOf("json", "xml", "csv")
val pretty by option("--pretty")

// Good: Type-safe enum
enum class LogLevel { DEBUG, INFO, WARN, ERROR }
val level by option("--level").enum<LogLevel>()

// Avoid: String validation
val level by option("--level").oneOf("debug", "info", "warn", "error")

// kotlinx.cli
val input by argument(ArgType.String, description = "Input file")
val verbose by option(ArgType.Boolean, shortName = "v", description = "Verbose")

// Argos
val input by positional("input").help("Input file")
val verbose by option("--verbose", "-v").help("Verbose")

// JCommander
@Parameter(names = ["--input", "-i"], description = "Input file", required = true)
var input: String = ""

// Argos
val input by option("--input", "-i").required().help("Input file")

// Clikt
val input by argument(help = "Input file")
val verbose by option("--verbose", "-v").flag()

// Argos
val input by positional("input").help("Input file")
val verbose by option("--verbose", "-v").bool().help("Verbose mode")

// Don't do this
val sharedApp = MyApp()
// Multiple threads calling sharedApp.parse() - NOT SAFE

// Do this instead
fun parseInThread(args: Array<String>) {
    val app = MyApp() // New instance per thread
    app.parse(args)
}

fun createApp(): MyApp = MyApp()

// Later...
val app1 = createApp()
app1.parse(firstArgs)

val app2 = createApp()
app2.parse(secondArgs)