How to Use macOS networkQuality Command to Generate JSON Diagnostic Reports for Wi-Fi Capacity

When troubleshooting intermittent wireless connectivity issues on a fleet of enterprise MacBooks, administrators often rely on external speed test websites. However, these browser-based tests are highly subjective, heavily influenced by browser extensions, caching, and local network congestion. They also provide zero actionable data regarding the actual capacity of the local Wi-Fi link itself. For a definitive, objective measurement of network performance built directly into the operating system, Apple provides the command-line networkQuality utility.

Introduced in macOS Monterey, the networkQuality tool executes a rigorous, concurrent upload and download test against Apple’s own global Content Delivery Network (CDN) edge servers. More importantly for system administrators, it can generate its diagnostic output in structured JSON format, making it perfectly suited for ingestion into monitoring dashboards, automated IT ticketing systems, or Mobile Device Management (MDM) extension scripts.

Executing a Basic Network Quality Test

To initiate a standard test, open the macOS Terminal application and simply execute the command without any arguments:

networkQuality

The utility will run for approximately 15 seconds, simultaneously testing upload and download speeds. This concurrent testing is crucial because it accurately reflects real-world usage—such as a user participating in a video conference while synchronising files to cloud storage. The output will display the upload capacity, download capacity, and the Responsiveness (measured in RPM, or Round-trips Per Minute), which is Apple’s metric for measuring network latency under load.

Generating Structured JSON Output

While the standard human-readable output is useful for a quick check, it is useless for automated diagnostics. To force the utility to output the results as a structured JSON object, append the -c (computer-readable) flag.

networkQuality -c

This command suppresses the progress indicators and outputs a single JSON block upon completion. The JSON payload contains granular details that are not visible in the standard output, including the exact interface being tested (e.g., en0 for Wi-Fi), the protocol used (IPv4 or IPv6), and precise byte counts.

Testing Specific Network Interfaces

In complex environments, a Mac might be connected to multiple networks simultaneously (for example, a wired Ethernet connection to a corporate LAN and a Wi-Fi connection to a guest network). By default, networkQuality tests the primary default route. If you specifically need to diagnose the Wi-Fi capacity, you must force the tool to bind to the wireless interface using the -I flag.

networkQuality -I en0 -c

You can identify the correct interface identifier for the Wi-Fi adapter by running the networksetup -listallhardwareports command.

Automating Wi-Fi Diagnostics with jq

Because the output is standard JSON, you can easily pipe the results into command-line JSON processors like jq (if installed via Homebrew) or Python to extract specific metrics for alerting scripts.

For example, you could write a bash script that runs as a launch daemon, executes the test every few hours, and extracts only the download capacity (measured in Mbps). If that capacity drops below a predefined threshold, the script could trigger an alert to the IT helpdesk.

#!/bin/bash
# Extract the download capacity in Mbps using Python's built-in JSON module
DOWNLOAD_CAPACITY=$(networkQuality -c | python3 -c "import sys, json; print(json.load(sys.stdin)['dl_throughput'])")

echo "Current Download Capacity: $DOWNLOAD_CAPACITY Mbps"

By leveraging the native networkQuality command and its JSON output capabilities, Mac administrators can build highly reliable, automated network diagnostic workflows without relying on inconsistent third-party web tools or installing additional heavy monitoring agents on the endpoints.