Skip to content

Usage Guide

Basic Usage

Full Diagnostic Suite

Run all diagnostic tests at once:

netspecs run

This runs: 1. Connectivity check to default endpoints 2. Latency tests (20 packets per endpoint) 3. Jitter measurement (30 seconds on first 3 endpoints) 4. Speed tests (HTTP downloads + Ookla if available) 5. Bandwidth variability analysis

Skip Specific Tests

# Skip speed tests (faster)
netspecs run --skip-speed

# Skip jitter tests
netspecs run --skip-jitter

# Skip both
netspecs run --skip-speed --skip-jitter

Individual Tests

Latency Testing

# Test default endpoints
netspecs latency

# Custom endpoints
netspecs latency --endpoints 8.8.8.8,google.com,cloudflare.com

# More packets for accuracy
netspecs latency --count 50

Speed Testing

# Full speed test
netspecs speed

# Skip Ookla (HTTP only)
netspecs speed --skip-ookla

# More variability iterations
netspecs speed --iterations 10

Jitter Measurement

# Default (30 seconds)
netspecs jitter

# Longer measurement
netspecs jitter --duration 60

# Custom endpoints
netspecs jitter --endpoints 8.8.8.8,1.1.1.1

Prioritization Detection

This test detects if your connection gets worse under load:

# Default (60 seconds per phase, ~5 minutes total)
netspecs prioritization

# Shorter test
netspecs prioritization --duration 30

# Test against specific host
netspecs prioritization --host 8.8.8.8

Output Formats

Console (Default)

Rich formatted output with colors and tables:

netspecs run --output console

JSON

Machine-readable JSON output:

netspecs run --output json

CSV

Spreadsheet-compatible CSV files:

netspecs run --output csv --output-dir ./results

Saving Results

Save output to a directory:

netspecs run --output-dir ./internet_diagnostics

This creates timestamped files: - diagnostic_YYYYMMDD_HHMMSS.json (JSON mode) - latency_YYYYMMDD_HHMMSS.csv (CSV mode) - etc.

AI-Powered Reports

Generate a narrative analysis of your results:

# With API key from environment
netspecs run --ai-report

# With explicit API key
netspecs run --ai-report --api-key YOUR_API_KEY

# Custom model
netspecs run --ai-report --model gpt-4o

# Generate report from saved results
netspecs report results.json

Custom Endpoints

Override the default test endpoints:

netspecs run --endpoints "8.8.8.8,1.1.1.1,google.com,aws.amazon.com"

Default endpoints include: - DNS servers (Google, Cloudflare, OpenDNS) - Popular services (Google, Cloudflare) - Gaming servers (Epic Games, Riot, Blizzard, Steam)

Configuration

View current configuration:

netspecs config --show

Configuration is loaded from (in priority order): 1. CLI arguments 2. Environment variables 3. .env.local file 4. Default values

Environment Variables

Variable Description
OPENAI_API_KEY API key for OpenAI models
ANTHROPIC_API_KEY API key for Anthropic models
NETSPECS_MODEL Default LLM model

Interpreting Results

Latency

Range Status Impact
< 50ms Excellent Imperceptible for most uses
50-100ms Good Fine for most applications
100-200ms Fair May notice delay in real-time apps
> 200ms Poor Noticeable lag in games/calls

Packet Loss

Range Status Impact
0% Excellent Perfect connection
< 1% Good Minimal impact
1-5% Concerning May cause issues
> 5% Problematic Significant disruption

Jitter

Range Status Impact
< 10ms Good Stable for real-time
10-30ms Moderate May affect call quality
> 30ms High Problematic for gaming/VoIP

Speed Discrepancy

If Ookla shows much higher speeds than HTTP tests (>50% difference), your ISP may be prioritizing speed test traffic over regular usage.