Understand deps.edn and the Clojure CLI

The Clojure CLI is not a Maven clone. It is a small set of commands that reads deps.edn, builds a classpath, and starts Clojure in a few different modes.

For Java engineers, the most useful translation is:

clj vs clojure

The installed CLI commonly gives you two commands:

For learning, use clj when you want a terminal REPL. Use clojure in scripts, README command blocks, and CI examples.

The Core deps.edn Keys

A compact project file:

1{:paths ["src" "resources"]
2 :deps {org.clojure/clojure {:mvn/version "1.12.5"}
3        org.clojure/data.json {:mvn/version "2.5.2"}}
4 :aliases
5 {:dev {:extra-paths ["dev"]}
6  :run {:main-opts ["-m" "orders.core"]}
7  :test {:extra-paths ["test"]
8         :main-opts ["-m" "orders.test-runner"]}}}

Read it as classpath data:

Unlike Maven or Gradle, deps.edn does not define a full lifecycle. It describes how to assemble code and dependencies for the command you choose.

Command Modes

The CLI flags matter because they activate aliases differently.

For a first project, -M is enough. Learn -X and -T when you start using task functions and build tools.

Main Invocation With -M

Alias:

1{:aliases
2 {:run {:main-opts ["-m" "orders.core"]}}}

Namespace:

1(ns orders.core)
2
3(defn -main
4  [& args]
5  (println "Args:" args))

Run:

1clojure -M:run 1001

This is closest to a Java main method: the namespace loads, then -main receives command-line arguments.

Exec Functions With -X

Exec functions are useful for data-oriented tasks:

1(ns orders.tasks)
2
3(defn report
4  [{:keys [format limit]}]
5  (println "format =" format "limit =" limit))

Alias:

1{:aliases
2 {:report {:exec-fn orders.tasks/report
3           :exec-args {:format "edn" :limit 10}}}}

Run:

1clojure -X:report :limit 5

Think of -X as “call this task function with an EDN map,” not as a shell-style main argument parser.

Tools With -T

Tools aliases are commonly used for build functions, especially with tools.build:

1{:aliases
2 {:build {:deps {io.github.clojure/tools.build {:mvn/version "0.10.13"}}
3          :ns-default build}}}

Run:

1clojure -T:build uber

The -T mode is for tool execution. Keep it conceptually separate from your application’s normal runtime classpath.

Common Mistakes

Key Takeaways

• deps.edn is classpath and command data, not a full build lifecycle.
• clj is convenient for interactive terminal REPL work; clojure is better for scripts and automation.
• Use -M for -main, -X for exec functions, and -T for tools.
• Aliases should make classpath differences explicit.
• Java build-tool instincts help, but the CLI is intentionally smaller and more composable.

Quiz: deps.edn and CLI