Minercon

A full-featured RCON client for Minecraft servers — available both as a VS Code extension (integrated terminal panel) and as a standalone CLI tool (minercon) that runs in any terminal.

A heavy fork of "Minecraft RCON Terminal"

Features

Command completion

• Real-time suggestions as you type, cycling with Tab / Shift+Tab
• Argument hints showing the full usage signature of the current command
• Works with vanilla, Bukkit/Spigot/Paper, and plugin-extended servers
• When the Paper TabComplete or Spigot TabComplete plugins or the Fabric TabComplete mod is installed on your server, completions come directly from the server (fastest, most accurate). Without it, the extension builds a local command tree by crawling /help output once per server and caching it.

Emacs-style line editing

• Full cursor movement, word-jump, selection, and kill/yank (session-local kill ring)
• Scrollable command history, persistent across reconnects

Ctrl-r command history search -- with a filtered suggestion list

Minecraft color codes — server responses render with full § color support

Robust connection handling — exponential-backoff auto-reconnect on drop; TCP keepalive to detect silent disconnects

No response truncation — custom RCON protocol implementation handles fragmented multi-packet responses correctly (vanilla server /help returns 300+ commands in full)

Server setup

Add these lines to server.properties and restart:

enable-rcon=true
rcon.port=25575
rcon.password=your-secure-password

The password is only needed at connect time and is never written to disk by this tool.

VS Code extension

Installation

Search "Minercon" in the VS Code Extensions panel, or install from a .vsix file:

Ctrl+Shift+P → Extensions: Install from VSIX...

Connecting

| Command (Ctrl+Shift+P) | Description | |---|---| | Minercon: Connect to Server | Connect using saved defaults, or prompt if none saved | | Minercon: Connect with New Credentials | Always prompt for host, port, and password | | Minercon: Save Current Connection as Default | Save the current connection's host and port; password goes to VS Code's secure secret storage |

You can also open a terminal via the Terminal menu → New Terminal → select Minecraft Server from the terminal profile picker.

Multiple RCON terminals can be open simultaneously, each to a different server.

VS Code settings

{
  "minercon.defaultHost": "localhost",
  "minercon.defaultPort": 25575
}

The password is not stored in settings — it lives in VS Code's encrypted secret storage.

CLI tool

Installation

npm install -g minercon

Or, after cloning and building locally:

npm run compile
node out/minercon --help

Usage

minercon [host] [port] [options]

