Clojure Q&A - Recent activity in tools.cli

Closed: tools.cli: capture unrecognized options as unparsed arguments

Tue, 10 Mar 2026 16:08:38 +0000

I frequently write a command that accepts options and in turn execute a shell command passing arguments through; I want to be able to specify additional arguments to that shell command.

In tools.cli, the :in-order key almost does what i want:

`
(require '[clojure.tools.cli :as cli])
=> nil
(def opts [["-d" "--debug"]])
=> #'net.lewisship.cli-tools-test/opts
(cli/parse-opts

["--foo"]
[]
:in-order true)

=> {:options {}, :arguments [], :summary "", :errors ["Unknown option: \"--foo\""]}
(cli/parse-opts

["xxx" "--foo"]
[]
:in-order true)

=> {:options {}, :arguments ["xxx" "--foo"], :summary "", :errors nil}
`

However, it will assume an undefined option is an error until the first non-option argument is consumed.

I would like a further option that is like :in-order but accepting of these unrecognized options. Maybe, :passthru-options would be a good name?

I can work on a patch if we have some consensus on direction.

Closed: Review cli-matic for inspiration for enhancing tools.cli

Fri, 06 Mar 2026 01:06:24 +0000

See https://cljdoc.org/d/cli-matic/cli-matic/0.2.7/doc/readme

Closed: Tools.cli :validate: provide a way to post-validate (after updates)

Fri, 06 Mar 2026 01:05:21 +0000

aratare on Slack had this code:

["-v" nil "Verbosity level; may be specified up to 2 times. Levels: INFO (Default) -> DEBUG -> TRACE"
    ;; If no long-option is specified, an option :id must be given
    :id :min-level
    :default 0
    :update-fn inc
    :validate [(fn [a]
                 (println a)
                 (<= a 2)) "Verbosity level cannot exceed 2."]]

and asked:

and a is printed as true instead of either the level before or after applying update-fn. Is there a way to work around this so I can validate after update-fn has been called? Thanks in advance. (edited)

Closed: Tools.cli :validate: provide function of invalid value in addition to fixed string

Fri, 06 Mar 2026 01:04:56 +0000

The :validate option currently takes a validation function and a string error message.

Could we extend the second argument to a function instead so you can return an error message like "--foo should be greater than 10, but was: 11.

We could even plug clojure.spec.alpha or malli in there:

(def cli-options
  [["-n" "--number NUM" "A number"
    :parse-fn (m/decoder int? mt/string-transformer)
    :validate [(fn [input]
                 (m/validate [:< 100] input))
               (fn [input]
                 (me/humanize (m/explain [:< 100] input)))]]])

Closed: tools.cli: display default value for --[no-]foo flags in help summary

Fri, 06 Mar 2026 01:04:34 +0000

Salut

While boolean options of the form "--foo" are false by default and enabled by specifying them, flag options of the form "--[no-]foo" accept "--foo" and "--no-foo" to toggle them on or off respectively. The default could be true or false, but the user has no way to tell what the default value is based on the help summary.

For those options I think it is helpful (even necessary) to always display the default value, whether the option is required or not.

I've drafted a patch that could serve as a starting point.

A related thought: shouldn't the default always be shown, even if it isn't a required option? Maybe there is a good reason for this, but I don't get why non-required options hide their default in the help summary.

Thanks for your work!

Closed: Compile parser ahead of time

Fri, 06 Mar 2026 01:03:57 +0000

tools.cli/parse-opts accepts the args, the option-spec, and the additional options. It calls compile-option-specs and required-arguments to build the specs and req. Then it performs the validation with those specs and req on the provided args (along with the options). For a given application, the first two steps aren't going to change across calls.

I propose a new make-parse-opts-fn function that performs the compile-option-specs and required-arguments up front and returns a function that relies on the compiled specs and req. It could be used like this: (def compiled-parser (make-parse-opts-fn cli-options)).

Microbenchmarking with criterium shows a more than double increase in speed (tools.cli/parse-opts first, pre-compiled parser second):

; user=> (def cli-options
  [["-h" "--help" "This message"]
   [nil "--extra" "Output in extra format"
    :default false]
   ["-q" "--quiet" "Print no suggestions, only return exit code"
    :default false]])
#'user/cli-options

; user=> (bench (cli/parse-opts ["--quiet" "src"] cli-options :in-order true))
Evaluation count : 10962 in 6 samples of 1827 calls.
             Execution time mean : 65.021329 µs
    Execution time std-deviation : 5.276033 µs
   Execution time lower quantile : 58.658638 µs ( 2.5%)
   Execution time upper quantile : 69.724228 µs (97.5%)
                   Overhead used : 9.607933 ns
nil

; user=> (bench (compiled-parser ["--quiet" "src"] :in-order true))
Evaluation count : 24660 in 6 samples of 4110 calls.
             Execution time mean : 25.090846 µs
    Execution time std-deviation : 253.361821 ns
   Execution time lower quantile : 24.769079 µs ( 2.5%)
   Execution time upper quantile : 25.413286 µs (97.5%)
                   Overhead used : 9.607933 ns
nil

If the additional options are lifted into the make-parse-opts-fn as well (trading flexibility for speed), the difference is even more dramatic, providing roughly 10x speed increase over the existing tools.cli/parse-opts function:

