librespeed-cli runs LibreSpeed server tests from a terminal or a container

The measurement you already have a server for

LibreSpeed is a self-hostable speed test, and this repository is its command line client. The README states the problem in one sentence: if you do not have a GUI but want to use LibreSpeed servers to test your Internet speed, the tool comes to the rescue. It is a command line interface for LibreSpeed speed test backends, written in Go.

That framing determines what the client is and is not. It is not a general purpose internet speed test that talks to a commercial provider. It speaks the LibreSpeed backend protocol, which means it works against the public LibreSpeed.org server list and against your own LibreSpeed instances, and the servers it talks to are the same ones the browser-based test uses.

The feature list is short and complete: ping, jitter, download, upload, the IP address, ISP information, optional result sharing through telemetry, testing against multiple servers in a single run, the ability to use your own server list or telemetry endpoints, and testing that has been carried out against both the PHP and the Go backends.

The audience is whoever already runs LibreSpeed, or wants to. That is a self-hosted operator, a homelab builder, or anyone measuring a link on a server with no browser, and the container image and the machine-readable output flags both point at the automation use case.

The licence is LGPL-3.0, and the last push to the default branch was on 2026-10-15, with releases v1.0.12 on 2025-06-12, v1.0.13 on 2026-04-30 and v1.0.14 on 2026-08-17.

Building it: Go, build.sh and the out directory

The build is a shell script and a Go toolchain, and the README's steps are literal.

The first step is installing Go. The compiling requirements section says Go 1.18 or newer, while the build walkthrough asks for at least version 1.11, and the go.mod in the repository declares go 1.26.0. The container image uses golang:1.27-alpine, which is the version the project actually builds with today. Install a current Go and the disagreement stops mattering.

Then clone and build:

$ git clone -b v1.0.0 https://github.com/librespeed/speedtest-cli

$ cd speedtest-cli
$ ./build.sh

The build script produces the binary under the out directory, and the README shows what that looks like:

$ ls out
librespeed-cli-windows-amd64.exe

Cross compilation uses the standard Go environment variables, and the README points at go tool dist list for the possible combinations:

$ GOOS=windows GOARCH=amd64 ./build.sh

There is a note for older toolchains. The CLI can technically be compiled with older Go versions that support modules, with GO111MODULE=on set, and you might have to change the Go version in go.mod if you compile with an older runtime.

If you would rather not build at all, the releases page carries binaries compiled for various platforms, and the repository has a .goreleaser.yml at the top level, which is how those artefacts are produced.

Package managers for every platform the tool targets

The distribution story is thorough, which is what you expect from a tool whose whole point is running on servers and in CI.

On Arch, the AUR route uses an AUR helper and the package librespeed-cli-bin:

$ yay librespeed-cli-bin

Or you clone and build the AUR package yourself, with git clone of the librespeed-cli-bin repository and makepkg -si.

macOS users have a Homebrew tap, with the setup instructions in the librespeed-cli Homebrew tap repository.

Windows has three options, and the README gives the exact commands for each:

> scoop install librespeed-cli

> choco install librespeed-cli

> winget install LibreSpeed.librespeed-cli 

The Scoop note asks you to add the extras bucket, and the Chocolatey and WinGet commands install the same binary under different package identifiers.

The dependency set is modest, which is worth noticing for a network tool. The go.mod requires the spinner and the gocsv packages, pro-bing for the ping measurements, urfave/cli v2 for the command line surface, and golang.org/x/sys. The indirect list is longer but conventional, with the colour, markdown and terminal detection helpers that urfave/cli pulls in.

The container image and the ping permission problem

There is a Dockerfile, and the README documents the container flow in two steps, building the image and running it:

docker build -t librespeed-cli:latest .

docker run --rm --name librespeed-cli librespeed-cli:latest

The image is a two stage build. The builder is golang:1.27-alpine with bash, upx and git added, and it runs ./build.sh. The runtime stage is alpine:3.24 with the built binary copied into /bin and librespeed-cli as the entry point.

The two run variants in the README are the interesting part. The first passes options to the tool, including --telemetry-level disabled and --no-upload, which turn off the sharing of results. The second adds a sysctl setting:

docker run --rm --name librespeed-cli --sysctl net.ipv4.ping_group_range="0 2147483647" librespeed-cli:latest --verbose

The comment next to it explains why: without that setting you get Failed to ping target host: socket: permission denied errors when using --verbose. Containers normally cannot send ICMP echo requests, and widening the permitted ping group range is the way to allow it.

That is a genuine papercut, and the fact that the README documents it with an exact command rather than a hint is a good sign about the rest of the documentation.

The flag surface, and the ones that change the numbers

The help output is long, and most flags fall into three groups: what to measure, how to report it, and which server to use.

For measurement, --no-download and --no-upload skip a direction, and --no-icmp turns off the ICMP ping, which the README says is worth doing because ICMP does not work well under Linux at the moment. --concurrent sets the number of concurrent HTTP requests, with a default of 3, and that value directly changes how the transfer is shaped.

For units, --bytes displays values in bytes instead of bits, and --mebibytes switches from 1000 to 1024 bytes per kilobyte. Both affect the display only: the README is explicit that --bytes does not affect the image generated by --share nor the output from --json or --csv, and that CSV speeds are listed in bit/s regardless.

For output, --simple suppresses verbose output, --csv produces CSV with optional --csv-delimiter and --csv-header, and --json produces JSON. --distance sets the unit shown in the ISP information, with 'mi' for miles, 'km' for kilometres and 'NM' for nautical miles, defaulting to kilometres.

For servers, --list displays a list of the LibreSpeed.org servers, --server takes a server ID and can be supplied more than once, and --exclude removes a server from selection. The README notes that --server and --exclude cannot be used together, which is the sort of constraint that is easier to read in the help output than to discover at runtime.

Telemetry, sharing and the choice to keep results local

Result sharing is listed as optional in the feature list, and the container example shows the flags that control it, so it is worth being precise about what leaves your machine.

Two separate switches appear. --share generates and provides a URL to the LibreSpeed.org share results image, and the README notes that the image is not displayed with --csv. --no-upload and --telemetry-level disabled appear in the container run command, which suggests the tool can send telemetry to an endpoint without being asked to share a results image.

The feature list also says you can use your own server list or telemetry endpoints, which is the option that matters for anyone who does not want results going to a public service at all. A self-hosted LibreSpeed server is the natural companion here, and the fact that the tool is tested with both the PHP and the Go backends means it works with whichever one you deployed.

The two extremes are therefore available: a fully public run against the LibreSpeed.org server list, which is the same measurement the browser test gives and is therefore comparable with it, and a fully private run against your own servers with telemetry disabled.

What the tool does not offer is a measurement against a provider that is not LibreSpeed, so the resulting number lives in LibreSpeed's world and is not directly comparable with results from other speed test services.

Editorial conclusion

Adopt librespeed-cli when you need to measure a link against a LibreSpeed server from a terminal, a script or a CI job, especially if you want the result as JSON or CSV rather than a chart. Do not adopt it if you need a single number to compare against Ookla style tests, because it measures against LibreSpeed backends and your own server list, which changes what the number means. Before you build on it, check the Go version you actually need, since the README says 1.18 while go.mod declares go 1.26.0 and the container image builds with golang 1.27, and confirm whether your measurements may be uploaded to LibreSpeed.org, which the --no-upload and --telemetry-level flags control.

Frequently asked questions

Official sources

1. Issues
2. librespeed/speedtest-cli on GitHub
3. License: LGPL-3.0
4. README
5. Releases