|
| 1 | + |
| 2 | + |
| 3 | +# LibreSpeed command line tool |
| 4 | +Don't have a GUI but wants to use LibreSpeed servers to test your Internet speed? 🚀 |
| 5 | + |
| 6 | +`librespeed-cli` comes to rescue! |
| 7 | + |
| 8 | +This is a command line interface for LibreSpeed speed test backends, written in Go. |
| 9 | + |
| 10 | +## Features |
| 11 | +- Ping |
| 12 | +- Jitter |
| 13 | +- Download |
| 14 | +- Upload |
| 15 | +- IP address |
| 16 | +- ISP Information |
| 17 | +- Result sharing (telemetry) *[optional]* |
| 18 | +- Test with multiple servers in a single run |
| 19 | +- Use your own server list or telemetry endpoints |
| 20 | +- Tested with PHP and Go backends |
| 21 | + |
| 22 | +[](https://asciinema.org/a/J17bUAilWI3qR12JyhfGvPwu2) |
| 23 | + |
| 24 | +## Requirements for compiling |
| 25 | +- Go 1.14 |
| 26 | + |
| 27 | +## Runtime requirements |
| 28 | +- Any [Go supported platforms](https://github.com/golang/go/wiki/MinimumRequirements) |
| 29 | + |
| 30 | +## Building `librespeed-cli` |
| 31 | + |
| 32 | +1. First, you'll have to install Go. For Windows users, [you can download an installer from golang.org](https://golang.org/dl/). |
| 33 | +For Linux users, you can use either the archive from golang.org, or install from your distribution's package manager. |
| 34 | + |
| 35 | + For example, Arch Linux: |
| 36 | + |
| 37 | + ```shell script |
| 38 | + # pacman -S go |
| 39 | + ``` |
| 40 | + |
| 41 | +2. Then, clone the repository: |
| 42 | + |
| 43 | + ```shell script |
| 44 | + $ git clone -b v1.0.0 https://github.com/librespeed/speedtest-cli |
| 45 | + ``` |
| 46 | + |
| 47 | +3. After you have Go installed on your system (and added to your `$PATH` if you're using the archive from golang.org), you |
| 48 | +can now proceed to build `librespeed-cli` with the build script: |
| 49 | +
|
| 50 | + ```shell script |
| 51 | + $ cd speedtest-cli |
| 52 | + $ ./build.sh |
| 53 | + ``` |
| 54 | +
|
| 55 | + If you want to build for another operating system or system architecture, use the `GOOS` and `GOARCH` environment |
| 56 | + variables. Run `go tool dist list` to get a list of possible combinations of `GOOS` and `GOARCH`. |
| 57 | + |
| 58 | + ```shell script |
| 59 | + # Let's say we're building for 64-bit Windows on Linux |
| 60 | + $ GOOS=windows GOARCH=amd64 ./build.sh |
| 61 | + ``` |
| 62 | +
|
| 63 | +4. When the build script finishes, if everything went smoothly, you can find the built binary under directory `out`. |
| 64 | +
|
| 65 | + ```shell script |
| 66 | + $ ls out |
| 67 | + librespeed-cli-windows-amd64.exe |
| 68 | + ``` |
| 69 | + |
| 70 | +5. Now you can use the `librespeed-cli` and test your Internet speed! |
| 71 | +
|
| 72 | +## Install from AUR/Homebrew |
| 73 | +
|
| 74 | +TODO |
| 75 | +
|
| 76 | +## Usage |
| 77 | +
|
| 78 | +You can see the full list of supported options with `librespeed-cli -h`: |
| 79 | +
|
| 80 | +```shell script |
| 81 | +$ librespeed-cli -h |
| 82 | +NAME: |
| 83 | + librespeed-cli - Test your Internet speed with LibreSpeed 🚀 |
| 84 | +
|
| 85 | +USAGE: |
| 86 | + librespeed-cli [global options] [arguments...] |
| 87 | +
|
| 88 | +GLOBAL OPTIONS: |
| 89 | + --help, -h show help (default: false) |
| 90 | + --version Show the version number and exit (default: false) |
| 91 | + --no-download Do not perform download test (default: false) |
| 92 | + --no-upload Do not perform upload test (default: false) |
| 93 | + --bytes Display values in bytes instead of bits. Does not affect |
| 94 | + the image generated by --share, nor output from |
| 95 | + --json or --csv (default: false) |
| 96 | + --distance value Change distance unit shown in ISP info, use 'mi' for miles, |
| 97 | + 'km' for kilometres, 'NM' for nautical miles (default: "km") |
| 98 | + --share Generate and provide a URL to the LibreSpeed.org share results |
| 99 | + image, not displayed with --csv (default: false) |
| 100 | + --simple Suppress verbose output, only show basic information |
| 101 | + (default: false) |
| 102 | + --csv Suppress verbose output, only show basic information in CSV |
| 103 | + format. Speeds listed in bit/s and not affected by --bytes |
| 104 | + (default: false) |
| 105 | + --csv-delimiter CSV_DELIMITER Single character delimiter (CSV_DELIMITER) to use in |
| 106 | + CSV output. (default: ",") |
| 107 | + --csv-header Print CSV headers (default: false) |
| 108 | + --json Suppress verbose output, only show basic information |
| 109 | + in JSON format. Speeds listed in bit/s and not |
| 110 | + affected by --bytes (default: false) |
| 111 | + --list Display a list of LibreSpeed.org servers (default: false) |
| 112 | + --server SERVER Specify a SERVER ID to test against. Can be supplied |
| 113 | + multiple times. Cannot be used with --exclude |
| 114 | + --exclude EXCLUDE EXCLUDE a server from selection. Can be supplied |
| 115 | + multiple times. Cannot be used with --server |
| 116 | + --server-json value Use an alternative server list from remote JSON file |
| 117 | + --local-json value Use an alternative server list from local JSON file |
| 118 | + --source SOURCE SOURCE IP address to bind to |
| 119 | + --timeout TIMEOUT HTTP TIMEOUT in seconds. (default: 15) |
| 120 | + --secure Use HTTPS instead of HTTP when communicating with |
| 121 | + LibreSpeed.org operated servers (default: false) |
| 122 | + --no-pre-allocate Do not pre allocate upload data. Pre allocation is |
| 123 | + enabled by default to improve upload performance. To |
| 124 | + support systems with insufficient memory, use this |
| 125 | + option to avoid out of memory errors (default: false) |
| 126 | + --telemetry-json value Load telemetry server settings from a JSON file. This |
| 127 | + options overrides --telemetry-level, --telemetry-server, |
| 128 | + --telemetry-path, and --telemetry-share |
| 129 | + --telemetry-level value Set telemetry data verbosity, available values are: |
| 130 | + disabled, basic, full, debug |
| 131 | + --telemetry-server value Set the telemetry server base URL |
| 132 | + --telemetry-path value Set the telemetry upload path |
| 133 | + --telemetry-share value Set the telemetry share link path |
| 134 | + --telemetry-extra value Send a custom message along with the telemetry results |
| 135 | +``` |
| 136 | +
|
| 137 | +## Use a custom backend server list |
| 138 | +The `librespeed-cli` supports loading custom backend server list from a JSON file (remotely via `--server-json` or |
| 139 | +locally via `--local-json`). The format is as below: |
| 140 | +
|
| 141 | +```json |
| 142 | +[ |
| 143 | + { |
| 144 | + "name": "PHP Backend", |
| 145 | + "server": "https://example.com/", |
| 146 | + "dlURL": "garbage.php", |
| 147 | + "ulURL": "empty.php", |
| 148 | + "pingURL": "empty.php", |
| 149 | + "getIpURL": "getIP.php" |
| 150 | + }, |
| 151 | + { |
| 152 | + "name": "Go Backend", |
| 153 | + "server": "http://example.com/speedtest/", |
| 154 | + "dlURL": "garbage", |
| 155 | + "ulURL": "empty", |
| 156 | + "pingURL": "empty", |
| 157 | + "getIpURL": "getIP" |
| 158 | + } |
| 159 | +] |
| 160 | +``` |
| 161 | +
|
| 162 | +As you can see in the example, all servers have their schemes defined. In case of undefined scheme (e.g. `//example.com`), |
| 163 | +`librespeed-cli` will use `http` by default, or `https` when the `--secure` option is enabled. |
| 164 | +
|
| 165 | +## Use a custom telemetry server |
| 166 | +By default, the telemetry result will be sent to `librespeed.org` by default. You can also customize your telemetry settings |
| 167 | +via the `--telemetry` prefixed options. In order to load a custom telemetry endpoint configuration, you'll have to use the |
| 168 | +`--telemetry-json` option to specify a local JSON file containing the configuration bits. The format is as below: |
| 169 | + |
| 170 | +```json |
| 171 | +{ |
| 172 | + "telemetryLevel": "full", |
| 173 | + "server": "https://example.com", |
| 174 | + "path": "/results/telemetry.php", |
| 175 | + "shareURL": "/results/" |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +For `telemetryLevel`, four values are available: |
| 180 | + |
| 181 | +- `disabled` to disable telemetry |
| 182 | +- `basic` to enable telemetry with result only) |
| 183 | +- `full` to enable telemetry with result and timing |
| 184 | +- `debug` to enable the most verbose telemetry information |
| 185 | + |
| 186 | +`server` defines the base URL for the backend's endpoints. `path` is the path for uploading the telemetry result, and |
| 187 | +`shareURL` is the path for fetching the uploaded result in PNG format. |
| 188 | +
|
| 189 | +Currently, `--telemetry-json` only supports loading a local JSON file. |
| 190 | +
|
| 191 | +## Bugs? |
| 192 | +
|
| 193 | +Although we have tested the cli, it's still in its early days. Please open an issue if you encounter any bugs, or even |
| 194 | +better, submit a PR. |
| 195 | + |
| 196 | +## How to contribute |
| 197 | + |
| 198 | +If you have some good ideas on improving `librespeed-cli`, you can always submit a PR via GitHub. |
| 199 | + |
| 200 | +## License |
| 201 | + |
| 202 | +`librespeed-cli` is licensed under [GNU Lesser General Public License v3.0](https://github.com/librespeed/speedtest-cli/blob/master/LICENSE) |
0 commit comments