Terminal Experience Direction

This page sets the direction for how NetPace looks and behaves in a terminal: what it is aiming to be, the decisions already made, the principles every change follows, and a prioritised backlog that issues are drafted from. Last reviewed 18 October 2026.

Direction

NetPace shows how your connection feels, not just how fast it is.

A speed number on its own does not set a tool apart; every speed test produces one. What people actually notice is a connection that stutters: a video call that freezes while someone downloads, or a game that lags in the evening. NetPace aims to make that visible, as htop made visible what top left out.

The direction has two separate features, each with its own use case:

• The speed test, run once. It measures how fast the line is and how it behaves when the line is full, then gives a verdict on how it will feel to use.
• The monitor, which keeps running. It sits alongside a video call, a game or a download, and watches how the connection behaves over time without loading the line itself. It is a new kind of tool, not a repeated speed test, and it may become what NetPace is known for.

Decisions

The speed test

• While the test runs, the screen shows the connection's behaviour: throughput live as it climbs, with latency under load alongside it. A percentage bar is not enough.
• The live speed figure is the average since the test began, so it lands on exactly the speed the result reports. A graph, added later, shows the shape that the average smooths out.
• The test ends with a verdict on how the connection will feel. The scale is not decided yet; see Open questions.
• The result fits on one screen as a compact card that is worth a screenshot. It is private by default: no IP address and no ISP unless asked for.
• The card lives in the terminal only. NetPace does not post results anywhere, which keeps it consistent with Shareable result image under Not doing in the Consolidated Backlog.

The monitor

• It is its own command, netpace monitor, with its own options, separate from the speed test's.
• It never runs speed tests in a loop, because a speed test fills the line and would cause the lag the monitor is watching for. It measures lightly instead:
  • Latency and jitter over time, from small, frequent probes to one server.
  • The machine's own traffic, read from the operating system's per-interface byte counters. This sends no extra traffic.
• Both are plotted on one timeline, so a latency spike that lines up with a burst of download traffic explains itself.
• By default it probes one nearby Ookla server, chosen at start.
• The user can name a specific server instead, including a self-hosted one such as the repository's Docker OoklaServer.
• The pace of probing is tunable, much as --profile tunes the speed test, and it works the same whichever server is used.
• The default pace is gentle, around one probe a second, like ping and gping.
• If a server answers "too many requests", the monitor slows down by itself, says so on screen, and returns to its pace gradually.
• The screen tells the user the pace can be changed, and a keyboard shortcut changes it live.
• The interactive terminal is the priority. Outside a terminal (piped, scripted, scheduled), the monitor streams one machine-readable record per probe. This only has to work well enough; the interactive view gets the polish.

Themes

• Themes change how NetPace looks, never what it does.
• A theme sets the colour palette, the glyphs used for bars, graphs, borders and small ornaments, and the banner font.
• The terminal owns the text font, so themes cannot change it.
• Planned themes include desert, autumn, Halloween and Christmas.
• Seasonal themes do not switch on by themselves unless the user opts in.
• The visual work is built on named colours and glyphs from the start, so themes are cheap to add later.

Principles

Every change under this direction follows these:

1. Colour carries meaning first and decoration second. Each theme supplies its own colours for good, warning and bad. A bad result looks bad in every theme, on dark and light backgrounds alike.
2. The rich view needs a real terminal. Every view has defined fallbacks: no colour (including NO_COLOR), plain glyphs for fonts without braille or box characters, and narrow windows. Where Spectre.Console already degrades gracefully, NetPace relies on it rather than building its own.
3. Screenshots are private by default. Nothing that identifies the user or their network appears unless they ask for it.
4. The monitor never fills the line. It measures the connection without changing what it measures.
5. Be a good guest on shared servers. Public speed-test servers are run by volunteers and ISPs. Defaults are gentle, and NetPace backs off when asked.
6. CSV and JSON are untouched. They stay plain numbers in fixed units. Everything on this page concerns the output people read.

Non-goals

