Unravel your REPL
Clone or download
cgrand Merge pull request #70 from kommen/readme-clojure-cli
Document starting a repl server with Clojure 1.9
Latest commit 2d21ee3 Feb 23, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci WIP Dec 5, 2017
bin New release Dec 31, 2017
dev/cljs Use cljs.user ns Apr 14, 2017
provision Run in container Dec 29, 2017
resources/unrepl Update unrepl Dec 7, 2017
scripts Dual pane wrapper Jan 1, 2018
src/unravel Evil times evil equals not evil Jan 2, 2018
test Set up Circle CI (#43) Nov 27, 2017
.editorconfig NPM-ify Apr 2, 2017
.gitignore WIP Dec 31, 2017
.ignore Add --blob option Nov 20, 2017
README.md Document starting a repl server with Clojure 1.9 Feb 23, 2018
TODO.md Prepare release Jul 29, 2017
contributing.md WIP Dec 5, 2017
package.json New release Dec 31, 2017
project.clj Check on CI Dec 4, 2017
version.txt New release Dec 31, 2017
yarn.lock Set up Circle CI (#43) Nov 27, 2017



Unravel your REPL

npm version

Unravel is a simple command-line client for Clojure REPLs. It is based on the unrepl protocol, so instead of relying on nREPL, unravel communicates with your Clojure process through a Socket Server REPL.

Unravel provides a richer user experience by:

  • showing docstring and arglist of vars as you type them
  • eliding long or infinite sequences but allowing the user to request a continuation


To use unravel you need Clojure 1.8.0 or above.

Simple installation

On macOS, the easiest way to install unravel is via brew:

brew install unrepl/bin/unravel

On Linux or macOS you can also install (or update) unravel via npm:

sudo npm install -g unravel-repl

In either case you should end up with an unravel binary in your PATH:

unravel --version

Installation from git

For a more up-to-date version, you can check out master:

git clone https://github.com/pesterhazy/unravel.git
cd unravel
npm install
scripts/run [--debug] <host> <port>


Connect to a Clojure Socket REPL:

unravel [--debug] <host> <port>

In addition to common readline shortcuts, the following keybindings are available:

  • Control-D: exit the REPL
  • Control-O: show docstring for symbol under the cursor
  • <Tab>: complete var or namespace

Lines starting with #__ are treated as special commands and interpreted by the REPL client. The following specials are available:

  • #__help shows a help screen
  • #__1, #__2, #__3 ...: expand the numberd lazy seq ellipsis
  • #__: expand the most recent lazy seq ellipsis

Launching a Socket REPL

You can easily enable the Socket REPL feature for your Clojure project, whether you use boot, lein or a plain clojure jar. The Socket REPL does not have any dependencies other than Clojure 1.8.0.

To launch a Clojure process with a Socket REPL listening on port 50505 using boot, use:

boot -i "(do (require 'clojure.core.server) (clojure.core.server/start-server {:port 50505 :name :repl :accept 'clojure.core.server/repl}))" wait

Or if you have boot >= 2.7.2:

boot socket-server --port 50505 wait

Using Leiningen:

JVM_OPTS='-Dclojure.server.myrepl={:port,50505,:accept,clojure.core.server/repl}' lein repl

Using a plain Clojure jar:

java -Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}" -jar ~/.m2/repository/org/clojure/clojure/1.8.0/clojure-1.8.0.jar

As of Clojure 1.9 you can use the clojure command line tool:

clojure -J-Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}"

You can then connect to the process by running unravel in a separate terminal window:

unravel localhost 50505



  • Print vars correctly
  • Update unrepl
  • Use 'user as init-ns
  • Don't write to socket after closing connection
  • Update to Lumo 1.6.0


  • Enable lumo caching (3x startup time improvement)
  • Interrupt running process on SIGINT
  • Fix exceptions when connected to Boot-based socket server


  • Live docs for vars and namespaces
  • Use separate tooling connection for tab completion and docs
  • Start in "user" namespace


  • Fix installation via NPM


  • Add repl specials
  • Expand lazy seq ellipsis
  • Fix issue with non-existant namespaces


  • Tab completion (namespaces and vars)
  • Pretty-print exceptions
  • Use tagged literals
  • Re-prompt on newline or Control-C


Persistent history


Distribute via npm


Show docstring

Future work

See TODO.md for a list of planned improvements. Unravel is developed in conjunction with unrepl.


  • The Ultimate Guide To Clojure REPLs on the Socket REPL

  • replicant: proof of concept of using Socket REPL for tooling

Join the #unrepl channel in the Clojurians slack!


See [contributing.md].


(c) 2017 Paulus Esterhazy

Unrepl payload.clj (c) 2017 Christophe Grand

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.