A practical website diagnostic workflow
Website not loading? Separate DNS, TLS and HTTP before changing anything.
Run one QZX command to correlate name resolution, certificate validity and the response from a specific HTTPS URL. diagnoseWebsite identifies the layer to inspect first while preserving the underlying DNS, TLS and HTTP evidence for deeper debugging.
Created and maintained by Alejandro Sánchez · QZX — Quick Zap Exchange
Run the complete workflowInstall QZX
diagnoseWebsite and its underlying probes are available in the published Alpha 0.2.2.0.15. Use standard Python >=3.11 and verify the installed version before running them. No account or API key is required.
python -m pip install --upgrade qzx
qzx version --jsonNeed pipx or help with your Python environment? Choose an installation path.
Run the complete workflow
Start with the single diagnosis command below, or prepare it for your own hostname and safe, read-only HTTPS path. It runs bounded DNS, trusted TLS and HTTP checks, correlates their evidence and returns the most likely layer to inspect first. The three underlying probes remain available when you want to inspect one layer independently.
Prepare a diagnosis for your website
For example: example.com or https://status.example.com:8443/health. HTTPS is assumed for a bare domain. Use a hostname and a simple path without credentials, query parameters or fragments.
Your destination stays in this page: it is not sent to QZX or saved. Preparing the command does not contact your website; you run it in your own terminal.
qzx diagnoseWebsite https://example.com --jsonNeed the three underlying probes?
diagnoseWebsite already runs these layers and keeps their raw results. Run them separately when you need to isolate one layer, compare observations or tune the HTTP timeout independently.
qzx checkDns example.com --json
qzx checkSslCertificate example.com 443 --json
qzx checkUrlStatus https://example.com 10 --jsonNeed help or want to share how it went?
The diagnosis performs network probes against DNS resolvers and the remote server. It is read-only: it does not change DNS, replace certificates or edit server configuration. It rejects embedded credentials, query strings and fragments before probing; still choose a safe path that does not trigger a server-side action, and review returned data before sharing a report.
1. Does the name resolve?
Read records.A, records.AAAA, record_status and errors. A missing AAAA or MX record alone does not prove a website outage. query_failed means the query was inconclusive; dns_name_not_found is a different result. Partial answers can coexist with success: true.
2. Is the certificate valid here?
Check is_valid, chain_trusted, hostname_match and days_remaining. An inspected but invalid certificate can return success: true and is_valid: false. Check the local clock and trust store as well as the remote certificate; never disable validation to turn a failed check green.
3. What does this URL return?
Read is_online, status_code, status_detail and response_time_ms. The command follows ordinary redirects and reports the resulting response, not a full redirect trace. It does not render JavaScript or log in to the application.
A completed check is not a healthy website
success and the process exit code describe execution of the diagnostic, not website health. Start with overall_status, primary_issue_layer and probe_status, then verify that conclusion against the underlying DNS, TLS and HTTP evidence. In particular, a received HTTP 404 can still exist inside a completed diagnosis with success: true and is_online: false while the HTTP layer needs attention.
Recorded, not invented
Excerpt captured from the published QZX 0.2.2.0.8 wheel on standard CPython 3.13.13, Windows x64. A temporary local HTTP endpoint intentionally returned 404. This is a controlled fixture, not an outage of example.com or QZX.
{
"success": true,
"is_online": false,
"status_code": 404
}- DNS name not found or every query failed
- Check spelling, local resolver/network access and authoritative DNS. Do not change hosting based only on a failed lookup.
- Certificate inspected, but is_valid is false
- Read the trust, hostname and date fields. Resolve the reported cause before relying on this TLS connection.
- HTTP 401 or 403
- A server or intermediary replied. Check access rules and authentication; this is not proof that the server is offline.
- HTTP 404
- Check the exact path, routing and deployment. The endpoint replied, but did not provide the requested resource.
- HTTP 5xx, or no status_code
- For 5xx, inspect application/proxy logs you control. With no HTTP response, separate DNS, connection, TLS and timeout evidence in status_detail.
- HTTP 2xx/3xx and a valid certificate
- This probe reached a responding endpoint. Check the real user journey separately; a login page, cached page or broken JavaScript can still return 200.
Give an agent an incident briefing, not permission to improvise
Using this QZXdiagnoseWebsiteresult, verifyprimary_issue_layeragainstfindingsand the rawdns,tlsandhttpevidence. Distinguish an unhealthy target from a partial or failed probe, cite actual fields, separate facts from assumptions, and propose one next check. Do not change DNS, certificates, firewall rules or deployments. Do not claim the application works merely because HTTP returned 200.
Prefer terminal text? Remove --json. For structured evidence, keep it: one result contains the correlated diagnosis plus the raw results from all completed probes. Use related_commands when you want to rerun a layer independently.
Keep the evidence in scope
Results describe this machine and this moment. A CDN or proxy can answer while the origin is unavailable; a firewall may treat this CLI differently from a browser. This workflow is not continuous monitoring, a browser test, a load test or a security audit. Repeat a bounded check from an authorized second network when the location matters.
Did this workflow help you?
After trying it in your terminal, tell Alejandro what happened—or go straight to help. No account or explanation is needed for the optional response.
Optional: your selected category is sent with the existing website analytics session. We do not read your terminal, project, destination or clipboard. This is your assessment, not an automatic check. How this response is used
Keep the workflow for your next project. QZX is free; optional support helps Alejandro maintain its commands, guides and tests.
Support QZX developmentChoose pip for a Python environment you control, or pipx for an isolated CLI. The guide explains managed environments and checking your first result.
Choose an installation pathRun qzx version --json and check the exact command in the installed help. Keep a reproducible error and the relevant versions before requesting help; do not share secrets.
Find the command referenceA completed diagnostic is not the same as a healthy target. Read the command-specific fields and limitations; the guide separates observed facts from assumptions.
Review the result fieldsFound a reproducible problem? Open the existing bug report form, review its fields and decide what to share. Reports are public and require GitHub sign-in.
Report a workflow problem to Alejandro