Start a REPL (default):
clj [clj-opts] [-Aaliases]

Execute a function (-X):
clojure [clj-opts] -X[aliases] my/fn? [kpath v …​] kv-map?

Run a tool (-T):
clojure [clj-opts] -T[name|aliases] my/fn [kpath v …​] kv-map?

Run a main namespace or script (-M):
clojure [clj-opts] -M[aliases] [init-opts] [main-opts] [args]

Use this option to start a Clojure REPL.

To run a REPL, invoke clj without arguments.

This works in any directory, either with a deps.edn or not. If you are not in a project directory, the version of Clojure used will depend on the Clojure language version from the org.clojure dependency in the root deps.edn (will match the version number in CLI version number) or the user deps.edn in the config directory (usually not specified).

To supply aliases that modify the classpath or JVM properties, use -A with one or more concatenated alias keywords:

The Clojure CLI can execute any function on the project classpath that takes keyword args in a map as input.

Function execution ultimately needs the following pieces of information:

• Classpath - based on the deps sources and aliases

• Function to execute

• Map of function arguments

The function and its arguments may be supplied either via data in aliases and/or at the command line.

The aliases can contain the following arg map keys:

• :exec-fn - a function symbol to use if none is supplied on the command line

• :exec-args - a map of key to value to include when exec-fn is executed

• :ns-default - default namespace symbol to use when resolving the exec-fn

• :ns-aliases - map of alias symbol to namespace symbol to use when resolving the exec-fn

If the function to invoke is defined in a specified alias, the function is optional on the command line. If the function symbol is specified on the command line, it overrides the :exec-fn in aliases, and is resolved in terms of :ns-default and :ns-aliases in aliases.

The :exec-args form a base map that is merged with keys and values and trailing kv-map on the command line, merged in that order.

Keys on the command line may be either keywords or vector key paths (as used with assoc-in) to specify a nested key. The final arg on the command line is an optional trailing map of keys and values. See the later sections on keys and key paths and quoting for more details on how to properly specify edn keys and values.

Tools are functions external to the project classpath. Running tool functions with -T is the same as running project functions with -X, except the project classpath is not included.

When constructing the classpath for the tool, the project :deps and :paths are not included.

The tool deps are included either via the tool aliases or a tool name. Tools may be installed locally with a short name for use. Installed tools can be used on any project with the same user configuration. See tool installation for more details.

To run a tool by name, use -Ttoolname, like -Tlinter. To run a tool by alias[es], use -T:linter (aliases are always keywords).

Unlike -X, a tool function MUST be specified on the command line and cannot be specified in the tool alias or installed tool configuration. Otherwise, tool functions and arguments are specified the same as -X in both aliases and command line.

You can use the -M exec-opt to invoke clojure.main, which supports calling a namespace with a -main function or a Clojure script:

The -M aliases (if provided) are pulled from deps.edn and combined to form an arg map. The arg map can modify the classpath or supply :main-opts, a vector of string main options. See the clojure.main page for more information on the available main-opts.

Common uses:

Main opts can be provided in aliases with the arg map key :main-opts - when aliases are merged, any :main-opts provided replaces those from previous aliases. Additional options on the command line after -M are appended to those found in the merged alias arg map.

The alias keys above are meaningful for Clojure CLI execution, but you may define aliases for any purpose. If you are creating a custom tool that needs configuration, it is a good practice to define well-known, namespaced aliases or alias-keys for use by your tool. Please refrain from adding top-level keys to the deps.edn files - they may not always be available via programmatic tools.

Programs run by the Clojure CLI are given the runtime basis for the execution, including all alias data. The clojure.java.basis API added in Clojure 1.12 can be used to retrieve alias data at runtime in the program.

Symbols in the exec-opts or arg maps (like :exec-fn) are resolved with the following rules:

• If function is unqualified, use the namespace in the :ns-default key in the arg map (if none, this is an error)

• If function is qualified, and the qualifier is an alias in the arg map under :ns-aliases, use that namespace

• Else use the fully qualified function symbol

The Clojure CLI will construct the map of paths, dependencies, and aliases to use by combining up to four deps edn sources:

• Root deps - defined as a resource embedded in the tools.deps library, defines:

  • Clojure itself as the only dependency (version will match the Clojure CLI version)

  • :paths ["src"]

  • Two built-in aliases:

    • :deps

    • :test, with :extra-paths ["test"]

  • Two built-in Maven repositories: Maven central and Clojars.

• User deps (optional) - a deps.edn file in the user configuration directory. The file starts empty but may have additional configuration and tools defined that cross projects.

