Using cider-mode

cider-mode is a pretty standard Emacs minor mode, which exists mostly to provide a common keymap for all of CIDER’s REPL-powered commands that are meant to be used from Clojure(Script) source buffers.

There you’ll find commands for evaluation, code and documentation lookup, debugging and other related functionality. This mode is the very heart of CIDER and it’s important to master it, so you can be productive.

Enabling cider-mode

cider-mode is normally enabled automatically when you start CIDER, but you can also enable it explicitly for Clojure(Script) buffers like this:

(add-hook 'clojure-mode-hook #'cider-mode)
There’s no need to enable it explicitly for modes derived from clojure-mode like clojurescript-mode.

Disabling cider-mode

cider-mode is normally disabled automatically when you quit CIDER, but you can also disable it in any buffer explicitly by typing M-x cider-mode (provided it’s already enabled in that buffer).

Basic Workflow

Typically you’d begin your interaction with any source buffer by evaluating it with C-c C-k. Afterwards you’d normally evaluate just individual forms with C-c C-e (evaluate preceding form) or C-c C-c (evaluate current top-level form).

From time to time some evaluation would take forever and you’d interrupt it with C-c C-b.

Jumping between source files and the REPL is as easy as pressing C-c C-z. If you invoke the command with a C-u prefix, while in a source buffer, it will also change the namespace of the REPL buffer to match that of the source buffer.

It’s also highly likely that you’d look up some definition with M-. or some documentation with C-c C-d C-d.

Definition and documentation lookup commands work with both Java and Clojure.

If you’re struggling to remember the name of some var you need, cider-apropos (C-c C-d a or C-c C-d C-a) and cider-apropos-documentation (C-c C-d f or C-c C-d C-f) will help you find vars matching some string.

cider-mode also provides you with code completion that works out-of-the-box and requires no extra setup and eldoc integration.

Those few essential commands can get you really far in your day to day work. Keep on reading for a lot more information!

Key Reference

Here’s a list of the key bindings of cider-mode:

Command Keyboard shortcut Description

cider-eval-last-sexp

C-x C-e
C-c C-e

Evaluate the form preceding point and display the result in the echo area and/or in an buffer overlay (according to cider-use-overlays). If invoked with a prefix argument, insert the result into the current buffer.

cider-eval-last-sexp-and-replace

C-c C-v w

Evaluate the form preceding point and replace it with its result.

cider-eval-last-sexp-to-repl

C-c M-e

Evaluate the form preceding point and output it result to the REPL buffer. If invoked with a prefix argument, takes you to the REPL buffer after being invoked.

cider-insert-last-sexp-in-repl

C-c M-p

Load the form preceding point in the REPL buffer.

cider-insert-last-sexp-in-repl

C-u C-c M-p

Load the form preceding point in the REPL buffer and eval.

cider-pprint-eval-last-sexp

C-c C-v C-f e

Evaluate the form preceding point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment.

cider-pprint-eval-defun-at-point

C-c C-v C-f d

Evaluate the top level form under point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment.

cider-eval-defun-at-point

C-M-x
C-c C-c

Evaluate the top level form under point and display the result in the echo area.

cider-eval-dwim

C-c C-v s
C-c C-v C-s

If no region is active, eval the toplevel form with cider-eval-defun-at-point. If a region is active, run cider-eval-region

cider-eval-list-at-point

C-c C-v l
C-c C-v C-l

Evaluate the list around point.

cider-eval-sexp-at-point

C-c C-v v
C-c C-v C-v

Evaluate the form around point.

cider-eval-defun-at-point

C-u C-M-x
C-u C-c C-c

Debug the top level form under point and walk through its evaluation

cider-eval-defun-up-to-point

C-c C-v z

Evaluate the preceding top-level form up to the point.

cider-eval-region

C-c C-v r

Evaluate the region and display the result in the echo area.

cider-interrupt

C-c C-b

Interrupt any pending evaluations.

cider-macroexpand-1

C-c C-m

Invoke macroexpand-1 on the form at point and display the result in a macroexpansion buffer. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1.

cider-macroexpand-all

C-c M-m

Invoke clojure.walk/macroexpand-all on the form at point and display the result in a macroexpansion buffer.

cider-eval-ns-form

C-c C-v n

Eval the ns form. If invoked with a prefix argument, undefine all vars and aliases in the ns first.

cider-repl-set-ns

C-c M-n (M-)n

Switch the namespace of the REPL buffer to the namespace of the current buffer.

cider-switch-to-repl-buffer

C-c C-z

Switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.

cider-switch-to-repl-buffer

C-u C-u C-c C-z

Switch to the REPL buffer based on a user prompt for a directory.

cider-load-buffer-and-switch-to-repl-buffer

C-c M-z

Load (eval) the current buffer and switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.

cider-describe-connection

C-c M-d

Display default REPL connection details, including project directory name, buffer namespace, host and port.

