Where is the documentation of `cli -Ttools install ...` and what will it do?

An example using that install command is found in the clj-new project: GitHub - seancorfield/clj-new: Generate new projects based on clj, Boot, or Leiningen Templates!

clojure -Ttools install com.github.seancorfield/clj-new '{:git/tag "v1.2.399"}' :as clj-new

Before running it, I would like to know “What will ‘install’ do?”. But I find it difficult to find the documentation of that.

The clj-new documentation suggest a command to get the clj-new help documentation:

clojure -A:deps -Tclj-new help/doc

So, I decided to give it a try to change clj-new to tools:

clojure -A:deps -Ttools help/doc

Which worked fine and game me this information about install:

-------------------------                                                                                                                                                                                  
clojure.tools.tools.api/install                                                                                                                                                                            
([{:keys [as], :as args}])                                                                                                                                                                                 
  Install a tool under a local tool name for later use. On install, the tool is procured, and                                                                                                              
  persisted with the tool name for later use.                                                                                                                                                              
                                                                                                                                                                                                           
  Options:                                                                                                                                                                                                 
    lib-name (required) - value is coord map (git coords may omit sha)                                                                                                                                     
    :as (required) - tool name                                                                                                                                                                             
                                                                                                                                                                                                           
  Example:                                                                                                                                                                                                 
    clj -Ttools install io.github.clojure/tools.deps.graph '{:git/tag "v1.0.63"}' :as deps-graph                                                                                                           
                                                                                                                                                                                                           
  Also see:                                                                                                                                                                                                
    clj -X:deps find-versions :lib <lib>

Ok, It tells what are the permanent effects, but doesn’t detail exactly what happens in my machine.

I ran it and noticed the ~/.clojure/tools/clj-new.edn file existing, because I had a feeling it would make changes to my ~/.clojure/deps.edn file. But no, it creates instead that clj-new.edn file (I think it did, because I’m not sure if I had it there before running the command, from years ago).

Anyways, something interesting is the namespace I see in the help command: clojure.tools.tools.api/install. So… I suppose this is the repo concerning that install command: GitHub - clojure/tools.tools: Clojure CLI tool for managing Clojure CLI tools, which point to this API, which is I think the same info you’ll get with the previous help command.

So, that’s all the documentation I could find about those commands.

I too find the documentation about installing clj tools hard to find, but what I do is go to the “deps and cli reference” which has all the info and then look at the side bar:

https://clojure.org/reference/deps_and_cli#tool_install

2 Likes

Where did you look first for this info? (happy to make it more visible, just looking for where people are starting to look already)

1 Like

I’ve run into this a couple of times in the past month. Googling for “clojure tools install” only comes up with pages about how to install Clojure. You almost have to know where the info resides, to be able to find it.