tcprcon-cli

• tcprcon-cli
  • Local Development
  • Features
  • Installation
    • Binary
    • Docker
    • Go
    • Windows
  • Usage
    • Interactive Mode
    • Single Command Mode
    • Keepalive (Pulse)
    • Using Environment Variable for Password
  • Configuration Profiles
  • CLI Flags
  • Interactive UX
  • Protocol Compliance
  • Using as a Library
    • Streaming Responses
  • License

A fully native RCON client implementation, zero third parties*

_{*except for other golang maintained packages about terminal emulators, until i fully master tty :(}

Local Development

You can use the provided Makefile and compose.yaml to spin up a local development environment. This will start a Mordhau game server in a container.

Prerequisites

• Docker and Docker Compose
• Go 1.22+
• Make (optional, but recommended)

Getting Started

1. Start a Game Server:

Beware that the first time you build and run the server it might take a while for its RCON port to be usable, not sure why, but Rust one for example took a few minutes before it was responding, idk.

make lift-mh-server 

or

make lift-rust-server

Note: The server uses network_mode: host and may take a few minutes to fully initialize, make sure network_mode is supported by your docker engine

2. Build and Run the Client:

   make run

   This will build the tcprcon-cli binary into .out/ and execute it against the local server (see step 1) using the default development credentials.

3. Run Tests:

   make test

4. Dockerized Client: If you prefer to run the client itself inside a container:

   make run-docker

Features

• Interactive Terminal UI: full-screen exclusive TUI (like vim or nano) with command history and scrollable output
• Single Command Mode: execute a single RCON command and exit
• Multiple Authentication Methods: supports password via CLI flag, environment variable (rcon_password), or secure prompt
• Keepalive (Pulse): configurable periodic command to keep the connection alive on idle servers
• Configurable Logging: syslog-style severity levels for debugging
• Installable as library: use the RCON client in your own Go projects, (see examples)

Installation

Binary

Linux binaries are available on the releases page.

Docker

docker run -it ghcr.io/ultimateform/tcprcon-cli:latest --address=192.168.1.100 --port=7778

Go

go install github.com/UltimateForm/tcprcon-cli@latest

Or build from source:

_{note: requires golang 1.22+}

git clone https://github.com/UltimateForm/tcprcon-cli.git
cd tcprcon-cli
go build -o tcprcon-cli .

Windows

Windows is not natively supported due to Unix-specific terminal dependencies. Use WSL2 or the Docker image above.

Might change my mind about supporting windows in the future but given that this is essentially a CLI app windows is kind of an after thought for me... and there's likely a better UI app for windows out there.

Usage

Interactive Mode

tcprcon-cli --address=192.168.1.100 --port=7778

Single Command Mode

tcprcon-cli --address=192.168.1.100 --cmd="playerlist"

Keepalive (Pulse)

To keep the connection alive on idle servers, use -pulse with a command your server accepts as a no-op:

tcprcon-cli --address=192.168.1.100 --pulse="alive"

The default interval is 60 seconds. Override it with -pulse-interval:

tcprcon-cli --address=192.168.1.100 --pulse="alive" --pulse-interval=30s

Pulse settings can also be saved to a profile:

tcprcon-cli --address=192.168.1.100 --pulse="alive" --pulse-interval=30s --save="my_server"

Using Environment Variable for Password

export rcon_password="your_password"
tcprcon-cli --address=192.168.1.100

Configuration Profiles

tcprcon-cli supports saving and loading connection profiles to a local configuration file, located at ~/.config/tcprcon/config.json on Linux/macOS or %AppData%\tcprcon\config.json on Windows.

Saving a Profile

You can save your current connection parameters (address, port, and optionally password) to a named profile using the --save flag.

# Connect to a server and save its details as "my_server"
tcprcon-cli --address=192.168.1.100 --port=7778 --pw="mysecret" --save="my_server"

When saving, you will be prompted if you wish to store the password. If you choose 'y', the password will be saved in plaintext within the config.json file with restricted 0600 file permissions (read/write only by owner). If you choose 'n' or omit the password, you will be prompted for it when loading the profile.

Loading a Profile

To load a previously saved profile, use the --profile flag.

# Load the "my_server" profile
tcprcon-cli --profile="my_server"

Explicit CLI flags will always override values from a loaded profile. For example:

# Load "my_server" but connect to a different port
tcprcon-cli --profile="my_server" --port=27015

CLI Flags

  -address string
    	RCON address, excluding port (default "localhost")
  -cmd string
    	command to execute, if provided will not enter into interactive mode
  -log uint
    	sets log level (syslog severity tiers) for execution (default 4)
  -port uint
    	RCON port (default 7778)
  -profile string
    	loads a saved profile by name, overriding default flags but overridden by explicit flags.
  -pulse string
    	keepalive method: a command sent on a schedule to keep the connection alive
  -pulse-interval duration
    	keepalive interval, use Go duration format e.g. 30s, 2m (default 1m0s)
  -pw string
    	RCON password, if not provided will attempt to load from env variables, if unavailable will prompt
  -save string
    	saves current connection parameters as a profile. Value is the profile name.

Interactive UX

The interactive terminal UI supports the following keyboard controls:

Key	Action
Enter	Submit command
Backspace	Delete last character
↑ / ↓	Navigate command history
Page Up	Scroll output up one page
Page Down	Scroll output down one page

When scrolled up, a [↑ N] indicator is shown in the prompt line, where N is the number of lines scrolled above the bottom. Submitting a command snaps the view back to the bottom.

Protocol Compliance

While tcprcon-cli follows the standard Source RCON Protocol, some game servers (like Rust) have non-standard implementations that might introduce unexpected behaviors, such as duplicated responses or incorrect packet IDs, the cli should still work, you might just have to deal with an overly chatty server.

For a detailed breakdown of known server quirks and how they are handled, see the Caveats section in the core library documentation.

Using as a Library

See https://github.com/UltimateForm/tcprcon

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.