Using the CLI

Documentation for the image tag 1.0.0-rc1.1. See Versions for the documentation of a release.

Using the CLI (qca)

Not distributed yet. qca is not inside the container images, and it is not downloadable until the first public release ships it. This page describes how it behaves so you can plan scripts and runbooks; until then use the Web UI or the REST API for the same operations.

qca is the command line client for Qertum. It talks to the REST API, so it needs the same permissions as the matching web page, and everything it does is audited like a web action.

Pointing it at your CA

qca needs the API address and, to sign in, the identity provider address. Either pass them on each command or set environment variables:

Option	Environment variable	Example
-a, --api-url	QERTUM_API_URL	http://qertum.example.org:8082
-i, --identity-url	QERTUM_IDENTITY_URL	http://qertum.example.org:8081
-t, --token	QERTUM_TOKEN	A bearer token; bypasses the saved session
-o, --output		table (default) or json

Use --output json in scripts. Errors print the reason and, when the server sent one, a correlation id: line; quote it when you report a problem.

Signing in

qca auth login      # prints a code and a URL; open it in any browser and approve
qca auth status     # who you are and when the session expires
qca auth logout     # revokes the refresh token and clears the saved session

login uses the OAuth device authorization flow, so it works over SSH and on machines without a browser. The session is saved in your user profile and refreshed automatically. For unattended jobs, pass a token with --token or QERTUM_TOKEN instead; see Using the REST API.

If your organisation requires stronger authentication for sensitive operations (key download, issuer changes, bulk revoke, policy publish), the command refuses and prints the exact qca auth login line to run with the required options.

Everyday tasks

# ask whether policy would accept a request, without creating anything
qca requests create --common-name www.example.com --san www.example.com --type WebServer --dry-run

# create it; it waits as Pending until someone approves
qca requests create -n www.example.com --san www.example.com -T WebServer -k ECDSA-P256

# approve, and wait until it is issued
qca requests approve <id> --wait

# download the certificate (PEM, CRT, CER, P7B or PFX)
qca cert download-cert <id> -F pem -f www.example.com.pem

# renew, history, listing
qca cert renew <id>
qca cert history <id>
qca cert list --status issued
qca cert inventory

Exit codes are meaningful in scripts. For example requests create --dry-run exits 0 when the request would be accepted and 2 when policy would reject it; requests approve --wait exits 0 when everything was issued, 1 on a rejection or failed call, and 3 on timeout while still in progress. Every command's --help lists its Needs (permissions), Exit codes and an Example.

Command groups

Group	Purpose
requests	List, create, approve and deny certificate requests
cert	Inventory, list, download certificate or key, renew, history, metadata and notes
ca	CA certificate info, CRL and delta CRL, who may approve CA-capable requests
issuers	List and inspect issuers, create intermediates, rollover, trust bundle
root	Offline root CA: create it, sign intermediate request files and its CRL, with no server
bulk	Preview and run bulk revoke or renew
policies	Issuance policies: draft, publish, archive
pqc	Post-quantum enforcement stage and exceptions (admin)
acme	ACME external account bindings and order diagnostics
est	EST enrollment credentials
webhooks	Webhook subscriptions and allowed destinations
notices	Expiry and stalled-renewal notices
approvals	Two-person approval of sensitive operations
permissions	Role permissions; permissions me shows your own
audit	Audit log, chain checkpoint, and offline verification of copied log files
doctor	Read-only check that the CA can be reached, trusted and used from this machine

Run qca <group> --help for the commands in a group.

Bulk operations

qca bulk revoke and qca bulk renew only preview by default: they print how many certificates match and the exact qca bulk execute <id> --confirm-count N line to run. Nothing changes until you run it, and the count must match what the preview showed.

First checks

qca doctor is the quickest way to see why something does not work from a given machine. It checks, in order, that the API and identity provider are reachable, your session, the issuers, whether this machine trusts the root, enrollment, CRL freshness and the server's own attention report. It exits 0 when clean, 2 with warnings only, and 1 on a failure.

See also

• Using the Web UI
• Using the REST API
• Troubleshooting