jodersky / cmdr

Pragmatic command line parsing and configuration for Scala apps

Version Matrix


Pragmatic command line parsing for Scala apps.

Guiding Principles

  • Avoid ceremony and target the common use-case. The design is inspired by the argparse package from python and the @main annotation available in Scala 3.

  • Read configuration from the environment. This encourages separation of config from code, as described in "the 12 factor app"


def main(args: Array[String]): Unit = {
  val parser = cmdr.ArgumentParser()

  val host = parser.param[String](
    default = "localhost"

  val port = parser.param[Int](
    default = 8080,
    aliases = Seq("-p"),
    env = "PORT"

  val path = parser.requiredParam[java.nio.file.Path](

  1. Build the above application by running ./mill examples.readme.dist.

  2. Try running the ./readme executable:

$ ./readme
missing argument: path
try ' --help' for more information
$ ./readme --help
Usage:  [OPTIONS] <path>

  --help               Show this message and exit
  --port=, -p=
  --version            Show the version and exit

  PORT                 --port
$ ./readme /srv/www
$ ./readme --port=9090 /srv/www
$ ./readme /srv/www --port=9090
$ PORT=80 ./readme /srv/www --host=
# all parse errors are displayed; not just the first
$ ./readme --port="aaaahhhhh" a b c
unknown argument: b
unknown argument: c
error processing argument --port: 'aaaahhhhh' is not an integral number
try '--help' for more information


This library is published on maven central and may be obtained by adding the following coordinates to your build:

  • mill: ivy"io.crashbox::cmdr:<version>"
  • sbt: "io.crashbox" %% "cmdr" % "<version>"

where <version> is given by Latest version

This library is published for Scala 2.13 and Dotty.

  • Under Scala 2.13, the additional macros require the scalac option "-Ymacro-annotations" to be enabled.

  • It may also be possible to use this library with Scala 2.12 and the macro-paradise plugin.


Look at the API docs (defined here) for parsing rules and explanations on how it works.


parameter : a named variable in an command line definition

argument : the value assigned to a parameter

named argument : an argument that starts with --. The characters following determine the name of the parameter that the argument is assigned to. The actual value assigned to the parameter is given after an '=' or a spance. For instance --foo=bar assigns bar to foo. Named arguments may appear in any order on a command line.

positional argument : an argument that is not named. Positional arguments are assigned to positional parameters according to their respective order of occurence.