{"id":13532525,"url":"https://github.com/Kotlin/kotlinx-cli","last_synced_at":"2025-04-01T20:32:16.855Z","repository":{"id":39855048,"uuid":"104216599","full_name":"Kotlin/kotlinx-cli","owner":"Kotlin","description":"Pure Kotlin implementation of a generic CLI parser.","archived":false,"fork":false,"pushed_at":"2023-09-01T16:05:12.000Z","size":350,"stargazers_count":899,"open_issues_count":35,"forks_count":67,"subscribers_count":36,"default_branch":"master","last_synced_at":"2024-05-18T19:24:03.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kotlin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-20T13:07:21.000Z","updated_at":"2024-08-01T07:33:43.068Z","dependencies_parsed_at":"2024-08-01T07:43:50.146Z","dependency_job_id":null,"html_url":"https://github.com/Kotlin/kotlinx-cli","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kotlin","download_url":"https://codeload.github.com/Kotlin/kotlinx-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246709923,"owners_count":20821297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T07:01:11.619Z","updated_at":"2025-04-01T20:32:11.845Z","avatar_url":"https://github.com/Kotlin.png","language":"Kotlin","funding_links":[],"categories":["Kotlin","[Kotlin](https://kotlinlang.org/)","Additional Languages"],"sub_categories":["Useful awesome list for Go cli","Kotlin 🎯"],"readme":"# kotlinx-cli\n\n[![Kotlin Experimental](https://kotl.in/badges/experimental.svg)](https://kotlinlang.org/docs/components-stability.html)\n[![JetBrains obsolete project](https://jb.gg/badges/obsolete.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)\n[![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-cli.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-cli)\n\n## This library is obsolete\n\nIt is effectively unmaintained. Please consider using other libraries.\n\n## Description\n\nPure Kotlin implementation of a generic command-line parser.\n\n* Declarative: describe what your commands and parameters are \n* Platform-agnostic: core library has no platform-specific dependencies and can be used in any Kotlin project \n* Hackable: build extensions on top of it however you like\n\n`kotlinx-cli` can be used to create user-friendly and flexible command-line interfaces\nfor Kotlin/JVM, Kotlin/Native, and any other Kotlin console applications.\nProgram defines what arguments are expected.\n`kotlinx-cli` will figure out how to parse those, reporting errors if the program arguments are invalid,\nand also generate help and usage messages as well.\n\n## Using in your projects\n\n\u003e Note that the library is experimental and the API is subject to change.\n\nThe library is published to Maven Central repository.\n\n### Gradle\n\n- Add the Maven Central repository if it is not already there:\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n```\n\nIn Kotlin multiplatform projects, add the following dependency to a source set (it may be a common or platform specific source set):\n\n```groovy\nkotlin {\n    sourceSets {\n        commonMain {\n             dependencies {\n                 implementation(\"org.jetbrains.kotlinx:kotlinx-cli:0.3.6\")\n             }\n        }\n    }\n}\n```\n\n### Maven\n\nIn Kotlin projects, add the following dependency to the `dependencies` element of `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.jetbrains.kotlinx\u003c/groupId\u003e\n    \u003cartifactId\u003ekotlinx-cli-jvm\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.6\u003c/version\u003e\n\u003c/dependency\u003e\n```\n## Command line entities\nThere are 2 base entity: option and argument.\n\n*Option* - command line entity started with some prefix (-/--) and can have value as next entity in command line string.\n\n*Argument* - command line entity which role is connected only with its position.\n\nCommand line entities can be several types:\n* ArgType.Boolean\n* ArgType.Int\n* ArgType.String\n* ArgType.Double\n* ArgType.Choice (value can be only from predefined list)\n\nCustom types can be created.\n\n### Example\n\n```kotlin\nimport kotlinx.cli.*\n\nfun produce(result: List\u003cDouble\u003e, format: String, outputFileName: String?) {\n    outputFileName.let {\n        // Print to file.\n        ...\n    } ?: run {\n        // Print to stdout.\n        ...\n    }\n}\n\nfun readFrom(inputFileName: String): String {\n    ...\n}\n\nfun calculate(inputData: String, eps: Double, debug: Boolean = false): List\u003cDouble\u003e {\n    ...\n}\n\nenum class Format {\n    HTML,\n    CSV,\n    PDF\n}\n\nfun main(args: Array\u003cString\u003e) {\n    val parser = ArgParser(\"example\")\n    val input by parser.option(ArgType.String, shortName = \"i\", description = \"Input file\").required()\n    val output by parser.option(ArgType.String, shortName = \"o\", description = \"Output file name\")\n    val format by parser.option(ArgType.Choice\u003cFormat\u003e(), shortName = \"f\", \n        description = \"Format for output file\").default(Format.CSV).multiple()\n    val stringFormat by parser.option(ArgType.Choice(listOf(\"html\", \"csv\", \"pdf\"), { it }), shortName = \"sf\", \n        description = \"Format as string for output file\").default(\"csv\").multiple()\n    val debug by parser.option(ArgType.Boolean, shortName = \"d\", description = \"Turn on debug mode\").default(false)\n    val eps by parser.option(ArgType.Double, description = \"Observational error\").default(0.01)\n\n    parser.parse(args)\n    val inputData = readFrom(input)\n    val result = calculate(inputData, eps, debug)\n    format.forEach {\n        produce(result, it, output)\n    }\n}\n```\n\nIt's also possible to use arguments in current example.\n\n```kotlin\n...\n    val input by parser.argument(ArgType.String, description = \"Input file\")\n    val output by parser.argument(ArgType.String, description = \"Output file name\").optional()\n```\n\nAuto-generated help message for this example is\n```\nUsage: example options_list\nArguments: \n    input -\u003e Input file { String }\n    output -\u003e Output file name (optional) { String }\nOptions: \n    --format, -f [csv] -\u003e Format for output file { Value should be one of [html, csv, pdf] }\n    --debug, -d [false] -\u003e Turn on debug mode \n    --eps [0.01] -\u003e Observational error { Double }\n    --help, -h -\u003e Usage info\n```\n\n## Subcommands\n\nIf application has rich command line interface and executes different actions with different arguments,\n subcommands can be useful.\n \n```kotlin\n@file:OptIn(ExperimentalCli::class)\n\nimport kotlinx.cli.*\n\nfun main(args: Array\u003cString\u003e) {\n    val parser = ArgParser(\"example\")\n    val output by parser.option(ArgType.String, \"output\", \"o\", \"Output file\")\n    class Summary: Subcommand(\"summary\", \"Calculate summary\") {\n        val invert by option(ArgType.Boolean, \"invert\", \"i\", \"Invert results\").default(false)\n        val addendums by argument(ArgType.Int, \"addendums\", description = \"Addendums\").vararg()\n        var result: Int = 0\n\n        override fun execute() {\n            result = addendums.sum()\n            result = if (invert!!) -1 * result else result\n        }\n    }\n    class Multiply: Subcommand(\"mul\", \"Multiply\") {\n        val numbers by argument(ArgType.Int, description = \"Addendums\").vararg()\n        var result: Int = 0\n\n        override fun execute() {\n            result = numbers.reduce{ acc, it -\u003e acc * it }\n        }\n    }\n    val summary = Summary()\n    val multiple = Multiply()\n    parser.subcommands(summary, multiple)\n\n    parser.parse(args)\n}\n```\n\nThen help information will be available for each subcommand separately.\n\nIn case of `example summary -h` help info will be\n```\nUsage: example summary options_list\nArguments: \n    addendums -\u003e Addendums { Int }\nOptions: \n    --invert, -i -\u003e Invert results \n    --help, -h -\u003e Usage info \n```\n\nIn case of `example mul -h` help info will be\n```\nUsage: example mul options_list\nArguments: \n    numbers -\u003e Addendums { Int }\nOptions: \n    --help, -h -\u003e Usage info\n```\n    \nThe boolean property `strictSubcommandOptionsOrder` defines the allowed order of options and arguments for subcommands. \nWhen it is `false` (default), then the main program's options can be specified everywhere, even after the subcommand.\nOtherwise, parameters can only be specified after the subcommands where they are defined. For example,\n\n```kotlin\n@file:OptIn(ExperimentalCli::class)\n\nimport kotlinx.cli.*\n\nfun main(args: Array\u003cString\u003e) {\n    val parser = ArgParser(\"example\", strictSubcommandOptionsOrder = true)\n    val output by parser.option(ArgType.String, \"output\", \"o\", \"Output file\")\n\n    class Multiply: Subcommand(\"mul\", \"Multiply\") {\n        val numbers by argument(ArgType.Int, description = \"Addendums\").vararg()\n        var result: Int = 0\n\n        override fun execute() {\n            result = numbers.reduce{ acc, it -\u003e acc * it }\n        }\n    }\n    val multiple = Multiply()\n    parser.subcommands(summary, multiple)\n\n    parser.parse(args)\n}\n```\n`example -o out.txt mul 1 2 3 -o out.txt # OK`\n\n`example mul 1 2 3 -o out.txt # fail in this case, but OK if strictSubcommandOptionsOrder is false`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKotlin%2Fkotlinx-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKotlin%2Fkotlinx-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKotlin%2Fkotlinx-cli/lists"}