{"id":19917199,"url":"https://github.com/athos/trenchman","last_synced_at":"2025-05-03T06:30:45.430Z","repository":{"id":38679891,"uuid":"368884280","full_name":"athos/trenchman","owner":"athos","description":"A standalone nREPL/prepl client written in Go and heavily inspired by Grenchman","archived":false,"fork":false,"pushed_at":"2023-01-29T15:08:49.000Z","size":167,"stargazers_count":64,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T11:51:29.048Z","etag":null,"topics":["clojure","golang","nrepl","prepl","repl"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/athos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-19T13:45:47.000Z","updated_at":"2025-04-02T17:46:59.000Z","dependencies_parsed_at":"2023-02-15T23:30:54.742Z","dependency_job_id":null,"html_url":"https://github.com/athos/trenchman","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Ftrenchman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Ftrenchman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Ftrenchman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athos%2Ftrenchman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/athos","download_url":"https://codeload.github.com/athos/trenchman/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252154732,"owners_count":21702982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","golang","nrepl","prepl","repl"],"created_at":"2024-11-12T21:49:08.017Z","updated_at":"2025-05-03T06:30:45.171Z","avatar_url":"https://github.com/athos.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trenchman\n[![release](https://github.com/athos/trenchman/actions/workflows/release.yaml/badge.svg)](https://github.com/athos/trenchman/actions/workflows/release.yaml)\n[![test](https://github.com/athos/trenchman/actions/workflows/test.yaml/badge.svg)](https://github.com/athos/trenchman/actions/workflows/test.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/athos/trenchman)](https://goreportcard.com/report/github.com/athos/trenchman)\n\nA standalone nREPL/prepl client written in Go and heavily inspired by [Grenchman](https://github.com/technomancy/grenchman)\n\nTrenchman 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.\nUnlike 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.\n\n## Features\n\n- Fast startup\n- Written in Go and runs on various platforms\n- Support for nREPL and prepl\n- Works as a language-agnostic nREPL client\n\n## Table of Contents\n\n- [Trenchman](#trenchman)\n  - [Features](#features)\n  - [Table of Contents](#table-of-contents)\n  - [Installation](#installation)\n    - [Homebrew (macOS and Linux)](#homebrew-macos-and-linux)\n    - [Scoop installer (Windows, Intel and AMD)](#scoop-installer-windows-intel-and-amd)\n    - [Manual Install](#manual-install)\n  - [Usage](#usage)\n    - [Connecting to a server](#connecting-to-a-server)\n      - [Port file](#port-file)\n      - [Retry on connection](#retry-on-connection)\n    - [Evaluation](#evaluation)\n      - [Evaluating an expression (`-e`)](#evaluating-an-expression--e)\n      - [Evaluating a file (`-f`)](#evaluating-a-file--f)\n      - [Calling `-main` for a namespace (`-m`)](#calling--main-for-a-namespace--m)\n  - [License](#license)\n\n## Installation\n\n### Homebrew (macOS and Linux)\n\nTo install Trenchman via [Homebrew](https://brew.sh/), run the following command:\n\n```console\nbrew install athos/tap/trenchman\n```\n\nTo upgrade:\n\n```console\nbrew upgrade trenchman\n```\n\n### Scoop installer (Windows, Intel and AMD)\n\nTo install Trenchman via [Scoop](https://scoop.sh), run following commands:\n\n```console\nscoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure\nscoop install trenchman\n```\n\nTo upgrade use:\n\n```console\nscoop update trenchman\n```\n\nNote: To install on ARM architecture you have to use manual install.\n\n### Manual Install\n\nPre-built binaries are available for linux, macOS and Windows on the [releases](https://github.com/athos/trenchman/releases) page.\n\nIf you have the Go tool chain installed, you can build and install Trenchman by the following command:\n\n```console\ngo install github.com/athos/trenchman/cmd/trench@latest\n```\n\nTrenchman does not have `readline` support at this time. If you want to use features like line editing or command history, we recommend using [`rlwrap`](https://github.com/hanslub42/rlwrap) together with Trenchman.\n\n## Usage\n\n```\nusage: trench [\u003cflags\u003e] [\u003cargs\u003e...]\n\nFlags:\n      --help                    Show context-sensitive help (also try --help-long and --help-man).\n  -p, --port=PORT               Connect to the specified port.\n      --port-file=FILE          Specify port file that specifies port to connect to. Defaults to .nrepl-port.\n  -P, --protocol=nrepl          Use the specified protocol. Possible values: n[repl], p[repl]. Defaults to nrepl.\n  -s, --server=[(nrepl|prepl)://]host[:port]|nrepl+unix:path\n                                Connect to the specified URL (e.g. prepl://127.0.0.1:5555, nrepl+unix:/foo/bar.socket).\n      --retry-timeout=DURATION  Timeout after which retries are aborted. By default, Trenchman never retries connection.\n      --retry-interval=1s       Interval between retries when connecting to the server.\n  -i, --init=FILE               Load a file before execution.\n  -e, --eval=EXPR               Evaluate an expression.\n  -f, --file=FILE               Evaluate a file.\n  -m, --main=NAMESPACE          Call the -main function for a namespace.\n      --init-ns=NAMESPACE       Initialize REPL with the specified namespace. Defaults to \"user\".\n  -C, --color=auto              When to use colors. Possible values: always, auto, none. Defaults to auto.\n      --debug                   Print debug information\n      --version                 Show application version.\n\nArgs:\n  [\u003cargs\u003e]  Arguments to pass to -main. These will be ignored unless -m is specified.\n```\n\n### Connecting to a server\n\nOne way to connect to a running server using Trenchman is to specify the server URL with the `-s` (`--server`) option. For example, the following command lets you connect to an nREPL server listening on `localhost:12345`:\n\n```console\ntrench -s nrepl://localhost:12345\n```\n\nTrenchman 0.4.0+ can also establish an nREPL connection via UNIX domain socket.\nTo do so, specify the `--server` option with the `nrepl+unix:` scheme\nfollowed by the address path of the socket:\n\n```console\ntrench -s nrepl+unix:/foo/bar.socket\n```\n\nIn addition to nREPL, Trenchman supports the prepl protocol as well.\nTo connect to a server via prepl, use the `prepl://` scheme instead of `nrepl://`:\n\n```console\ntrench -s prepl://localhost:5555\n```\n\nAlso, the connecting port and protocol can be specified with dedicated options:\n\n- port: `-p`, `--port=PORT`\n- protocol: `-P`, `--protocol=(nrepl|prepl)`\n\nIf you omit the protocol or server host, Trenchman assumes that the following default values are specified:\n\n- protocol: `nrepl`\n- server host: `127.0.0.1`\n\nSo, in order to connect to `nrepl://127.0.0.1:12345`, you only have to do:\n\n```console\ntrench -p 12345\n```\n\nrather than `trench -s nrepl://127.0.0.1:12345`.\n\nIf you omit the port number, Trenchman will read it from a port file, as described in the next section.\n\n#### Port file\n\nA *port file* is a file that only contains the port number that the server is listening on.\nTypical nREPL servers generate a port file named `.nrepl-port` at startup.\n\nTrenchman 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.\n\nSo, the following example connects to `nrepl://127.0.0.1:12345`:\n\n```console\n$ cat .nrepl-port\n12345\n$ trench\n```\n\nIf you'd rather use another file as a port file, specify it with the `--port-file` option:\n\n```console\n$ cat my-port-file\n3000\n$ trench --port-file my-port-file\n```\n\n#### Retry on connection\n\nWhen connecting to a server that is starting up, it's useful to be able to automatically retry the connection if it fails.\n\nThe `--retry-timeout` and `--retry-interval` options control connection retries.\n`--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](https://pkg.go.dev/time#ParseDuration), like `500ms`, `10s` or `1m`).\n\nFor example, the following command will retry the connection every 5 seconds for up to 30 seconds:\n\n```console\ntrench --retry-timeout 30s --retry-interval 5s\n```\n\nIf the connection fails after retrying the connection until the timeout, Trenchman will print the error and exit.\n\nIf `--retry-timeout` is not specified, Trenchman will not retry the connection.\n\n### Evaluation\n\nBy default, Trenchman starts a new REPL session after the connection is established:\n\n```console\n$ trench\nuser=\u003e (println \"Hello, World!\")\nHello, World!\nnil\nuser=\u003e\n```\n\nTo exit the REPL session, type `Ctrl-D` or `:repl/quit`.\n\nIn addition to starting a REPL session, Trenchman provides three more\nevaluation modes (`-e`/`-f`/`-m`).\n\n#### Evaluating an expression (`-e`)\n\nIf the `-e` option is specified with an expression, Trenchman evaluates that expression:\n\n```console\n$ trench -e '(println \"Hello, World!\")'\nHello, World!\n$\n```\n\nTrenchman will print the evaluation result if the given expression evaluates to a non-`nil` value:\n\n```console\n$ trench -e '(map inc [1 2 3])'\n(2 3 4)\n$\n```\n\n#### Evaluating a file (`-f`)\n\nWith the `-f` option, you can load (evaluate) the specified file:\n\n```console\n$ cat hello.clj\n(println \"Hello, World!\")\n$ trench -f hello.clj\nHello, World!\n$\n```\n\nNote that the specified file path is interpreted as one from the client's working directory.\nThe client will send the entire content of the file to the server once the connection is established.\n\nIf `-` is specified as the input file, the input code will be read from stdin:\n\n```console\n$ echo '(println \"Hello, World!\")' | trench -f -\nHello, World!\n$\n```\n\n#### Calling `-main` for a namespace (`-m`)\n\nWith the `-m` option, you can call the `-main` function for the specified namespace:\n\n```console\n$ cat src/hello/core.clj\n(ns hello.core)\n\n(defn -main []\n  (println \"Hello, World!\"))\n$ trench -m hello.core\nHello, World!\n```\n\nNote that the file for the specified namespace must be on the server-side classpath.\n\n## License\n\nCopyright (c) 2021 Shogo Ohta\n\nDistributed under the MIT License. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathos%2Ftrenchman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fathos%2Ftrenchman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathos%2Ftrenchman/lists"}