dot-clojure

This is my personal .config/clojure/deps.edn (or .clojure/deps.edn) file providing useful clj aliases drawn from a variety of projects. It is published to GitHub so I can keep all my computers sync'd up -- and to provide a range of examples that folks new to the Clojure CLI might find helpful.

I highly recommend ensuring you have the latest Clojure CLI installed!

The latest Clojure CLI was 1.12.3.1577 (Sep 25, 2025) when I last updated this file.

In addition, my .config/clojure/tools/ (.clojure/tools/) folder is also here, containing the tools that I've installed globally, via the Clojure CLI -- see Tool installation and invocation in the Clojure CLI Reference. As I add global tools, I am removing them as aliases.

The main alias I use here is :dev/repl which starts various combinations of REPL tooling. See The :dev/repl Alias below for more details.

Since it is my personal file, it may make assumptions about my own environment. I make no effort at backward-compatibility and may add, delete, or change aliases as they benefit me personally. Caveat Programmer!

If you want a really well-documented, well-maintained alternative that actually tracks versions of tools, I would recommend you use the Practicalli Clojure deps.edn project instead!

With that caveat out of the way, here is some basic documentation about my tools and aliases (there are additional examples in the comments in the deps.edn file itself). Note: I have recently cleaned this file up and removed a lot of aliases I no longer use!

TL;DR: add the following dependency and then start a REPL with clj -M:dev/repl (optionally with other aliases before it to bring in more tooling):

:aliases
{:dev/repl
 {:extra-deps
  {io.github.seancorfield/dot-clojure
   {:git/tag "v1.4.1"
    :git/sha "b5f7199"}}
  :main-opts ["-m" "org.corfield.dev.repl"]}}

There is also a bin/repl bash script that runs clojure "$@" -M:1.12:allow-attach-self:portal:test:cider-nrepl:rebel:dev/repl to start an nREPL server with CIDER middleware, and then a Rebel Readline interactive REPL, as a client to that nREPL server, with Portal available (and clojure.tools.logging, if present, patched to tap> all log messages for Portal, also logging4j2 -- my log4j2 wrapper).

The :allow-attach-self alias is a recent addition, which sets the JVM property -Djdk.attach.allowAttachSelf for JDK 21+ so that nREPL can stop evaluation threads.

Basic Tools

These are installed via clojure -Ttools install ... and usable via clojure -T with the tool name.

• antq -- the outdated dependencies checker:
  • clojure -Tantq outdated -- check the current project's dependencies,
  • clojure -A:deps -Tantq help/doc -- for more information and other functions.
• clj-watson -- a software composition analysis scanner, based on the National Vulnerability Database: clj-watson
  • clojure -Tclj-watson scan :deps-edn-path '"deps.edn"' :output '"stdout"'
• new -- the latest version of deps-new to create new CLI/deps.edn projects: [This uses a different (simpler!) templating system to clj-new, below, and therefore does not recognize Leiningen or Boot templates!]
  • clojure -Tnew app :name myname/myapp -- creates a new deps.edn-based application project,
  • clojure -Tnew lib :name myname/mylib -- creates a new deps.edn-based library project,
  • clojure -Tnew template :name myname/mytemplate -- creates a new deps.edn-based template project,
  • clojure -A:somealias -Tnew create :template some/thing :name myname/myapp -- locates a template for some/thing on the classpath, based on :somealias, and uses it to create a new deps.edn-based project,
  • clojure -A:deps -Tnew help/doc -- for more information and other functions.

And the older clj-new tool:

• clj-new -- a recent stable release of clj-new to create new projects from (Leiningen and other) templates:
  • clojure -Tclj-new app :name myname/myapp -- creates a new deps.edn-based application project (using tools.build for the uberjar),
  • clojure -Tclj-new lib :name myname/mylib -- creates a new deps.edn-based library project (using tools.build for the jar),
  • clojure -Tclj-new template :name myname/mytemplate -- creates a new deps.edn-based template project (using tools.build for the jar),
  • clojure -Tclj-new create :template something :name myname/myapp -- locates a template for something and uses it to create a new project (which might be deps.edn-based or lein-based, depending on the template),
  • clojure -A:deps -Tclj-new help/doc -- for more information and other functions.

More tools will be added to this section over time (as more tools add :tools/usage to their deps.edn files).

