Skip to content

CLI reference

gapcert ships two binaries: gapcert (standalone, agent, and courier) and gapcertd (the broker).

gapcert

$ gapcert
gapcert — certificates for airgapped and egress-restricted systems

Usage:
  gapcert issue  [-config FILE] [-force] [NAME ...]   obtain certificates now
  gapcert renew  [-config FILE] [-force] [NAME ...]   renew certificates that are due
  gapcert status [-config FILE]                       show stored certificates and expiry
  gapcert agent   <enroll|obtain|renew|status> ...    broker-backed mode
  gapcert courier <init|pair|export|run|import> ...   offline zero-egress mode
  gapcert version                                     print version
  • issue obtains every configured certificate now. Names limit it to a subset.
  • renew re-issues only certificates inside their renewal window (rotating the key), unless -force. Run it from cron / a systemd timer.
  • status prints the stored certificates and their expiry; exits non-zero if any is missing or expired.

gapcert agent

Broker-backed mode — the host has no DNS/ACME credentials of its own.

gapcert agent enroll -broker URL -token TOKEN -ca-fingerprint SHA256 [-config FILE]
gapcert agent obtain [-config FILE] [-force] [NAME ...]
gapcert agent renew  [-config FILE] [-force] [NAME ...]
gapcert agent status [-config FILE]

-ca-fingerprint is mandatory: enrollment pins the broker's CA fingerprint and fails closed without it. Config defaults to $GAPCERT_AGENT_CONFIG or ~/.config/gapcert/agent.yaml.

gapcert courier

Offline mode — see the courier walkthrough.

gapcert courier init    [-data-dir DIR]              create this side's signing identity
gapcert courier pubkey  [-data-dir DIR]              print this side's public key
gapcert courier pair    -peer HEX [-data-dir DIR]    pin the peer's public key
gapcert courier export  -config inside.yaml  -out request.bundle
gapcert courier run     -config outside.yaml -in request.bundle -out response.bundle
gapcert courier import  -config inside.yaml  -in response.bundle

gapcertd

The broker — see the broker walkthrough.

$ gapcertd
gapcertd — gapcert broker

Usage:
  gapcertd init   -config FILE            create the internal CA (one-time)
  gapcertd serve  -config FILE            run the broker
  gapcertd token  -config FILE -agent N   mint a one-time enrollment token
  gapcertd status -config FILE            fleet view of issued certificates
  gapcertd version                        print version

Exit codes

0 on success; 1 on a runtime failure (a certificate failed to issue, config error, an expired/missing certificate in status); 2 on a usage error (unknown command, missing required flag).