• Project deps (optional) - the deps.edn in the current directory (aka the project directory)

• Extra deps (optional) - provided on the command-line with -Sdeps

The deps sources are merged into a single master deps edn in the order listed above except:

• -T tool execution - project :deps is removed, and project :paths are replaced with ["."]

• -Srepro - user :deps is ignored

The merge is essentially merge-with merge, except for :paths where only the last deps source :paths is used.

Once merging of deps and alias args has occurred, there are :paths from deps.edn and :extra-paths from aliases. These both consist of vectors and the order in those vectors is retained. The extra paths are always before the paths, so that aliases may override the project settings.

Note that both project paths and extra-paths are resolved relative to the current directory and should refer only to paths inside the project, not parent or sibling directories. Currently, referring outside the project will emit a warning, but support for this is deprecated and will be removed in the future (use local deps instead).

Once deps have been merged, there is a top-level set of dependencies and these form the roots of the dependency graph. The graph is explored top-down and each dependency is expanded in turn using the appropriate procurers (Maven. Git, local). Cycles are detected and will not be examined again.

When multiple versions of the same library are found, a version selection process occurs. The dependency expansion page has more details on this process but generally the newest version of a library is used. The top-level dependency versions however, are always used without modification - if you need to specify a specific version or resolve a conflict, set the version in a top-level dependency.

Dependencies are ordered in graph depth from the top, and alphabetically sorted by lib name at each level.

For more information on the arg map modifiers like :extra-deps, :override-deps, and :default-deps, see the deps.edn reference page.

The classpath will contain:

• Extra paths (relative to project), in order declared in the last alias to specify them

• Source paths (relative to project), in order declared in the last deps to specify them

• Dependency paths (usually absolute) referring to jars or directories in the appropriate procurer download locations

  • Dependencies are ordered from the top of the dependency graph based on depth, then alphabetically sorted by lib name

Classpaths may further be modified by the arg map key :classpath-overrides (see the deps.edn reference).

You can print the computed classpath with -Spath.

You are expected to install Java and have it available by one of several means when using the Clojure CLI. Java 8 or higher is required. Any Java distribution will work.

Java is found by checking the following in this order:

• $JAVA_CMD environment variable

• java on the $PATH

• $JAVA_HOME/bin/java

If not found, the CLI will stop with an error message. If clj -h completes successfully, then a Java executable was found.

There are several important directories used by the Clojure CLI, this section details how they are computed.

Project directory

Config directory

Cache directory

The following environment variables can influence CLI execution (many are described in more detail elsewhere on this page):

• CLJ_CONFIG - user config directory, used to store user deps.edn, tool config, and cpcache for commands without a project deps.edn (default = ~/.clojure)

• XDG_CONFIG_HOME - if this standard var is set, will use $XDG_CONFIG_HOME/clojure as the user config directory

• CLJ_CACHE - user cache directory, (defaults = <config-dir>/.cpcache)

• XDG_CACHE_HOME - if this standard var is set, will use $XDG_CACHE_HOME/clojure as the user cache directory

• CLJ_JVM_OPTS - JVM options to be included in internal calls to the classpath building process, which can be useful to provide things like a truststore with a self-signed certificate using to download internal artifacts

• JAVA_CMD - path to Java executable to use

• JAVA_HOME - if no $JAVA_CMD and no java on path, will try to use $JAVA_HOME/bin/java

• JAVA_OPTS - JVM options to be included in the user command being executed - not cached. Included before any -J command line parameters and any :jvm-opts

• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and other AWS env vars are used when accessing S3-based Maven repos

• GITLIBS - the path to the gitlibs storage directory (default = ~/.gitlibs)

• GITLIBS_COMMAND - the git command to run (default = git)

• GITLIBS_DEBUG - set to true to print all git commands being run

• CLOJURE_CLI_ALLOW_HTTP_REPO - set to true to allow http:// repository urls (this may make your dependency downloads subject to man-in-the-middle attacks)

With the -X or -T exec-opts you can supply key-path/value pairs on the command line. The key-path is either a single key or a vector of keys to refer to a nested key (as with assoc-in). Each key-path will be used to assoc-in to the original :exec-args map, overriding the value there.

In addition to passing key-path/value pairs and key paths in the command line, an optional map providing value mappings may be passed as the final argument. This map will merge with and perhaps override the previously provided key-path/value mappings:

Keys and values on the command line are read as edn. The following data can be used without quoting:

• Numbers - 123, 12.4

• Booleans - true, false

• Nil - nil