Basic Aliases

Deploy jar files (if you don't have a build.clj file):

• :deploy -- pulls in and runs a recent stable release of Erik Assum's deps-deploy and deploys the specified JAR file to Clojars, based on your pom.xml and the CLOJARS_USERNAME and CLOJARS_PASSWORD environment variables; clojure -X:deploy :artifact '"MyProject.jar"'

There are aliases to pull in various useful testing and debugging tools:

• :test -- adds both test and src/test/clojure to your classpath and pulls in the latest stable version of test.check

• :lazy -- adds a recent stable release of NoahTheDuke's Lazytest for more expressive and powerful testing; can be used as clojure -M:test:lazy to run just Lazytest tests, or clojure -X:test:lazy:runner to run both Lazytest and clojure.test tests (via my fork of Cognitect's test-runner project)

• :runner -- pulls in my fork of Cognitect Labs' test-runner project and runs any tests it can find

• :eastwood -- pulls and runs in a recent stable release of Eastwood on your src and test folders; use with :test above

• :splint -- pulls in and runs a recent stable release of Splint on your project or specific files

• :check -- pulls in Athos' Check project to compile all your namespaces to check for syntax errors and reflection warnings like lein check

• :bench -- pulls in a recent stable release of Criterium for benchmarking your code

• :this -- adds the current directory as a :local/root dependency so that you can use help/doc on namespaces within your project, e.g., clojure -X:deps:this help/doc :ns my.app.core

• :no-main -- adds an empty :main-opts so that you can run clojure -M:test:no-main ... in projects that combine the test deps with the test runner (instead of having them separate as this deps.edn has them). Because :main-opts is "last one wins", this allows you to essentially override (or remove) any :main-opts from aliases, so you can manually specify your own main options on the command-line.

There are aliases to pull in and start various REPL-related tools:

