nkapp certs

Read-only TLS (Transport Layer Security) certificate inspection — CLI parity for the Hub Certificates view. The CLI, the bridge and the Hub all go through the same code path (gateway Caddy storage read + a live :443 probe), so they can never disagree.

nkapp certs <subcommand> [options]

Subcommands

certs list

List the environment's TLS certificates: the gateway's Caddy certificate storage (a single read-only docker exec that globs *.crt files only) merged with a live :443 probe of the environment's configured public hosts.

Usage:

nkapp certs list [-e <env>] [--json]

Output: columns HOST · STATUS · EXPIRES · SOURCE · ISSUER, plus a ⚠ warning line per certificate when one exists. The header always carries the honest storage verdict — storage: readable (n stored chain(s)) or storage: not readable — <reason> — so a cloud environment without readable storage shows live-probe data only instead of failing.

An empty list exits 0 with an explainer: local/docker environments have no public certificates, and remote environments need a running gateway plus public host: entries in nanokit.yml.

certs show <host>

Show one host's full certificate record.

Usage:

nkapp certs show <host> [-e <env>] [--json]

Fields: status (+ days remaining), valid from/until, subject, issuer (+ kind public/internal/unknown), SAN (Subject Alternative Name), serial, SHA-256 fingerprint, storage path, source, last-checked time — and, under --json, the public chain itself as PEM (Privacy-Enhanced Mail).

An unknown host prints a hint ("only PUBLIC hosts appear here; check nanokit.yml host: entries") and exits 1 in both output shapes.

Flags

Flag	Type	Default	Description
-e, --env <env>	string	the config's activeEnv, falling back to local	Environment to inspect.
--json	boolean	off	Machine-readable JSON on stdout (the banner is suppressed so stdout stays pipeable).

Examples:

nkapp certs list -e production
nkapp certs list -e production --json | jq '.certs[] | {host,status,daysRemaining}'
nkapp certs show app.example.com -e production
nkapp certs show app.example.com --json

Status vocabulary

Status	Meaning
valid	Present, public and not expiring.
expiring-soon	Expires in ≤ 7 days.
expired	Past its expiry date.
not-yet-issued	Public host but no cert yet (ACME — Automatic Certificate Management Environment — never completed).
missing	Nothing presented on :443.
unreachable	The probe could not connect.
not-managed	TLS is terminated outside a Nanokit gateway (gcp, digitalocean, cloudflare, azure) — printed with the mandated copy "TLS non gestito da Nanokit per questo provider". No renewal is promised for these providers.

What this command deliberately does NOT do

• No certs renew. Renewal is Hub-only: the Hub's Renew action sends a CERT_ACTION {renew} over the local bridge, which recycles the environment's gateway so Caddy re-issues the certificates (environment-wide, with an explicit confirmation). No per-host re-issue, no revoke, and no write path to the gateway storage exist in v1.
• The private key never leaves the gateway. The storage dump globs *.crt only — .key files are never read — and both the CLI footer and the Hub dialog state "Public chain only — the private key never leaves the gateway".

See specs/CERTIFICATES.md in the repository for the full design (decisions D1–D7).