{"id":16122041,"url":"https://github.com/foxcapades/lib-kt-cli-builder","last_synced_at":"2026-01-11T05:49:18.332Z","repository":{"id":255611377,"uuid":"850780005","full_name":"Foxcapades/lib-kt-cli-builder","owner":"Foxcapades","description":"Kotlin-based CLI call generator.","archived":false,"fork":false,"pushed_at":"2024-09-17T16:57:26.000Z","size":2663,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-07T21:23:49.623Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Foxcapades.png","metadata":{"files":{"readme":"readme.adoc","changelog":null,"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":"2024-09-01T18:52:08.000Z","updated_at":"2024-09-17T16:52:03.000Z","dependencies_parsed_at":"2024-10-27T16:08:40.333Z","dependency_job_id":"23c50e22-0096-448d-b985-812b29eb0bac","html_url":"https://github.com/Foxcapades/lib-kt-cli-builder","commit_stats":{"total_commits":68,"total_committers":1,"mean_commits":68.0,"dds":0.0,"last_synced_commit":"1b45c0e4ffa914ecc9c53356aa9d276a6d5aa6b7"},"previous_names":["foxcapades/lib-kt-cli-builder"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-kt-cli-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-kt-cli-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-kt-cli-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxcapades%2Flib-kt-cli-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Foxcapades","download_url":"https://codeload.github.com/Foxcapades/lib-kt-cli-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246769965,"owners_count":20830769,"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-10-09T21:09:09.804Z","updated_at":"2026-01-11T05:49:18.327Z","avatar_url":"https://github.com/Foxcapades.png","language":"Kotlin","readme":"= CLI Call Builder\n:version-actual: 0.8.5\n:version-feature: 0.8.0\n:source-highlighter: highlightjs\n\nProvides delegates, annotations, and tools to generate CLI calls from\nclasses, making it easier to define type-safe, validating wrappers around\nexternal CLI tools.\n\nimage:https://img.shields.io/github/license/foxcapades/lib-kt-cli-builder[GitHub License]\nimage:https://img.shields.io/badge/docs-dokka-%230e86d4[API Documentation, link=\"https://foxcapades.github.io/lib-kt-cli-builder/{version-feature}\"]\nimage:https://img.shields.io/badge/kotlin-2.0.20-%237F52FF[Kotlin Version]\nimage:https://img.shields.io/badge/jvm-21-%23f90[Target JVM Version]\nimage:https://img.shields.io/maven-central/v/io.foxcapades.kt/cli-builder[Version, link=\"https://central.sonatype.com/artifact/io.foxcapades.kt/cli-builder/{actual-version}\"]\n\n\n== Usage\n\n.build.gradle.kts\n[source, kotlin, subs=\"attributes\"]\n----\n  implementation(\"io.foxcapades.kt:cli-builder:{version-actual}\")\n----\n\n=== Examples\n\n==== Delegates\n\nFlags and arguments may be defined on a type by use of the `Flag` or `Argument`\ndelegate types.\n\n[source, kotlin]\n----\n@CliCommand(\"my-command\")\nclass MyCommandConfig {\n  // creates a required `-i` flag with\n  val input by stringFlag('i') { required = true }\n\n  // creates an optional `-o` flag with a default value of \"-\"\n  val output by stringFlag('o') { default = \"-\" }\n\n  // creates an optional `--threads/-t` flag with a default value of \"1\"\n  val threads by intFlag(\"threads\", 't') { default = 1 }\n}\n----\n\n==== Annotations\n\nFlags and arguments may be defined on a type by use of the `@CliFlag` or\n`@CliArgument` annotations.\n\n[source, kotlin]\n----\n@CliCommand(\"my-command\")\ndata class MyCommandConfig(\n  // creates a required `-i` flag\n  @CliFlag(shortForm='i', required=true)\n  val input: String,\n\n  // creates an optional `-o` flag\n  @CliFlag(shortForm='o')\n  val output: String,\n\n  // creates an optional `--threads/-t` flag\n  @CliFlag(\"threads\", 't')\n  val threads: Int,\n)\n----\n\n==== Headless\n\n[source, kotlin]\n----\nclass MyCommandConfig : Command {\n  // Combine an annotation with a delegate\n  @CliFlag(\"input\", 'i')\n  var input by pathFlag()\n\n  override fun getCliCallComponents(config: CliSerializationConfig) =\n    \"my-command\" to listOf(::input)\n}\n\nval foo = MyCommandConfig()\nfoo.input = Path(\"path/to/some/file\")\n\nrequire(Cli.toCliString(foo) == \"my-command --input='path/to/some/file'\")\n----\n\n=== Building A CLI Command\n\nA CLI command is expected to be a value that is annotated with `@CliCommand`\nand/or implements the `Command` interface.\n\nA command may contain flags and/or arguments defined as delegated properties, as\nannotated values, or as raw `Flag` or `Argument` instances directly used as\nvalues from properties or getters.\n\nFor classes that implement the `Command` interface, the output of the\n`getCliCallComponents` method will be used as the source for what components may\nbe considered for inclusion in a generated CLI call.\n\n[source, kotlin]\n----\nclass MyCommandConfig : Command {\n  // Will not be considered when generated CLI calls as the getCliCallComponents\n  // method does not include this property.\n  var input by pathFlag()\n\n  override fun getCliCallComponents(config: CliSerializationConfig) =\n    \"my-command\" to emptyList()\n}\n----\n\nFor classes that instead use the `@CliCommand` annotation, the class will be\ninspected to determine what components may be considered for inclusion in a\ngenerated CLI call.\n\n[source, kotlin]\n----\n@CliCommand(\"my-command\")\nclass MyCommandConfig {\n  // Will be considered when generating CLI calls due to the @CliFlag annotation\n  @CliFlag(\"input\", 'i')\n  var input: Path?\n\n  // Will be considered when generating CLI calls as it is a Flag delegate\n  var output by pathFlag()\n\n  // Will be considered when generating CLI calls as it is an Argument value\n  val value: Argument\u003cString\u003e\n\n  // Will NOT be considered when generating CLI calls as it is a plain value\n  val toggle: Boolean\n}\n----\n\n==== Delegation vs Annotation vs Value\n\nTODO\n\nannotation can be combined with either delegate or value, but value and delegate\ncannot be used together.\n\nWhen an annotation is used in combination with either a delegate or a component\nvalue, the settings from the annotation take priority over the settings from\nthe component itself.\n\nTODO\n\nwhen using the `@CliCommand` annotation on an implementation of `Command`, the\ncommand name returned by the `getCliCallComponents` method is ignored.\nAdditionally, any positional args included in the annotation will precede the\ncomponents returned by the `getCliCallComponents` method.\n\n\n==== Component Filtering\n\nWhen and if individual components are included in a generated CLI call is based\non configurable predicates that are applied to components when they are to be\nserialized.\n\nThe default configuration for whether a flag should be included in a CLI call\nfalls through to the flag's argument predicate.\n\nThe default configuration for whether an argument should be included simply\ntests whether the argument has been explicitly set.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxcapades%2Flib-kt-cli-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoxcapades%2Flib-kt-cli-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxcapades%2Flib-kt-cli-builder/lists"}