; user=> (bench (compiled-parser-2 ["--quiet" "src"]))
Evaluation count : 73116 in 6 samples of 12186 calls.
             Execution time mean : 8.349923 µs
    Execution time std-deviation : 51.419864 ns
   Execution time lower quantile : 8.282266 µs ( 2.5%)
   Execution time upper quantile : 8.407998 µs (97.5%)
                   Overhead used : 9.607933 ns

Found 2 outliers in 6 samples (33.3333 %)
	low-severe	 1 (16.6667 %)
	low-mild	 1 (16.6667 %)
 Variance from outliers : 13.8889 % Variance is moderately inflated by outliers
nil

I can provide a patch for this if there's interest.

Closed: Providing nil for long option in tools.cli does not seem to work per readme

Fri, 06 Mar 2026 01:01:11 +0000

Hi,

A very simplified tools.cli call:

(let [cli-opts [["-m" "--mode MODE" "Application mode"]]]
  (cli/parse-opts ["-m" "hub"] cli-opts))

Evaluates as expected to:

{:options {:mode "hub"} ... }

However, when I try to replace the long option with nil per the docs:

(let [cli-opts [["-m" nil "Application mode" :id :mode]]]
  (cli/parse-opts ["-m" "hub"] cli-opts))

I get:

{:options {:mode true} :arguments ["hub"] ... }

I get the same behaviour with long option = "", "--mode", and "MODE"; the only way it seems to work is with the full "--mode MODE". Setting the short option to nil works as I'd expect.

Tested in Clojure 1.12.0, tools.cli 1.1.230, Java 23; same behaviour on Windows 11 and MacOS 15.

Am I doing something wrong, or is tools.cli? :)

Closed: Incorrect docstring for parse-opts

Fri, 06 Mar 2026 01:00:43 +0000

In the docstring for clojure.tools.cli/parse-opts (seen here), it says,

:id           The key for this option in the resulting option map. This
              is normally set to the keywordized name of the long option
              without the leading dashes.

              Multiple option entries can share the same :id in order to
              transform a value in different ways, but only one of these
              option entries may contain a :default(-fn) entry.

              This option is mandatory.

The final line says "This option is mandatory." which is technically true for parse-opts' internals, but it's not true for users because (as the first paragraph says) :id is also generated by keywordizing the long option.

May I recommend changing it to be more explicit? Something like "If a long option is not provided, this option is mandatory."

Answer selected: Dependency between options in Clojure/tools.cli ?

Tue, 27 May 2025 17:37:23 +0000

Here's one way to do it, but it requires for the -f and -d options to be specified on the command line before the -a option:

(let [opts [["-a" nil "something"
             :id :a
             :assoc-fn (fn [opts opt-id val]
                         (assoc opts opt-id
                                     (if (and (:file opts) (:dir opts))
                                       val
                                       ::missing-required)))
             :validate [#(not= % ::missing-required)
                        "Missing required -f and -d options"]
             :post-validation true]
            ["-f" "--file FILE" "file doc"]
            ["-d" "--dir DIR" "dir doc"]]]
  [(cli/parse-opts ["-a"] opts)
   (cli/parse-opts ["-f x" "-d y" "-a"] opts)])
=>
[{:options {},
  :arguments [],
  :summary "  -a               something\n  -f, --file FILE  file doc\n  -d, --dir DIR    dir doc",
  :errors ["Failed to validate \"-a \": Missing required -f and -d options"]}
 {:options {:file " x", :dir " y", :a true},
  :arguments [],
  :summary "  -a               something\n  -f, --file FILE  file doc\n  -d, --dir DIR    dir doc",
  :errors nil}]

Answered: tools.cli: Support default value for arg with value

Mon, 28 Apr 2025 19:08:37 +0000

The closest you can get is this:

clojure.tools.cli=> (parse-opts ["--diff="] [[nil "--diff NAME" "Diff" :parse-fn #(or (not-empty %) "foo")]])
{:options {:diff "foo"}, :arguments [], :summary "      --diff NAME  Diff", :errors nil}
clojure.tools.cli=> (parse-opts ["--diff=bar"] [[nil "--diff NAME" "Diff" :parse-fn #(or (not-empty %) "foo")]])
{:options {:diff "bar"}, :arguments [], :summary "      --diff NAME  Diff", :errors nil}

clojure.tools.cli=>

As discussed on Slack, there are reasonable cases for a value-bearing option to want to accept a string that starts with -- or just - (consider = to be optional here):

meta-command --option-to-use=--cabbage... \
--divider=--sep-- \
--value=-1

Commented: Can't know if value in option map is default or user-supplied

Sat, 16 Dec 2023 12:45:52 +0000

I read that, but I find it quite dense. Compare that paragraph to the multiple examples demonstrating individual parts of the specs above it in the readme.

I’ll take a crack at something a little more readable.

Answered: Is it possible to parse positional arguments in tools.cli?

Tue, 07 Apr 2020 17:23:10 +0000

As the maintainer of tools.cli, I'm going to give this some thought and decide whether to create a JIRA issue for it.

Most programs that use tools.cli end up needing some boilerplate code for help/usage, as well as some additional parsing and/or validation of arguments so enhancing the library to make this easier would help "everyone" if it can be done in a fairly simple way.

One conceptual issue to figure out is that the format for specifying options is only for actual options (i.e., starting with - or --) so there's currently nowhere to "hang" any free text argument processing right now.