CheckPQC CLI & SDK

The browser scanner at checkpqc.app is great for one-off checks. For CI pipelines, internal hosts, batch audits, or embedding the verdict logic into your own tools, install the CLI.

Install

One-liner (recommended)

macOS / Linux:

curl -fsSL https://checkpqc.com/install.sh | sh

Windows (PowerShell 5.1+ / PowerShell 7+):

iwr -useb https://checkpqc.com/install.ps1 | iex

Both scripts are POSIX-/PowerShell-strict, check for Node 18+, install @aegyrix/check-pqc globally via npm, and verify the result. OpenSSL 3.5+ with ML-KEM is only required for offline/local handshakes. Source: /install.sh · /install.ps1. Pin a version with CHECKPQC_VERSION=0.2.8 (sh) or $env:CHECKPQC_VERSION='0.2.8' (pwsh).

Behind a corporate proxy / blocked .ps1 downloads

Many enterprise proxies and Windows Defender ASR rules block direct .ps1 (and sometimes .sh) downloads. The same installers are also published as a universally-allowed zip:

# Windows
iwr -useb https://checkpqc.com/install.zip -OutFile install.zip
Expand-Archive .\install.zip -DestinationPath .\check-pqc-installer
.\check-pqc-installer\install.ps1
# (or: powershell -ExecutionPolicy Bypass -File .\check-pqc-installer\install.ps1)

# macOS / Linux
curl -fsSL https://checkpqc.com/install.zip -o install.zip
unzip install.zip -d check-pqc-installer
sh check-pqc-installer/install.sh

# Verify integrity
curl -fsSL https://checkpqc.com/install.zip.sha256
sha256sum install.zip   # or: shasum -a 256 install.zip

For environments where downloading any installer is restricted, prefer one of the package-manager paths below (PSGallery / winget / Docker) — those flow through allow-listed package channels in most enterprises.

npm (any OS with Node 18+)

# Org-branded (recommended)
npm install -g @aegyrix/check-pqc

# Short alias (same package)
npm install -g check-pqc

# Or run without installing
npx @aegyrix/check-pqc example.com

PowerShell module (PSGallery)

# Simplest hosted check. No Node.js, npm, local OpenSSL, or PATH changes.
iwr -useb https://checkpqc.com/test.ps1 | iex

# Manual equivalent. This also fixes stale older CheckPQC modules.
Remove-Module CheckPQC -Force -ErrorAction SilentlyContinue
Install-Module -Name CheckPQC -Scope CurrentUser -MinimumVersion 0.2.8 -Force -AllowClobber
Import-Module CheckPQC -MinimumVersion 0.2.8 -Force

Test-PQC -HostName google.com
Test-PQC -HostName api.example.com -AsJson

# Offline/private checks need the local CLI + OpenSSL 3.5+.
Install-PQCCli
Test-PQC -HostName internal.example.com -Port 8443 -Offline -AsJson
Test-PQCOffline   # local capability check

The PowerShell module uses the hosted CheckPQC API by default, so public HTTPS checks need no Node.js, npm, OpenSSL, or PATH changes. Test-PQC -Offline and Test-PQCOffline use the local CLI path for air-gapped/private checks and can install @aegyrix/check-pqc when Node 18+ is available. Recommended path for managed Windows fleets — PSGallery is allow-listed in most enterprise environments.

winget (Windows Package Manager)

winget install aegyrix.check-pqc

check-pqc google.com

The winget package declares Node.js 18+ as a dependency, so Windows Package Manager will install Node automatically if needed. Use this path when you want the local CLI instead of the PSGallery hosted-API cmdlets.

Docker (no Node required)

docker run --rm ghcr.io/aegyrix/check-pqc:latest example.com

# Pin a version for reproducible CI
docker run --rm ghcr.io/aegyrix/check-pqc:0.2.8 example.com

Multi-arch image: linux/amd64 and linux/arm64. :offline tag bundles OpenSSL 3.5+ with ML-KEM for hosts that can't reach the public internet. The image runs as a non-root checkpqc user and ships only the compiled CLI.

Verify a host

check-pqc google.com
check-pqc internal.corp.example:8443
check-pqc --json api.checkpqc.app   # machine-readable

# Local capability check (no network)
check-pqc --check-offline

Getting started

You just installed check-pqc. Here's the 3-minute orientation so you actually get value out of it instead of running it once and forgetting.

1. Confirm the install.

   check-pqc --version
   check-pqc --check-offline   # local OpenSSL + ML-KEM capability

   If --check-offline says "PQC-capable", you're set. If not, online probes still work — the offline mode is only needed for airgapped use.
