netspeed-cli

Command line interface for testing internet bandwidth using speedtest.net

Overview

netspeed-cli is a Rust-based command line tool for testing your internet bandwidth using speedtest.net servers. It provides fast, accurate speed testing with detailed metrics including latency under load, peak speeds, jitter, per-metric letter grades, and an overall connection quality rating.

Runtime behavior highlights:

CLI configuration precedence is CLI flags > config file > built-in defaults.
Speedtest server URLs from the XML feed are normalized internally, so latency, download, and upload endpoints are derived from the same canonical server definition.
Corrupted local history files fail safely instead of being silently overwritten.
Human-readable formats output to stderr (so they don't interfere with pipes); machine-readable formats (JSON, JSONL, CSV) output to stdout.

Installation

Homebrew (macOS/Linux) - Recommended

# Add the tap (one-time)
brew tap mapleDevJS/homebrew-netspeed-cli

# Install netspeed-cli
brew install netspeed-cli

Note: After adding the tap, you can use brew install netspeed-cli for all future installations and updates.

Cargo

cargo install netspeed-cli

Direct Download

Pre-built binaries are available for download at: https://github.com/mapleDevJS/netspeed-cli/releases/latest

From source

git clone https://github.com/mapleDevJS/netspeed-cli.git
cd netspeed-cli
cargo build --release
./target/release/netspeed-cli

Note: The CLI is officially supported on macOS 12+, Linux (kernel 5.4+), and Windows 10+. While it may work on other Unix-like systems, it's not guaranteed.

System Requirements

Requirement	Details
OS	macOS 12+, Linux (kernel 5.4+), Windows 10+
Rust	1.86+ (for building from source)
Terminal	Any Unicode-capable terminal (UTF-8)
Network	Internet access to speedtest.net servers
Architecture	x86_64, aarch64 (Apple Silicon, ARM Linux)

Note: The CLI uses Unicode box-drawing characters and emoji indicators (set NO_COLOR=1 or --no-emoji for plain-text fallback compatible with screen readers and limited terminals).

Usage

$ netspeed-cli --help

Basic Usage

Test your connection automatically:

netspeed-cli

Test against a specific server:

netspeed-cli --server 1234

Output in JSON format:

netspeed-cli --format json

Output in CSV format:

netspeed-cli --format csv

Test download speed only:

netspeed-cli --no-upload

View test history:

netspeed-cli --history

Use a user profile:

netspeed-cli --profile gamer

Show config file location:

netspeed-cli --show-config-path

Options

Option	Description
`--no-download`	Skip download test
`--no-upload`	Skip upload test
`--single`	Use single connection
`--bytes`	Display values in bytes instead of bits
`--format TYPE`	Output format: `json`, `jsonl`, `csv`, `minimal`, `simple`, `compact`, `detailed`, `dashboard` (supersedes `--json`, `--csv`, `--simple`)
`--json`	Legacy alias for `--format json`
`--csv`	Legacy alias for `--format csv`
`--simple`	Legacy alias for `--format simple`
`--minimal`	Legacy alias for `--format minimal`
`--csv-delimiter CHAR`	CSV delimiter character: `,`, `;`, `\|`, or tab (default: `,`)
`--csv-header`	Include CSV header row
`--quiet`	Suppress all progress output (for cron jobs / CI)
`--list`	List available servers
`--server ID`	Test against specific server (can be used multiple times)
`--exclude ID`	Exclude server from selection (can be used multiple times)
`--source IP`	Bind to source IP address
`--timeout SEC`	HTTP timeout in seconds (default: 10, range: 1-300)
`--theme THEME`	Color theme: `dark`, `light`, `high-contrast`, `monochrome` (default: `dark`)
`--profile PROFILE`	User profile: `power-user`, `gamer`, `streamer`, `remote-worker`, `casual` (default: `power-user`)
`--no-emoji`	Disable emoji indicators in output
`--ca-cert PATH`	Path to custom CA certificate file (PEM/DER)
`--tls-version VERSION`	Minimum TLS version: `1.2` or `1.3`
`--pin-certs`	Restrict TLS connections to speedtest.net and ookla.com domains while preserving normal certificate validation
`--history`	Show test history with sparkline trends
`--dry-run`	Show test configuration without running the test
`--show-config-path`	Print the config file path and exit
`--strict-config`	Treat config file warnings as errors
`--generate-completion SHELL`	Generate shell completion script
`--version`	Show version

Configuration File

netspeed-cli can be configured via a TOML file. Use --show-config-path to find the platform-specific location.

netspeed-cli --show-config-path

Precedence: CLI flags > config file > built-in defaults.

Example `config.toml`

# Test selection
no_download = false
no_upload = false
single = false
timeout = 10

# Output
format = "detailed"          # json, jsonl, csv, minimal, simple, compact, detailed, dashboard
bytes = false
theme = "dark"               # dark, light, high-contrast, monochrome
profile = "power-user"       # power-user, gamer, streamer, remote-worker, casual
no_emoji = false
quiet = false

# CSV
csv_delimiter = ","
csv_header = false

# TLS
ca_cert = "/path/to/ca.pem"
tls_version = "1.2"
pin_certs = false

# Strict mode (warnings become errors)
strict = false

User Profiles

Profiles adjust scoring weights, grading thresholds, and which sections appear in the output. Use --profile or set profile in the config file.

Profile	Description	Notes
`power-user`	Full report with all metrics (default)	Shows everything: estimates, percentiles, stability, bufferbloat, UL/DL ratio
`gamer`	Optimized for gaming quality	Higher weight on ping and jitter; strict latency thresholds
`streamer`	Optimized for streaming quality	Higher weight on download speed and consistency
`remote-worker`	Optimized for remote work/video calls	Higher weight on upload speed and stability
`casual`	Simplified output	Relaxed thresholds, fewer sections, minimal output

Profiles are case-insensitive. Aliases: poweruser, remote, remoteworker.

Output Formats

Dashboard

Rich terminal dashboard with 3-column metrics and capability matrix:

  ┌────────────────────────────────────────────────────────┐
  │          NetSpeed CLI                                 │
  │  Rogers (Toronto) - CA - 12km - 192.168.1.1           │
  └────────────────────────────────────────────────────────┘

  ┌ PERFORMANCE ┬ STABILITY ┬ BUFFERBLOAT ┐
  │  450.2 Mb/s v│ DL: A+    │ Grade: C    │
  │  120.5 Mb/s ^│ UL: A+    │             │
  │    12.1 ms  │           │ Overall: B+ │
  └─────────────┴───────────┴─────────────┘

Compact

Key metrics with quality ratings between simple and detailed:

  TEST RESULTS
  Overall: Good

  Latency        12.1 ms    (Good)
  Download     450.23 Mb/s  (Excellent)
  Peak         520.10 Mb/s
  Upload      120.45 Mb/s   (Good)

  Download: 14.6 MB in 3.2s
  Upload: 4.1 MB in 2.1s
  Total time: 5.3s

Detailed (default)

Default full report with overall grading, latency metrics, transfer speeds, connection info, summary totals, total time, and completion timestamp. When available, it also includes packet loss, bufferbloat, latency under load, variance, and UL/DL ratio. Profile-driven extras such as transfer estimates, stability analysis, latency percentiles, and history comparison may be appended after the main report when the necessary data is available.

  TEST RESULTS
  Overall: Excellent

  Latency:        5.2 ms  (Excellent)
  Jitter:         1.3 ms
  Packet Loss:    0.0%
  Bufferbloat:    A (+7.2 ms)
  Download:     450.23 Mb/s  (Excellent)
  Peak:         520.10 Mb/s
  Latency (load): 12.4 ms  +138% (significant)
  Variance:     +/-4.8% (stable)
  Upload:       120.45 Mb/s  (Good)
  Peak:         145.80 Mb/s
  Latency (load):  8.1 ms  +56% (significant)
  Variance:     +/-8.6% (variable)
  UL/DL Ratio:  3.74x download-heavy

  CONNECTION INFO
  Server:       Rogers (Toronto)
  Location:     CA  (12 km)
  Client IP:    192.168.1.1

  TEST SUMMARY
  Download:     12.4 MB in 3.2s
  Upload:       4.1 MB in 2.1s
  Total:        16.5 MB in 5.3s

  Total time: 5.3s
  Completed at: 2026-04-04T12:00:00Z

Tip: Use --no-download or --no-upload to skip a phase. Skipped tests show -- (skipped) in the output.

Simple

Latency: 5.2 ms | Download: 450.23 Mb/s | Upload: 120.45 Mb/s

Minimal

Ultra-compact single line for status bars and scripts:

B+  450.2v  120.5^  12ms

JSON

One-line JSON object:

{"status":"ok","server":{"id":"1234",...},"ping":5.2,"download":450230000,"phases":{"ping":{"state":"completed"},"download":{"state":"completed"},"upload":{"state":"completed"}}}

Runtime failures in JSON mode also emit a JSON object with a stable error envelope and a non-zero exit code:

{"status":"error","exit_code":69,"timestamp":"2026-04-18T12:00:00Z","error":{"code":"download_failed","category":"network","message":"Download test failed: all streams failed","suggestion":"Try with --single for a simpler test."}}

JSONL

JSON Lines format - one JSON object per line, ideal for logging:

{"server":{"id":"1234",...},"ping":5.2,"download":450230000,...}
{"server":{"id":"1234",...},"ping":4.8,"download":445000000,...}

On failure, JSONL emits a single error object line with the same schema as JSON mode. Successful JSON and JSONL payloads also include per-phase state so scripts can distinguish completed phases from user-skipped phases without inferring from missing metrics.

CSV

Server ID,Sponsor,Server Name,Timestamp,Distance,Ping,Jitter,Packet Loss,Download,Download Peak,Upload,Upload Peak,IP Address
1234,Rogers,Toronto,2026-04-04T12:00:00Z,12.0,5.2,1.3,0.0,450230000.0,520100000.0,120450000.0,145800000.0,192.168.1.1

Features

Connection Quality Rating

An overall rating combining all metrics:

Rating	Score	Description
Excellent	90+	Fiber-grade connection
Great	75-89	Very good performance
Good	55-74	Solid everyday connection
Fair	40-54	Acceptable, some limitations
Moderate	25-39	Noticeable performance issues
Poor	<25	Significant problems

Letter Grades (A+ to F)

Each metric receives a letter grade based on profile-aware thresholds. For example, the gamer profile requires lower latency for an A+ than the casual profile.

Grade	Score Range
A+	97+
A	93-96
A-	90-92
B+	87-89
B	83-86
B-	80-82
C+	77-79
C	73-76
C-	70-72
D	60-69
F	<60

Grades are assigned to: ping, jitter, download speed, upload speed, bufferbloat, and stability (CV%).

Latency Under Load

Measures ping latency during download and upload tests to show how your connection degrades under bandwidth saturation. The degradation percentage shows how much worse latency gets compared to idle:

< 25%: Minimal impact -- great for gaming/calls while downloading
25-50%: Moderate impact -- noticeable but manageable
> 50%: Significant impact -- connection struggles under load

Stability Analysis

Coefficient of Variation (CV%) measures how consistent your speeds are during a test:

< 3%: Very stable
3-8%: Stable
> 8%: Variable

Latency Percentiles

When latency samples are available, the detailed output includes P50, P95, and P99 values to show the full distribution of your connection's latency.

Peak Speeds

Shows the maximum burst speed observed during each test phase, helping you understand your connection's capacity beyond just the average.

Test History

Results are automatically saved after a successful test (up to 100 entries). View with --history.

Sparkline trends: visual trend of download/upload speeds across the last 20 tests
Comparison: shows percentage faster/slower than your historical average
Atomic writes: temp file written first, then renamed; previous valid file rotated to history.json.bak
Corruption recovery: corrupt primary file is preserved as history.json.corrupt before recovery from backup

To disable history: machine-readable formats (--format json, --format jsonl, --format csv) skip history saving automatically.

Usage Estimates

When using profiles with usage targets, the detailed output shows estimated download times for common file sizes (e.g., a 1 GB file, a 50 GB game).

Building from Source

Requirements

Rust 1.86+
cargo

cargo build --release
cargo test

Privacy

netspeed-cli stores test results locally for historical comparison. The following data is saved:

Server information: name, sponsor
Test metrics: ping, jitter, packet loss, download/upload speeds and peaks, latency under load (download/upload), timestamps
Client IP address: discovered from speedtest.net during each test

Storage location: Platform-specific data directory (via the directories crate). Use --show-config-path to display the exact path. On Unix systems, the history file is created with 0o600 permissions (owner-only access).

No data is transmitted to any server other than speedtest.net infrastructure. No analytics, telemetry, or crash reporting is included.