• integer (BigInt)
• decimal (BigDecimal)
• path (java.io.file.Path). For this one, we should accept (optionally) some options like: should it exist or not exist (or doesn't matter?)? should it be a file or a directory (or doesn't matter?)?
• all java.time structures (instant, datetime, etc.)

The Options constructors create a wide range of options. Their validate method and other methods should be documented and tested in OptionsSpec.

Grouping is a feature whereby boolean, single-letter flags may be clustered together.

For example, instead of writing:

wc -l -c -w

You could write:

wc -lcw

Supporting this is tricky, because it requires two things:

1. All of the clustered options need to be of type boolean.
2. The clustered option cannot match any other option.

This seems to require "global knowledge" but right now the validation / parsing only has "local" knowledge; that is, every Options may only have access to part of the command-line arguments and may not know about the decisions about other Options and Args.

Displaying help should work for subcommands, and such help pages should make it clear that the help they are displaying is not the top-level help, but rather, help for the specific subcommand.

e.g.:

git merge --help

Operators like optional and alias work on Single only. This way it's not possible to do
Options.bool("fullname", true).alias("f")

Single should be an implementation detail instead. All constructors and operations should return Options[A].

ZIO 2.0 is at Milestone 4, with an RC expected in the next few weeks.
https://github.com/zio/zio/releases/tag/v2.0.0-M4

The API is nearly stable at this point, so any early migration work against this version should pay off towards the official 2.0 release.

The progress is being tracked here:
zio/zio#5470

The Stream Encoding work in progress is the only area where the API might still change before the RC.

We are actively working on a ScalaFix rule that will cover the bulk of the simple API changes:
https://github.com/zio/zio/blob/series/2.x/scalafix/rules/src/main/scala/fix/Zio2Upgrade.scala
We highly recommend starting with that, and then working through any remaining compilation errors :)

To assist with the rest of the migration, we have created this guide:
https://zio.dev/howto/migrate/zio-2.x-migration-guide/

@kitlangton Has already done a substantial amount of the work required.

The user of ZIO CLI must define a CLIApp, which is the command-line application itself. One of the fields is Command, which represents the top-level command of the CLI application.

Currently, this command is kept separate from the "built-in" options that CLIApp supports, including --help, and in the future, --version. This means that when a user prints out help documentation, the --help option is not included in the help documentation.

In order to avoid this problem, we need to push the help option and other options into the user's own command structure. Probably, this can be done by adding a new method to Command, such as:

sealed trait Command[A] {
  ...
  def addOption[B](opt: Options[B]): Command[Either[B, A]]
  ...
}

Then with this new method, the --help option that CLIApp provides "for free" can be cleanly integrated into the existing user's Command, so that when --help is run, that option appears with other documented help options.

Once a parser is written, this can be used to render the name of the CLI application in a nice way, e.g.:

 ______ _____  _____      _______        _____
  ____/   |   |     | ___ |       |        |  
 /_____ __|__ |_____|     |_____  |_____ __|__                                              

Example here and some discussion on format here.

https://zio.github.io/zio-cli/ is giving a 404 right now.

Is this project discontinued?

See here for a tutorial, here for the reference, and #2 for the corresponding Bash ticket for more details.

Currently running app --help just prints name of the commands but it would be nice if it also prints Summary or Header information along with the name similar to following git --help command

Currently, HelpDoc.toPlaintext is implemented. However, some details are not preserved well in plaintext format, but can be captured more precisely using HTML. Therefore, we should implement a renderer to HTML on HelpDoc, which tries to create a beautiful and useful representation of the help documentation for a CLI application.

The PrimType values are the primitive types in ZIO CLI, and represent things like strings or numbers or paths. They have, principally, a validate method which attempts to validate the value of a primitive type.

Tests and Scala doc should be added for all PrimType classes.

All the PrimType methods need a validator / parser. The method has been sketched out but not implemented.

This can be used to render the name of the CLI application in a nice way, e.g.:

 ______ _____  _____      _______        _____
  ____/   |   |     | ___ |       |        |  
 /_____ __|__ |_____|     |_____  |_____ __|__                                              

Example here and some discussion on format here.

This will be used in conjunction with #1.

A user-defined ADT, consisting of sealed traits, case classes, and strings/collections, could, in theory, be used to derive a Command that produces a data structure of that type.

For example:

case class WordCount(c: Boolean, l: Boolean, w: Boolean)

val wordCount: Command[WordCount] = DeriveCommand.genCommand

This can be done using Magnolia, and following a pattern similar to ZIO JSON.

We should also add annotations to provide custom details which cannot be inferred from the structure of the ADT alone.

Using custom assertions and / or other combinators, it should be easy to test ZIO CLI applications, feeding them test "standard input" and validating standard error / standard output, as well as process exit codes.

