Home › Docs › CLI reference

CLI reference

Every command and flag, as homepki <command> --help prints them in v0.8.0.

Commands

Global flags

The working directory is resolved in this order: --workdir, then the HOMEPKI_WORKDIR environment variable, then ~/.homepki. In a script that runs several commands, exporting HOMEPKI_WORKDIR once is shorter than repeating the flag.

Errors and exit codes

• A successful command exits 0. Any failure exits 1.
• An unknown flag, or a value a typed flag cannot parse, prints the error followed by the command's usage.
• Every other error prints on its own, without usage: a missing required flag, existing material without --force, a missing tier, a name-constraint violation, a failed sudo.
• Generate commands print what they do and each file written on stdout. Errors go to stderr. In scripts, rely on the exit code and check results with list -o json.

root-ca

Generate a self-signed Root CA for a domain. The certificate and key go to <workdir>/<domain-with-dashes>/ca/. The root may sign intermediates only (pathlen:1).

$ homepki root-ca -d runlocal.dev
$ homepki root-ca -d klimax.internal --key-type ecdsa --validity 3650d \
    --name-constraint "permitted;DNS:.klimax.internal"

See Name constraints and Server and client certificates for key types and validity.

intermediate-ca

Generate an Intermediate CA signed by the domain's Root CA. It writes the certificate, the key and <name>-intermediate-ca-chain.crt (intermediate followed by root). An intermediate may sign leaves only (pathlen:0).

$ homepki intermediate-ca -d runlocal.dev -n bu1
$ homepki intermediate-ca -d klimax.internal -n bu1 \
    --name-constraint "permitted;DNS:.bu1.klimax.internal"

server-cert

Generate a key and a serverAuth certificate under an Intermediate CA, in <intermediate>/server-tls/. The common name is <server>.<intermediate>.<domain>, which is also the first SAN. The certificate is verified against its chain before anything is written.

$ homepki server-cert -d runlocal.dev -i bu1 -s kong-gateway \
    --san kong.local --san 192.168.1.10 --san 'DNS:*.kong.local'
$ homepki server-cert -d runlocal.dev -i bu1 -s kong-gateway --validity 24h --pkcs12 --force

client-cert

Generate a key and a clientAuth certificate under an Intermediate CA, in <intermediate>/client-tls/. Same naming and checks as server-cert.

$ homepki client-cert -d runlocal.dev -i bu1 -c my-client \
    --san URI:spiffe://runlocal.dev/ns/default/sa/my-client
$ homepki client-cert -d runlocal.dev -i bu1 -c my-client --pkcs12

list subcommands

Every tier has a list subcommand, with aliases ls and l. It reports expiry, days left and a verified chain of trust. Leaf lists also report revocation.

$ homepki server-cert ls -d runlocal.dev -i bu1 -o json \
    | jq -e 'all(.[]; .chain_valid)' >/dev/null || echo "broken chain"

The JSON format is described in Listing and verification.

sign

Sign a PEM certificate signing request with an Intermediate CA. Only the subject (C, ST, L, O, OU, CN) and the SANs are taken from the request. Basic constraints and key usages are set by homepki, so a request cannot ask to become a CA. The subject must carry O= the root's literal name and OU= the intermediate name.

$ homepki sign -d runlocal.dev -i bu1 --csr my-service.csr
$ homepki sign -d runlocal.dev -i bu1 --csr my-client.csr --type client --name my-client --out ./my-client.crt

See Signing external CSRs.

revoke

Add a leaf's serial number to the Intermediate CA's CRL, then re-sign the intermediate CRL, the root CRL and the CRL chain file. Pass exactly one of --server, --client or --cert. Revoking a certificate that is already revoked prints a message and exits 0.

$ homepki revoke -d runlocal.dev -i bu1 -c my-client --reason keyCompromise
$ homepki revoke -d runlocal.dev -i bu1 --cert ./my-service.crt

crl

Write or re-sign the CRLs of an Intermediate CA and its Root CA, keeping every revocation already recorded. Use it before anything is revoked, since a server configured with a CRL file refuses to start without one, and to push nextUpdate forward before the CRLs go stale.

$ homepki crl -d runlocal.dev -i bu1
$ homepki crl -d runlocal.dev -i bu1 --validity 7d

See Revocation for the files written.

trust

Manage the trust stores that accept a Root CA. --store takes system, nss and java, repeated or comma-separated. Without it, every store available on the host is used; a store named explicitly must be available.

trust install

Add the Root CA to each selected store. A store that already trusts it is skipped. The system store, and a Java cacerts file you cannot write, are changed under sudo.

trust uninstall

Remove the Root CA from each selected store. Stores that do not hold it are skipped. Same flags as install.

trust status

Report which stores accept the Root CA. Alias st. Needs no privileges and never prompts.

$ homepki trust install -d runlocal.dev --store nss,java
$ homepki trust status -d runlocal.dev -o json | jq '.[0].trusted'

See Trusting the root CA for each store and the JSON fields.

skill

Install the Agent Skill compiled into the binary. See Agent Skill.

skill install

skill path

Print where the skill is installed for Claude Code: ~/.claude/skills/homepki/SKILL.md. No flags.

$ homepki skill install
$ homepki skill install --print > ./SKILL.md

version

Print the version, commit and build date. Alias v; homepki --version prints the same.

$ homepki version