minecraft-ping

minecraft-ping measures Minecraft server latency with ping-style ergonomics while staying honest about the underlying protocols.

• Java Edition is the default.
• Bedrock Edition is available with --bedrock or --edition bedrock.
• Text mode behaves like a ping session and runs continuously by default.
• JSON mode is a single probe intended for scripts and automation.

Installation

Install the public module:

go install github.com/omkhar/minecraft-ping/v2@latest

Install from a checkout:

go install .

If you want a local binary in the repository root instead:

go build -o minecraft-ping .

Signed release archives and Linux packages are published from tagged releases on GitHub Releases. Linux packages install the minecraft-ping(1) man page, and release archives ship the same source at man/minecraft-ping.1.

Quick Start

minecraft-ping [options] destination

At a glance:

• --bedrock or --edition bedrock: switch from Java to Bedrock
• -c count: stop after a fixed number of probes
• -j: emit one JSON probe for scripts
• -4 or -6: force one address family
• --allow-private: permit local or private IP targets

Common examples:

To keep the snippets reproducible, the sample stdout blocks below were captured against the repository's local staging backend. That means the samples show localhost-style targets even when the command example uses a public hostname. On a real server, the host label, resolved address, port selection, and latency will differ.

# Java, default port 25565, continuous until Ctrl-C
minecraft-ping mc.example.com
#
# Sample stdout:
# PING 127.0.0.1 port 25565 [java]:
# pong from 127.0.0.1:25565: seq=1 time=1.000 ms
# pong from 127.0.0.1:25565: seq=2 time=1.000 ms
# ...

# Java, 3 probes
minecraft-ping -c 3 mc.example.com
#
# Sample stdout:
# PING 127.0.0.1 port 25565 [java]:
# pong from 127.0.0.1:25565: seq=1 time=1.000 ms
# pong from 127.0.0.1:25565: seq=2 time=1.000 ms
# pong from 127.0.0.1:25565: seq=3 time=1.000 ms
#
# --- 127.0.0.1 ping statistics ---
# 3 probes transmitted, 3 received, 0% packet loss, time 2003ms
# rtt min/avg/max/mdev = 1.000/1.000/1.000/0.000 ms

# Bedrock, default port selected from the resolved address family
minecraft-ping --bedrock play.example.com
#
# Sample stdout:
# PING 127.0.0.1 port 19132 [bedrock]:
# pong from 127.0.0.1:19132: seq=1 time=0.151 ms
# pong from 127.0.0.1:19132: seq=2 time=0.242 ms
# ...

# Bedrock, default IPv6 port 19133
minecraft-ping --bedrock -6 2001:db8::20
#
# Sample stdout:
# PING ::1 port 19133 [bedrock]:
# pong from [::1]:19133: seq=1 time=0.080 ms
# pong from [::1]:19133: seq=2 time=0.273 ms
# ...

# Explicit port
minecraft-ping --bedrock play.example.com:19132
#
# Sample stdout:
# PING 127.0.0.1 port 19132 [bedrock]:
# pong from 127.0.0.1:19132: seq=1 time=0.220 ms
#
# --- 127.0.0.1 ping statistics ---
# 1 probes transmitted, 1 received, 0% packet loss, time 0ms
# rtt min/avg/max/mdev = 0.220/0.220/0.220/0.000 ms

# Local or private target
minecraft-ping --allow-private 127.0.0.1:25565
#
# Sample stdout:
# PING 127.0.0.1 port 25565 [java]:
# pong from 127.0.0.1:25565: seq=1 time=1.000 ms
#
# --- 127.0.0.1 ping statistics ---
# 1 probes transmitted, 1 received, 0% packet loss, time 0ms
# rtt min/avg/max/mdev = 1.000/1.000/1.000/0.000 ms

# Single JSON probe
minecraft-ping -j mc.example.com
#
# Sample stdout:
# {"server":"127.0.0.1","latency_ms":1}

Key Behavior

• Java and Bedrock stay explicit. The CLI does not auto-detect editions.
• By default, the CLI rejects loopback, RFC1918, ULA, link-local, and documentation-only IP addresses. Pass --allow-private only when you intentionally want to probe a local or private host.
• Java probing uses the Minecraft status and ping/pong handshake over TCP and only performs SRV lookup when the target is a hostname with no explicit port.
• Bedrock probing uses RakNet unconnected ping/pong over UDP.
• The CLI intentionally does not fake ICMP-only fields such as ttl, byte counts, or icmp_seq.

For the full flag reference, destination rules, exit status contract, and protocol notes, see CLI Reference.

Supported Release Targets

Release artifacts are built for:

• macOS arm64
• Linux amd64 and arm64
• Windows amd64 and arm64

Intel macOS (amd64) archives are no longer part of the release matrix. The final Intel macOS archive shipped in v2.0.6 as a Darwin_amd64 archive.

Release Artifacts

Releases are built from GitHub Actions on GitHub-verified signed, annotated tags at the current main head.

• Signed release artifacts are published for macOS arm64, Linux, and Windows.
• Release archives and packages are built with deterministic paths and commit-based mtimes so the artifact bytes can be reproduced from the same source tree and toolchain.
• The release workflow publishes signed SPDX SBOM assets for each release.
• GitHub artifact attestations and downloadable provenance bundles are published with public releases.

For quick consumer verification instructions, see Release Verification.

Support

• Usage questions, operational questions, and maintainer contact: minecraft-ping@omkhar.net
• Bug reports: open a bug report
• Feature requests: open a feature request
• Security reports: open a private security advisory or follow SECURITY.md

Project Documentation

Users:

• CLI Reference
• Release Verification
• Support
• Man Page Source

Contributors:

• Contributing
• Development
• Architecture

Maintainer And Policy:

• Releasing
• Security
• Governance
• Code of Conduct
• Changelog

Automation:

• Agent Instructions

License

This project is licensed under the Apache License, Version 2.0. See LICENSE.