CLI experience report

cli-experience-report.md

I started using clojure cli a few months ago and I'm already sold on switching all my projects to work with deps.edn.

It works really well for projects and tools that I write, but I struggle when trying to use the cli to run tools like depstar and deps-deploy.

My conceptual model for how to use clojure cli:

1. specify the clojure environment (deps, java command flags, initial values)
2. specify a clojure function to run
3. specify arguments to pass to pass the #2

As a clojure cli user, is there a better conceptual model? I tend to struggle because the available clj command line options aren't organized into those 3 steps.

1. specify the clojure environment (deps, java command flags, initial values)

• -Jopt Pass opt through in java_opts, ex: -J-Xmx512m
• -Sdeps EDN Deps data to use as the last deps file to be merged
• -Scp CP Do NOT compute or cache classpath, use this one instead
• -Srepro Ignore the ~/.clojure/deps.edn config file
• -Sforce Force recomputation of the classpath (don't use the cache)

2. specify a clojure function to run

• -Sdeps EDN Deps data to use as the last deps file to be merged
• -Spath Compute classpath and echo to stdout only
• -Spom Generate (or update) pom.xml with deps and paths
• -Stree Print dependency tree
• -Sdescribe Print environment and command parsing info as data
• -A Runs a repl
• -M -r Runs a repl
• -M -m Runs a -main function
• -X Runs a clojure function

3. specify arguments to pass to pass the #2

• -Sdeps EDN Deps data to use as the last deps file to be merged
• -X parses arguments as key-value pairs of edn
• -M arguments as strings

When I write my own tool targeting the cli, it's fairly easy to figure out how to make it work. However, when using common cli tools like depstar or deps-deploy, I find I need to spend time jumping between the project github page, my deps.edn, clj --help, the cli reference page, and the deps cli guide. In contrast, when I use the aws cli tools, I find I can usually figure out how to do the right thing using just aws help even though I only need to use the aws cli every few months.

I know I could fix these problems for myself by writing my own cli scripts and updating my deps.edn file, but that route makes it more difficult to help other clojure users and provide good documentation for my clojure projects that provide a cli interfaces.

For example:

When I was trying to follow https://github.com/seancorfield/depstar#my-deployment-process, I got stuck on this step:

Run depstar with :sync-pom true :version '"x.y.z"' to update the and SCM in the pom.xml file.

My attempt was:

bash-3.2$ clj -X:depstar :sync-pom true :version '"x.y.z"'
No function found on command line or in :exec-fn

I know this is a 3rd party library that's not part of the clojure cli code, but I think the root cause is deeper. It's not a big deal that my first attempt didn't work. The problem is that there's not really a good way to figure out what the right command should be.

Ideally there would be 1) A way to examine how the clojure cli is handling my command, 2) A common way to show help for a command.

My example command with -X:depstar uses the depstar alias, but I don't actually know what that alias does. I just copied the alias from the github readme into my deps.edn file. To try to fix my usage, it would be great to have a command like the following so I can try to figure out what the depstar alias actually does.

clj explain -X:depstar :sync-pom true :version '"x.y.z"'

Additionally, it would be great to be able to type something like the following to see the available options and some examples.

clj help -A:depstar

The above command doesn't really make sense in the clojure cli paradigm, but not having an idiomatic way to see help text as a user or provide help text as an author makes the clojure cli less approachable.

For a command line tool, another very useful affordance is a way to list all of the commands available. Something similar to aws help. I'm currently using deps.edn file from seancorfield's dot-clojure repos, but I miss out on a lot of goodies because there's no standard way to list all of the commands at my disposal.

Suggestions:

• organize clj --help by -A, -X, -M, -P. for example https://gist.github.com/phronmophobic/97ea46dfae51958e2e7686243ac27860
• add an explain option that shows how the cli interprets the command
• provide an idiomatic way for users to see a help page and authors to provide one.

Hi! Take a look at my templates https://github.com/redstarssystems/rssyslib
https://github.com/redstarssystems/rssysapp

Mike.