• No hosted share service, and no telemetry.
• No font switching. The terminal owns the font.
• No speed tests on a loop inside the monitor. Repeated speed tests already exist as --count and --loop, and they are a different thing.
• No decoration without meaning. Density is welcome; noise is not.

Open questions

Which scale the verdict uses

Not decided. Each candidate below may have a place, and choosing between them needs more research and real user feedback.

• Per-activity verdicts. For example, Video calls: great · Gaming: poor · Streaming: great, judged from latency, jitter and latency under load against published guidance for each activity, as LibreQoS does. It answers "will my call stutter?" directly. The thresholds come from several sources that would each need citing, and it gives no single badge to share.
• A letter grade, A+ to F. Waveform's bufferbloat scale, based on how much latency rises under load: A+ for under 5 ms extra, F for 400 ms or more. It is widely recognised and easy to share. It grades only one thing, so a connection with high jitter can still score well.
• Responsiveness (RPM). The measure behind Apple's networkQuality, now an IETF draft: round trips per minute under load, labelled Low, Medium or High. It is the most rigorous and standards-backed option, but "RPM" means little to most people without explanation, and the labels are coarse.
• A letter grade with per-activity verdicts beneath it. One headline grade to share, with verdicts by activity to explain it. It has two scales to source and keep consistent, and needs more room on the result card.

Backlog

This list is in priority order. Items carry an E prefix so they do not clash with the numbers in the Consolidated Backlog. Where an item extends one there, the Related column names it. Each item is sized to become one issue. Sizes are estimates: S, M or L.

No.	Feature	Outcome	Related	Size
E1	Quick wins	A successful run no longer ends with the "Try 'netpace --help'" hint, and a server with no sponsor name gets a meaningful label instead of "(Unknown)".		S
E2	Theme-ready foundation	Every colour and glyph in the default output comes from one named set, including good, warning and bad, with defined fallbacks for no colour, plain glyphs and narrow windows. The look does not change yet.		S to M
E3	Live speed readout	While download and upload run, a speed figure beside each progress bar updates live and settles on exactly the speed the result reports. The bar stays. Raised as #409.		S
E4	Live speed graph	While download and upload run, the user also sees throughput as a graph, so ramp-up and stalls are visible. Builds on E3.	Parked Ramp-up visualiser	M
E5	Latency under load in the speed test	Latency and jitter are measured during the transfer and plotted in the live view beside throughput.	26, 24	M
E6	Verdict research	The verdict scale is chosen from the candidates under Open questions, with its thresholds sourced and cited. A research spike, not code.		S
E7	Feel verdict	The speed test ends with a verdict on how the connection will feel, using the scale chosen in E6.		M
E8	Result card	The final result is one compact, screenshot-worthy card that is private by default.		M
E9	netpace monitor	A new command shows latency, jitter and the machine's own traffic live on one timeline, probing gently, backing off when a server asks, and accepting a named or self-hosted server.		L
E10	Monitor pace control	The user picks how aggressively the monitor probes, with a profile option, an on-screen hint that pacing can be changed, and a keyboard shortcut that changes it live.		M
E11	Monitor outside a terminal	Piped or scripted, the monitor streams one machine-readable record per probe until stopped.		S to M
E12	Themes	Desert, autumn, Halloween and Christmas themes change colours, glyphs and the banner font. Seasonal themes switch on only if the user opts in.		M
E13	README demo	The README opens with an animated demo of the speed test and the monitor, generated from a script in the repository so it can be regenerated.	7	S
E14	LibreSpeed provider	Both the speed test and the monitor can run against a self-hosted LibreSpeed server.	27	L

Later

These are worth doing once the items above have shipped:

• History across runs. A sparkline of recent results, or "your best evening result this week".
• A lane per connection. The speed test's parallel connections drawn separately, so a stalled one stands out.
• Result trustworthiness. How far the result can be trusted: server distance, number of samples, and the spread between connections.
• Multi-server comparison. Several servers measured and drawn side by side.