pdq-cli is a command-line interface tool designed to interact with PDQ products, enabling users to query and manage devices, groups, packages, and deployments via the PDQ Connect API. It also provides access to device details, vulnerabilities, applications, and scan surfaces through the PDQ Detect API.
Key Features:
Device Management: Query and manage devices across PDQ Connect and Detect, including filtering by OS, group, or custom fields.
Package Deployment: Create and deploy packages to specific devices or groups, streamlining software distribution.
Vulnerability Scanning: Identify and assess vulnerabilities across devices, applications, and scan surfaces for enhanced security.
API Integration: Leverage the PDQ Connect and Detect APIs to automate workflows and integrate with existing systems.
Customizable Output: View results in table, JSON, or CSV format, allowing seamless integration into reporting and analysis pipelines.
Audience & Benefit:
Ideal for IT administrators, system engineers, and security professionals managing multiple devices. pdq-cli provides a powerful toolset to streamline endpoint management, vulnerability scanning, and deployment workflows, ensuring efficient and secure operations.
pdq-cli can be installed via winget, offering a seamless setup process for users on supported platforms.
README
Unofficial — not affiliated with or endorsed by PDQ.com
pdq-cli
A command-line interface for PDQ products, written in TypeScript.
Note — macOS Gatekeeper: The binary is not notarized (Apple notarization requires a paid Developer account). macOS will block it on first run with "cannot be opened because the developer cannot be verified".
To allow it, remove the quarantine attribute:
xattr -d com.apple.quarantine pdq-macos-arm64 # or pdq-macos-x64
You only need to do this once, before moving the binary to your PATH. Alternatively, open System Settings → Privacy & Security, scroll down to the blocked app notice, and click Allow Anyway.
Windows install steps
Download pdq-windows-x64.exe, rename to pdq.exe, and move to a directory on your PATH (e.g. C:\tools\). Windows SmartScreen may show a warning on first run — click More info → Run anyway. Windows ARM devices can run the x64 binary via emulation.
Run from source
Requires Node.js 22+.
git clone https://github.com/bogdan-calapod/pdq-cli
cd pdq-cli
npm install
npm run build
node dist/index.js --help
# or link globally:
npm link
Authentication
PDQ Connect
PDQ Connect uses Bearer token auth. Provide your API key via env var (takes priority) or save it to the config file:
The base URL defaults to https://detect.pdq.com. Override it if needed:
export PDQ_DETECT_URL=https://your-instance.example.com
# or persist it:
pdq detect config set-url https://your-instance.example.com
# or pass it inline:
pdq detect --url https://your-instance.example.com devices list
If your API key has access to multiple tenants, specify the tenant ID to scope requests:
export PDQ_DETECT_TENANT_ID=12345
# or persist it:
pdq detect config set-tenant 12345
# or pass it inline:
pdq detect --tenant 12345 devices list
Commands
All list/get commands support --output table|json|csv (default: table).
pdq connect
pdq connect devices
# List all devices (table output by default)
pdq connect devices list
# Filter by OS, group, or any device field
pdq connect devices list --filter os=windows
pdq connect devices list --filter name=~LAB --group grp_abc123
# Sort
pdq connect devices list --sort lastSeenAtDesc
# Output as JSON or CSV
pdq connect devices list --output json
pdq connect devices list --output csv > devices.csv
# Get a single device
pdq connect devices get dvc_abc123
pdq connect groups
pdq connect groups list
pdq connect groups list --filter type=dynamic --output json
pdq connect packages
pdq connect packages list
pdq connect packages list --filter name=~Firefox
pdq connect packages get pkg_abc123
pdq connect deployments
# Deploy a package to a device and/or group
pdq connect deployments create \
--package pkg_abc123 \
--targets dvc_abc123,grp_xyz456
pdq detect
pdq detect devices
# List all discovered devices
pdq detect devices list
# Filter
pdq detect devices list --os Windows --risk critical
pdq detect devices list --status active --scan-type agent
pdq detect devices list --tags "server,production"
# Sort
pdq detect devices list --sort riskLevel --sort-dir descending
# Get a single device (numeric ID)
pdq detect devices get 42
pdq detect devices get 42 os
pdq detect devices get 42 users
pdq detect devices get 42 vulnerabilities --state open
pdq detect vulnerabilities (alias: vulns)
pdq detect vulnerabilities list
pdq detect vulns list --open-only
pdq detect vulns list --filter Log4j --filter-col summary
pdq detect vulns list --sort cvssBase --sort-dir descending --output json
pdq detect applications (alias: apps)
pdq detect applications list
pdq detect apps list --risk critical
pdq detect apps list --filter Firefox --sort deviceCount --sort-dir descending
pdq detect apps get 123
pdq detect scan-surface
# List scan targets
pdq detect scan-surface list
# Add IPs, hostnames, or CIDR ranges (triggers a scan immediately)
pdq detect scan-surface add 192.168.1.0/24
pdq detect scan-surface add host1.corp.local host2.corp.local --no-scan
# Trigger a full rescan
pdq detect scan-surface rescan
# Remove entries
pdq detect scan-surface delete 7 8 --delete-assets
pdq get-skill
Prints a SKILL.md file that tells AI coding assistants how to use this CLI.
# Print to stdout
pdq get-skill
# Write directly to the OpenCode skills directory
pdq get-skill --out .opencode/skills/pdq-cli/SKILL.md
Contributing
See DEVELOPMENT.md for build instructions, project structure, and release process.
License
MIT
Built with the assistance of AI (Claude by Anthropic).