# pouriyajamshidi/tcping: TCP port latency and availability checks > pouriyajamshidi/tcping is a cross-platform Go command-line utility for probing TCP ports instead of sending ICMP echo requests. It supports terminal output, JSON, CSV, SQLite, IPv4 and IPv6 selection, DNS retry behavior, and long-running connection monitoring. **pouriyajamshidi/tcping** — Ping TCP ports using tcping. Inspired by Linux's ping utility. Written in Go - Repository: https://github.com/pouriyajamshidi/tcping - Stars: 1,359 · Forks: 128 - Language: Go - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/pouriyajamshidi-tcping ## Why TCPING targets ports rather than ICMP pouriyajamshidi/tcping addresses a practical gap left by conventional `ping`. An ICMP test can show that a host or network path responds to echo requests, but it does not establish whether the particular TCP service a client needs is accepting connections. This utility applies the familiar ping workflow to a destination port, making it relevant when diagnosing a web server, database endpoint, SSH listener, or another TCP-only service. The README positions the tool as an alternative to `ping` in environments where ICMP is blocked. That makes it useful across restrictive office networks, cloud networks, containers, and peer networks where administrators allow TCP traffic but suppress ICMP. It is aimed at people who need a repeatable signal about port reachability and connection latency. The repository description clearly limits its scope: it probes TCP ports rather than validating the application protocol carried inside those connections. A successful connection answers one specific question: was the destination's TCP port reachable during that probe? It does not prove that an HTTP response is healthy, that credentials are valid, or that application logic is functioning. A closed or filtered port can result from the service process, host firewall, network policy, or an intermediate device. This distinction matters when adopting it as a monitoring tool. It gives direct evidence about TCP connectivity, not a complete service-health verdict. The package also supports repeated observation over time. According to the README, operators can set a timeout, choose an interval between probes, select a source interface, and enforce either IPv4 or IPv6. These controls make the command more suitable for deliberate diagnostics than for unrestricted scanning. ## How TCPING probes and classifies connection attempts Based on the repository description and README, the core operation is a TCP connection attempt against a host and port. Each probe produces a reachability result and timing information that the program accumulates as latency, packet loss, uptime, and downtime observations. The README does not describe a background daemon or separate configuration server. The repository layout instead presents a conventional Go CLI with files such as `tcping.go`, `statsprinter.go`, `csv.go`, and `db.go`, plus output-related tests. The README says successful and unsuccessful probes use different TCP sequence numbering so operators can infer successful and failed totals at a glance. It also reports the longest downtime and uptime encountered, including their durations and times. Pressing `Enter` prints accumulated connection statistics without terminating the running process. That behavior is useful during an incident or manual investigation because it avoids ending the current monitoring session. A less common feature is hostname-resolution retry through the `-r` flag. The README says tcping retries resolution after a configured number of failed probes. This is intended for DNS load balancing and Global Server Load Balancer (`GSLB`) scenarios where temporary resolution failure or changing returned addresses matter. It should not be confused with retrying the TCP connection itself. Source-interface selection can be significant on multihomed hosts. Operators can constrain probes to a chosen interface rather than relying entirely on normal route selection. IPv4 and IPv6 can also be required explicitly. These controls are useful when reproducing a specific service path, although the README excerpt does not document every option's exact spelling. ## Installing TCPING across supported platforms For Go developers, the README gives the shortest installation route and states that it requires at least Go version `1.24.10`. This is more specific than the `go 1.24.0` directive in `go.mod`, because the documented install requirement includes the patch release. The following command installs the latest v2 module into the Go environment: ```bash go install github.com/pouriyajamshidi/tcping/v2@latest ``` On macOS, Homebrew is the documented package-manager path: ```bash brew install pouriyajamshidi/tap/tcping ``` For Debian and derivatives, the README downloads a release package and installs it through `apt`. Choose the package matching the machine architecture: ```bash wget https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-amd64.deb -O /tmp/tcping.deb sudo apt install -y /tmp/tcping.deb ``` The README also publishes static and dynamic archives for Windows, macOS, Linux, and BSD on amd64 and arm64. It describes static binaries as containing the needed code in one file, while dynamic binaries load some code from shared operating-system libraries. Maintainers who want to build locally can run the documented Make target: ```bash make build ``` The Makefile sets `VERSION := 2.8.0` and defines build output locations. The README says compilation places executables in the `output` folder, while the Makefile also declares a `target` directory, so users should inspect the local build result instead of assuming one path applies to every release workflow. For containers, the README offers two registries: ```bash docker pull pouriyajamshidi/tcping:latest ``` The multi-stage `Dockerfile` builds with `make`, copies the resulting executable to `/usr/bin/`, and sets `tcping` as the container entry point. The final image uses `scratch`, which suits a single-purpose network utility but means users should check argument and network requirements before expecting a general-purpose Linux environment. ## A first TCP port probe and structured output The README gives `example.com 80` as a basic invocation, including its x-cmd form. The same hostname-and-port syntax provides a straightforward first use for checking whether TCP port 80 accepts connections: ```bash tcping example.com 80 ``` For interactive use, the default output supports colorized terminal presentation, while `--pretty` is documented for readable JSON output. The README also lists plain, CSV, and SQLite database formats. A colored terminal is convenient for a person watching a probe session, whereas JSON or CSV is more suitable for parsing and storage. The JSON example described by the README combines `-j` with `--pretty`: ```bash ``` The README does not reproduce the complete JSON schema, so consumers should check the exact fields emitted by the selected release before writing a parser. The repository contains `csv.go`, `db.go`, and tests for those components, confirming dedicated output implementations, but the README does not state the CSV column order or SQLite table design. The README also presents x-cmd as an installation-free option: ```bash x tcping example.com 80 ``` This executes through x-cmd rather than requiring the standalone executable to be placed on the system `PATH`. For a first probe, use a destination and port the operator is authorized to test. The expected observation is a stream of TCP connection results and timing statistics. It is not an HTTP body check or a DNS diagnosis unless the `-r` resolution behavior is specifically in use. ## Limits of TCP reachability as a health signal The largest limitation is the gap between a live TCP connection and a healthy application. Port 443 may accept TLS connections while returning certificates for the wrong name, slow responses, invalid application data, or authorization failures. TCPING's documented statistics do not replace protocol-specific checks. A team monitoring only this utility could receive a positive connection signal during a partial service failure. The reverse situation is also important. Repeated successful connections can fail if the service limits connection rates, uses a source allowlist, requires a particular source interface, or rejects the traffic shape generated by frequent probes. The README's configurable interval and timeout help operators shape those attempts, but it does not specify default values or a built-in rate-limit policy. Monitoring settings must be reviewed against the target service's tolerance. TCPING is not an ICMP path diagnostic. It cannot substitute for tracerouting, packet capture, routing inspection, or firewall logs. It is also not a UDP monitoring tool, despite `ping` being a common term for several kinds of probes. The repository description and README explicitly identify TCP as the protocol under test. There is also a Windows-specific packaging concern. The README warns that TCPING may be flagged by Windows Defender or other anti-malware software, attributing this to behavior common among Go programs. It links to the Go project's FAQ. The warning does not prove a false positive in any particular environment, but enterprise users may need to verify package provenance and internal allowlisting policy before distributing the executable. A real alternative is an HTTP client or HTTP monitoring tool when the service speaks HTTP. Those tools can request a URL, inspect status codes, and often evaluate response content or application latency. TCPING remains the better fit when the target may be any TCP service and the requirement is repeated connection reachability. ## Release history and upgrade considerations The repository is not archived, and its last push was on 2026-09-27. The project has recent repository activity, although that fact alone does not guarantee compatibility or operational stability. The release list names `v2.8.0` from 2026-05-11, following `v2.7.1` from 2025-01-26 and `v2.7.0` from 2025-01-18. The module is `github.com/pouriyajamshidi/tcping/v2`, which matters for both installation and downstream Go integrations. `go.mod` declares `go 1.24.0`. The README's `go install` instruction calls for at least Go version `1.24.10`, so operators should treat that stated patch-level requirement as the documented installation constraint. The dependency list includes `github.com/google/go-github/v45`, `github.com/gookit/color`, `github.com/stretchr/testify`, and `zombiezen.com/go/sqlite`, with several indirect dependencies. The repository contains Go tests and GitHub workflow references for code analysis and container publishing, but the README does not report test results, coverage, or signed release details. Upgrade planning should account for the Go toolchain requirement and behavior differences across major versions rather than assuming output or flags are identical. The project uses the MIT licence. That licence generally permits broad use, modification, distribution, and sublicensing subject to its terms and notice requirements. This is a repository-level observation, not legal advice. Organisations should retain the applicable copyright and licence notice when redistributing binaries or incorporating source code. ## License and operational ownership boundaries The MIT licence keeps reuse relatively permissive, but the operational work remains with the adopter. TCPING probes a destination and records connection results; it does not provision firewall rules, manage DNS, configure services, or interpret application errors. Those boundaries should be reflected in an adoption decision. A deployment based on JSON or CSV needs a process for rotating or retaining probe records. SQLite support can simplify local persistence, but the README does not specify schema compatibility, migration behavior, or database-locking guidance. A scheduled monitoring system also needs to define when a failed connection becomes an alert. The utility reports observations, but it does not document notification integrations or an alert policy. The container image is useful when the probe must run close to a monitored network, yet its scratch base offers no shell for basic diagnosis inside the container. That is acceptable for a narrow probe process, but it increases the value of checking container arguments and network routing before deployment. Static and dynamic release binaries create a similar choice. Static binaries reduce runtime library dependencies, while dynamic binaries depend on compatible shared libraries. For teams using the Go module, upgrading can affect the build environment because the documented requirement is Go version `1.24.10` or later. Pinning a release and testing output compatibility is more predictable than changing an unversioned executable during an incident. The repository has a recent last push, but adoption still depends on the release notes and the target environment. ## Conclusion pouriyajamshidi/tcping fits operators, developers, and support teams that need repeated TCP reachability and latency observations when ICMP is unavailable or unsuitable. It is a weaker choice for full HTTP application checks, UDP monitoring, or service-level interpretation rather than port connectivity. Before adopting it, verify the invocation against the installed release, confirm that the target permits repeated connection attempts, and test the required output format. For v2, first check whether `go install github.com/pouriyajamshidi/tcping/v2@latest` succeeds with the documented Go version requirement. ## FAQ ### How do I install pouriyajamshidi/tcping on Linux, macOS, or Windows? The README documents `go install github.com/pouriyajamshidi/tcping/v2@latest`, Homebrew installation, Debian packages, Windows Package Manager, Docker images, and manually extracted release archives. The Go route requires at least Go version `1.24.10` according to the README. ### How do I use pouriyajamshidi/tcping to check a TCP port? Pass a hostname followed by a port. The README uses `tcping example.com 80` as the basic form, with JSON output available through `-j --pretty`. ### Can pouriyajamshidi/tcping monitor latency and connection availability? Yes. The README documents latency, packet loss, uptime, and downtime statistics, with configurable timeout, probe interval, source interface, and IPv4 or IPv6 enforcement. Pressing `Enter` prints accumulated connection statistics without stopping the program. ## Sources - [Issues](https://github.com/pouriyajamshidi/tcping/issues) - [License: MIT](https://github.com/pouriyajamshidi/tcping/blob/master/LICENSE) - [pouriyajamshidi/tcping on GitHub](https://github.com/pouriyajamshidi/tcping) - [README](https://github.com/pouriyajamshidi/tcping/blob/master/README.md) - [Releases](https://github.com/pouriyajamshidi/tcping/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pouriyajamshidi-tcping