spidy 0.1.2

A fast, customizable CLI tool for testing your internet connection speed using Cloudflare's speed test infrastructure.
spidy-0.1.2 is not a library.

Spidy

A fast, customizable CLI tool for testing your internet connection speed using Cloudflare's speed test infrastructure.

Features

  • Download & Upload Speed Testing - Measure both download and upload speeds with configurable test sizes
  • Latency & Jitter Metrics - Track network latency and jitter for both directions
  • Statistical Analysis - Automatic calculation of percentiles (75th, 90th), median latency, and jitter
  • Customizable Tests - Define custom test configurations with specific sizes and iterations
  • Multiple Output Formats - Results in human-readable text or JSON format
  • Location & ISP Info - Displays server location, ASN, and your IP information
  • Progress Tracking - Real-time progress bar showing test completion

Installation

From Source

git clone https://github.com/mipsel64/spidy.git
cd spidt
cargo build --release
./target/release/spidy --hlep

From crates.io

cargo install --locked spidy
spidy --help

Usage

Basic Usage

Run with default test configuration:

spidy

Custom Tests

Define custom tests using the --test or -t flag:

spidy -t "d=100kB=10,u=1MB=5,d=10MB=3"

Test format: <direction>=<size>=<iterations>

  • Direction: d/down for download, u/up for upload
  • Size: Human-readable format (e.g., 100kB, 1MB, 10MB, 100MB)
  • Iterations: Number of times to run each test

Output Formats

Text output (default):

spidy

JSON output:

spidy --format json

Examples

# Quick test with smaller files
spidy -t "d=100kB=5,u=100kB=5"

# Heavy download test
spidy -t "d=25MB=10,d=50MB=5"

# Upload-focused test
spidy -t "u=1MB=10,u=10MB=8,u=25MB=5"

# Get JSON output for parsing
spidy -f json > results.json

Default Test Configuration

If no tests are specified, the following default configuration is used:

  • Download 100kB × 10 iterations
  • Download 1MB × 8 iterations
  • Upload 100kB × 8 iterations
  • Upload 1MB × 6 iterations
  • Download 10MB × 6 iterations
  • Upload 10MB × 4 iterations
  • Download 25MB × 4 iterations
  • Download 100MB x 3 iterations

Output

Text Format

CLOUDFLARE SPEED TEST CLI
=========================

Server Location:    San Francisco - US
ASN:                13335 (Cloudflare, Inc.)
Your IP:            xxx.xxx.xxx.xxx

Completed 8/8 tests in 42.46s

Latency details
    Min:              116.00  ms
    Max:              188.00  ms
    Average:          138.15  ms
    Median:           131.00  ms
    Jitter:           22.05   ms
    90th Percentile:  170.20  ms
    75th Percentile:  143.50  ms

Download details:
    (10/10)  100kB  233.33  Mbps
    (8/8)    1MB    59.26   Mbps
    (6/6)    10MB   164.67  Mbps
    (4/4)    25MB   194.37  Mbps
Download Latency (Median):   131.50 ms
Download Jitter:             26.36  ms
Overall Download:
    90th Percentile:  306.67  Mbps
    75th Percentile:  200.15  Mbps

Upload details:
    (8/8)  100kB  2.74   Mbps
    (6/6)  1MB    18.32  Mbps
    (4/4)  10MB   38.60  Mbps
Upload Latency (Median): 145.00 ms
Upload Jitter:           306.38 ms
Overall Upload:
    90th Percentile:  38.18  Mbps
    75th Percentile:  24.39  Mbps

JSON Format

The JSON output includes:

  • Individual test results with all measurements
  • Aggregated statistics (percentiles, median latency, jitter)
  • Server metadata (location, ASN, IP information)
  • Latency stats

How It Works

Spidy uses Cloudflare's speed test infrastructure to measure your internet connection:

  1. Metadata Request - Retrieves information about the nearest Cloudflare server and your connection
  2. Download Tests - Downloads data from https://speed.cloudflare.com/__down?bytes=<size>
  3. Upload Tests - Uploads data to https://speed.cloudflare.com/__up
  4. Metrics Calculation:
    • Speed: Calculated from transfer size and transfer time (excluding TTFB)
    • Latency: Time to first byte minus server processing time
    • Jitter: Average absolute difference between consecutive latency measurements
    • Percentiles: Statistical distribution of all speed measurements

Proxy Support

Spidy does not have proxy-related command line flags by design. The tool uses libcurl under the hood, which automatically respects standard proxy environment variables:

  • HTTP_PROXY / http_proxy
  • HTTPS_PROXY / https_proxy

To use a proxy, simply set the appropriate environment variable:

export HTTPS_PROXY=http://proxy.example.com:8080
spidy

This approach keeps the CLI simple and allows users to run spidy without specifying any flags.

License

See LICENSE for details.