certdoctorDocumentation
Everything the command line and the window do, and how to read what they tell you.
certdoctor is two programs over one diagnosis. certdoctor is the command line: you give it the URL that fails, and it prints a report in the terminal or writes one for a ticket or a pipeline. certdoctor-gui is a window that runs the same command line and shows the same report, for anyone who would rather type an address into a box.
A run walks the path a connection takes - the environment, name resolution, the proxy, TCP, TLS - and then asks every trust store it finds on the machine whether it trusts the chain the server presented. The report opens with one sentence naming the cause, and every store that refuses carries the command that would fix it.
If you came here with an error message, the error pages start from the message. If you know which program refuses, the fix guides start from the program.
Getting started
Download certdoctor, run it against the URL that fails, and read the sentence that names the cause. Then try it on a deliberately broken site.
Reading a report
What each part of a certdoctor report means: the verdict sentence, the exit code, the six layers, the trust matrix rows and the commands they carry.
The six layers
The six layers of a certdoctor run: environment variables, DNS from every resolver, proxy and PAC, TCP to every address, the TLS chain and the trust matrix.
The trust matrix
certdoctor asks every trust store on the machine - Windows store, Linux bundle, each JDK, git, curl, node, Python and pip - and prints the fix for each.
Proxy and PAC script
How certdoctor finds which proxy a URL really goes through: environment variables, Windows Internet and WinHTTP settings, the PAC script, and 407 checks.
Reports and formats
Write a certdoctor report as Markdown for a ticket, one self-contained HTML page or JSON, mask host names with --redact, and turn saved JSON into a page later.
Using it in CI
Check that a build agent can reach a registry or an API: certdoctor exit codes, JSON validated against its schema, and a report kept as an artifact.
Inside a container
Copy the static Linux binary into a container and run it there: the report then describes the container's DNS, proxy and trust stores, not the host's.
The window
certdoctor-gui shows the same report in a window on Windows, Linux and macOS: type the address, press Diagnose, read the report and save it.
Command line
Every switch of the certdoctor command line: the URL, --pac-url, --from, --format, --json, --out, --redact, --quiet, --verbose, timeouts and more.
Exit codes
The exit codes of certdoctor: 0 OK, 4 a failure was found, 5 something could not be assessed, and the codes for usage, configuration, output and interruption.
Verify a download
Check a certdoctor archive against the release's SHA-256 list, and prove where it came from with the signed bill of materials GitHub attests.