Postman Client Diagnostics

CLI tool that verifies network connectivity to all required Postman domains. Tests DNS resolution, TCP connectivity (port 443), HTTPS reachability, and WebSocket upgrade handshakes.

Built for IT and network administrators who need to validate firewall rules before deploying Postman.

Download

Grab the latest artifact for your platform from GitHub Releases:

| Platform | Artifact | |----------|----------| | macOS (Apple Silicon) | postman-client-diagnostics-darwin-arm64.zip (contains .app) | | Linux (x64) | postman-client-diagnostics-linux-x64 | | Windows (x64) | postman-client-diagnostics-win32-x64.exe |

These are standalone executables — no Node.js installation required. Intel Mac users can run via npx (see below).

Signing status: Binaries are not yet code-signed. Before distributing to external users, the release pipeline needs proper signing:

• macOS — Apple Developer ID certificate + notarization via notarytool
• Windows — Authenticode code-signing certificate
• Linux — GPG-sign the binary and publish the .sig alongside it

Internal users can follow the per-platform steps below to run the unsigned builds.

Running on macOS

1. Download postman-client-diagnostics-darwin-arm64.zip from GitHub Releases
2. Double-click the .zip to extract (Safari does this automatically)
3. (Workaround since binary is not signed) Using your Terminal, run the below commands
4. A Terminal window opens and runs the diagnostics automatically

cd ~/Downloads
xattr -dr com.apple.quarantine "Postman Client Diagnostics.app"
open "Postman Client Diagnostics.app"

Running on Windows

1. Download postman-client-diagnostics-win32-x64.exe from GitHub Releases
2. Windows SmartScreen may show "Windows protected your PC" — click More info, then Run anyway
3. Alternatively, run from PowerShell or Command Prompt:

.\postman-client-diagnostics-win32-x64.exe

If your organization uses AppLocker or WDAC policies that block unsigned executables, use the npx method instead.

Running on Linux

1. Download postman-client-diagnostics-linux-x64 from GitHub Releases
2. Make it executable and run:

chmod +x postman-client-diagnostics-linux-x64
./postman-client-diagnostics-linux-x64

Alternative: npm

If you already have Node.js 18+, no binary download is needed:

npx @postman/client-diagnostics

This works on all platforms including Intel Macs and avoids code-signing issues entirely.

Usage

postman-client-diagnostics [options]

Options:
  --json            Output results as JSON (for scripting or support tickets)
  --group <name>    Only test a specific group
                    Aliases: core, auth, vscode, web-ws, desktop-ws, desktop-http
  --timeout <ms>    Override per-check timeout (default: 3000-5000ms)
  --no-color        Disable colored output
  -h, --help        Show help

Exit codes

