Clojure CLIλ︎

Learn by doing

To learn Clojure CLI by doing, jump to Terminal REPL or Clojure project sections to start using the Clojure CLI

Clojure CLI (command line interface) is the latest approach to working with Clojure projects, libraries and tools. Clojure CLI focuses on:

running Clojure code (applications and tools)
starting a REPL process (Read-Eval-Print Loop) for interactive development with a Clojure editor or a command line REPL UI.
managing dependencies (tools.deps) -downloading from Maven and Git repositories
building Clojure projects (using tools.build) to create deployable Clojure services

Practicalli Clojure CLI Config extends the feautres of Clojure CLI, defining aliases that add community libraries and tools.

Video commands dated but concepts remain valid

Common tasks for Clojure developmentλ︎

The Clojure CLI has several built-in tasks. Additional tasks are provided via aliases that include libraries and tools from the Clojure community, e.g. Practicalli Clojure CLI Config

REPL Reloaded

clojure -M:repl/reloaded runs a rich terminal UI REPL prompt that includes portal data inspector, namespace reloading and library hotload tools. test path is included to support editor test runners and dev path for custom user namespace for custom REPL startup

Task	Command	Defined In
Basic terminal UI REPL	`clojure` (or `clj` if `rlwrap` binary installed)	Clojure CLI
Enhanced terminal UI REPL (Rebel & nREPL)	`clojure -M:repl/rebel` or `clojure -M:repl/reloaded`	Practicalli
Create project	`clojure -T:project/new :template app :name domain/appname :args '["+h2"]'`	Practicalli
Run unit tests / watch for changes	`clojure -X:test/run` or `clojure -X:test/watch`	Practicalli
Run the project (clojure.main)	`clojure -M -m domain.main-namespace`	No Alias
Find libraries (maven & git)	`clojure -M:search/library library-name`	Practicalli
Find library versions (maven)	`clojure -X:deps find-versions domain/library-name`	CLojure CLI
Download dependencies	`clojure -P` (plus optional execution flags with aliases)	CLojure CLI
Check for new dependency versions	`clojure -T:search/outdated`	Practicalli
Package library	`clojure -X:build/jar` and `clojure -X:build/uberjar`	Practicalli
Deploy library locally	`clojure -X:deps mvn-install`	Clojure CLI
Check code for unused vars	`clojure -X:search/unused`	Practicalli

tools.build is recommended for packaging projects

Package with tools.build is the recommended approach to create jar and Uberjar packages of a Clojure project.

Execution option flagsλ︎

The execution option flags for the clojure command define how to run Clojure code. The most commonly used options are:

-M uses clojure.main and calls the -main function of the given namespace, passing positional string arguments.
-X uses clojure.exec to call a fully qualified function which has a map argument, passing key/value pair arguments. -T is the same as -X execpt setting the classpath to ., ignoring project dependencies not defined in a given alias.

Flag	Purpose
`-A`	Pass alias to built-in terminal UI REPL (`clojure` or `clj`)
`-M`	Run Clojure with clojure.main
`-P`	Prepare / dry run (Build scripts, CI servers, Containers)
`-X`	Execute a fully qualified function, optional default arguments
`-T`	Run a tool independently from a project configuration
`-J`	Java Virtual Machine specific options (heap size, etc)

Examples of execution option flags

Execution option page expands on flag usage with numerous examples

Configure Clojure CLIλ︎

A deps.edn file configures the Clojure CLI, using extensible data notation (EDN), the underlying syntax of Clojure itself.

Configuration is defined using a hash-map with the following top-level keys:

:deps - library dependencies
:paths - directories to search for code and resources (Java classpath)
:aliases - named configuration defining extra paths, extra deps and configuration to run Clojure
:mvn/repos - library dependency sources, remote and local (e.g. Clojars, Maven, Artifactory, etc).

:aliases configuration is only included when using the alias name with the Clojure CLI, e.g. :repl/rebel alias in Practicalli Clojure CLI Config adds library dependencies only used during development to run a rich terminal UI REPL.

clojure -M:repl/rebel

Add a wide range of aliases by installing Practicalli Clojure CLI Config

Practicalli Clojure CLI Config provides aliases for a wide range of tools for use with Clojure CLI to support Clojure software development.

Precedence Orderλ︎

Clojure CLI Configuration can be used from several different sources.

Configuration	Description
Command line arguments	string or edn (key value) arguments passed to the `clojure` command
project `deps.edn`	Project specific configuration: paths, dependencies, aliases
`$XDG_CONFIG_HOME/clojure/deps.edn` / `$HOME/.clojure/deps.edn`	User level configuration for use with all projects
Clojure CLI install	Includes Clojure standard library, `src` path and built-in `:deps` aliases

Command line arguments take preceedence over the other configurations. When running the clojure command the configurations are merged, with key/values being added or replaces following the precedence order.

Install configurationλ︎

Clojure CLI install has a built-in configuration:

org.clojure/clojure library dependency, setting the default version of Clojure for the Clojure CLI
src set as the default path

Clojure CLI Install deps.edn

The Clojure CLI install includes a deps.edn configuration, e.g. /usr/local/lib/clojure/deps.edn

{
  :paths ["src"]

  :deps {
    org.clojure/clojure {:mvn/version "1.11.1"}
  }

  :aliases {
    :deps {:replace-paths []
           :replace-deps {org.clojure/tools.deps.cli {:mvn/version "0.9.10"}}
           :ns-default clojure.tools.deps.cli.api
           :ns-aliases {help clojure.tools.deps.cli.help}}
    :test {:extra-paths ["test"]}
  }

  :mvn/repos {
    "central" {:url "https://repo1.maven.org/maven2/"}
    "clojars" {:url "https://repo.clojars.org/"}
  }
}

Check version of Clojure

Evaluate *clojure-version* in a REPL shows which version of the Clojure language is currently being used.

Including org.clojure/clojure as a dependency the project deps.edn file specifies a version of the Clojure language. The Clojure CLI version is used if no other dependency is specified.

User configurationλ︎

A Clojure CLI user configuration is available to all projects by the operating system user account. Practicalli Clojure CLI Config is a user configuration that contains a set of well-formed aliases that add common tools for all Clojure project.

Clojure CLI User Configuration Location

Clojure CLI tools creates a configuration directory called .clojure, which by default is placed in the root of the operating system user account directory, e.g. $HOME/.clojure.

XDG_CONFIG_HOME may be set by your operating system and over-rides the default location, e.g. $HOME/.config/.clojure

CLJ_CONFIG can be used to over-ride all other location settings

Run clojure -Sdescribe in a terminal and checking the :config-user value to see the location of your Clojure configuration directory

A basic example of a user configuration for Clojure CLI

{
  :aliases {
    :test/env {:extra-paths ["test"]}

    :project/new
    {:extra-deps {seancorfield/clj-new {:mvn/version "1.0.199"}}
     :main-opts  ["-m" "clj-new.create"]}
  }

  :mvn/repos {
    "central" {:url "https://repo1.maven.org/maven2/"}
    "clojars" {:url "https://repo.clojars.org/"}
  }
}

Clojure Tools install sets Clojure version

A default version of Clojure is set by the Clojure tools install, enabling the clojure command to know what version of Clojure library to use. This version will be over-ridden by the user or project specific deps.edn configuration files if set.

Referencesλ︎

tools.deps and cli guide clojure.main API Reference tools.deps.alpha API Reference

Last update: November 14, 2023