{"id":13566570,"url":"https://github.com/zio/zio-cli","last_synced_at":"2025-10-25T14:36:51.838Z","repository":{"id":40522879,"uuid":"261205274","full_name":"zio/zio-cli","owner":"zio","description":"Rapidly build powerful command-line applications powered by ZIO","archived":false,"fork":false,"pushed_at":"2025-03-18T17:42:40.000Z","size":812,"stargazers_count":132,"open_issues_count":5,"forks_count":82,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-26T08:02:00.517Z","etag":null,"topics":["cli","command-line","scala","zio"],"latest_commit_sha":null,"homepage":"https://zio.dev/zio-cli","language":"Scala","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/zio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-04T14:30:15.000Z","updated_at":"2025-03-21T17:52:36.000Z","dependencies_parsed_at":"2024-08-01T13:23:44.709Z","dependency_job_id":"fa5fb29d-fb01-4e0a-9a67-bbd45ea458c2","html_url":"https://github.com/zio/zio-cli","commit_stats":{"total_commits":219,"total_committers":51,"mean_commits":4.294117647058823,"dds":0.7899543378995434,"last_synced_commit":"5b509020a76cce2806b0e8d5a2218ebd95e65a6b"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zio","download_url":"https://codeload.github.com/zio/zio-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246777832,"owners_count":20832032,"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":["cli","command-line","scala","zio"],"created_at":"2024-08-01T13:02:12.244Z","updated_at":"2025-10-25T14:36:46.803Z","avatar_url":"https://github.com/zio.png","language":"Scala","funding_links":[],"categories":["Scala"],"sub_categories":[],"readme":"[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)\n[//]: # (So please do not edit it manually. Instead, change \"docs/index.md\" file or sbt setting keys)\n[//]: # (e.g. \"readmeDocumentation\" and \"readmeSupport\".)\n\n# ZIO CLI\n\nRapidly build powerful command-line applications powered by ZIO\n\n[![Experimental](https://img.shields.io/badge/Project%20Stage-Experimental-yellowgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-cli/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-cli_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-cli_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-cli_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-cli_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-cli-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-cli-docs_2.13) [![ZIO CLI](https://img.shields.io/github/stars/zio/zio-cli?style=social)](https://github.com/zio/zio-cli)\n\n## Installation\n\nTo use **ZIO CLI**, we need to add the following to our `build.sbt` file:\n\n```scala\nlibraryDependencies += \"dev.zio\" %% \"zio-cli\" % \"0.6.0\"\n```\n## Getting Started\n**ZIO CLI** allows to easily construct a CLI application. A CLI or Command-Line Interface is an application that allows the user to give instructions by means of pieces of text called commands. A command has the following structure\n```\ncommand param1 param2 ... paramN\n```\nwhere `command` is the name of the command and `param1`, `param2`, ..., `paramN` form a list of parameters depending on the command that determines the precise instruction to the CLI application.\n\nGiven the case, a command itself might contain subcommands. This allows a better design of the command-line application and a more comfortable user experience.\n\nA command might include arguments and options.\n- Arguments are name-less and position-based parameters that the user specifies just by the position in the command. As an example, we can consider the widely used command-line application Git. One subcommand is `clone`. It creates a copy of an existing repository. An argument of `git clone` is `repository`. If the repository name is `https://github.com/zio/zio-cli.git`, we will use it in the following manner:\n```\ngit clone https://github.com/zio/zio-cli.git\n```\n\n\n- Options are named and position-independent parameters that are specified by writing the content after the name. The name is preceded by `--`. An option may have a shorter form called an alias. When the alias is used instead of the full name, only `-` is needed. An option of command `git clone` is `local`. It is a boolean option, so it is not necessary to write true or false after it: it will be true only if it appears. It is used in the following manner:\n```\ngit clone --local\n```\nIt also has an alias `-l`:\n```\ngit clone -l\n```\n\nThe description of the command `git clone`, taking only into account option `local` and argument `repository` will be\n```\ngit clone [-l] \u003crepository\u003e\n```\nwhere `[]` implies that the option is optional and `\u003c\u003e` indicates an argument.\n\n\n### Difference between Args and Options\nArguments and options are different due to the way the user specifies them. Arguments are not specified using its name, only by the position inside the command. On the other hand, options must be preceded by its name and `--` indicating that it is the name of an option. \n\nFurthermore, a command-line application will represent them in different ways. Argument's name will be inside `\u003c\u003e` while an option will be preceded by `--`. In case that the option has a short form or alias, this will be preceded by `-`.\n\n### First ZIO CLI example\n\n This is done by defining `cliApp` value from `ZIOCliDefault` using `CliApp.make` and specifying a `Command` as parameter. A `Command[Model]` is a description of the commands of a CLI application that allows to specify which commands are valid and how to transform the input into an instance of `Model`. Then it is possible to implement the logic of the CLI application in terms of `Model`. As a sample we are going to create a command of Git. We are going to implement only command `git clone` with argument `repository` and option `local`.\n\n```scala\nimport zio.cli._\nimport zio.cli.HelpDoc.Span.text\nimport zio.Console.printLine\n\n// object of your app must extend ZIOCliDefault\nobject Sample extends ZIOCliDefault {\n\n  /**\n   * First we define the commands of the Cli. To do that we need:\n   *    - Create command options\n   *    - Create command arguments\n   *    - Create help (HelpDoc) \n   */\n  val options: Options[Boolean] = Options.boolean(\"local\").alias(\"l\")\n  val arguments: Args[String] = Args.text(\"repository\")\n  val help: HelpDoc = HelpDoc.p(\"Creates a copy of an existing repository\")\n  \n  val command: Command[(Boolean, String)] = Command(\"clone\").subcommands(Command(\"clone\", options, arguments).withHelp(help))\n  \n  // Define val cliApp using CliApp.make\n  val cliApp = CliApp.make(\n    name = \"Sample Git\",\n    version = \"1.1.0\",\n    summary = text(\"Sample implementation of git clone\"),\n    command = command\n  ) {\n    // Implement logic of CliApp\n    case _ =\u003e printLine(\"executing git clone\")\n  }\n}\n```\nThe output will be\n```\n   _____@       @           @        @   __@     @       @  ______@   _ @  __ @\n  / ___/@ ____ _@  ____ ___ @   ____ @  / /@ ___ @       @ / ____/@  (_)@ / /_@\n  \\__ \\ @/ __ `/@ / __ `__ \\@  / __ \\@ / / @/ _ \\@       @/ / __  @ / / @/ __/@\n ___/ / / /_/ / @/ / / / / /@ / /_/ /@/ /  /  __/@       / /_/ /  @/ /  / /_  @\n/____/  \\__,_/  /_/ /_/ /_/ @/ .___/ /_/   \\___/ @       \\____/   /_/   \\__/  @\n        @       @           /_/      @     @     @       @        @     @     @\n\n\nSample Git v1.1.0 -- Sample implementation of git clone\n\nUSAGE\n\n  $ clone clone [(-l, --local)] \u003crepository\u003e\n\nCOMMANDS\n\n  clone [(-l, --local)] \u003crepository\u003e  Creates a copy of an existing repository\n```\n\nIf there is a `CliApp`, you can run a command using its method `run` and passing parameters in a `List[String]`.\n\n## References\n\n- [10 Minute Command-Line Apps With ZIO CLI](https://www.youtube.com/watch?v=UeR8YUN4Tws) by Aiswarya Prakasan\n- [Hacking on ZIO-CLI](https://www.youtube.com/watch?v=HxPCXfnbg3U) by Adam Fraser and Kit Langton\n- [Behold! The Happy Path To Captivate Your Users With Stunning CLI Apps!](https://www.youtube.com/watch?v=0c3zbUq4lQo) by Jorge Vasquez\n\n## Documentation\n\nLearn more on the [ZIO CLI homepage](https://zio.dev/zio-cli/)!\n\n## Contributing\n\nFor the general guidelines, see ZIO [contributor's guide](https://zio.dev/contributor-guidelines).\n\n## Code of Conduct\n\nSee the [Code of Conduct](https://zio.dev/code-of-conduct)\n\n## Support\n\nCome chat with us on [![Badge-Discord]][Link-Discord].\n\n[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord \"chat on discord\"\n[Link-Discord]: https://discord.gg/2ccFBr4 \"Discord\"\n\n## License\n\n[License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzio%2Fzio-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-cli/lists"}