A standalone nREPL/prepl client written in Go, heavily inspired by Grenchman
Trenchman is a standalone nREPL/prepl client, which means that it can be used as an ordinary REPL without having to make it cooperate with an editor or any other development tool. Unlike ordinary Clojure REPLs, it starts up instantly as it just connects to a running nREPL/prepl server, eliminating the overhead of launching a JVM process and bootstrapping Clojure for every startup.
- Fast startup
- Written in Go and runs on various platforms
- Support for nREPL and prepl
- Works as a language-agnostic nREPL client
Table of Contents
Homebrew (macOS and Linux)
To install Trenchman via Homebrew, run the following command:
$ brew install athos/tap/trenchman
$ brew upgrade trenchman
Pre-built binaries are available for linux, macOS and Windows on the releases page.
If you have the Go tool chain installed, you can build and install Trenchman by the following command:
$ go install github.com/athos/trenchman/cmd/[email protected]
Trenchman does not have
readline support at this time. If you want to use features like line editing or command history, we recommend using
rlwrap together with Trenchman.
usage: trench [<flags>] [<args>...] Flags: --help Show context-sensitive help (also try --help-long and --help-man). -p, --port=PORT Connect to the specified port. --port-file=FILE Specify port file that specifies port to connect to. Defaults to .nrepl-port. -P, --protocol=nrepl Use the specified protocol. Possible values: n[repl], p[repl]. Defaults to nrepl. -s, --server=[(nrepl|prepl)://]host[:port] Connect to the specified URL (e.g. prepl://127.0.0.1:5555). --retry-timeout=DURATION Timeout after which retries are aborted. By default, Trenchman never retries connection. --retry-interval=1s Interval between retries when connecting to the server. -i, --init=FILE Load a file before execution. -e, --eval=EXPR Evaluate an expression. -f, --file=FILE Evaluate a file. -m, --main=NAMESPACE Call the -main function for a namespace. --init-ns=NAMESPACE Initialize REPL with the specified namespace. Defaults to "user". -C, --color=auto When to use colors. Possible values: always, auto, none. Defaults to auto. --version Show application version. Args: [<args>] Arguments to pass to -main. These will be ignored unless -m is specified.
Connecting to a server
One way to connect to a running server using Trenchman is to specify the server URL with the
--server) option. For example, the following command lets you connect to an nREPL server listening on
$ trench -s nrepl://localhost:12345
In addition to nREPL, Trenchman supports the prepl protocol as well. To connect to a server via prepl, use the
prepl:// scheme instead of
$ trench -s prepl://localhost:5555
Also, the connecting port and protocol can be specified with dedicated options:
If you omit the protocol or server host, Trenchman assumes that the following default values are specified:
- server host:
So, in order to connect to
nrepl://127.0.0.1:12345, you only have to do:
$ trench -p 12345
trench -s nrepl://127.0.0.1:12345.
If you omit the port number, Trenchman will read it from a port file, as described in the next section.
A port file is a file that only contains the port number that the server is listening on. Typical nREPL servers generate a port file named
.nrepl-port at startup.
Trenchman tries to read the port number from a port file if the connecting port is not specified explicitly. By default, Trenchman will read
.nrepl-port for nREPL connection and
.prepl-port for prepl connection.
So, the following example connects to
$ cat .nrepl-port 12345 $ trench
If you'd rather use another file as a port file, specify it with the
$ cat my-port-file 3000 $ trench --port-file my-port-file
Retry on connection
When connecting to a server that is starting up, it's useful to be able to automatically retry the connection if it fails.
--retry-interval options control connection retries.
--retry-timeout DURATION specifies the amount of time before connection retries are aborted and
--retry-interval DURATION specifies the time interval between each retry (
DURATION can be specified in the format accepted by Go's duration parser, like
For example, the following command will retry the connection every 5 seconds for up to 30 seconds:
$ trench --retry-timeout 30s --retry-interval 5s
If the connection fails after retrying the connection until the timeout, Trenchman will print the error and exit.
--retry-timeout is not specified, Trenchman will not retry the connection.
By default, Trenchman starts a new REPL session after the connection is established:
$ trench user=> (println "Hello, World!") Hello, World! nil user=>
To exit the REPL session, type
In addition to starting a REPL session, Trenchman provides three more evaluation modes (
Evaluating an expression (
-e option is specified with an expression, Trenchman evaluates that expression:
$ trench -e '(println "Hello, World!")' Hello, World! $
Trenchman will print the evaluation result if the given expression evaluates to a non-
$ trench -e '(map inc [1 2 3])' (2 3 4) $
Evaluating a file (
-f option, you can load (evaluate) the specified file:
$ cat hello.clj (println "Hello, World!") $ trench -f hello.clj Hello, World! $
Note that the specified file path is interpreted as one from the client's working directory. The client will send the entire content of the file to the server once the connection is established.
- is specified as the input file, the input code will be read from stdin:
$ echo '(println "Hello, World!")' | trench -f - Hello, World! $
-main for a namespace (
-m option, you can call the
-main function for the specified namespace:
$ cat src/hello/core.clj (ns hello.core) (defn -main  (println "Hello, World!")) $ trench -m hello.core Hello, World!
Note that the file for the specified namespace must be on the server-side classpath.
Copyright (c) 2021 Shogo Ohta
Distributed under the MIT License. See LICENSE for details.