Options:
  -p, --password <pw>   RCON password
  --save                Save host/port/history-size to ~/.config/minercon/config.json
  --log-file <path>     Write log output to a file instead of the console
  --log-level <level>   consola log level, e.g. debug, info, warn, error (default: info)
  --history-size <n>    Number of commands to remember in history (default: 100)
  --no-plugin           Skip the server-side tab-complete plugin probe (manual
                         testing only; not persisted to config)
  --no-unpaginate       Do not request unpaginated output via the plugin
                         (keep the server's small pages)
  --no-pager            Do not page tall output; print it all at once
  -h, --help            Show help

Environment variables:
  MCRCON_PASSWORD       RCON password (used when --password is not given)
  MCRCON_LOG_FILE       Log file path (used when --log-file is not given)
  MCRCON_LOG_LEVEL      Log level (used when --log-level is not given)
  MCRCON_HISTORY_SIZE   History size (used when --history-size is not given)
  MCRCON_UNPAGINATE     Set to 0 to disable unpaginated output (default on)
  MCRCON_PAGER          Set to 0 to disable the output pager (default on)

Password handling: the CLI never writes the password to disk. Supply it with --password, the MCRCON_PASSWORD environment variable, or leave both unset and you will be prompted with masked input.

Saved host/port: --save writes host and port (never the password) to ~/.config/minercon/config.json. On subsequent invocations, those values are used as defaults so you can just run minercon with no arguments.

Kill/yank: the CLI uses an in-process kill ring (Ctrl+K stashes text; Ctrl+Y yanks it back). The kill ring is not connected to the system clipboard. Ctrl+X / Ctrl+C-with-selection do the same within the session.

Log output: diagnostic messages are printed via consola, colored and leveled by default. Use --log-file to redirect that output to a file instead (useful when console output would interfere with piped output or the interactive session). Use --log-level debug for verbose per-command RCON send/receive logging.

History size: --history-size controls how many commands are remembered for Up/Ctrl+P/Ctrl+R recall and the .history command, and (with --save) persists to the saved config.

--no-plugin: forces local mode (crawling /help for tab completion) even if the server-side TabComplete plugin/mod is installed. Intended for testing the local-mode crawl — see docs/ARCHITECTURE.md for what "local mode" vs. "plugin mode" means.

Unpaginated output & pager: on Paper/Spigot, the TabComplete plugin exposes an rcat command that re-runs a command as the console so Bukkit's tiny RCON pagination (e.g. the /help "Help: Index (1/N)" pages) is bypassed — the terminal requests this automatically in plugin mode. Output taller than the window is then shown through a built-in pager (Space: more, G: all, q: quit) that keeps the content in your terminal scrollback. Disable either with --no-unpaginate / --no-pager, the MCRCON_UNPAGINATE / MCRCON_PAGER environment variables, or the minercon.unpaginateOutput / minercon.terminalPager VS Code settings. See docs/UNPAGINATED_OUTPUT.md.

Quick examples

# One-off connection (prompts for password)
minercon localhost 25575

# Password from environment
MCRCON_PASSWORD=secret minercon mc.example.com

# Save host/port for future sessions
minercon mc.example.com 25575 --password secret --save

# Next time, no arguments needed
minercon

Keyboard shortcuts

Navigation and completion

| Key | Action | |---|---| | Tab | Fetch / cycle to next suggestion | | Shift+Tab | Cycle to previous suggestion | | Up / Ctrl+P | Previous command in history (or move up in suggestion list) | | Down / Ctrl+N | Next command in history (or move down in suggestion list) | | Ctrl+R | Reverse search command history; press again to cycle to the next-older match | | Page Up / Page Down | Page through suggestion list | | Esc | Close suggestion list; if already closed, clear the line | | Enter | Submit the current command |

Cursor movement

| Key | Action | |---|---| | Left / Ctrl+B | Move left one character | | Right / Ctrl+F | Move right one character | | Ctrl+Left / Alt+B | Move left one word | | Ctrl+Right / Alt+F | Move right one word | | Home / Ctrl+A | Move to start of line | | End / Ctrl+E | Move to end of line |

Selection

| Key | Action | |---|---| | Shift+Left | Extend selection left | | Shift+Right | Extend selection right | | Ctrl+Shift+Left | Extend selection left by word | | Ctrl+Shift+Right | Extend selection right by word | | Shift+Home | Select to start of line | | Shift+End | Select to end of line |

Editing

| Key | Action | |---|---| | Backspace | Delete character before cursor | | Delete | Delete character after cursor | | Ctrl+T | Transpose characters around cursor | | Ctrl+K | Kill (cut) from cursor to end of line → kill ring | | Ctrl+U | Kill from cursor to start of line → kill ring | | Ctrl+W / Alt+Backspace | Kill word before cursor → kill ring | | Alt+D | Kill word after cursor → kill ring | | Ctrl+Y | Yank (paste) from kill ring | | Ctrl+X | Cut selection → kill ring | | Ctrl+C | Copy selection → kill ring (if text selected); otherwise echo ^C and clear line | | Ctrl+V | Paste from kill ring |

The kill ring is session-local in both the CLI and VS Code extension.

Terminal control

| Key | Action | |---|---| | Ctrl+L | Clear screen and redraw | | Ctrl+D | On a non-empty line: delete character under cursor (forward delete). On an empty line: disconnect and exit |

Built-in commands

These are handled by the terminal itself and never sent to the server. They use a . prefix so there is no conflict with server commands (which use /).

| Command | Description | |---|---| | .help | Show this list of built-in commands and keyboard shortcuts | | .clear | Clear the terminal screen | | .history | Show command history | | .reconnect | Manually reconnect to the server | | .disconnect | Disconnect (stays open; use Ctrl+D to also exit) | | .reload-commands | Force a fresh crawl of the server's command tree (local mode only) | | .clear-cache | Delete the cached command tree for this server (local mode only) | | .cache-info | Show the age and location of the cached command tree |

Everything else — including any /command — is sent directly to the server as an RCON command.

Tab completion modes

The terminal detects which mode to use automatically when it first connects.

Plugin mode (preferred) — requires the Paper TabComplete or Spigot TabComplete plugin (or the Fabric TabComplete mod) installed on your server. Completions are fetched live from the server as you type, identical to in-game tab completion.

Local mode (fallback) — the terminal fetches and parses your server's /help output once, builds a command tree, and caches it to disk. Subsequent connections load from cache (nearly instant). Use .reload-commands to refresh after a server update.

Cache location:

• VS Code: <extension global storage>/command-cache/<host>_<port>.json
• CLI: ~/.config/minercon/command-cache/<host>_<port>.json

Building and installing the TabComplete plugins

Paper

The Paper plugin lives in paper-plugin/. It requires Java 21 and a Paper 1.21+ server, and uses paperweight-userdev for direct typed access to Paper's Brigadier command dispatcher (no reflection).

Build:

cd paper-plugin
./gradlew build

The built jar ends up at paper-plugin/build/libs/paper-tabcomplete-1.0.0.jar.

Spigot

The Spigot plugin lives in spigot-plugin/. It requires Java 21 and a Spigot 1.21+ server.

Build:

cd spigot-plugin
./gradlew build

The built jar ends up at spigot-plugin/build/libs/spigot-tabcomplete-1.0.0.jar.

Install (both)

Drop the jar into your server's plugins/ directory and restart. No configuration is needed — the plugin activates automatically and exposes the /tabcomplete and /cmdusage RCON commands that this client uses.

Troubleshooting

"Connection refused" — verify enable-rcon=true in server.properties and that the RCON port is not blocked by a firewall.

"Authentication failed" — double-check rcon.password in server.properties. Passwords are case-sensitive.

Autocomplete not working in local mode

1. .clear-cache to discard the old tree
2. .reload-commands to re-crawl
3. Check that your account has permission to run /help on the server
4. In VS Code, check View → Output → Minercon for crawl diagnostics

Truncated responses — this was a bug in versions before v2.0, which used an external library with a 4096-byte limit. The current implementation has no such limit.

Suggestion display looks wrong — try .clear to redraw the screen. If the issue persists in the CLI, ensure your terminal reports correct dimensions (echo $COLUMNS $LINES).

Contributing

git clone https://github.com/xton/minercon.git
cd minercon
npm install
npm run compile
npm test

The test suite runs inside VS Code's extension host. Run it with npm test; no live server is required — the RCON layer has a record/replay fixture harness.

See CHANGELOG.md for version history and CONTRIBUTING.md for development guidelines.

Acknowledgements

Minercon (formerly "Minecraft RCON Terminal") began as a fork of jaketcooper/Minecraft-rcon, which provided the initial RCON protocol implementation and VS Code extension scaffold, help-based tab completion, interactive terminal experience, line editing. Plugin-mode tab-completion, standalone CLI, history search, lots of testing, loads of polish, countless fixes, and the new name were developed from there with significant help from Claude.

License

MIT — see LICENSE.