mainargs

You can parse command line arguments and dispatch them to a method by using Parser(objectContainingMethod).

Key features:

• Use @main to mark entrypoint methods.
• Use @arg to customize arguments (e.g., setting short names or doc strings).
• Arguments with default values are automatically treated as optional.
• CamelCase parameter names are automatically converted to kebab-case for the CLI (e.g., myNum becomes --my-num).
• Flag types can be passed without a value to become true.

package testhello
import mainargs.{main, arg, Parser, Flag}

object Main{
  @main
  def run(@arg(short = 'f', doc = "String to print repeatedly")
          foo: String,
          @arg(doc = "How many times to print string")
          myNum: Int = 2,
          @arg(doc = "Example flag, can be passed without any value to become true")
          bool: Flag) = {
    println(foo * myNum + " " + bool.value)
  }
  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
}

To avoid duplicating argument definitions, define a @main case class and provide an implicit def for its Parser. Other @main methods can then take that case class as a parameter.

package testclassarg
import mainargs.{main, arg, Parser, Flag}

object Main{
  @main
  case class Config(@arg(short = 'f', doc = "String to print repeatedly")
                    foo: String,
                    @arg(doc = "How many times to print string")
                    myNum: Int = 2,
                    @arg(doc = "Example flag")
                    bool: Flag)
  implicit def configParser = Parser[Config]

  @main
  def bar(config: Config,
          @arg(name = "extra-message")
          extraMessage: String) = {
    println(config.foo * config.myNum + " " + config.bool.value + " " + extraMessage)
  }
  @main
  def qux(config: Config,
          n: Int) = {
    println((config.foo * config.myNum + " " + config.bool.value + "\n") * n)
  }

  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
}

Arguments with single-character names are automatically treated as short arguments (using - instead of --).

Key behaviors:

• Combining flags: Multiple short flags can be combined, e.g., -ab is equivalent to -a -b.
• Combining with values: A combined short argument group can include a value for the last argument, e.g., -ab true or -abtrue.
• Key-value pairs with =: You can use -b=value to set a value. If using a combined group, -a -b=value works.
• Concise key-value pairs: -bkey=value passes key=value as the value to the first short argument b.
• Single token consumption: The first non-Flag short argument in a token can consume subsequent characters as a string.

# Examples of short argument usage
$ ./mill example.short bools -a
Seq(true, false)

$ ./mill example.short bools -b true
Seq(false, true)

$ ./mill example.short bools -ab true
Seq(true, true)

$ ./mill example.short bools -btrue
Seq(false, true)

$ ./mill example.short strs -b=value
Seq(false, value)

$ ./mill example.short strs -a -b=value
Seq(true, value)

$ ./mill example.short strs -a -b=
Seq(true, )

$ ./mill example.short strs -a -bkey=value
Seq(true, key=value)

The Parser object provides several configuration options to customize the CLI experience beyond annotations.

Parser Configuration Options

• allowPositional: Boolean: Allows passing arguments without their --name prefix. Defaults to false.
• allowRepeats: Boolean: Allows a flag to be passed multiple times, using the last value provided instead of erroring. Defaults to false.
• totalWidth: Int: Width for re-formatting doc strings in help text. Defaults to 100.
• printHelpOnExit: Boolean: Whether to print full help text on parsing failure. Defaults to true.
• docsOnNewLine: Boolean: Whether to print argument doc-strings on a new line. Defaults to false.
• autoprintHelpAndExit: Option[(Int, PrintStream)]: Automatically detects --help. Defaults to Some((0, System.out)). Pass None to handle help manually.
• sorted: Boolean: Whether to sort arguments alphabetically in help text. Defaults to true.
• nameMapper: String => Option[String]: Defines how camelCase names map to CLI names. Defaults to kebab-case. Use mainargs.Util.snakeCaseNameMapper for snake_case or mainargs.Util.nullNameMapper to disable mapping.
• customName/customNames and customDoc/customDocs: Overrides method names and documentation at runtime (useful for dynamic strings).

Use annotations to customize how Scala methods and parameters are exposed as CLI commands and flags.

@main

Used on a method to define a top-level command.

• name: String: Specifies the command name. If multiple @main methods exist, this name determines the sub-command. If omitted, camelCase and kebab-case versions of the method name are accepted.
• doc: String: Documentation string printed below the command name in help messages.

@arg

Used on method parameters to define CLI flags or positional arguments.

• name: String: The long name of the parameter (e.g., --foo). If omitted, camelCase and kebab-case versions of the parameter name are accepted.
• short: Char: The short name (e.g., -f).
• doc: String: Documentation string for the argument.
• noDefaultName: Boolean: If true, the argument can only be called via its mangled name (e.g., --foo-bar) and not the original camelCase name. Defaults to false.
• positional: Boolean: If true, the argument can be passed without the --name prefix. Defaults to false.
• hidden: Boolean: If true, the argument is excluded from help text. Defaults to false.