Skip to content

Practicalli Clojure CLI Configurationλ︎

Practicalli Clojure CLI Config

Practicalli Clojure CLI Config is a user configuration for Clojure CLI tools providing a range of community tools via meaningful aliases, supporting Clojure and ClojureScript development.

Alias names are designed with qualified keywords that provide context for the use of an alias (env, inspect, project, repl, search test). These keywords help with discovery and reduce cognitive load required to remember their purpose.

Commonly used arguments are included in many alias via :main-opts or :exec-args which can be overridden on the command line.

Minimum Clojure CLI Version -

Clojure CLI version is the minimum version, although the latest available version is recommended.

Check the version of Clojure CLI currently installed via clojure --version or clojure -Sdescribe

Remote Environments or Continuous Integration

For remote environments or Continuous Integration services, include Practicalli Clojure CLI Config) in the environment build or copy specific aliases to the Clojure project deps.edn configuration.


Fork or clone Practicalli Clojure CLI Config GitHub repository, first removing the $XDG_CONFIG_HOME/clojure or $HOME/.clojure directory if they exist.

Check Clojure CLI configuration location

Check the location of your Clojure configuration directory by running clojure -Sdescribe and checking the :user-config value.

If XDG_CONFIG_HOME environment variable is set, clone the repository to $XDG_CONFIG_HOME/clojure

git clone $XDG_CONFIG_HOME/clojure

Clojure CLI will look for its configuration in $HOME/.clojure directory if $XDG_CONFIG_HOME and CLJ_CONFIG environment variables not set.

git clone $HOME/.clojure

Community Toolsλ︎

The Clojure configuration directory contains a deps.edn file containing a substantial :aliases section with a long list of aliases. These aliases are described in the README of the project.

All tools are provided via libraries and are only installed on first use. Unused aliases will therefore not install their libraries.

Aliases to start with

Start with the following aliases to keep things simple

clojure -T:project/create :name domain/project-name to create a new clojure project

clojure -M:repl/reloaded to run a fully loaded REPL and rich terminal UI (which can be connected to from Clojure editors)

clojure -X:test/watch to run tests on file save (or :test/run to manually run tests once)

Use Clojure to create jar and uberjar packages of the project.

REPL experienceλ︎

Rebel REPL terminal UI provides a feature rich REPL prompt experience, far beyond the basic clj command.

Command Description
clojure -M:repl/rebel Rebel terminal UI
clojure -M:env/dev:repl/rebel Rebel including deps & path from :env/dev alias to configure REPL start
clojure -M:repl/reloaded Rebel with dev & test paths, library hotload, namespace reload, portal data inspector
clojure -M:repl/rebel-cljs Run a ClojureScript REPL using Rebel Readline

:repl/help in the REPL for help and available commands. :repl/quit to close the REPL.

Clojure Projectsλ︎

  • Create Clojure CLI specific projects using deps-new
  • Create projects from deps, leiningen and boot templates with clj-new
Command Description
clojure -T:project/create library project called playground
clojure -T:project/create :template app :name practialli/service Clojure CLI project from app template
clojure -T:project/new :template luminus :name practicalli/full-stack-app +http-kit +h2 Luminus project with given name and template options

Run projectsλ︎

Run project with or without an alias:

clojure -M:alias -m
clojure -M -m

The -M flag is required even if an alias is not included in the running of the application. A warning will be displayed if the -M option is missing.

In the project deps.edn file it could be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.

{:ns-default domain.main-namespace
 :exec-fn -main
 :exec-args {:port 8888}}

Then the project can be run using clojure -X:project/run and arguments can optionally be included in this command line, to complement or replace any default arguments in exec-args.

Project dependenciesλ︎

Command Description
clojure -M:project/errors detailed report of compilation errors for a project
clojure -M:search/libraries library-name fuzzy search Maven & Clojars
clojure -M:search/libraries -F:merge library-name fuzzy search Maven & Clojars and save to project deps.edn
clojure -M:search/outdated report newer versions for maven and git dependencies
clojure -M:search/unused-vars search and remove unused vars

Project Deploymentλ︎

Deploy a project archive file locally or to

Package projects into jars using

Clojure is the recommended way to create library jar files and application Uberjar files.

Command Description
clojure -X:deps mvn-install project.jar [NEW] deploy jar file to local maven repository, i.e. ~/.m2/repository
clojure -M:project/clojars project.jar deploy jar file to Clojars
clojure -M:project/clojars-signed project.jar deploy signed jar file to Clojars

Set Clojars username/token in CLOJARS_USERNAME and CLOJARS_PASSWORD environment variables.

Set fully qualified artifact-name and version in project pom.xml file

Path to project.jar can also be set in alias to simplify the Clojure command.

clojure -X:deps mvn-install project.jar for local deployment of jars is part of the release of the Clojure CLI tools in September 2020.

Java Sourcesλ︎

