CIDER comes with a powerful REPL, which is quite handy when you want to experiment with the code you're working on or just explore some stuff (e.g. a library you're playing with). The REPL offers a number of advanced features:

  • auto-completion
  • font-locking (the same as in clojure-mode)
  • quick access to many CIDER commands (e.g. definition and documentation lookup, tracing, etc)

Here's a list of the keybindings that are available in CIDER's REPL:

Keyboard shortcut Description
RET Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If invoked with a prefix argument is given then the input is evaluated without checking for completeness.
C-RET Close any unmatched parenthesis and then evaluate the current input in Clojure.
C-j Open a new line and indent.
C-c C-o Remove the output of the previous evaluation from the REPL buffer. With a prefix argument it will clear the entire REPL buffer, leaving only a prompt.
C-c M-o Switch between the Clojure and ClojureScript REPLs for the current project.
C-c C-u Kill all text from the prompt to the current point.
C-c C-b
C-c C-c
Interrupt any pending evaluations.
C-up
C-down
Go to to previous/next input in history.
M-p
M-n
Search the previous/next item in history using the current input as search pattern. If M-p/M-n is typed two times in a row, the second invocation uses the same search pattern (even if the current input has changed).
M-s
M-r
Search forward/reverse through command history with regex.
C-c C-n
C-c C-p
Move between the current and previous prompts in the REPL buffer. Pressing RET on a line with old input copies that line to the newest prompt.
C-c C-x Reload all modified files on the classpath.
C-u C-c C-x Reload all files on the classpath.
TAB Complete symbol at point.
C-c C-d d
C-c C-d C-d
Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol
C-c C-d j
C-c C-d C-j
Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c C-d r
C-c C-d C-r
Lookup symbol in Grimoire.
C-c C-d a
C-c C-d C-a
Apropos search for functions/vars.
C-c C-d f
C-c C-d C-f
Apropos search for documentation.
C-c C-z Switch to the previous Clojure buffer. This complements C-c C-z used in cider-mode.
C-c M-i Inspect expression. Will act on expression at point if present.
C-c M-n Select a namespace and switch to it.
C-c C-. Jump to some namespace on the classpath.
C-c M-t v Toggle var tracing.
C-c M-t n Toggle namespace tracing.
C-c C-t t
C-c C-t C-t
Run test at point.
C-c C-t g
C-c C-t C-g
Re-run the last test you ran.
C-c C-t n
C-c C-t C-n
Run tests for current namespace.
C-c C-t l
C-c C-t C-l
Run tests for all loaded namespaces.
C-c C-t p
C-c C-t C-p
Run tests for all project namespaces. This loads the additional namespaces.
C-c C-t r
C-c C-t C-r
Re-run test failures/errors.
C-c C-t b
C-c C-t C-b
Show the test report buffer.
C-c C-q Quit the current nREPL connection. With a prefix argument it will quit all connections.

There's no need to memorize this list. In any REPL buffer you'll have a REPL menu available, which lists all the most important commands and their keybindings. You can also invoke C-h f RET cider-repl-mode to get a list of the keybindings for cider-repl-mode.

In the REPL you can also use "shortcut commands" by pressing , at the beginning of a REPL line. You'll be presented with a list of commands you can quickly run (like quitting, displaying some info, clearing the REPL, etc). The character used to trigger the shortcuts is configurable via cider-repl-shortcut-dispatch-char. Here's how you can change it to ;:

(setq cider-repl-shortcut-dispatch-char ?\;)

REPL Configuration

Behavior on connect

Normally, the REPL buffer is auto-displayed in a separate window after a connection is established. You can suppress this behaviour like this:

(setq cider-repl-pop-to-buffer-on-connect nil)

If you want the REPL buffer to be auto-displayed, but don't want it to be focused, use this:

(setq cider-repl-pop-to-buffer-on-connect 'display-only)

Behavior on switch

By default C-c C-z will display the REPL buffer in a different window. You can make C-c C-z switch to the CIDER REPL buffer in the current window:

(setq cider-repl-display-in-current-window t)

Eldoc

Eldoc displays function signatures in the minibuffer as you're typing. It's extremely useful! Enable eldoc in REPL buffers like this:

(add-hook 'cider-repl-mode-hook #'eldoc-mode)

Customizing the REPL prompt

You can customize the prompt in REPL buffer. To do that you can customize cider-repl-prompt-function and set it to a function that takes one argument, a namespace name. For convenience, three functions are already provided: cider-repl-prompt-lastname, cider-repl-prompt-abbreviated, cider-repl-prompt-default and by default the last one is being used. Prompt for each of them for namespace leiningen.core.ssl:

  • cider-repl-prompt-lastname:

ssl>

  • cider-repl-prompt-abbreviated:

l.c.ssl>

  • cider-repl-prompt-default:

leiningen.core.ssl>

You may, of course, write your own function. For example, in leiningen there are two namespaces with similar names - leiningen.classpath and leiningen.core.classpath. To make them easily recognizable you can either use the default value or you can opt to show only two segments of the namespace and still be able to know which is the REPL's current namespace. Here is an example function that will do exactly that:

(defun cider-repl-prompt-show-two (namespace)
  "Return a prompt string with the last 2 segments of NAMESPACE."
  (let ((names (reverse (subseq (reverse (split-string namespace "\\.")) 0 2))))
    (concat (car names) "." (cadr names) "> ")))

TAB Completion

You can control the TAB key behavior in the REPL via the cider-repl-tab-command variable. While the default command cider-repl-indent-and-complete-symbol should be an adequate choice for most users, it's very easy to switch to another command if you wish to. For instance if you'd like TAB to only indent (maybe because you're used to completing with M-TAB) use the following snippet:

(setq cider-repl-tab-command #'indent-for-tab-command)

Result Prefix

Change the result prefix for REPL evaluation (by default there's no prefix):

(setq cider-repl-result-prefix ";; => ")

And here's the result of that change:

user> (+ 1 2)
;; => 3

Customize the REPL Buffer's Name

The REPL buffer name has the format *cider-repl project-name*. You can change the separator from space to something else by overriding nrepl-buffer-name-separator.

(setq nrepl-buffer-name-separator "-")

The REPL buffer name can also display the port on which the nREPL server is running. Buffer name will look like *cider-repl project-name:port*.

(setq nrepl-buffer-name-show-port t)

Font-locking

Normally code in the REPL is font-locked the same way as in clojure-mode. Before CIDER 0.10 by default REPL input was font-locked with cider-repl-input-face (after you press RET) and results were font-locked with cider-repl-result-face. If you want to restore the old behaviour use:

(setq cider-repl-use-clojure-font-lock nil)

Pretty printing in the REPL

Make the REPL always pretty-print the results of your commands.

M-x cider-repl-toggle-pretty-printing

Limiting printed output in the REPL

Accidentally printing large objects can be detrimental to your productivity. Clojure provides the *print-length* var which, if set, controls how many items of each collection the printer will print. You can supply a default value for REPL sessions via the repl-options section of your Leiningen project's configuration.

:repl-options {:init (set! *print-length* 50)}

REPL history

  • To make the REPL history wrap around when its end is reached:
(setq cider-repl-wrap-history t)
  • To adjust the maximum number of items kept in the REPL history:
(setq cider-repl-history-size 1000) ; the default is 500
  • To store the REPL history in a file:
(setq cider-repl-history-file "path/to/file")

Note that the history is written to the file when you kill the REPL buffer (which includes invoking cider-quit) or you quit Emacs.

There is a facility to browse the REPL history; see REPL input history browser in Miscellaneous Features