The installer or package should do the following:

• Download the GraalVM native image or Docker image
• Add the CLI application to the path
• Add completions for bash and zshell

Inspiration could be taken from Fury which seems to do a nice job with this.

Introduce a test spec for HelpDoc.scala. Look to test tricky combination and things like:

what happens when you have a header, then you have an enumeration (bulletpoint list), and inside the bulletpoint list, you have another bulletpoint list. Does toPlaintext do the right thing?

I am using ZIO in my current project and I would like to include CLI functionality. Unfortunately, this github repo has a broken documentation link and the README.md file has no info on how to import this library into a project.

Please provide information how to import this into my project, it would be greatly appreciated. Note: I am using gradle.

There are places in the code that use List[HelpDoc]. However, two help docs can be combined into one using +. So this is not necessary. In fact, we can change all code that currently uses the type List[HelpDoc] into an ordinary HelpDoc.

This ticket is to create a new module in the repository, called examples. This module will define CLIApp (command-line applications) for a variety of simple existing or fictional command-line applications.

Examples could include:

• wc
• cat
• tail

These examples should demonstrate a range of features of ZIO CLI, including booleans, options, flags, arguments, custom documentation, and more.

This will be similar to ZIO's Zippable, which helps deal with awkward nesting of tuples when zipping polymorphic effects. In our case, don't want to be forced to .map(_._2), when the left or right hand side of a composed Command/Options/Args is a Unit. These Units are usually the cruft of combining Options or Args values that do not generate a value. For example:

Command("something", Options.none, Args.int) will generate a Command[(Unit, Int)]. Though, with this new capability, it should return Command[Int].

I'd recommend taking a look at the implementation of Zippable as well as the Zymposium on Path Dependent Types.

The process standard input should be available as a ZStream from ZIO environment, so that CLI applications that process the standard input can do so easily.

The structure of Command permits an interactive mode that generates menus and prompts, e.g.:

Please enter the command you would like to execute:

1. commit — Commits the changes
2. version — Prints out the version
...


Please enter the boolean flags you would like to use:

[ ] (f) Force — Forces the deletion
[ ] (r) Remove — Removes the files

Please enter any combination of r, f: 

This ticket is to prototype such a wizard mode, which will walk the user through providing arguments and options using interactive menu prompts.

Right now command separates options and args into 2 state channels and there is no way to merge into 1 piece of state (i.e. a single case class).

If we can make Options.none and Args.none extend Option[Nothing]/Args[Nothing], then we'll be able to provide default values for these in the Command.apply method. Currently, you need to write Args.none or Options.none, which isn't as nice as it could be.

There are two potential points of integration:

• It should be possible to generate a ZIO Config descriptor from a CLI specification. This would allow code that uses ZIO Config to plug a nice CLI on top.
• It should be possible to load ZIO Config data as a set of "defaults", that can be overwritten using CLI information. For example, like .gitconfig and .jvmopts and many other command-line utilities that support reading common options from a standardized location.

/cc @afsalthaj

Currently, ParserOptions are not threaded down into PrimType#validate, which means the primitive types cannot take advantage of any parser-specific settings. This could be useful, especially in the future. So we should refactor the validate method to take the parser options.

When using subcommands, the generated synopsis for non-leaf subcommands does not include the partial subcommand "path."

For example, given a sub command structure

foo
└── a
    └── one
        ├── blue
        └── red

such that foo a one blue is a leaf command, the Synopsis section in --help documentation doesn't include relevant subcommand names.

Example:
Any level of non-leaf subcommand foo a --help, foo a one --help, produces

SYNOPSIS

    foo   <command> [<args>]

The expected output for foo a --help would be

SYNOPSIS

    foo a <command> [<args>]

and for foo a one --help

SYNOPSIS

    foo a one <command> [<args>]

and for foo a one blue --help

SYNOPSIS

    foo a one blue [<args>]

Note that the expected synopsis for a leaf command does not include the string <command> (whereas it is included in the current code), but that can be considered a separate issue.

Bonus nitpick

There's an extra space in here :)

SYNOPSIS

    foo   <command> [<args>]
       ^^^

There is a type HelpDoc in the code now, and various methods that generate help doc, implemented with ??? for now.

All these methods need to be implemented.

Several commands can be supported by default, including:

• --help which displays help on standard output. This variation should work with commands and subcommands, and display specific / tailored help if appropriate.
• --version which displays version information on standard output

It should be possible for users to "opt out" of these default commands or override them in some fashion.

Overview

There is a failing spec in master:

[info] - PrimTypeTests
[info]   - Boolean Suite
[info]     - validate false combinations returns proper Boolean representation

Changes Requested

Fix the failing spec