2. Audit one host you actually care about.

   check-pqc your-domain.example.com

   Read the verdict. The exit code tells your shell whether the host is OK (0) or needs work (non-zero).
3. Wire it into something durable — pick one:
   • A CI gate that runs on every deploy.
   • A scheduled audit that emails on regression.
   • A library import in your own dashboard.
4. Bookmark the verdict table below so you know what each verdict means and what to do if a host fails.

Full getting-started guide on GitHub →

Verdicts

Same seven verdicts the web scanner uses, with matching exit codes:

Use as a library

import { offlineProbe, detectOpensslCapability } from '@aegyrix/check-pqc';

const result = await offlineProbe('example.com', 443);
console.log(result.verdict, result.hybrid.namedGroup);

What's under the hood

• Twin-probe handshake: one TLS 1.3 handshake offering hybrid groups (X25519MLKEM768, SecP256r1MLKEM768), a second offering only classical ECDH. The two outcomes determine the verdict.
• OpenSSL 3.5+ (or 3.2+ with oqsprovider) is required for the hybrid attempt. The CLI auto-detects.
• SSRF guard: the live scanner refuses to probe RFC1918, link-local, loopback, or cloud-metadata IPs. (Only relevant when running the API server, not the CLI.)
• Source: same engine powers checkpqc.app. CLI repo: aegyrix/checkpqc.app.

CI examples

GitHub Actions

- name: Verify production is PQC-ready
  run: npx -y @aegyrix/check-pqc app.example.com

Cron / monitoring

# /etc/cron.daily/pqc-watch
check-pqc app.example.com --json | tee -a /var/log/pqc-watch.log
test ${PIPESTATUS[0]} -eq 0 || mail -s "PQC regression" ops@example.com < /var/log/pqc-watch.log

Operate (run it day-to-day)

Scheduled audit (Linux/macOS cron)

MAILTO=ops@example.com
30 6 * * * /usr/local/bin/check-pqc api.example.com >/dev/null \
  || echo "PQC regression on api.example.com" \
     | mail -s "[checkpqc] regression" ops@example.com

Scheduled audit (Windows Task Scheduler)

$action  = New-ScheduledTaskAction -Execute 'pwsh.exe' `
  -Argument '-NoProfile -Command "if ((check-pqc api.example.com; $LASTEXITCODE) -ne 0) { Send-MailMessage -To ops@example.com -Subject ''[checkpqc] regression'' -SmtpServer smtp.example.com }"'
$trigger = New-ScheduledTaskTrigger -Daily -At 6:30am
Register-ScheduledTask -TaskName 'CheckPQC daily audit' -Action $action -Trigger $trigger -User SYSTEM

Update

npm update -g check-pqc                       # npm
docker pull ghcr.io/aegyrix/check-pqc:latest  # Docker
Update-Module CheckPQC                        # PowerShell
winget upgrade aegyrix.check-pqc              # winget

Troubleshooting

• command not found: check-pqc → npm prefix not on $PATH. Add export PATH="$(npm config get prefix)/bin:$PATH" to your shell rc.
• All hosts return UNKNOWN → outbound TLS to api.checkpqc.app blocked. Use --offline mode (needs OpenSSL 3.5+) or run via Docker.
• --check-offline says "not capable" → upgrade OpenSSL. brew upgrade openssl@3 on macOS, or use docker run ghcr.io/aegyrix/check-pqc:offline.
• EACCES during install → npm prefix not user-writable. Use sudo or a Node version manager (nvm/fnm/asdf).

Anything else: file an issue.

Uninstall

The CLI installs only the global npm package (or Docker image, or PowerShell module). It writes nothing to your home directory, registers no daemons, and creates no files outside its install path. Removal is one command.

# npm — whichever name you used
npm uninstall -g check-pqc
npm uninstall -g @aegyrix/check-pqc

# Homebrew (if applicable)
brew uninstall check-pqc

# Docker
docker rmi ghcr.io/aegyrix/check-pqc:latest
docker rmi ghcr.io/aegyrix/check-pqc:offline

# winget
winget uninstall aegyrix.check-pqc

# PowerShell module
Uninstall-Module CheckPQC -AllVersions

The only artifacts that may persist are output you redirected yourself (e.g. --json > report.txt) and any cron entries or scheduled tasks you wrote. check-pqc itself does not create them.

License

MIT-licensed; published by Aegyrix LLC. Bug reports and security issues: see security.