Skip to main content

CLI reference

Every CertAutoPilot subcommand, every flag, every exit code. The binary is the same on standalone hosts (/usr/local/bin/certautopilot) and in Kubernetes pods (run via kubectl exec). All subcommands read the same config.yaml and env vars as the main server, so run them from the same host or an equivalent one with MongoDB access.

Standalone hosts: use the cap wrapper. MongoDB credentials and KEK material live in /etc/certautopilot/secrets.env, which systemd loads into the service process — your interactive shell does not, so a naked certautopilot user list or certautopilot kek status fails with Command find requires authentication. The installer drops /usr/local/bin/cap, which sources secrets.env, re-execs itself under sudo when needed, and passes --config=/etc/certautopilot/config.yaml for you:

cap user list
cap kek status

cap-kek (the older, kek-only wrapper) still works as a shim: cap-kek status = cap kek status. The bare-binary forms below apply to Kubernetes / Docker / dev environments where the credentials are already in the process environment.

Global flags​

FlagDefaultPurpose
--config <path>(none)Config file to load. Pass it explicitly. When omitted no file is read at all — there is no search path — and the command runs on built-in defaults plus CERTAUTOPILOT_* env vars, which means localhost:27017 and provider: env. On a pkcs11 install that silently points a kek command at a different keystore than the running service. Standalone: /etc/certautopilot/config.yaml (the cap wrapper supplies it). Kubernetes: add --config=/config/config.yaml to every kubectl exec, matching the pod's own arguments.
--help, -h—Subcommand help.

serve​

certautopilot serve [--mode=api|worker|scheduler|all] [--config=...]

The main entry point. Runs the HTTP API, the job worker, and the leader-elected scheduler in the selected mode (all by default).

FlagDefaultNotes
--modeallapi, worker, scheduler, or all.

Three independent modes so you can scale each surface horizontally (e.g. many API pods, a few worker pods, exactly 2 scheduler pods for leader-election redundancy).

version​

certautopilot version

Prints the embedded build metadata (semver, commit, build date, Go version). Injected at build time via -ldflags.

kek​

KEK lifecycle management — inspect, rotate, retire, verify. Every mutation is CLI-only, deliberately: no REST route can start, cancel or undo a rotation. A read-only GET /api/v1/settings/kek-status (admin) exposes the same state to the UI.

kek status​

certautopilot kek status

Lists the keystore's versions (status, source, record count, timestamps), this process's provider and current/loaded versions, and the last rotation record. For the cluster heartbeat roster and the fleet-readiness verdict — the actual rotation pre-flight — use kek verify --target=N.

With the pkcs11 provider it also prints IV source: host or IV source: hsm: who generates the AES-GCM IV of each wrapped key, CertAutoPilot or the HSM. The process settles this when it opens the token (see use_gcm_iv_from_hsm).

The version table includes a RECORDS column: how many stored documents are stamped with each version (? when the count could not be taken). A stamp records a document's oldest envelope, so a zero there is an indicator, not a clearance — kek remove runs the full check.

