homepki

A simple PKI management tool for local development. Create and manage three-tier certificate authorities, intermediate CAs, and TLS certificates with a single CLI.

📖 Documentation · bcollard.github.io/homepki

Install

brew tap bcollard/homepki
brew install --cask homepki

Quick Start

# Create root CA
homepki root-ca --domain runlocal.dev

# Create intermediate CA
homepki intermediate-ca --domain runlocal.dev --name bu1

# Create server certificate
homepki server-cert --domain runlocal.dev --intermediate bu1 --server kong-gateway

# Create client certificate
homepki client-cert --domain runlocal.dev --intermediate bu1 --client my-client

# Trust the root CA in the system, Firefox and Java trust stores (macOS, Linux)
homepki trust install --domain runlocal.dev

Certificates and keys are stored in ~/.homepki by default. homepki is a single Go binary with no runtime dependency: keys, signing and chain verification use Go's crypto/x509, so openssl does not need to be installed.

Configuration

Override the default storage location using:

• The --workdir flag:

  homepki root-ca --domain runlocal.dev --workdir /path/to/pki
  

• The HOMEPKI_WORKDIR environment variable:

  export HOMEPKI_WORKDIR=/path/to/pki
  homepki root-ca --domain runlocal.dev
  

Agent Skill (AI coding tools)

homepki ships an Agent Skill that teaches AI coding tools how to drive homepki — issuing TLS and mTLS material for scripts, demos, and tests. Install it once and every future agent session knows how to use homepki without you explaining it each time:

homepki skill install          # → ~/.claude/skills/homepki/SKILL.md
homepki skill install --force  # overwrite an existing copy (e.g. after upgrading homepki)
homepki skill path             # print the install path
homepki skill install --print  # emit the skill to stdout (pipe it anywhere)

The skill is embedded in the binary, so no download is needed. Start a new agent session after installing to pick it up.

Overview

homepki implements a three-tier PKI structure:

• Root CA: The top-level certificate authority
• Intermediate CA: Organization/tenant-specific intermediate certificate authorities
• End-entity certificates: Server and client certificates for services

Build from Source

go build -o homepki

Project Structure

.
├── main.go                         # Entry point
├── skill.go                        # Embeds SKILL.md into the binary
├── SKILL.md                        # Agent Skill definition (single source of truth)
├── go.mod
├── cmd/
│   ├── root.go                     # CLI setup, --workdir flag
│   ├── root_ca.go                  # root-ca command (generate + list)
│   ├── intermediate_ca.go          # intermediate-ca command (generate + list)
│   ├── server_cert.go              # server-cert command (generate + list)
│   ├── client_cert.go              # client-cert command (generate + list)
│   ├── sign.go                     # sign command (external CSRs)
│   ├── trust.go                    # trust install/uninstall/status (system, NSS, Java)
│   ├── revoke.go                   # revoke + crl commands
│   ├── leaf.go                     # shared server/client leaf issuance
│   ├── paths.go                    # shared flags, CA file locations, helpers
│   └── skill.go                    # skill install + path
└── pkg/
    └── pki/
        ├── pki.go                  # file helpers, chain verification, SAN parsing
        ├── certs.go                # certificate issuance (crypto/x509)
        ├── keys.go                 # --key-type → key generation, PEM key I/O
        ├── constraints.go          # --name-constraint parsing
        ├── csr.go                  # CSR loading and subject policy checks
        ├── crl.go                  # CRL signing, loading, revocation reasons
        ├── pkcs12.go               # PKCS#12 bundles
        └── trust.go                # trust store detection and commands

Usage Guide

1. Creating a Root CA

homepki root-ca --domain runlocal.dev

# List root CAs (table, default)
homepki root-ca list

# List as JSON
homepki root-ca list -o json

This creates:

• Root CA directory structure
• Root CA private key and self-signed certificate

2. Creating an Intermediate CA

homepki intermediate-ca --domain runlocal.dev --name bu1

# List intermediate CAs (table, default)
homepki intermediate-ca list --domain runlocal.dev

# List as JSON
homepki intermediate-ca list --domain runlocal.dev -o json

This creates:

• Intermediate CA private key and certificate signed by the root CA
• Certificate chain file ({name}-intermediate-ca-chain.crt)

3. Creating Server Certificates

homepki server-cert --domain runlocal.dev --intermediate bu1 --server kong-gateway

# List server certificates (table, default)
homepki server-cert list --domain runlocal.dev --intermediate bu1

# List as JSON
homepki server-cert list --domain runlocal.dev --intermediate bu1 -o json

4. Creating Client Certificates

homepki client-cert --domain runlocal.dev --intermediate bu1 --client my-service

# List client certificates (table, default)
homepki client-cert list --domain runlocal.dev --intermediate bu1

# List as JSON
homepki client-cert list --domain runlocal.dev --intermediate bu1 -o json

5. Signing an External CSR

Sign a request generated elsewhere — the private key never reaches homepki:

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