• Symbols - name, foo/bar

• Keywords - :id, :company/name

These data types need to be surrounded by single quotes:

• Strings - '"hi there"' - note use of both single quotes for the shell and double quotes to be read as an edn string

• Vectors - '[1 2 3]'

• Maps - '{:a 1, :b 2}'

• Sets - '#{:a :b}'

• Lists - '(1 2 3)'

On Windows, WSL2 shells can follow the advice above, but using clojure.exe, additional escape quoting is required for string values. Unfortunately the combination of quoting rules for converting command line Windows program arguments, quoting, and word splitting are very complicated.

To pass a string value at the top level, if the string value does not have spaces, you can use '\"str\"'. If the string value does have spaces (or not) you should use '"""str value"""'.

For string values nested inside other collections, use double quotes if there are spaces and triple quotes if there are not:

Prints sorted list of all transitive dependencies selected for the classpath, and license information (if found). Additional options can be used to select aliases or other classpath modifications, or to modify printing information.

See API docs.

Prints dependency tree with inclusion/exclusion information as determined during dependency expansion). Additional options can be used to select aliases or other classpath modifications, or to modify printing information.

For example, the following can be used to print the deps tree for a :test alias:

See API docs.

This program prints all aliases available at the command line based on the current deps environment. Additional options can be used to select aliases or other classpath modifications.

See API docs.

The help/doc and help/dir functions introspect how a tool can be used. Because the :deps alias does not include the project classpath, these are not currently useful when executing functions in your own project.

• -X:deps help/doc - show the doc strings and parameter lists of the functions given with key :ns or function specified by an additional key :fn; if neither given then :ns-default is used

• -X:deps help/dir - prints the public functions in namespace provided with key :ns or :ns-default if not given

Example for listing the set of functions in the :ns-default for the built in tools tool:

Example for listing the set of functions in an alias:

Print the docstrings for the help namespace itself (note that help is defined in the :ns-aliases map for :deps):

See: API docs

Source libs with Clojure source can immediately be added to the classpath of a project using it. However, some source libs require some preparation before they can be added, for example due to needing Java compilation, or copying / replacing resource files, etc. The Clojure CLI will now detect projects that need preparation and prevent the program from being run from source unless the prep step has been completed.

If your library needs preparation, add the :deps/prep-lib key to your deps.edn:

The keys under :deps/prep-lib are:

• :ensure - directory existence determines whether prep is needed (if it exists, prep has been done)

• :alias - alias to invoke with -T during prep

• :fn - function to invoke with -T during prep

Thus, the deps.edn should also have an alias that can execute the fn specified. See the tools.build Guide for how to use tools.build to define a build script with an invokable function.

If you add this git library as a dependency and try to run a program, the Clojure CLI will download it, detect that it needs preparation, and that it has not been prepared ("target/classes" path does not exist), and exit.

To find and "prepare" libs in the dependency tree you can use the prep tool provided with the built-in :deps alias:

The prep task will find all libs in the dependency expansion and look for libs that are source libs, need prep (based on their :deps/prep-lib key), and are not yet prepped (based on the :ensure dir in their :deps/prep-lib map). Those libs will run the command specified there by alias and function, as if: clj -T:<alias> <fn>.

Once a library has been prepped, it does not need to be prepped again by other users of this git library version.

See: API doc

To search for available versions of a Maven or git lib use the find-versions tool provided with the built-in :deps alias:

The params that can be provided are:

• :lib - git or Maven lib name. The git url will be automatically constructed from the git library name. For example, a :git/lib of io.github.clojure/tools.deps.graph will construct the git url https://github.com/clojure/tools.deps.graph.git. For Maven, use the Maven lib name like org.clojure/tools.deps.graph.

• :tool - a tool name if the tool has already been installed

find-versions will print the git or Maven coordinates, one per line, to the console.

See: API doc

The -X:deps mvn-install program is provided with the Clojure CLI for convenience and can be executed with -X to install a jar into your local Maven cache.

The install params include the following options:

You can pass overrides on the command line for these as needed:

As mentioned above, edn strings must be in double quotes, and then single-quoted for the shell.

A pom file must be either provided explicitly, generated from :lib/:version, or found inside the .jar file (the default).

See: API doc

Use the following program to generate or update an existing pom.xml with the deps and paths from your project:

• -X:deps mvn-pom - generate (or update an existing) pom.xml with deps and paths

See: API doc

A tool for managing tools is automatically installed by the Clojure CLI under the name "tools". There are several useful functions provided:

• install - Installs or reinstalls a tool