Include Java source on the classpath to look up Java Class and method definitions, e.g. cider-find-var in Emacs Requires: Java sources installed locally (e.g. "/usr/lib/jvm/openjdk-11/lib/")

  • :lib/java17-source

Use the aliases with either -M or -X flags on the Clojure command line.

Format toolsλ︎

Use formatting tools to support a consistent code style across all Clojure projects

Command Description
clojure -M:format/cljstyle check / fix Check or fix code style (cljstyle)
clojure -M:format/cljfmt check / fix Check or fix code style (cljfmt)
clojure -M:format/zprint filename Format file using zprint

Include :lib/pprint-sorted when starting a REPL to pretty print data with sorted keys and set values

Databases and driversλ︎

Databases and drivers, typically for development time inclusion such as embedded databases

  • :database/h2 - H2 embedded database library and next.jdbc
  • lib/next.jdbc - include the next.jdbc library

clojure -M:database/h2 - run a REPL with an embedded H2 database and next.jdbc libraries

Use the aliases with either -M or -X flags on the Clojure command line.

Data Scienceλ︎

Visualizing projectsλ︎

Create Graphviz graphs of project and library dependencies

Morpheus creates grahps of project vars and their relationships

  • :graph/vars - generate graph of vars in a project as a .dot file
  • :graph/vars-png - generate graph of vars in a project as a .png file using src and test paths
  • :graph/vars-svg - generate graph of vars in a project as a .svg file using src and test paths

Install Graphviz to generate PNG and SVG images. Or use the Edotor website to convert .dot files to PNG or SVG images and select different graph layout engines.

Vizns creates graphs of relationships between library dependencies and project namespaces

  • :graph/deps
  • :graph/deps-png - generate a single deps-graph png image

Other options: - clojure -M:graph/deps navigate # navigable folder of SVGs - clojure -M:graph/deps single # file - clojure -M:graph/deps single -o deps-graph.png -f png - clojure -M:graph/deps single -o deps-graph.svg -f svg - clojure -M:graph/deps single --show # View graph without saving

Data Inspectorλ︎

Portal Navigate data in the form of edn, json and transit

Practicalli Clojure - data browsers section - portal

Command Description
clojure -M:inspect/portal-cli Clojure REPL with Portal dependency
clojure -M:inspect/portal-web ClojureScript web browser REPL with Portal dependency
clojure -M:inspect/portal-node ClojureScript node.js REPL with Portal dependency

Using Portal once running

(require '[portal.api :as portal]) once the REPL starts. For inspect/portal-web use (require '[portal.web :as portal]) instead

(portal/open) to open the web based inspector window in a browser.

(portal/tap)to add portal as a tap target (add-tap)

(tap> {:accounts [{:name "jen" :email ""} {:name "sara" :email ""}]}) to send data to the portal inspector window (or any other data you wish to send)

(portal/clear) to clear all values from the portal inspector window.

(portal/close) to close the inspector window.

Clojure Specificationλ︎

Clojure spec, generators and test.check

  • :lib/spec-test - generative testing with Clojure test.check
  • :lib/spec2 - experiment with the next version of Clojure spec - alpha: design may change

Unit Testing frameworksλ︎

Unit test libraries and configuration. The Clojure standard library includes the clojure.test namespace, so no alias is required.

Use expectations in a project clojure -M:test:expectations or from the command line with a test runner, e.g. clojure -M:lib/expectations:test/runner

Test runners and Test Coverageλ︎

Tools to run unit tests in a project which are defined under test path.

Run clojure with the specific test runner alias: clojure -M:test-runner-alias

Command Description
clojure -M:test/run Kaocha test runner for Clojure
clojure -M:test/watch Kaocha: watch for changes
clojure -M:test/cljs Kaocha test runner for ClojureScript

Lint toolsλ︎

Static analysis tools to help maintain code quality and suggest Clojure idioms.

Command Description
clojure -M:lint/clj-kondo comprehensive and fast static analysis lint tool
clojure -M:lint/eastwood classic lint tool for Clojure
clojure -M:lint/idiom Suggest idiomatic Clojure code

Performance testingλ︎

:performance/benchmark alias includes the Criterium library for performance testing of Clojure expressions.

Use the aliases with either -M or -X flags on the Clojure command line.

:dev/reloaded and :repl/reloaded both include criterium library

Start a REPL using the :repl/reloaded alias, or by including the :performance/benchmark in a Clojure command to start a REPL.

```shell clojure -M:repl/reloaded


```shell clojure -M:performance/benchmark:repl/basic


Require the Criterium quick-bench function

(require '[criterium.core :refer [quick-bench]])
(quick-bench (adhoc-expression))

Performance test a project in the REPL

clojure -M:performance/benchmark:repl/rebel

(require '[practicalli/namespace-name]) ; require project code
(in-ns 'practicalli/namespace-name)
(quick-bench (project-function args))

Use the aliases with either -M or -X flags on the Clojure command line.

In the REPL:

  (require '[clj-memory-meter.core :as memory-meter])
   (memory-meter/measure (your-expression))

Last update: April 27, 2023