decline

CLI Idioms

decline supports standard Unix command-line patterns:

• Flags: Boolean switches (e.g., --quiet).
• Options: Key-value pairs (e.g., --target <string>).
• Positional Arguments: Arguments identified by position.
• Subcommands: Hierarchical command structures.
• Mutually-exclusive options: Ensuring only one of a set of options is provided.
• Custom validations: Logic to ensure input meets specific criteria.

Design Principles

• Full-featured: Supports complex CLI shapes including subcommands and validation.
• Helpful: Automatically generates usage text and precise error messages.
• Functional: Built on cats, providing an immutable and functional API that works in both functional and imperative codebases.

decline does not provide Argument instances for some types to encourage more idiomatic CLI patterns:

• Boolean: Instead of --verbose true, use Opts.flag("verbose", "...").orFalse to support the idiomatic --verbose flag.
• java.io.File / java.net.URL: Use java.nio.file.Path and java.net.URI instead, as they are modern alternatives.
• List[A]: To avoid complex comma-separated parsing issues, use Opts.options or Opts.arguments to allow users to repeat the flag (e.g., --exclude foo --exclude bar) instead of providing a single list (e.g., --exclude foo,bar).

Use cats applicative syntax to combine multiple Opts into a single action.

• mapN: Combines multiple options and passes their values into a function.
• tupled: Combines multiple options into a single Opts that returns a tuple.
• orElse: Used for mutual exclusivity or providing alternatives. The parser will choose the first alternative that matches the command-line arguments.

import cats.syntax.all._

// Combine options into a single effect
val tailOptions = (linesOrDefault, fileList).mapN { (n, files) =>
  println(s"LOG: Printing the last $n lines from each file in $files!")
}

// Combine options into a tuple
val tailOptionsTuple = (linesOrDefault, fileList).tupled

// Mutual exclusivity: choose verbose, or if quiet is present, return -1, otherwise 0
val verbosity = verbose orElse quiet.map { _ => -1 } withDefault 0

While the 'Config pattern' is great for testing, you can also use an 'Effect style' where you skip intermediate configuration objects and map Opts directly to your application's effectful functions (e.g., functions returning IO, Future, or String). This is more direct and concise but can be harder to test and validate.

import cats.effect.IO

def fetchRemote(uri: URI, timeout: Duration): IO[String] = ???
def fetchLocal(file: Path): IO[String] = ???

val remoteOpts = (uriOpt, timeoutOpt).mapN(fetchRemote)
val localOpts = fileOpt.map(fetchLocal)
val inputOpts = remoteOpts orElse localOpts

def run(input: IO[String], output: Path): IO[Unit] = ???

val configOpts = (inputOpts, outputOpt).mapN(run)

To manage complexity in large CLIs, group related options into smaller case classes. This allows you to validate groups of options together and ensures that dependent options (like a timeout that only applies to a uri) are always provided together. This also improves the autogenerated Usage: help text.

case class RemoteConfig(uri: URI, timeout: Duration)

// Grouping uri and timeout into RemoteConfig
val remoteOpts = (uriOpt, timeoutOpt).mapN(RemoteConfig.apply)

case class Config(
    remote: Option[RemoteConfig],
    file: Option[Path],
    output: Path,
)

val configOpts = 
  (remoteOpts.orNone, fileOpt.orNone, outputOpt)
    .mapN(Config.apply)
    .validate("must provide either uri or file")(c => c.remote.isDefined ^ c.file.isDefined)

When you specify a type for an option (e.g., Opts.option[Path](...)), decline uses the com.monovore.decline.Argument type class to perform two tasks:

1. Parsing: It provides a function to interpret the input string into the target type. If parsing fails, decline reports an error.
2. Metavar Generation: It provides a default 'metavar' (the placeholder text shown in help output, like <path>) to help users understand the expected input format.

decline provides built-in instances for common types like String, numbers, Path, and URI.

import com.monovore.decline._
import java.nio.file.Path

val path = Opts.option[Path]("input", "Path to the input file.")

If you have a custom type that needs specific parsing logic and a custom metavar, you can implement the com.monovore.decline.Argument type class. This is cleaner than using .mapValidated repeatedly in your command definitions.

Implement the read method (returning Validated[Nel[String], T]) and the defaultMetavar method.

import cats.data.Validated

case class Config(key: String, value: String)

implicit val configArgument: Argument[Config] = new Argument[Config] {
  def read(string: String) = {
    string.split(":", 2) match {
      case Array(key, value) => Validated.valid(Config(key, value))
      case _ => Validated.invalidNel(s"Invalid key:value pair: $string")
    }
  }

  def defaultMetavar = "key:value"
}

// Usage
val configOpt = Opts.option[Config]("config", "Specify an additional config.")

To build a CLI application, extend or instantiate CommandApp. You provide a name for the application, a header for the help text, and a main block which contains the logic for parsing options and executing the application. The main block typically uses Opts to define command-line arguments and then applies the parsed values to your application logic using functional combinators like mapN.

import cats.syntax.all._
import com.monovore.decline._

object HelloWorld extends CommandApp(
  name = "hello-world",
  header = "Says hello!",
  main = {
    val userOpt =
      Opts.option[String]("target", help = "Person to greet.")
        .withDefault("world")

    val quietOpt = Opts.flag("quiet", help = "Whether to be quiet.").orFalse

    (userOpt, quietOpt).mapN { (user, quiet) => 

      if (quiet) println("...")
      else println(s"Hello $user!")
    }
  }
)

To use decline within a pure functional Cats Effect application, use the decline-effect module. This module provides CommandIOApp, which combines decline's rich CLI parsing capabilities with the effect management of Cats Effect's IOApp.

libraryDependencies += "com.monovore" %% "decline-effect" % "@DECLINE_VERSION@"