Rapidly build powerful command-line applications powered by ZIO
ZIO CLI turns a typed description of a command line into a working program. We describe the commands, options and arguments a program accepts, and ZIO CLI parses the user's input into Scala values, reports errors, and generates the help text from the same description.
Key features of ZIO CLI:
- Typed options and arguments: Text, numbers, booleans, dates, paths, enumerations and key-value pairs are parsed into Scala types.
- Commands and subcommands: Programs such as
git remote addare built from small commands that compose. - Generated help: The
--helpoutput, usage line and error messages come from the command description, so they never drift from the code. - Built-in features: Every app gets
--help, an interactive--wizardmode and bash completion without extra code. - Testing support: The
zio-cli-testkitmodule checks parsing and app behaviour inside ZIO Test. - Cross-platform: The library runs on the JVM, Scala.js and Scala Native.
ZIO CLI is published for Scala 2.12, 2.13 and 3. To use it on the JVM, add the following to your build.sbt file:
// Commands, options, arguments, generated help, wizard mode and shell completion (JVM, Scala.js, Scala Native)
libraryDependencies += "dev.zio" %% "zio-cli" % "0.8.2"For Scala.js or Scala Native projects, use %%% instead:
// Commands, options, arguments, generated help, wizard mode and shell completion (JVM, Scala.js, Scala Native)
libraryDependencies += "dev.zio" %%% "zio-cli" % "0.8.2"The Getting Started page walks through a first program.
Besides the core library, ZIO CLI has a module for tests and an sbt plugin.
The testkit adds assertions and generators that check how commands parse their input and how apps behave. To use it on the JVM, add it as a test dependency:
// Assertions and generators for testing commands and apps with ZIO Test (JVM, Scala.js, Scala Native)
libraryDependencies += "dev.zio" %% "zio-cli-testkit" % "0.8.2" % TestFor Scala.js or Scala Native projects, use %%% instead:
// Assertions and generators for testing commands and apps with ZIO Test (JVM, Scala.js, Scala Native)
libraryDependencies += "dev.zio" %%% "zio-cli-testkit" % "0.8.2" % TestThe Testing reference lists the assertions, and How to test a CLI app shows them in use.
The ZIO CLI sbt plugin is not published to Maven Central; the sbt Plugin page explains how to build it from source and what it provides.
The following program implements a small part of git clone, with one boolean option, one argument and help text for both:
import zio.Console.printLine
import zio.cli._
import zio.cli.HelpDoc.Span.text
object GitClone extends ZIOCliDefault {
val local: Options[Boolean] =
Options.boolean("local").alias("l") ?? "Clone from a repository on this machine."
val repository: Args[String] =
Args.text("repository") ?? "The repository to clone."
val cloneCommand: Command[(Boolean, String)] =
Command("clone", local, repository).withHelp("Creates a copy of an existing repository.")
val cliApp = CliApp.make(
name = "Sample Git",
version = "1.1.0",
summary = text("Sample implementation of git clone"),
command = cloneCommand
) { case (isLocal, repo) =>
printLine(s"Cloning $repo (local: $isLocal)")
}
}Running the program with -l https://github.com/zio/zio-cli.git prints Cloning https://github.com/zio/zio-cli.git (local: true). Running it with --help prints a banner with the app name, followed by help text generated from the description:
Sample Git 1.1.0 -- Sample implementation of git clone
USAGE
$ clone [(-l, --local)] <repository>
DESCRIPTION
Creates a copy of an existing repository.
ARGUMENTS
<repository>
A user-defined piece of text.
The repository to clone.
OPTIONS
(-l, --local)
A true or false value.
Clone from a repository on this machine.
This setting is optional. Default: 'false'.
Learn more on the ZIO CLI homepage!
For the general guidelines, see ZIO contributor's guide.
See the Code of Conduct