qualys-cli 0.1.1

Command-line interface for the Qualys REST APIs (VM, PC, PM, ETM, WAS, TC, CA, CS, CSAM, Sub, Asset, User).

qualys-cli

A unified command-line interface for the Qualys REST APIs — covering VM, PC, Patch Management, ETM, WAS, TotalCloud (TC), Cloud Agent (CA), Container Security (CS), CSAM, Subscription, Asset, and User management. Rich table output, JSON / YAML / JSONL export, automatic retry with backoff, JWT auto- refresh, OS-keyring credential storage, and a clean machine-readable mode for scripting and AI agents.

  ╭─────────────────────────────────────────────────╮
  │  qualys-cli   ·   273 endpoints, one CLI        │
  │  vm · pc · pm · etm · was · tc · ca · cs        │
  │  csam · sub · asset · user · scanauth           │
  ╰─────────────────────────────────────────────────╯

Install

# End user (recommended)
pipx install qualys-cli

# Or from source
pipx install git+https://github.com/qualys/qualys-cli

# Development
git clone https://github.com/qualys/qualys-cli && cd qualys-cli
uv sync
uv run qualys-cli --help

Python 3.11+ required. Works on macOS, Linux, and Windows.

Quick start

# 1. Configure credentials (interactive — password stored in OS keyring)
qualys-cli configure

# 2. Run any command
qualys-cli vm host list --limit 10
qualys-cli was webapp list
qualys-cli pm job list --format json

Non-interactive setup (CI / Docker)

qualys-cli configure \
  --url https://qualysapi.qualys.com \
  --username "$QUALYS_USERNAME" \
  --password "$QUALYS_PASSWORD" \
  --output-mode agentic

Credentials resolve in this priority order:

1. QUALYS_URL / QUALYS_USERNAME / QUALYS_PASSWORD / QUALYS_TOKEN env vars
2. OS keyring (per-profile entry)
3. ~/.config/qualys-cli/config.toml

Multiple profiles via --profile <name> or QUALYS_PROFILE. List with qualys-cli profiles.

Output modes

The CLI has two top-level modes that govern the default output style:

Mode	Default output	Spinners / colours	Use case
interactive	Rich table (first 25 rows)	Yes	Humans in a terminal
agentic	JSON, no decoration	No	Scripts, pipelines, AI agents

Switch the persistent default for a profile:

qualys-cli mode                # show current
qualys-cli mode agentic        # set agentic
qualys-cli mode interactive    # set interactive

Or set per-shell with export QUALYS_OUTPUT_MODE=agentic.

Per-command output flags

These work on every command and override the mode default:

Flag	Behaviour
--format json	Full JSON to stdout
--format jsonl	One flattened JSON object per line (JSON Lines / NDJSON)
--format yaml	YAML to stdout
--format table	Rich table (forced)
--limit 0	Remove the default 25-row cap
--output-file results.json	Dump full data to file (extension picks JSON or YAML)
-v, -vv	Log requests (and response sizes); secrets never logged

Examples by module

VM (Vulnerability Management)

qualys-cli vm host list --ips 10.0.0.0/24
qualys-cli vm host detection --ips 10.0.0.0/24
qualys-cli vm scan launch --title "Weekly" --ip 10.0.1.0/24 --option-id 12345
qualys-cli vm scan fetch SCAN-REF-123 --output-file results.json

Patch Management (PM)

qualys-cli pm job list --format json
qualys-cli pm job create --name "Critical patches" \
  --patch-ids "12345,67890" --asset-group-ids "AG-1"
qualys-cli pm patch list --severity Critical

Web Application Scanning (WAS)

qualys-cli was webapp list --name "prod"
qualys-cli was webapp get 12345
qualys-cli was scan launch --webapp-id 12345 --name "Nightly WAS"
qualys-cli was finding list --webapp-id 12345 --severity 5
qualys-cli was report download 99999 --output-file was-report.pdf

TotalCloud (TC) — CSPM

