# PKI Client — Command Reference

## Global Options

All commands support these flags:

| Flag | Description |
|------|-------------|
| `--format text\|json\|compact\|forensic` | Output format (default: text) |
| `--fips` | FIPS 140-3 mode — restricts to approved algorithms |
| `--color auto\|always\|never` | Color output control |
| `-q, --quiet` | Suppress non-essential output |
| `-v, --verbose` | Verbose output |

---

## show

Auto-detect and display any PKI file (cert, key, CSR, CRL, PKCS#7, PKCS#12).

```bash
pki show server.pem                # Auto-detect file type
pki show server.pem --lint         # Run security linting
pki show server.pem -a             # Full analysis (details + lint + revocation)
pki show server.pem -I             # Interactive menu mode
pki show server.pem --format forensic  # Deep-dive with hex dumps
```

## cert

Certificate operations.

```bash
pki cert show server.pem           # Show certificate details
pki cert expires server.pem        # Check expiration
pki cert expires *.pem --within 30d  # Find certs expiring within 30 days
pki cert fingerprint server.pem    # SHA-256 fingerprint
```

## key

Private key operations.

```bash
pki key gen ec --curve p384 -o server.key    # Generate EC P-384 key
pki key gen ec --curve p256 -o server.key    # Generate EC P-256 key
pki key gen rsa --bits 4096 -o server.key    # Generate RSA-4096 key
pki key show server.key                       # Inspect key
pki key match server.key server.crt           # Verify key matches cert
```

## csr

Certificate Signing Request operations.

```bash
pki csr create --key server.key --cn "example.com" --san "dns:example.com" -o server.csr
pki csr show server.csr
```

## chain

Certificate chain operations.

```bash
pki chain build server.pem         # Build chain from AIA
pki chain show chain.pem           # Display chain as tree
pki chain verify chain.pem         # Verify chain integrity
```

## crl

Certificate Revocation List operations.

```bash
pki crl show myca.crl              # Display CRL details
pki crl show myca.crl --all        # List all revoked certs
pki crl check myca.crl 01AB        # Check if serial is revoked
```

## revoke

Revocation status checking.

```bash
pki revoke check server.pem        # Check OCSP + CRL status
pki revoke crl-show myca.crl       # Show CRL contents
```

## diff

Compare two certificates or CSRs.

```bash
pki diff old.pem new.pem           # Side-by-side comparison
pki diff old.pem new.pem --only-diff  # Show only differences
```

## convert

Format conversion (PEM ↔ DER ↔ Base64).

```bash
pki convert cert.pem --to der -o cert.der    # PEM to DER
pki convert cert.der --to pem -o cert.pem    # DER to PEM
pki convert cert.pem --to base64             # PEM to Base64
pki convert key.der --to pem --from key      # DER key (needs --from)
```

**Note:** `convert` changes encoding format only. It does NOT convert algorithms (e.g., RSA to PQC). For algorithm migration, use `key gen` → `csr create` → `pki build`.

## probe

TLS server inspection.

```bash
pki probe server google.com:443    # Full TLS probe with security grade
pki probe check google.com:443     # Quick connectivity check
pki probe lint server.pem          # Lint certificate against best practices
pki probe fetch google.com:443     # Fetch server certificate chain
```

## pki (hierarchy)

Declarative PKI hierarchy builder.

```bash
pki pki preview hierarchy.toml     # Preview hierarchy tree
pki pki build hierarchy.toml       # Build all CAs from TOML
pki pki build hierarchy.toml --force  # Overwrite existing output
```

### TOML configuration example

```toml
[hierarchy]
name = "My PKI"
output_dir = "./pki-output"

[hierarchy.defaults]
organization = "My Org"
country = "US"

[[ca]]
id = "root"
type = "root"
algorithm = "ecdsa-p384"
common_name = "My Root CA"
validity_years = 20
path_length = 1

[[ca]]
id = "issuing"
type = "intermediate"
parent = "root"
algorithm = "ecdsa-p384"
common_name = "My Issuing CA"
validity_years = 5
path_length = 0
```

### Supported algorithms

| Algorithm | TOML value | Type |
|-----------|------------|------|
| ECDSA P-256 | `ecdsa-p256` | Classical |
| ECDSA P-384 | `ecdsa-p384` | Classical |
| RSA 3072 | `rsa-3072` | Classical |
| RSA 4096 | `rsa-4096` | Classical |
| ML-DSA-44 | `ml-dsa-44` | Post-Quantum (NIST Level 2) |
| ML-DSA-65 | `ml-dsa-65` | Post-Quantum (NIST Level 3) |
| ML-DSA-87 | `ml-dsa-87` | Post-Quantum (NIST Level 5) |
| ML-DSA-44 + ECDSA P-256 | `ml-dsa-44-ecdsa-p256` | Hybrid |
| ML-DSA-65 + ECDSA P-384 | `ml-dsa-65-ecdsa-p384` | Hybrid |
| ML-DSA-87 + ECDSA P-384 | `ml-dsa-87-ecdsa-p384` | Hybrid |

## compliance

FIPS 140-3, NIST SP 800-57, and Federal Bridge compliance validation.

```bash
pki compliance levels                          # Show all compliance levels
pki compliance check --level 2 --algo ecdsa-p384  # Check against Level 2
pki compliance cps --level 2                   # Generate CP/CPS skeleton
pki compliance bridge --level 3 --dns .example.com  # FPKI bridge profile
```

## dane

DANE/TLSA record generation (RFC 6698).

```bash
pki dane generate -c server.pem               # Generate TLSA record
pki dane generate -c ca.pem --usage dane-ta    # CA TLSA record
pki dane verify -c server.pem --rdata '3 1 1 ab..'  # Verify against TLSA
```

## acme

ACME client (Let's Encrypt compatible). **Status: Beta**

```bash
pki acme directory                             # Fetch ACME directory
pki acme register --email admin@example.com    # Register account
pki acme certonly example.com                  # Request certificate
pki acme renew example.com                     # Renew certificate
pki acme status example.com                    # Check certificate status
```

## est

EST client (RFC 7030). **Status: Beta**

```bash
pki est cacerts https://est.example.com        # Get CA certificates
pki est enroll https://est.example.com -c req.csr  # Enroll with CSR
pki est csrattrs https://est.example.com       # Get CSR requirements
```

## scep

SCEP client (RFC 8894). **Status: Beta**

```bash
pki scep cacaps https://scep.example.com/scep  # Get CA capabilities
pki scep cacert https://scep.example.com/scep  # Get CA certificate
pki scep enroll https://scep.example.com -s "CN=myhost"  # Enroll
```

## batch

Run commands from a script file.

```bash
pki batch commands.txt
```

Script format (one command per line, `#` for comments):
```
# My batch script
key gen ec --curve p384 -o server.key
csr create --key server.key --cn "example.com" -o server.csr
show server.csr
```

## shell

Interactive REPL with tab completion and history.

```bash
pki shell    # or just: pki
```

## completions

Generate shell completions.

```bash
pki completions bash > /etc/bash_completion.d/pki
pki completions zsh > ~/.zsh/completions/_pki
pki completions fish > ~/.config/fish/completions/pki.fish
```

## manpages

Generate man pages.

```bash
pki manpages /usr/local/share/man/man1/
```