mainargs
A small, dependency-free library for command-line argument parsing in Scala, used by Ammonite and Mill.
What is mainargs?
MainArgs is a lightweight, dependency-free library for parsing command-line arguments in Scala. It allows developers to define CLI interfaces by annotating methods and case classes with `@main` and `@arg`, eliminating the need for boilerplate configuration code. It solves the problem of quickly building command-line tools with support for sub-commands, custom types, and flexible error handling.
Scala developers building command-line applications, tools, or scripts who want a simple, annotation-based argument parser without external dependencies.
Developers choose MainArgs for its zero-dependency design, ease of use with annotations, and seamless integration with Scala idioms like case classes. It offers a cleaner alternative to more verbose libraries like Scopt or Case App, with features tailored for real-world use in projects like Ammonite and Mill.
Overview
A small, convenient, dependency-free library for command-line argument parsing in Scala
Use Cases
Best For
- Adding CLI interfaces to Scala scripts and REPL tools
- Building command-line tools with multiple sub-commands
- Parsing arguments directly into Scala case classes
- Creating lightweight CLI applications without external dependencies
- Integrating custom type parsers into command-line arguments
- Developing Scala Native command-line utilities
Not Ideal For
- Projects requiring complex, interdependent CLI flag validation or business logic during parsing
- Teams that need automatic generation of extensive documentation or man pages from CLI definitions
- Large-scale applications with hundreds of CLI flags where annotation management becomes cumbersome
- Cross-language projects needing consistent CLI parsing across multiple programming languages
Pros & Cons
Pros
MainArgs has no external dependencies, keeping projects lightweight and avoiding build bloat, as emphasized in its README as a key feature.
Using @main and @arg annotations, developers define CLI interfaces with minimal boilerplate, turning simple Scala methods into full commands, as shown in basic examples.
Arguments parse directly into Scala case classes, enabling clean configuration objects and re-use via implicit parsers, detailed in the 'Re-using Argument Sets' section.
Multiple @main methods act as sub-commands, allowing complex CLI tools with distinct entrypoints without extra configuration, demonstrated with foo and bar examples.
Implicit TokensReader instances let developers parse custom types, providing extensibility for domain-specific arguments, illustrated with os.Path parsing in the README.
Cons
As a 0.x library, the API is not stable; the changelog shows frequent updates and breaking changes, which could disrupt production use.
Compared to Scopt or Case App, it lacks built-in features like argument grouping, rich help formatting, or complex validation, focusing only on basic parsing.
CLI definitions are tightly coupled to code via annotations, making dynamic CLI generation or integration with non-annotation frameworks difficult.
The README admits that using varargs parameters (e.g., String*) prevents assigning default values to other parameters, constraining design flexibility.
Frequently Asked Questions
Related Projects
scoptcommand line options parsing for Scala
scallopa simple Scala CLI parsing library
declineA composable command-line parser for Scala.
fansiScala/Scala.js library for manipulating Fancy Ansi colored strings
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.