qualys-cli tc connector list --provider AWS
qualys-cli tc evaluation list --provider AWS --account-id 123456789012
qualys-cli tc rule list --cloud-type AWS --rule-type simple_alert
qualys-cli tc exception list

Cloud Agent (CA), Container Security (CS), CSAM

qualys-cli ca agent list --status Active
qualys-cli ca actkey create --title "Linux Prod" --modules VM,PC

qualys-cli cs image list --filter "vulns.severity5Count:>0"
qualys-cli cs image get <sha>
qualys-cli cs container list --severity Critical

qualys-cli csam asset list --updated-after 2026-01-01T00:00Z
qualys-cli csam vuln list-easm --filter "vulnerability.cvss=GREATER=7"

Subscription, Asset, User

qualys-cli sub info
qualys-cli sub export --output-file sub-backup.xml
qualys-cli asset ip add --ips 10.0.0.0/24 --tracking-method IP
qualys-cli user create --username jdoe --first-name Jane --last-name Doe \
  --email [e-mail] --user-role scanner

Tip: append --help to any command (e.g. qualys-cli was scan launch --help) for the full flag set.

Documentation

A comprehensive usage reference with all 273 endpoints is included in the package:

• Source install: docs/usage.html in the repository
• Pip install: Located in your Python environment's share/qualys-cli/docs/usage.html

To find it after installation:

python -c "import sys; print(sys.prefix + '/share/qualys-cli/docs/usage.html')"

LLM / agent usage

The CLI is built to be safe to drive from a script or an AI agent:

# JSON output (set agentic mode persistently, or use --format json per call)
qualys-cli mode agentic
qualys-cli vm host list | jq '.HOST_LIST_OUTPUT.RESPONSE.HOST_LIST'

# JSON Lines — one record per line, ideal for streaming
qualys-cli pm job list --format jsonl | jq -r '.id'

# Errors emitted as JSON on stderr when stderr is not a TTY
qualys-cli --profile nonexistent vm host list 2>/tmp/err.json
# {"error": "No username for profile 'nonexistent'...", "type": "configuration_error"}

Behaviour contract for agents:

• stdout contains only data (JSON / JSONL / YAML / table text).
• stderr carries status, spinners, and human-readable errors. All decoration is suppressed when stderr is not a TTY.
• Exit code 0 = success, 1 = any error.
• When stderr is not a TTY, errors are emitted as {"error": "...", "type": "..."} JSON.

Authentication

Module group	Auth	Endpoint family
VM, PC, Asset, User, ScanAuth, Sub, WAS	HTTP Basic	/api/2.0/fo/, /qps/rest/
TC, PM, ETM, CS, CSAM	JWT Bearer	API gateway (/csapi/, /etm/)
CA agent ops	HTTP Basic	/qps/rest/
CA activation-key / config	JWT Bearer	/caui/v1/

JWT tokens are fetched via POST /auth, cached in config.toml, and auto-refreshed on 401.

Development

uv sync
uv run pytest                # tests
uv run ruff check src/       # lint
uv run mypy src/             # type check
uv run qualys-cli --help     # smoke
uv build                     # build sdist + wheel into dist/

Regenerating commands from Qualys docs

The codegen pipeline is opt-in via the codegen extra (it pulls in anthropic, trafilatura, selectolax, pypdf):

uv sync --extra codegen
export ANTHROPIC_API_KEY=sk-ant-...
uv run scripts/ingest_docs.py        # cache HTML pages
uv run scripts/extract_endpoints.py  # LLM extraction → api-model.json
uv run scripts/generate_commands.py  # regenerate commands/*.py

Generated files are marked with # Auto-generated from api-model.json and are safe to overwrite. Files without that header are treated as hand-edited and left alone.

Releasing

Releases are published to PyPI by GitHub Actions on a tag push:

# Bump version in pyproject.toml, update CHANGELOG.md, commit
git tag v0.1.1 && git push --tags

PyPI publishing uses Trusted Publishing (OIDC) — no API token is stored. Configure once at https://pypi.org/manage/project/qualys-cli/settings/publishing/.

License

MIT