cl-cli

cl-cli builds strict command-line parsers for Common Lisp: flags and typed options, arbitrarily deep subcommands, positional and rest arguments, context-sensitive help, shell completion for six shells, and offline man page/Markdown/JSON generation — all from one declarative app spec. It targets SBCL and also runs its portable core on ECL. It takes almost no third-party dependency: the cl-cli system depends on uiop alone (ships with every modern ASDF) on every implementation but SBCL, and additionally on cl-host-kit on SBCL.

Full documentation is published at https://nerima-lisp.github.io/cl-cli/. The source for that site lives in docs/src/.

Quick Start

(asdf:load-system "cl-cli")

(defparameter *app*
  (cl-cli:make-app
   :name "demo"
   :version "0.1.0"
   :global-options (list (cl-cli:make-option :name "verbose" :short #\v :kind :flag))
   :commands (list
              (cl-cli:make-command
               :name "compile"
               :options (list (cl-cli:make-option :name "output" :short #\o :kind :value))
               :positionals (list (cl-cli:make-positional :key :input :required-p t))
               :handler (lambda (invocation)
                           (format t "compile ~A -> ~A~%"
                                   (cl-cli:positional-value invocation :input)
                                   (cl-cli:option-value invocation :output)))))))

(cl-cli:run-app *app* :argv '("demo" "compile" "-o" "out.bin" "input.lisp"))
;; => compile input.lisp -> out.bin

The same spec drives --help, cl-cli:render-completion, and the generated man page. See Quick Start.

Install

As a library, from another flake:

# flake.nix
inputs.cl-cli = {
  url = "github:nerima-lisp/cl-cli/v1.3.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

Note the pinned tag. Consumers inside this org must pin a release tag rather than follow the default branch. On a lispDependencies edge, read cl-cli.packages.<system>.cl-cli -- packages.default is the demo binary described under Development, not the ASDF system.

To try the demo CLI without adding cl-cli to anything:

nix build              # -> ./result/bin/cl-cli-demo
./result/bin/cl-cli-demo greet --upcase ada

Without Nix, clone the repository somewhere ASDF looks — ~/common-lisp/ or ~/quicklisp/local-projects/ — and (asdf:load-system "cl-cli"). Full instructions, including the ASDF :depends-on entry, are in Installation.

Documentation

• Installation and Quick Start
• Option Values and Kinds — option kinds, typed values, env-var and config defaults, arity
• Commands and Dispatch — nested subcommands, aliases, grouping, the define-app DSL
• API Reference — every exported symbol and condition
• Migration Guide — mapping an existing in-house parser onto cl-cli
• Scope and Non-Goals — what cl-cli deliberately leaves to the application

Development

nix develop          # SBCL, ECL, and the shells the suite verifies against
nix build            # -> ./result/bin/cl-cli-demo
nix build .#cl-cli   # the library (the ASDF system, for lispDependencies)
nix run .#test       # run the SBCL test suite
nix flake check      # tests + formatting + docs, the same gate CI uses
nix fmt              # format Nix sources (treefmt)

cl-cli/demo is a small, real CLI (greet, a remote subcommand group, plus the standard help/version/completion/docs commands) built entirely from cl-cli's own primitives, so the library exercises itself as a binary, not only as a test suite. It is what this flake delivers as packages.default, so nix build produces it and nix run . -- greet --upcase ada runs it; nix build .#cl-cli-demo and nix run .#cl-cli-demo name the same derivation explicitly. Its source lives in demo/; its end-to-end dispatch tests are in t/demo-test.lisp.

Tests live in t/ and run under cl-weave, the org's test framework. The suite is split into a portable core (cl-cli/test) and a shell-verification half (cl-cli/test/shell-verification) that pipes generated completion scripts and man pages through the real bash, zsh, fish, nushell, pwsh, elvish, and mandoc. See Development.

Contributing

See the org-wide CONTRIBUTING guide and the package standard.

Release notes are on the Releases page.

Support

See SUPPORT. Report suspected vulnerabilities privately via SECURITY, not in a public issue.

License

MIT. See LICENSE.