https://github.com/indiscipline/cozycliparser
CLI parser builder, a thin but useful wrapper over `std/parseopt`
https://github.com/indiscipline/cozycliparser
cli cli-parser command-line command-line-parser nim
Last synced: about 1 month ago
JSON representation
CLI parser builder, a thin but useful wrapper over `std/parseopt`
- Host: GitHub
- URL: https://github.com/indiscipline/cozycliparser
- Owner: indiscipline
- License: gpl-2.0
- Created: 2026-03-10T01:51:26.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-10T19:00:10.000Z (2 months ago)
- Last Synced: 2026-03-11T00:34:50.180Z (2 months ago)
- Topics: cli, cli-parser, command-line, command-line-parser, nim
- Language: Nim
- Homepage: https://indiscipline.github.io/cozycliparser/
- Size: 69.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Cla: CLA.md
Awesome Lists containing this project
- awesome-nim - cozycliparser - Lean, feature-rich, DSL-free CLI parser based on `std/parseopt`. [Docs](https://indiscipline.github.io/cozycliparser/). (Development Tools / Command-Line Interface Automation)
README
# Cozy CLI Parser
[](LICENSE)
> Command-Line Parser Builder for Nim.
Cozy CLI Parser provides a thin convenience wrapper over `std/parseopt`.
It exports a `macro buildParser` which generates a command-line parser
from a set of regular, fully type-checked procedure calls and option-handling closures.
- A single place to declare options, flags and arguments — not
three (parser, help text, shortNoVal/longNoVal set and seq).
- Low-magic implementation: no cryptic compiler errors.
- Same DIY stdlib approach: parsing only, handling is fully in your control.
- No idiosyncratic DSL: just regular Nim checked by the compiler.
- Declaration and handling code are co-located and cannot go out of sync.
- Slim code, no dependencies beyond `std/[parseopt, strutils, terminal, envvars]`.
- Colorized help strings.
## Installation
**Relies on Nim devel** (>=2.3.1) due to using
[recent](https://github.com/nim-lang/Nim/pull/25506) `std/parseopt` changes.
Up-to-date Nimble should be able to install development nim with
`nimble install nim@#devel`.
Cozy CLI Parser is in the [nimble directory](https://nimble.directory/pkg/cozycliparser), use
`atlas` or `nimble` to install:
```bash
atlas use cozycliparser
```
```bash
nimble install cozycliparser
```
## Documentation
The rendered API documentation and detailed guides are located in the `docs`
directory and are available online at
[indiscipline.github.io/cozycliparser](https://indiscipline.github.io/cozycliparser).
## Usage example
Call `macro buildParser` with a program name, a help namespace name, a parser
mode, and a declarative body. The `opt`, `flag`, `arg` and `cmd` routines
register options, flags, positional arguments and subcommands along with their
handlers — closures passed as the last argument. The handlers are invoked when
the parser meets the corresponding input.
```nim
import cozycliparser
type Options = object
output: string
input: string
verbose: bool
greetName: string = "world"
var options: Options
buildParser(parserConfig(helpPrefix = "Greeter v0.1\nThis program greets."),
"greeter", "Cli", GnuMode):
opt('\0', "output", "Output file", "FILE") do (val: string):
options.output = val
flag('v', "verbose", "Enable verbose output") do ():
options.verbose = true
arg("INPUT", "Input file") do (val: string):
options.input = val
cmd("greet", "Greets NAME") do ():
arg("NAME", "Name to greet") do (val: string):
if val != "": options.greetName = val
echo "Hello ", options.greetName
cmd("version", "Displays version and quits") do ():
run do ():
quit("v0.42", 0)
# HelpText namespace is automatically built and injected in scope:
doAssert $Cli.help == """Greeter v0.1
This program greets.
Usage: greeter [options] INPUT
Arguments:
INPUT Input file
Commands:
greet Greets NAME
version Displays version and quits
Options:
--output=FILE Output file
-v, --verbose Enable verbose output
-h, --help Show this help and exit"""
# Display colorized help for the program and subcommands with:
Cli.help.display()
Cli.help("greet").display()
```
*By default, a `-h`/`--help` flag is auto-injected at every parser level,
providing styled, nested help outputs natively.*
See [module documentation](https://indiscipline.github.io/cozycliparser) for
details and many more examples.
## TODO:
- [ ] Propose standard library inclusion, close [#12425](https://github.com/nim-lang/Nim/issues/12425).
## Contributing
The project is open for contributions.
Simplifying and reducing loc is preferable to expanding the feature set.
**Important:** In order to facilitate possible standard library inclusion,
all contributors must agree to the [Contributor License Agreement (CLA)](CLA.md).
This guarantees that the Maintainer has the right to
submit the Project's code for inclusion into the Nim language Standard Library.
While your contributions will be distributed under GPL-2.0-or-later for this
project, the CLA explicitly grants the Maintainer the right to relicense your
contribution under the **MIT License** solely for the purpose of proposing its
inclusion into the official Nim Standard Library.
## License
Cozy CLI Parser is licensed under GNU General Public License version 2.0 or later.
See [`LICENSE`](LICENSE) for full details.