Postman Client Diagnostics

CLI tool that diagnoses common issues with the Postman desktop client. Runs checks across multiple diagnostic suites:

• Network — DNS resolution, TCP connectivity (port 443), HTTPS reachability, and WebSocket upgrade handshakes to all required Postman domains
• Terminal — Local shell detection, process spawning, and PTY (pseudo-terminal) allocation health

Built for IT administrators, support engineers, and enterprise customers who need to diagnose connectivity and local environment issues.

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)
  --suite <names>   Comma-separated list of suites to run (default: all)
                    Available: network, terminal
  --group <name>    Only test a specific group (network suite only)
                    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

Examples

# Run all diagnostic suites
postman-client-diagnostics

# Run only network checks
postman-client-diagnostics --suite network

# Run only terminal/PTY checks
postman-client-diagnostics --suite terminal

# Run specific suites with JSON output
postman-client-diagnostics --suite network,terminal --json

# Test only desktop WebSocket domains
postman-client-diagnostics --suite network --group desktop-ws

# Pipe JSON output to a file for a support ticket
postman-client-diagnostics --json > diagnostics.json

Exit codes

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

Diagnostic suites

Network suite

Tests connectivity to 26 Postman domains across 5 groups. Checks run in order per domain: DNS → TCP → HTTPS → WSS. If an earlier check fails, later checks are skipped.

| 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). Warn on timeout when HTTPS already passed. Fail only on connection reset or when HTTPS also 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. |

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.

Terminal suite

Tests whether the local environment can run a shell and allocate a pseudo-terminal (PTY). This suite diagnoses the "initializing terminal..." freeze in the Postman desktop app, which is typically caused by EDR (Endpoint Detection & Response) software or IT policies blocking PTY allocation.

| Check | What it tests | How | |-------|--------------|-----| | Shell detection | Default shell binary exists and is executable | Reads $SHELL (Unix) or %COMSPEC% (Windows), verifies the binary with fs.access | | Shell spawn | A child process can be spawned from the shell | child_process.execFile(shell, ['-c', 'echo ok']) with timeout — fails if EDR blocks basic process spawning | | PTY spawn | A pseudo-terminal can be allocated | Uses a layered strategy (see below) — fails if EDR blocks PTY allocation specifically |

PTY spawn strategy

The PTY check uses three strategies in priority order:

1. node-pty (dynamic import) — If node-pty is installed in the environment, the check uses it to spawn a PTY with the same parameters Postman Terminal uses (xterm-color, 80x30, home cwd, full env). This is the highest-fidelity check because it exercises the exact same native code path. node-pty is not bundled with this tool to avoid false positives from native module installation issues (see ADR-001).

2. script command (macOS/Linux) — Falls back to the OS script utility, which allocates a real kernel PTY without requiring any native modules. This covers most enterprise environments.

3. Skip (Windows without node-pty) — On Windows there is no OS-level PTY equivalent. The check reports skip with a message explaining how to install node-pty for a full PTY test.

Interpreting terminal results

| Result pattern | Likely cause | |---------------|-------------| | All three pass | Terminal environment is healthy | | Shell detection fails | $SHELL / %COMSPEC% not set or binary missing | | Shell spawn fails, detection passed | EDR blocking basic process spawning from this binary | | PTY spawn fails, shell spawn passed | EDR blocking PTY allocation specifically — this is the most common cause of the "initializing terminal..." freeze | | PTY spawn skipped | node-pty not installed and no OS-level fallback (Windows). For a definitive PTY test, install node-pty: npm install node-pty |

JSON output

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

Results are organized by suite:

{
  "timestamp": "2026-05-11T12:00:00.000Z",
  "node": "v20.11.1",
  "platform": "darwin arm64",
  "suites": {
    "network": {
      "results": [
        {
          "name": "Cloudflare Challenges (Sign-in)",
          "group": "Authentication & Core Services",
          "status": "pass",
          "critical": true,
          "ms": 94,
          "detail": {
            "hostname": "challenges.cloudflare.com",
            "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" }
            }
          }
        }
      ],
      "summary": { "total": 26, "passed": 26, "warned": 0, "failed": 0, "criticalFailed": 0 }
    },
    "terminal": {
      "results": [
        { "name": "Shell detection", "group": "Terminal", "status": "pass", "critical": true, "ms": 0, "detail": { "shell": "/bin/zsh" } },
        { "name": "Shell spawn", "group": "Terminal", "status": "pass", "critical": true, "ms": 6 },
        { "name": "PTY spawn", "group": "Terminal", "status": "pass", "critical": true, "ms": 12, "detail": { "method": "script", "shell": "/bin/zsh" } }
      ],
      "summary": { "total": 3, "passed": 3, "warned": 0, "failed": 0, "criticalFailed": 0 }
    }
  },
  "summary": { "total": 29, "passed": 29, "warned": 0, "failed": 0, "criticalFailed": 0 }
}

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.
• PTY check on Windows: Without node-pty installed, the PTY spawn check is skipped on Windows because there is no OS-level PTY allocation command. Install node-pty (npm install node-pty) alongside the tool for a definitive PTY test on Windows.
• node-pty not bundled: The tool does not ship node-pty as a dependency to avoid false positives. The native addon's spawn-helper binary can lose execute permissions during npm install, causing PTY spawn failures that are npm artifacts, not EDR blocks. If node-pty is already installed in the environment (e.g. from a development setup), the tool will use it automatically via dynamic import.

Building from source

git clone https://github.com/postmanlabs/postman-connectivity-cli.git
cd postman-connectivity-cli
npm install
npm run 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