• :dev/repl -- depending on what is on your classpath, start Rebel Readline, with a Socket REPL (if requested -- note that "port 0" will dynamically select an available port and print it out), but SOCKET_REPL_PORT env var and socket-repl-port property override, saves port to .socket-repl-port file for next time;

  • usage:
    • clj -M:dev/repl -- basic REPL or
    • clj -M:portal:dev/repl -- ...with Portal or
    • clojure -M:rebel:dev/repl -- Rebel Readline REPL or
    • clojure -M:rebel:portal:dev/repl -- ...with Portal or
    • clojure -M:nrepl:dev/repl -- basic nREPL server or
    • clojure -M:nrepl:portal:dev/repl -- ...with Portal (& middleware) or
    • clojure -M:cider-nrepl:dev/repl -- CIDER nREPL server or
    • clojure -M:cider-nrepl:portal:dev/repl -- ...with Portal (& middleware) or
    • clojure -M:rebel:nrepl:dev/repl -- Rebel Readline nREPL client + basic nREPL server or
    • clojure -M:rebel:nrepl:portal:dev/repl -- ...with Portal (& middleware) or
    • clojure -M:rebel:cider-nrepl:dev/repl -- Rebel Readline nREPL client + CIDER nREPL server or
    • clojure -M:rebel:cider-nrepl:portal:dev/repl -- ...with Portal (& middleware) or
  • Also works with Figwheel Main (now that I've started doing ClojureScript!):
    • clojure -M:portal:fig:build:dev/repl or

• :classes -- adds the classes folder to your classpath to pick up compiled code (e.g., see https://clojure.org/guides/dev_startup_time)

• :socket -- starts a Socket REPL on port 50505; can be combined with other aliases since this is just a JVM option

• :rebel -- starts a Rebel Readline REPL; note that this also loads the Rebel Readline nREPL client library

• :nrepl -- starts a (headless) nREPL server on a random available port; clojure -M:nrepl

• :cider-nrepl -- starts a (headless) CIDER-enhanced nREPL server on a random available port; clojure -M:cider-nrepl

• :datomic/dev.datafy -- adds datafy/nav support for Datomic objects via datomic/dev.datafy

• :dbxray -- adds donut-party/dbxray to help visualize your database structure

• :jedi-time -- adds datafy/nav support for Java Time objects via jedi-time

• :portal -- pulls in a recent stable release of the Portal data visualization tool -- see the Portal web site for usage options

• :reflect -- adds Stuart Halloway's reflector utility (best used with Portal)

There are aliases to pull in specific versions of Clojure:

• :1.12 -- Clojure 1.12.3 -- see changes to Clojure in version 1.12.3
  • :1.12.0 -- Clojure 1.12.0
  • :1.12.1 -- Clojure 1.12.1
  • :1.12.2 -- Clojure 1.12.2
• :1.11 -- Clojure 1.11.4
  • :1.11.3 -- Clojure 1.11.3
  • :1.11.2 -- Clojure 1.11.2
  • :1.11.1 -- Clojure 1.11.1
  • :1.11.0 -- Clojure 1.11.0
• :1.10 -- Clojure 1.10.3
  • :1.10.2 -- Clojure 1.10.2
  • :1.10.1 -- Clojure 1.10.1
  • :1.10.0 -- Clojure 1.10.0
• :1.9 -- Clojure 1.9.0
• :1.8 -- Clojure 1.8.0
• ... back to :1.0 (note: :1.5 is actually Clojure 1.5.1 to avoid a bug in Clojure 1.5.0, and :1.2 is 1.2.1)

Note: the :master alias has been removed since it is rarely different from the most recent (alpha) release of Clojure.

To work with the Polylith command-line tool:

• :poly -- the latest (stable) release of Polylith's poly tool, as a library from Clojars -- example usage:
  • clojure -M:poly shell -- start an interactive Polylith shell,
  • clojure -M:poly info :loc -- display information about a Polylith workspace, including lines of code,
  • clojure -M:poly create component name:user -- create a user component in a Polylith workspace,
  • clojure -M:poly test :dev -- run tests in the dev project context, in a Polylith workspace.
• :poly-next -- the latest cljs-support branch of the poly tool.

Note: the EXPERIMENTAL :add-libs alias has been removed -- use the clojure.repl.deps in Clojure 1.12.0 or later instead!

The :dev/repl Alias

The :dev/repl alias calls org.corfield.dev.repl/-main in the repl.clj file from this repo. That does a number of things (see the -main docstring for more details):

• Optionally, starts a Socket REPL server (with the port selected via an environment variable, a JVM property, or a dot-file created on a previous run).
• If both Portal and org.clojure/tools.logging are on the classpath, it patches tools.logging to also tap> every log message in a format that Portal understands and can display (usually with the ability to go to the file/line listed in the log entry).
• If both Portal and com.github.seancorfield/logging4j2 are on the classpath, it patches logging4j2 to also tap> every log message in a format that Portal understands and can display (usually with the ability to go to the file/line listed in the log entry).
• If Portal 0.33.0 or later is on the classpath, use the Portal middleware with nREPL (if CIDER or nREPL are on the classpath). If using Portal 0.40.0 or later, this also adds the Portal Notebook middleware.
• Starts Figwheel Main, if present on the classpath, else
• Starts Rebel Readline, if present on the classpath, else
• Starts a CIDER-enhanced nREPL Server, if cider-nrepl is present on the classpath, else
• Starts an nREPL Server, if present on the classpath.

As of v1.1.0, can start a Rebel Readline REPL and an nREPL Server together.

Note 1: since the repl.clj code uses requiring-resolve, it requires at least Clojure 1.10.0!

Note 2: if the Portal middleware is added to nREPL/CIDER, all evaluated results will be tap>'d (if the Portal UI is open and listening); my VS Code/Calva setup has additional configuration for working with Portal when the middleware is enabled!

Note 3: as of v1.1.3, adds user/uptime so you can easily see how long your REPL has been running, in a human-readable format.

Use with Figwheel

If you are doing ClojureScript development with Figwheel (figwheel-main) then you can do something like:

clojure -M:portal:fig:build:dev/repl

You'll get the regular Figwheel build REPL (for ClojureScript, which uses Rebel Readline) and a browser open on your application, plus a Socket REPL on an available port (or whatever your env says, for Clojure evaluation).

Connect to the Socket REPL, write your code as .cljc files, and you'll have the full power of your editor, Portal, and Figwheel! What you evaluate in your editor will be treated as Clojure code (and can be tap>'d into Portal, for example). What you evaluate at the REPL itself will be treated as ClojureScript code (and will affect your application instead).

License

Copyright © 2018-2025 Sean Corfield

Distributed under the Apache Software License version 2.0.