README.md — sigil-args

1# sigil-args

3Declarative command-line argument parsing for [Sigil](https://codeberg.org/sigil/sigil).

5Defines CLIs as composable record values: options, commands, subcommands, with automatic help generation.

7## Usage

9```scheme

10(import (sigil args))

12(define cli

13 (command

14 name: "greet"

15 description: "Print a greeting"

16 options: (list

17 (option name: 'name short: #\n long: "name"

18 value: "NAME" default: "World")

19 (option name: 'loud short: #\l long: "loud"

20 description: "Use uppercase"))

21 handler: (lambda (opts args)

22 (let ((greeting (format "Hello, ~a!" (alist-get 'name opts))))

23 (display (if (alist-get 'loud opts)

24 (string-upcase greeting)

25 greeting))

26 (newline)))))

28(run-command cli (cdr (command-line)))

29```

Supports short flags (`-v`, `-vvv`, `-vf`), long flags (`--verbose`, `--no-verbose`), values (`-o val`, `--output=val`), `--` to stop option parsing, env-var fallback, choice restriction, multi-value (repeatable) options, negatable booleans, custom parsers, and required flags.

33Commands that forward argv can declare `passthrough: #t`. Their handler takes

34`(opts args passthrough)`: `args` contains operands before `--`, while

35`passthrough` contains the exact unparsed tail. It is `#f` when the separator is

36absent and `()` for an explicitly empty tail.

38See [`docs/args.md`](docs/args.md) for the full reference.

40## Building

42```sh

43sigil deps install

44sigil build

45sigil test

46```

48For local development against an in-tree `sigil-lang` checkout:

50```sh

51sigil build --redirects ./dev-redirects.sgl

52```

54## License

56BSD-3-Clause. See [LICENSE](LICENSE) (license header lives in `package.sgl`).