NetPace Consolidated Backlog - FrankRay78/NetPace GitHub Wiki
Premise
NetPace is an open-source, scriptable network speed test for the command line and for .NET. This backlog lists the features that would get it installed, make its results easy for scripts to consume, and give people reasons to choose it. How it compares with other speed test tools, and the market opening those comparisons point to, is in Background research.
What NetPace already offers:
- Open source (MIT) with a reusable .NET library and test doubles.
- A single native binary on Linux and Windows, with no runtime and no Docker.
- Data-capped profiles, down to 1 MiB per run with
--profile tiny. - Unattended runs:
--loop,--count,--delayand--fail-on.
A feature earns a row here only if its absence would break a real script, or if it is worth having in its own right. Each row is one feature, sized to become one issue. Item numbers run 1 to 28 in document order; they are identifiers, not priorities. Sizes are estimates: S, M or L.
The Origin column names the section of Background research that each item came from.
Proposed first five
Start with the dotnet tool package, then alternate between reach and reasons to choose NetPace.
- Item 1,
dotnet toolpackage. All the work sits inside this repository and its existing NuGet release workflow, so the harness can build it end to end. It reaches .NET developers only, because installing a tool needs the .NET SDK. - Item 8, raw numeric values in JSON. The output gap that most often breaks a script, since scripts need numbers rather than display strings, and it is small.
- Item 16, custom server list file. Unique to NetPace. It opens private and self-hosted servers and gives monitoring a fixed set of servers to compare over time.
- Item 2, Homebrew tap. The channel the target audience actually uses. It needs a separate tap repository.
- Item 25, threshold exit codes. Turns NetPace into a check that cron and monitoring tools can act on.
Next in line: item 24 jitter, item 9 raw numeric values in CSV, item 17 server IDs.
Reach
Seven items that get NetPace installed and understood; today the only route is to download an archive and unzip it.
| No. | Feature | Why | Origin | Size |
|---|---|---|---|---|
| 1 | dotnet tool install -g package |
One-line install and update for anyone with the .NET 10 SDK, and dnx runs it without installing. .NET 10 tool packages can carry the existing Native AOT binaries per platform. |
Gap analysis | M |
| 2 | Homebrew tap | brew install for macOS and Linux users. Homebrew's main repository requires source builds, so a project-owned tap comes first. |
Gap analysis | M |
| 3 | winget manifest | One-line install on Windows. | Gap analysis | S to M |
| 4 | Lowercase netpace command |
The binary is NetPace, which is awkward on case-sensitive Linux. |
New | S |
| 5 | macOS Native AOT binaries | macOS gets only the large self-contained build, or needs the .NET runtime. | Demand research | M |
| 6 | Migration page | A switch-by-switch mapping from other speed test tools, so a script can be ported in minutes. Documentation only. | Gap analysis | S |
| 7 | README positioning | Lead with "single binary, no Docker, no setup" and replace the August 2025 screenshot. Documentation only. | Demand research | S |
Script-ready output
Eight items that let a script or log consume NetPace's results without parsing display text.
| No. | Feature | Why | Origin | Size |
|---|---|---|---|---|
| 8 | Raw numeric values in JSON | JSON emits "18.67 Kbps" and "100 ms" as strings. Scripts need numbers. |
Gap analysis | S |
| 9 | Raw numeric values in CSV | CSV cells carry units unless --csv-header-units and a fixed scale are both set. |
Gap analysis | S |
| 10 | Server details in JSON (ID, country, distance) | JSON has location, sponsor and URL only. | Gap analysis | S, after 17 |
| 11 | Server columns in CSV | CSV has no server columns, so a log cannot show which server each row used. | Gap analysis | S |
| 12 | Public IP and ISP in output | NetPace reports the local interface address. Logs that track ISP or address changes need the public one. | Gap analysis | S to M |
| 13 | Bytes sent and received in output | Core records bytes processed, but JSON and CSV omit it. Useful on metered links. | Gap analysis | S |
| 14 | CSV header control | NetPace prints the header at the start of every run, so appending from cron with >> repeats it. Check how --file append behaves first. |
Gap analysis | S |
| 15 | Device label and custom fields in output | A --device-id label and --custom-field key-value pairs, so a shared log can tell machines apart. |
IoT research | S |
Servers and connection
Eight items covering which servers NetPace tests against and how it connects to them. Item 16 is the new idea and makes item 19 largely unnecessary.
| No. | Feature | Why | Origin | Size |
|---|---|---|---|---|
| 16 | Custom server list file | Point NetPace at a file of servers and let screening pick the fastest. Serves private and self-hosted servers, a fixed set for consistent monitoring, and runs with no discovery call. | Demand research | M |
| 17 | Server IDs in the model and the servers list |
IServer has no ID, and the list shows location, sponsor and URL. Prerequisite for 10, 18 and 19. |
Gap analysis | S to M |
| 18 | Select a server by ID | --server takes a URL only; scripts and other tools identify a server by ID. |
Gap analysis | S, after 17 |
| 19 | Exclude servers | With item 16, a user curates the list instead. Build only if someone asks. | Gap analysis | S, after 17 |
| 20 | Bind to a source address or interface | Multi-WAN homelabs, dual-WAN offices, and cellular versus ethernet on a gateway. | Demand research | M |
| 21 | Single-connection mode | Parallelism is a Core setting with no switch. One connection simulates an ordinary file transfer. | Gap analysis | S |
| 22 | HTTP timeout switch | Timeouts are Core settings with no switch. | Gap analysis | S |
| 23 | HTTPS for discovery and tests | The discovery URL defaults to plain HTTP, and Ookla is moving its servers to HTTPS. | Gap analysis | S to M |
On item 16's format: the Ookla discovery response NetPace reads today is XML, not JSON. Core already accepts a different discovery URL through ServersUrl, but the CLI has no switch for it and nothing reads a local file. A JSON file using Ookla's field names, with only url required, would be the simplest thing for a user to write by hand.
Items 16 and 27 are linked. Hosting a server in Ookla's network needs registration and approval, so most people could only fill a server list with their own machines once the LibreSpeed provider exists. LibreSpeed's CLI already has --server-json and --local-json, which is a naming precedent.
Reasons to choose NetPace
Five measurements and behaviours that give someone a reason to choose NetPace, beyond the basics every speed test tool covers.
| No. | Feature | Why | Origin | Size |
|---|---|---|---|---|
| 24 | Jitter | Variation across the latency samples NetPace already collects, shown in every output format. | Demand research | S |
| 25 | Threshold exit codes | --min-download, --min-upload and --max-latency give a non-zero exit when a result misses its target. Extends --fail-on. |
Demand research | S |
| 26 | Latency under load | Latency measured during a transfer, which exposes bufferbloat. The most distinctive of the measurement ideas. | Measurement ideas | M |
| 27 | LibreSpeed provider | A second provider that anyone can self-host. It ends sole reliance on Ookla's endpoints and proves the provider interface. | Demand research | L |
| 28 | Quick test mode | --quick uses the first or a cached server and five pings instead of twenty, cutting a run from 30 to 60 seconds down to 5 to 10. |
IoT research | S to M |
Parked
Four directions were researched and are out of the queue for now. Their designs, switch sketches and commercial options are in Background research.
| Direction | Items | Why parked |
|---|---|---|
| IoT | Signal strength metrics; location tagging; modem and SIM identifiers; data usage estimate and warning; multi-carrier testing; battery monitoring | Signal and modem work needs cellular hardware in the test loop. The rest pays off only with a fleet backend. |
| Cloud service | --upload flag and history dashboard; AWS IoT Core fleet features; infrastructure as code; observability |
A service to run and pay for before there are users to fill it. |
| MSP product | Multi-tenant clients; scheduled tests with history; PDF reports; baselines and alerts; ticketing integration; white-label; web dashboard | A separate product built on top of the CLI. |
| Measurement ideas | Ramp-up visualiser; concurrency optimiser; asset burst simulation; VPN and proxy test; cross-region benchmark; baseline regression; protocol test; raw TCP and UDP mode | Measurements for a narrow audience. Revisit once more people have NetPace installed. |
Not doing
Five items considered and rejected.
| Item | Reason |
|---|---|
| Shareable result image | It means posting results to speedtest.net as an unofficial client. |
| Testing against a mini server | --server already takes a custom server URL. |
| Turning off upload pre-allocation | NetPace streams uploads in small chunks, so there is nothing to pre-allocate. |
| Packet loss | Over HTTP, TCP retransmission hides real loss. The honest figure is failed requests, which NetPace already reports. |
| Matching other tools' switch names | NetPace keeps its own names, such as --minimal and --unit. The migration page (item 6) maps them. |
Already shipped
Nine things the backlog builds on, so nothing above duplicates them.
| Item | Release |
|---|---|
Data-capped profiles (--profile, --downloadsize, --uploadsize) |
0.7.0 (--downloadsize/--uploadsize), 0.24.0 --profile |
| Native AOT binaries for Linux and Windows, x64 and ARM64 | 0.22.3 (Linux), 0.23.4 (Windows) |
| Local IP address and hostname in CSV and JSON | 0.21.0 |
Failure detection (--fail-on, request counts in every format) |
0.24.0 |
| Upload fix for Ookla servers that moved to HTTPS | 0.25.0 |
Required result properties in NetPace.Core |
0.26.0 |
| Server screening separated from measurement | 0.26.0 |
--minimal output format, replacing --verbosity |
0.26.0 |
--diagnostics per-request stream |
0.26.0 |