Basic Usage

CIDER comes with a powerful REPL that complements the interactive development functionality in cider-mode. Using the CIDER REPL you can experiment with your running program, test functions, or just explore a new library you’re interested in using. The CIDER REPL offers a number of advanced features:

  • code completion

  • font-locking (the same as in clojure-mode)

  • quick access to many CIDER commands (e.g. definition and documentation lookup, tracing, etc)

  • pretty-printing of evaluation results

  • inline display of images

  • persistent REPL history

  • powerful REPL history browser

  • eldoc support

  • highly customizable REPL prompt

Interacting with the REPL

Interacting with CIDER’s REPL is pretty simple - most of the time you’d just write expressions there and press RET to evaluate them.

But the REPL is a bit more powerful than that and it allows you to do some things that might not be available in other Clojure REPLs. Some examples of such things would be:

  • You can close an incomplete expression with C-RET

  • You can enter a multi-line expression by pressing C-j at the end of each line

  • You can quickly jump to the definition of a symbol (.) or to its documentation (C-c C-d d)

  • You can clear the output of the last expression with C-c C-o

  • You can clear the REPL buffer with C-u C-c C-o

  • You can jump between your source buffers and the REPL with C-c C-z

  • You can jump between your Clojure and ClojureScript REPLs with C-c M-o

On top of this the REPL is extremely configurable and you can tweak almost every aspect of it.

Interrupting Evaluations

If you accidentally try to evaluate something that’s going to take a lot of time (if it finishes at all), you can interrupt the rogue evaluation operation by pressing C-c C-c.

Note that this is different from the keybinding for interrupting evaluations in source buffers, namely C-c C-b.

Quitting a REPL

When you’re done with a REPL you can dispose of it with C-c C-q.

Avoid killing REPL buffers with C-c C-k. This will forgo some of the operations needed to properly dispose of a REPL buffer.

Loading REPL Utility Functions

Normally Clojure REPLs load the following code in the first REPL that you start:

(clojure.core/apply clojure.core/require clojure.main/repl-requires)

CIDER does this as well, but goes one step further and actually allows you to control what code to evaluate when a REPL is being initialized via the variable cider-repl-init-code.

This initialization code is auto-loaded only in the first REPL namespace (normally user), but you can easily invoke it in any namespace using the REPL shortcut require-repl-utils. The functionality is also accessible via CIDER’s menu ("REPL → Require REPL utils").

You’ll rarely need the REPL utility functions when using CIDER, as it provides many Emacs commands that behave similarly (e.g. instead of doing something like (doc str) you’d probably use the cider-doc (C-c C-d C-d) command).

Known Limitations

Performance can degrade when the REPL buffer grows very large. This is especially true if either cider-repl-use-clojure-font-lock or nrepl-log-messages are enabled.

Very long lines are guaranteed to bring Emacs to a crawl, so using a value of cider-print-fn that wraps lines beyond a certain width (i.e. any of the built-in options except for pr) is advised.

You can use cider-repl-clear-output to either clear the result of the previous evaluation, or with a prefix argument clear the entire REPL buffer. You can also set cider-repl-buffer-size-limit which will enable trimming the buffer automatically after each evaluation. This trimming can also be invoked manually with cider-repl-trim-buffer.