# Install Clojure CLI
{align=right loading=lazy style="height:150px;width:150px"}
Clojure CLI is a command line tool for running a Clojure REPL, project or tool.
Clojure CLI automatically downloads required library dependencies, including the Clojure Standard library.
??? INFO "Clojure distributed as a library"
Clojure is distributed as a library (`.jar` Java ARchive) via Maven Central.
A `deps.edn` file specifies the version of Clojure to be used with a project.
```clojure
:deps {org.clojure/clojure {:mvn/version "1.12.0"}}
```
The Clojure CLI tool provides a default Clojure library version if not specified in the project or user `deps.edn` files.
[Clojure releases](https://clojure.org/releases/downloads){target=_blank .md-button}
[:fontawesome-solid-book-open: Practicalli Clojure CLI Config](#practicalli-clojure-cli-config) extends the Clojure CLI with a range of development tools as well as configuration for Clojure LSP and cljstyle code format tool.
=== "Linux"
Use the Linux script installer from [Clojure.org - Getting Started](https://clojure.org/guides/getting_started#_installation_on_linux) to install or update to the latest stable release
```shell
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh && \
chmod +x linux-install.sh && \
sudo ./linux-install.sh
```
The installation creates `/usr/local/bin/clojure`, `/usr/local/bin/clj` wrapper and `/usr/local/lib/clojure` directory.
??? HINT "Use alternative location - unattended install"
`--prefix` option specifies an alternative lolcation for the Clojure CLI install.
When permissions are not available or for automating the install without password prompt, use a local user specific install, e.g.
```shell
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh && \
chmod +x linux-install.sh && \
./linux-install.sh --prefix $HOME/.local/
```
??? INFO "Include version number for specific release"
Each Clojure CLI version is a number that represents the version of Clojure used and the build version of the Clojure CLI tool, e.g. `1.11.1.1413`.
[Clojure CLI Releases page](https://clojure.org/releases/tools){target=_blank .md-button}
Include the version in the script name for repeatable environments, e.g. in Dockerfile configuration and Continuous Integraion workflows.
```shell title="Clojure CLI install specific version"
curl -L -O https://github.com/clojure/brew-install/releases/1.11.1.1413/download/linux-install.sh && \
chmod +x linux-install-1.11.1.1413.sh
sudo ./linux-install-1.11.1.1413.sh
```
=== "Homebrew"
Practically recommends setting `XDG_CONFIG_HOME` to the `.config` directory, to avoid creating another dot directory in the root of the user account. Add the following to `~/.bashrc` for the bash shell or `~/.zshenv` for Zsh.
```
export XDG_CONFIG_HOME="$HOME/.config"
```
Use the Homebrew command with the [clojure/tools tap](https://github.com/clojure/homebrew-tools), as defined in the [Clojure.org Getting started guide](https://clojure.org/guides/getting_started#_installation_on_linux)
```shell
brew install clojure/tools/clojure
```
Use Homebrew to update an install of Clojure CLI to the latest release
```shell
brew upgrade clojure/tools/clojure
```
> [Homebrew on Linux or Windows with WSL](https://docs.brew.sh/Homebrew-on-Linux)
=== "Windows"
For Windows 10 use [Windows Subsystem for Linux and Windows Terminal are recommended](https://conan.is/blogging/clojure-on-windows.html) if you have administrative privileges and are comfortable using a Unix system on the command line.
Alternatively install [scoop.sh](https://scoop.sh/), a command line installer for windows. [Powershell 5](https://aka.ms/wmf5download) or greater is required. Follow the [scoop-clojure getting started guide](https://github.com/littleli/scoop-clojure/wiki/Getting-started), summarized here:
Open "Windows PowerShell" and enter the following commands to configure the shell:
```shell
iwr -useb get.scoop.sh | iex
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
```
Then in the same PowerShell window, install the Clojure related tools using the following commands:
```shell
scoop bucket add extras
scoop bucket add java
scoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure
scoop install git 7zip pshazz temurin-lts-jdk clj-deps leiningen clj-kondo vscode coreutils windows-terminal
```
> Reference: [Clojure CLI Install - Clojure.org](https://clojure.org/guides/install_clojure){target=_blank} - official guide
## Practicalli Clojure CLI Config
Add a wide range of community tools to extend the capabilities of Clojure CLI via the aliases.
Clone [:fontawesome-solid-book-open: Practicalli Clojure CLI Config](https://github.com/practicalli/clojure-cli-config){target=_blank} GitHub repository, first removing the `$XDG_CONFIG_HOME/clojure` and `$HOME/.clojure` directory if they exist.
??? INFO "User configuration locations"
If `XDG_CONFIG_HOME` environment variable is set, then the user configuration is `$XDG_CONFIG_HOME/clojure/deps.edn`
Otherwise the user configuration is `$HOME/.clojure/deps.edn`.
`CLJ_CONFIG` environment variable can be used to set a custom location, overriding any other location.
!!! HINT "Practicalli recommends FreeDesktop XDG location"
Practically recommends setting `XDG_CONFIG_HOME` to the `.config` directory to simplify versioning of configuration.
Configure `~/.bashrc` for the bash shell
```shell title="Bash .bashrc file"
export XDG_CONFIG_HOME="$HOME/.config"
```
Configure `~/.zshenv` for Zsh
```shell
# Set XDG_CONFIG_HOME for clean management of configuration files
export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
export XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
export ZDOTDIR="${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}"
```
=== "Free Desktop XDG CONFIG"
If `XDG_CONFIG_HOME` environment variable is set, clone the repository to `$XDG_CONFIG_HOME/clojure`
Via SSH
```shell
git clone git@github.com:practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure
```
Via HTTPS:
```shell
git clone https://github.com/practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure
```
=== "Classic Config"
Clojure CLI will look for its configuration in `$HOME/.clojure` directory if `$XDG_CONFIG_HOME` and `CLJ_CONFIG` environment variables not set.
Via SSH
```shell
git clone git@github.com:practicalli/clojure-cli-config.git $HOME/.clojure
```
Via HTTPS
```shell
git clone https://github.com/practicalli/clojure-cli-config.git $HOME/.clojure
```
## Check Configuration
The `--version` flag shows prints the current version of Clojure CLI.
```shell
clojure --version
```
{loading=lazy}
> NOTE: `clojure -Sdescribe` is now deprecated and will be removed. Use tools.build API if more details are required about the configuration of Clojure CLI.
## Optional rlwrap readline
The `rlwrap` binary is a basic readline tool that provides a history of commands entered into a terminal UI when running a Clojure REPL with the `clj` wrapper script.
Pressing the ++arrow-up++ and ++arrow-down++ keys will scroll through the code previously entered in the REPL.
`rlwrap` is available with most Linux systems. Look for install instructions by searching for rlwrap in a web browser or build from source from the [:globe_with_meridians: rlwrap GitHub repository](https://github.com/hanslub42/rlwrap).
!!! HINT "Use Rebel Readline for a rich terminal UI experience"
[:fontawesome-solid-book-open: rebel readline](/clojure/clojure-cli/repl/) is an advanced readline tool providing auto-completion, documentation, signature help and multi-line editing, all within a terminal UI
Rebel is a much richer experience than the `clj` wrapper with `rlwrap`. Rebel should not be used with `clj`.
Rebel Readline is part of the [Practicalli Clojure CLI config](#practicalli-clojure-cli-config).
```shell
clojure -M:repl/rebel
```