cider-find-and-clear-repl-output

C-c C-o

Clear the last output in the REPL buffer. With a prefix argument it will clear the entire REPL buffer, leaving only a prompt. Useful if you’re running the REPL buffer in a side by side buffer.

cider-load-buffer

C-c C-k

Load (eval) the current buffer. If invoked with a prefix argument, undefine all vars and aliases in the ns before loading.

cider-load-file

C-c C-l

Load (eval) a Clojure file. If invoked with a prefix argument, undefine all vars and aliases in the ns before loading.

cider-load-all-files

C-c C-M-l

Load (eval) all Clojure files below a directory. If invoked with a prefix argument, undefine all vars and aliases in each file before loading.

cider-ns-refresh

C-c M-n (M-)r

Reload all modified files on the classpath. If invoked with a prefix argument, reload all files on the classpath. If invoked with a double prefix argument, clear the state of the namespace tracker before reloading.

cider-doc

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 it inverts the value of cider-prompt-for-symbol.

cider-javadoc

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 it inverts the value of cider-prompt-for-symbol.

cider-clojuredocs

C-c C-d c
C-c C-d C-c

Lookup symbol in ClojureDocs. If invoked with a prefix argument it inverts the value of cider-prompt-for-symbol.

cider-clojuredocs-web

C-c C-d w
C-c C-d C-w

Open the ClojureDocs documentation for symbol in a web browser. If invoked with a prefix argument it inverts the value of cider-prompt-for-symbol.

cider-apropos

C-c C-d a
C-c C-d C-a

Apropos search for functions/vars.

cider-apropos-documentation

C-c C-d f
C-c C-d C-f

Apropos search for documentation.

cider-apropos-documentation-select

C-c C-d e
C-c C-d C-e

Apropos search for documentation & select.

cider-inspect

C-c M-i

Inspect expression. Will act on expression at point if present.

cider-toggle-trace-var

C-c M-t v

Toggle var tracing. If invoked with a prefix argument it inverts the value of cider-prompt-for-symbol.

cider-toggle-trace-ns

C-c M-t n

Toggle namespace tracing.

cider-undef

C-c C-u

Undefine a symbol. If invoked with a prefix argument it inverts the value of cider-prompt-for-symbol.

cider-undef-all

C-c C-M-u

Undefine all symbols and aliases in the namespace.

cider-test-run-test

C-c C-t t
C-c C-t C-t

Run test at point. If the form under the point is a function, try to search and run a corresponding test.

cider-test-rerun-test

C-c C-t a
C-c C-t C-a

Re-run the last test you ran.

cider-test-run-ns-tests

C-c C-t n
C-c C-t C-n

Run tests for current namespace.

cider-test-run-loaded-tests

C-c C-t l
C-c C-t C-l

Run tests for all loaded namespaces.

cider-test-run-project-tests

C-c C-t p
C-c C-t C-p

Run tests for all project namespaces. This loads the additional namespaces.

cider-test-rerun-failed-tests

C-c C-t r
C-c C-t C-r

Re-run test failures/errors.

cider-test-show-report

C-c C-t b
C-c C-t C-b

Show the test report buffer.

cider-find-var

M-.

Jump to the definition of a symbol. If invoked with a prefix argument it inverts the value of cider-prompt-for-symbol.

cider-find-dwim-at-mouse

mouse-5 or mouse-9

Jump to the definition of a symbol using mouse.

xref-pop-marker-stack

mouse-4 or mouse-8

Jump back to where cider-find-dwim-at-mouse was invoked.

cider-find-resource

C-c M-.

Jump to the resource referenced by the string at point.

cider-find-ns

C-c C-.

Jump to some namespace on the classpath.

cider-xref-fn-refs

C-c C-? r

Display function usages across loaded namespaces in a dedicated buffer.

cider-xref-fn-refs-select

C-c C-? C-r

Display function usages across loaded namespaces in a minibuffer selector.

cider-xref-fn-deps

C-c C-? d

Display function deps (other functions used by it) in a dedicated buffer.

cider-xref-fn-deps-select

C-c C-? C-d

Display function deps (other functions used by it) in a minibuffer selector.

cider-pop-back

M-,

Return to your pre-jump location.

complete-symbol

M-TAB

Complete the symbol at point.

cider-quit

C-c C-q

Quit the current nREPL connection.

There’s no need to memorize this list. If you’re in a Clojure buffer with cider-mode active you’ll have a CIDER menu available. The menu lists all the most important commands and their keybindings. You can also invoke C-h f RET cider-mode to get a list of the keybindings for cider-mode.

CIDER interactions menu

An even better solution would be to install which-key, which will automatically show you a list of available keybindings as you start typing some keys. This will simplify your interactions with CIDER quite a lot, especially in the beginning. Here’s what you’d see if you typed C-c C-d in a Clojure buffer:

CIDER which-key