| Code | Meaning | |------|---------| | 0 | All critical domains reachable (warnings are informational and don't affect exit code) | | 1 | One or more critical domains unreachable | | 2 | Only non-critical domains unreachable |

Example output

Table (default)

Postman Client Diagnostics
darwin arm64 · Node v20.11.1 · 2026-03-10T15:27:51.767Z

  Authentication & Core Services
  ✓ Cloudflare Challenges (Sign-in)  dns 16ms  tcp 19ms  https 59ms 405
  ✓ Authentication Service           dns 20ms  tcp 31ms  https 171ms 302
  ✓ API Service                      dns 30ms  tcp 22ms  https 154ms 301
  ✗ Web App                          dns 52ms  tcp FAIL  --
    ⚠ TCP connection refused on port 443 [CRITICAL]

  VS Code Extension
  ✓ VS Code Extension HTTP           dns 24ms  tcp 103ms  https 493ms 404
  ✓ VS Code Extension WebSocket      dns 0ms   tcp 109ms  https 525ms 404  wss 1484ms 502
    ℹ Server responded HTTP 502 to upgrade request — network path is open

  Web App v10+ — WebSocket
  ✓ Web Premium (.com)               dns 72ms  tcp 14ms  https 469ms 404  wss 1408ms 502
    ℹ Server responded HTTP 502 to upgrade request — network path is open
  ~ Web Premium (.co)                dns 52ms  tcp 19ms  https 508ms 404  wss WARN
    ⚠ WSS upgrade timed out — server may not respond to anonymous upgrades

  ✗ 25/26 reachable — 1 critical failure(s), 1 warning(s)

  Blocked domains (copy for IT ticket):
    web.postman.co

JSON (--json)

postman-client-diagnostics --json > report.json

{
  "timestamp": "2026-03-10T15:21:56.690Z",
  "node": "v20.11.1",
  "platform": "darwin arm64",
  "results": [
    {
      "name": "Cloudflare Challenges (Sign-in)",
      "hostname": "challenges.cloudflare.com",
      "group": "Authentication & Core Services",
      "critical": true,
      "proto": "https",
      "checks": {
        "dns": { "status": "pass", "ms": 16, "ips": ["104.18.95.41"] },
        "tcp": { "status": "pass", "ms": 19 },
        "https": { "status": "pass", "ms": 59, "statusCode": 405 },
        "wss": { "status": "skip" }
      },
      "overall": "pass"
    }
  ],
  "summary": { "total": 26, "passed": 24, "warned": 1, "failed": 1, "criticalFailed": 1 }
}

What each check proves

| Check | What it tests | How | |-------|--------------|-----| | DNS | Hostname resolves to an IP address | dns.resolve4() — fails if DNS is blocked or the domain doesn't exist | | TCP | Port 443 is reachable | net.connect() on port 443 — fails if a firewall drops or rejects the connection | | HTTPS | TLS handshake succeeds and server responds | https.request() HEAD — reports the actual HTTP status code (200, 301, 403, etc.) | | WSS | Network path allows WebSocket traffic | Attempts wss:// upgrade via the ws library. Pass if the connection opens OR the server responds with an HTTP status code (e.g. 502 — the upgrade was rejected, but the request reached the server). Warn on timeout when HTTPS already passed (network path is proven open, server may just ignore anonymous upgrades). Fail only on connection reset or when HTTPS also failed. |

Checks run in order: DNS → TCP → HTTPS → WSS. If an earlier check fails, later checks are skipped (no point testing HTTPS if DNS failed).

Interpreting WSS results

Postman's bifrost servers reject WebSocket upgrade requests from unauthenticated clients with HTTP 502. This is expected — the tool is not a real Postman client. What matters is whether the network allows the request to reach the server at all.

| WSS result | What it means | |-----------|---------------| | wss 52ms (no HTTP status) | Full WebSocket connection opened. Rare with anonymous clients. | | wss 1484ms 502 | Server responded HTTP 502 to the upgrade. Network path is open. The 502 is the server rejecting an anonymous client, not a network issue. | | wss WARN (timeout) | No response to the upgrade request, but HTTPS already passed for this host. The network path is proven open. The server may simply not respond to anonymous WebSocket upgrades (common on several bifrost .co hosts). Does not affect the exit code. | | wss FAIL (connection reset) | Connection was forcibly closed during the upgrade, often by a firewall or proxy sending TCP RST. |

Caveat: If the network uses a TLS-intercepting proxy, the HTTP response may come from the proxy rather than the Postman server. The tool can confirm that something on the network path responded, but cannot distinguish the origin server from an intercepting proxy.

Domains tested

26 domains across 5 groups, covering all versions of Postman:

• Authentication & Core Services — challenges.cloudflare.com, identity.getpostman.com, api.getpostman.com, web.postman.co, desktop.postman.com, go.pstmn.io
• VS Code Extension — bifrost-extension-https-global.gw.postman.com, bifrost-extension-global.gw.postman.com
• Web App v10+ (WebSocket) — 9 bifrost-web-* domains
• Desktop App v10+ (WebSocket) — 5 bifrost-*-global domains
• Desktop App v10+ (HTTP) — 4 bifrost-*-https-* domains

Full list based on Postman's firewall documentation.

Known limitations

• TLS-intercepting proxies: If the network uses a proxy that terminates TLS (common in enterprise environments), all HTTPS and WSS checks will pass against the proxy, not the actual Postman server. If Postman still fails after all checks pass, ask the IT team whether a TLS inspection proxy is in use.
• WSS false negatives are unlikely but possible: A timeout on the WSS check is labeled as a potential firewall block. In rare cases, it could be caused by network congestion or server-side issues rather than a firewall. If HTTPS passes but WSS times out consistently, WebSocket-specific blocking is the most likely cause.
• Server-side outages: The HTTPS check reports the actual HTTP status code. A 503 or 502 from the server itself (not during a WSS upgrade) could indicate a Postman service outage rather than a network issue. Check Postman's status page if many HTTPS checks return 5xx.
• IPv6: DNS checks use dns.resolve4() (IPv4 only). If the network is IPv6-only, DNS checks may fail even if the domain is resolvable via AAAA records.

Building from source

git clone https://github.com/postmanlabs/postman-connectivity-cli.git
cd postman-connectivity-cli
yarn install
yarn build
node dist/bin/postman-client-diagnostics.js

Building a standalone binary

bash sea/build.sh
./dist/bin-sea/postman-client-diagnostics-*

Requires Node.js 20+ (for Single Executable Applications support).

License

MIT