• install-latest - Installs or reinstalls the latest version of a tool

• list - Lists all installed tools

• remove - Removes an installed tool

• show - Prints info and usage for a tool

Install

clj -Ttools install ...

clj -Ttools install io.github.clojure/tools.deps.graph '{:git/tag "v1.0.63"}' :as deps-graph

clj -Ttools install io.github.clojure/tools.deps.graph '{:git/tag """v1.0.63"""}' :as deps-graph

Install latest

clj -Ttools install-latest :lib io.github.clojure/tools.deps.graph :as deps-graph

clj -Ttools install-latest :tool deps-graph

List

clj -Ttools list

clj -Ttools remove :tool name

Best practices:

• Provide your tool as a public git library

• Define your tool api in one or more Clojure namespaces as functions that take a map

• Create a :tools/usage key in the root of your deps.edn with either an :ns-default and/or an :ns-aliases key for your api namespaces

• Tag your git repo to create a release, using a scheme that makes sequencing obvious to users. A common convention is to use versions strings like "v1.2.3".

Tools can provide these instructions for users:

• Find tool versions: clj -X:deps find-versions :lib io.github.USER/TOOL

• Install tool with clj -Ttools install io.github.USER/TOOL '{:git/tag "VERSION"}' :as NAME

• Invoke tool with clj -TNAME f args…​

Some tools provide functions designed to be used for programmatic execution from another process, with the following constraints and expectations:

• The function should take a single map argument

• Results are returned from the function (as usual)

• Exceptions thrown by the function will cause a failure and the exception data (ala Throwable→map will be conveyed to the external process, which will re-throw it in an ex-info)

• Printing output will (by default) not be captured

• Any result or exception data should be safe to print and read back to data in another process

There are several argument map keys that have special significance to the Clojure CLI during -X or -T. All of these keys will be removed from the argument map before the function is invoked:

• :clojure.exec/invoke - :fn to use this protocol

• :clojure.exec/out - :capture to capture and return stdout during function execution

• :clojure.exec/err - :capture to capture and return stderr during function execution

The result is wrapped into a printed envelope map with the following keys and returned via the CLI stdout:

• :tag - either :ret or :err based on whether the function returned a result or threw an exception

• :val - either return value or exception data, prn to a string

• :out - if requested, the captured stdout return

• :err - if requested, the captured stderr return

• :ms - function execution time in ms

A consumer API for this protocol is provided since Clojure 1.12.0-alpha2.

The Maven procurer uses the qualifier mvn and is used to retrieve library artifacts from Maven repositories, the standard repository manager in the Java ecosystem. Libraries are downloaded as .jar files and stored in the Maven local repository cache (located in ~/.m2/repository by default). Other JVM-based tools may also use this cache.

See the deps.edn reference for details on the Maven coordinate type and Maven procurer config.

Maven authenticated repos

<settings>
  ...
  <servers>
    <server>
      <id>my-auth-repo</id>
      <username>zango</username>
      <password>123</password>
    </server>
    ...
  </servers>
  ...
</settings>

{:deps
 {authenticated/dep {:mvn/version "1.2.3"}}
 :mvn/repos
 {"my-auth-repo" {:url "https://my.auth.com/repo"}}}

Maven S3 repos

{:deps
 {my/library {:mvn/version "0.1.2"}}
 :mvn/repos
 {"my-private-repo" {:url "s3://my-bucket/maven/releases"}}}

<settings>
  ...
  <servers>
    <server>
      <id>my-private-repo</id>
      <username>AWS_ACCESS_KEY_HERE</username>
      <password>AWS_SECRET_ACCESS_KEY_HERE</password>
    </server>
    ...
  </servers>
  ...
</settings>

Maven proxies

<settings>
  ...
  <proxies>
    <proxy>
      <id>my-proxy</id>
      <host>proxy.my.org</host>
      <port>3128</port>
      <nonProxyHosts>localhost|*.my.org</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>

Maven HTTP headers

<settings>
  ...
  <servers>
    <server>
      <id>my-token-repo</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value>abc123</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
    ...
  </servers>
  ...
</settings>

{:mvn/repos
 {"my-token-repo" {:url "https://my.auth.com/repo"}}}

The git procurer supports direct use of source-based libs hosted in Git repositories. Git libs are downloaded by default to the ~/.gitlibs directory. The working tree is checked out and cached for each sha included as a dependency.

See the deps.edn reference for details on the Git coordinate type.

Configuration and debugging

The local procurer includes local directories or jar files as a dependency. See the deps.edn reference for details on the local coordinate type.