Bash is a common shell for Linux / BSD operating systems. Bash has a feature whereby you can have the shell auto-complete options for a command-line argument, which can simplify usage of command-line applications.

See here for a tutorial and here for more extensive documentation.

Given a CLI, we should be able to nicely generate a bash script that when sourced, will add all appropriate completions using the complete process.

See CLIApp#completions.

We need to parse the command-line options into the data type required by the user.

(Args.file("files", true) *).validate("doesNotExist.file" :: Nil, ParserOptions.default)

fails with

List(Paragraph(Error(Text(Unexpected arguments for command wc: List(doesNotExist.file)))))

expected

List(Paragraph(Error(Text(doesNotExist.file is not a recognized path.))))

Can be reproduced by running the WcApp Example with unrecognized file.

My investigation so far:

validate in Variadic turns a validation failure into a success without consuming the argument. The unconsumed argument leads to "Unexpected arguments..."

CLI applications should be able to dump information to standard output / standard error (possibly via a stream?).

Would be nice to integrate with Github Actions to run tests on pull requests and merges to master.

Any volunteers? 😄

If a command or flag is not recognized verbatim, then using Levenstein distance calculation, the closest command(s) / flag(s) can be identified, and the suggestion made to the user.

e.g.:

> myapp load -forc -source foo.txt

- The flag "-forc" is not recognized. Did you mean "-force"?

In order to implement this feature, a simple Levenstein distance function can be implemented. Atop this, a separate method can be added to Command, perhaps, autoCorrections, which returns a List[HelpDoc] containing any possible auto-corrections.

Then, inside CLIApp, if it is not possible to parse the command-line arguments, then auto-corrections can be generated.

Args should support:

• optional, required, and variadic
• providing a name for an argument (this will be important when generating help and docs)
• providing a description

We need a test case that when we have something like git merge (a top-level command git with a subcommand merge), that the subcommand parses off the subcommand name (merge) from the command-line arguments, before trying to parse its own options and args.

When using nested subcommands, subcommand description text is not displayed next to each subcommand in the synopsis SUBCOMMANDS section. This would be helpful for usage understanding, and a cursory reading of the source for zio-cli seems to suggest that it was originally intended behavior.

Given a subcommand hierarchy like this

foo
└── a
    └── one
        ├── blue
        └── red

the command foo a one --help produces

SYNOPSIS

    foo   <command> [<args>]

SUBCOMMANDS

      - red

      - blue

The expected output would have some brief summary of subcommands red and blue to the right of their enumeration.

Currently thanks to @TobiasPfeifer and @ashprakasan, we have some examples of ZIO CLI in the Example.scala.

However, we should extract these examples into a separate top-level project, make sure each of them is in a separate file, and try to more fully flesh them out or add other examples that demonstrate more of ZIO CLI's features for options and arguments.

For boolean options, we should support an optional negation name, such that, for example:

-v

turns the option ON, where as:

-V

turns the option OFF.

Property arguments are options (which may be repeated) whose values are actually key/value pairs.

Example syntax:

-Dkey=value
-D key1=value key2=value

To support these, we probably need a new Options.Map which parses options of the specified name (-D in these examples) into a map, where the key and value types could be PrimType.

Currently, --help is only available for the top-level command. This is inconvenient, because we have full documentation for all subcommands. Yet, at the same time, we cannot display all documentation on a single page. We should wait until the user requests help for a subcommand to print the help.

Thus, our subcommand help can work a bit like git:

git fetch --help

Now, in order to make this work, we need to take care of a few details:

1. First, the way subcommand help is printed out will be somewhat different from the way the top-level command is printed out. We should look to git and other complicated CLI tools for inspiration.
2. Second, we need to ensure we can print out help even if a parent command does not have all of its required options and arguments. If we were to do a simple process of augmenting the child commands with --help, then we would only succeed in parsing them if the parents succeeded too. But for help, we really want to ignore required arguments/options for parents, and give the user help anyway. We need to make sure this is possible.
3. Third, we need to ensure the way it is rendered looks good for commands with subcommands, both the top-level help, as well as the subcommand help, and that it scales for subcommands of subcommands of subcommands (etc.).

The Args constructors create a wide range of options. Their validate method and other methods should be documented and tested in ArgsSpec.

A small and simple SBT plug-in that can package up a CLI application as a GraalVM native docker image would make it much easier to prepare ZIO CLI applications for deployment.

Perhaps this could be a source of inspiration or a component of this solution.

When using nested subcommands, the generated help doc does not list subcommands for any non-leaf subcommand whose distance from a leaf is > 1.

For example, given a sub command structure

foo
└── a
    └── one
        ├── blue
        └── red

The this command correctly enumerates subcommands in the SUBCOMMANDS section in the help doc

foo a one --help

But these commands do not

foo --help

foo a --help