Getting Started

Getting Started

This page gets you from nothing to a diagnosis you can act on. It deliberately does not list every flag; netdoc --help and the man page do that, and they are generated from and tested against the real command.

1. Install

Pick your platform from the README's install section. The exact package names, taps, buckets, and repository URLs live there because they change with releases.

The short version:

• Windows: Scoop (from the project bucket).
• macOS: Homebrew.
• Linux: A COPR repo on Fedora, or a downloadable .deb/.rpm/.apk.
• Anywhere with Go: go install, or build from a clone.

Two things worth knowing before you install:

• The project is called network-doctor; the installed command is netdoc.
• Every Linux package installs a second command, netdoc-sim, at the same version. That is the simulator, not part of diagnosing your network. macOS and Windows downloads ship netdoc alone; see Simulator Overview.

Confirm what you have:

netdoc --version

Releases carry signed build attestations. If you care about verifying the bytes you downloaded, the README's Verify your download section has the gh attestation verify invocation.

2. Run it

There are two useful first commands, and they answer different questions.

netdoc

No target. Checks the things that are true of your machine regardless of where you are going: is an interface up, can you reach the internet directly, does the environment proxy work, does DNS resolve, does encrypted DNS work, what Wi-Fi network are you on. This is the "is it me?" run.

netdoc github.com

With a target. Everything above, plus the path to that specific host: DNS for that name, a TCP connect, a TLS handshake, an HTTP response, and a path-MTU check. This is the "is it them?" run.

The target can be a hostname, a hostname with a port, an IP literal, or a URL. The port and the scheme independently decide which protocol rows appear: netdoc host:22 gets you SSH banner checks rather than TLS. netdoc --help prints the full target grammar.

3. Read the screen

You get a list of rows. Each row is one probe, and each lands in one of five states:

State	Meaning
✓ PASS	It worked.
! WARN	It worked but is impaired: high latency, one address family failing, an ambiguous source interface. Warn is never a failure and never changes the exit code.
✗ FAIL	It did not work.
⊘ SKIP	A prerequisite failed, so this was never attempted.
– N/A	Does not apply here, for example DNS against an IP literal.

Below the rows is a one-line summary in English and, in machine-readable runs, a verdict. The verdict is the part worth learning: Understanding Your Diagnosis walks through each one and what to do about it.

Select a failed row to see its evidence (what was actually observed) and a fix hint (what to try). Press ? at any time for the full key cheatsheet; it is generated from the live keymap, so it is never out of date.

Prefer Vim navigation? netdoc --keys vim adds gg/G, ctrl+b/ctrl+f, and ctrl+u/ctrl+d on top of the existing keys.

4. Get proof, not just a verdict

A diagnosis row is evidence. When you want to see the real thing, Network Doctor runs the actual tools for you as cancellable, streaming jobs: several at once, with tab switching between them. The hotkeys map to whatever each OS ships: ping, dig/nslookup, curl, traceroute/tracert, mtr/pathping, ss/netstat, ip route/route print, and nmap.

The exact per-OS command each key runs is in the README's Drill-down tools table. Three things about them are worth internalising:

• Output is bounded and sanitised, so a hostile server cannot inject terminal escapes into your terminal through a banner.
• The two active probes, the nmap port scan and the LAN map, are gated behind an explicit confirmation before they send anything.
• Nothing escalates privilege, and commands are built as argument slices, never as shell strings.

netdoc --toolbox [host] opens straight into the toolbox without running the diagnosis first, for when you already know what you want to look at.

5. The three workflows worth knowing

The intermittent failure

netdoc --watch host

Re-runs continuously, five seconds apart. The TUI keeps a strip of the last 20 states per check plus a failure count, so a check that fails one pass in twenty is visible, which is exactly the failure you cannot catch by staring at a single run.

The bug report, or the script

netdoc --json host

Runs headless and prints one JSON document. Field names, the status vocabulary (PASS/WARN/FAIL/SKIP/N/A), and the verdict vocabulary are stable and safe to script against. failed_stage names the first check that failed, which is usually enough to route a bug report without reading any prose.

Combined with --watch it streams one compact JSON object per line (NDJSON) with an added timestamp, until interrupted:

netdoc --json --watch host | jq -c 'select(.ok | not) | {ts, failed_stage, summary}'

The full JSON schema, including every optional per-check field, is in the README's JSON output section.

Before you paste a report anywhere, read it. Reports and tool output can contain hostnames, internal IP addresses, usernames, and interface names.

The narrowed run

netdoc --check dns,target_tcp,tls example.com
netdoc --skip internet_tcp,quic_udp_443 example.com

--check limits the run to those probe IDs plus everything they depend on. --skip removes probes and anything that then has no prerequisite. Useful when a probe is slow on your network, or when a strict egress policy means you do not want a particular endpoint contacted at all.

The probe IDs are stable. An unknown one is rejected before any diagnostics start, and the error message lists every valid ID, which is the fastest way to see the current set.

Exit codes

netdoc is designed to be used in a shell conditional:

netdoc github.com || echo "path to github is broken"

The exact code table is in the README's Exit codes section. The rule of thumb: 0 means nothing failed (warnings and skips are fine), 1 means something failed, 2 means you gave it bad arguments.

Where next

• Understanding Your Diagnosis: the verdict, and what to do about it.
• How Network Doctor Works: why the probes are laid out the way they are.
• Troubleshooting and FAQ: rows that surprise people.