When the KEK backend cannot be opened (the HSM is down, a version's key is missing), kek status still prints the keystore table and the last rotation, preceded by Registry unavailable: <reason>, and exits 0. The table then gains a KEY column: for the env provider whether the version's variable is set (present / missing); for pkcs11 what the token holds under the version's label (verified, WRONG KEY, missing, unknown, or found (…, no check value) for a row from before 1.7.3). VERSION and STATUS stay the first two columns.

kek verify​

certautopilot kek verify [--target=N] [--local]
FlagDefaultPurpose
--target0Report readiness for target version N. 0 = just list live processes.
--localfalseSkip the cluster heartbeat check; only verify the local process can round-trip wrap/unwrap.

Exit codes: 0 READY; 2 NOT READY (with a laggard list on stderr); 1 error.

The cluster table ends with an HSM column: the last periodic check of each process's KEK backend (ok with the time and, when there were any, the number of reconnects; FAILING with the time; - when no check runs — env provider, health_interval: 0, or an older release). Failing processes are listed below the table with their error. --local runs the check in the calling process: a round trip with the current key and every loaded version's key check value.

kek rotate​

certautopilot kek rotate --from-version=M --to-version=N [--batch-size=100] [--concurrency=2]
certautopilot kek rotate --cancel
FlagDefaultPurpose
--to-version—Target version (required unless --cancel).
--from-version0 (= infer from keystore)Source version — the version the DB's envelopes are currently wrapped with. When omitted, the CLI reads the keystore's active row (same source the running service uses). Pass it only when you know the keystore is mid-transition and want to be explicit.
--batch-size100Records per batch.
--concurrency2Parallel collection batches.
--cancelfalseRequest a graceful stop on the active rotation.

Returns a rotation ID immediately; the actual re-encryption runs as a leader-elected background job. Resume-safe (see failure modes).

kek remove​

certautopilot kek remove --version=N [--force]
FlagDefaultPurpose
--version—Version to retire (required).
--forcefalseSkip every CLI-side safety check: the stamped-record count, the envelope scan, the stamp-shape validation and the nested-value scan. Lab use only. The service-side fleet safety check (refuse if any live process still has the version as its current KEK) always runs — --force does not bypass it, because it addresses a different failure mode (stale instances writing new envelopes with the version being removed).

Several safety gates stack here. The stamped-record count catches leftover envelopes (a rotation that left some rows on the old version, typically because of per-batch failures). The fleet heartbeat check catches lagging nodes whose in-memory current KEK is still the version being removed; the error lists each such node so the operator knows exactly which to restart (or wait for the heartbeat-tick auto-reload to converge). Three further CLI-side checks run alongside it: an envelope scan that reads each field's own sealed version (a document stamped with an older version can still carry a newer envelope, which the count alone would miss), a stamp validation that refuses when any document's stamp is missing or claims to be newer than the material it holds, and a nested-value scan for ciphertext held inside a JSON field, which rotation cannot move forward. Combined: kek remove is safe to call immediately after a rotation completes, as long as the heartbeat window (~30 s) has passed.

kek reinstate​

certautopilot kek reinstate --version=N

Returns a version marked removed to retired, so the fleet loads it again and data still sealed under it can be swept forward. Use it when a removal turns out to have been premature. It applies only to a removed version and only while the key material still exists — if the material itself is gone, the data cannot be recovered. It checks that first and refuses otherwise: for env, the version's variable must be set on this host; for pkcs11, exactly one key must carry the version's label and open its key check value (a row from before 1.7.3 has none — then the key only has to work). It runs when the KEK backend cannot be opened, like kek status and kek remove.

kek repair-versions​

certautopilot kek repair-versions [--dry-run]

Reconciles each document's version stamp with the versions its own envelopes actually declare — stamping a document that has none, and lowering one that claims to be newer than the material it holds. It never guesses the current version. Documents whose envelopes cannot be read at all are reported for manual attention rather than altered. Run it when kek remove refuses because data is invisible to rotation, then rotate and retry.

kek pkcs11-init​

certautopilot kek pkcs11-init --version=N [--probe-only]

Provisions the HSM-backed KEK for version N. What it does depends on the version's keystore row and on the keys labelled <prefix>N in the token (table): it verifies an existing key against the row's key check value and generates nothing, refuses a row whose key is missing (wrong token), registers an existing key without a row (after proving it against data already sealed under N), and generates a key only when there is neither a row, a key nor data of the version. A removed version is reported and exits 0. Several keys under one label are refused. Every refusal is the last line printed.

FlagDefaultPurpose
--version—Version to initialise (required, except with --probe-only).
--probe-onlyfalseCheck the HSM and change nothing; needs no database. Without --version: key generation and an AES-GCM round-trip on a throwaway key. With --version=N: the existing key under N's label (round-trip and attributes). Prints who generates the IV (IV: supplied by CertAutoPilot (12 bytes) or IV: generated by the HSM (16 bytes)).

kek pkcs11-register​

certautopilot kek pkcs11-register --version=N [--config=...]

For workflows where the HSM key is created by a separate administrator (key ceremony, vendor policy), pkcs11-register attaches an existing key to the keystore. It never creates HSM material; it inserts the keystore row (with the key check value) and the install lock. It follows the same table as pkcs11-init without the key generation: the key must already exist, exactly once, as a token object (a session-only key is refused); its attributes are printed, with warnings for an extractable key or one not allowed to both encrypt and decrypt.

status​

certautopilot status

Prints database connectivity and replica-set topology: which member is PRIMARY, which are SECONDARY, and each member's response time. Exits non-zero when the replica set has no writable primary, so it can be wired into monitoring.

user​

Offline user administration — recovery commands that talk straight to MongoDB, for when nobody can log in to the panel.

user list​

certautopilot user list [--org-id=<id>] # standalone: cap user list

Lists local panel users with display name, org role, auth source, active/2FA state, and last login. Use it to find the account you need before user reset-password.

FlagDefaultPurpose
--org-id—Only list users in this org.

user reset-password​

certautopilot user reset-password --username <user> --password '<new>' \
[--org-id=<id>] [--clear-totp] [--make-local] [--enable-local-sign-in]
# standalone: cap user reset-password ...

printf '%s\n' "$NEW_PASSWORD" | \
certautopilot user reset-password --username <user> --password-stdin

Rewrites the account's bcrypt hash in MongoDB (does NOT touch MongoDB's own password). The new password must meet the panel's password policy. LDAP accounts are rejected — reset those in your directory.

FlagDefaultPurpose
--username—Account to reset (required).
--password—New password. Exactly one of --password and --password-stdin is required.
--password-stdinfalseRead the new password from the first line of standard input (only the line ending is stripped), so it never appears on the command line where other local accounts can read it from the process list.
--org-id—Disambiguate a username shared across orgs.
--clear-totpfalseAlso disable two-factor (TOTP) — e.g. a lost authenticator device.
--make-localfalseRecovery: turn an LDAP or SSO account into a local password account. Its LDAP link, SSO identity, sessions and the group memberships the directory or provider added are removed; roles stay; the account is re-activated. Sessions from before the change are refused even if removing them fails. If a step fails, the message says what was already done; running the command again finishes it. Without it an LDAP or SSO account is refused.
--enable-local-sign-infalseRecovery: turn password sign-in for local accounts back on (Settings → Sign-in).

Every reset also ends a login lockout of the account (failed-attempt counter cleared) and signs the account out everywhere: its sessions and any sign-in waiting for its 2FA code end, and a session from before the reset is refused even if removing it fails.

Exit codes​

CodeMeaning
0Success.
1Error — details on stderr.
2kek verify --target=N only: fleet NOT ready (including when no instance has heartbeated recently). No other subcommand returns 2 — every other failure, starting a rotation while one is already active included, exits 1.

Environment variables​

Every subcommand respects the same CERTAUTOPILOT_* env overrides as serve — see Environment variables. In particular, CERTAUTOPILOT_ENCRYPTION_ENV_KEK_V{N} and CERTAUTOPILOT_ENCRYPTION_PKCS11_PIN must be loaded for KEK subcommands to operate.

sudo alone does NOT load systemd's EnvironmentFile — on a standalone host use the cap wrapper, which sources /etc/certautopilot/secrets.env before invoking the binary:

cap kek status

See also​