From 157dd13c0c0bbe942e9946bc925615f99e00f9fa Mon Sep 17 00:00:00 2001
From: Luke Wilkinson <95864695+krakenhavoc@users.noreply.github.com>
Date: Sun, 3 May 2026 20:55:34 -0400
Subject: [PATCH] docs: document chain-path/fullchain-path inputs/outputs and
 cert download --format flag

---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 005c292..a66cfa8 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,9 @@ Issue, renew, or download TLS certificates from [KrakenKey](https://krakenkey.io
 | `wait` | Wait for issuance/renewal to complete | No | `true` |
 | `poll-interval` | Poll interval when waiting (Go duration, e.g., `15s`) | No | `15s` |
 | `poll-timeout` | Maximum time to wait (Go duration, e.g., `10m`) | No | `10m` |
-| `cert-path` | Path to save the certificate PEM | No | `./cert.pem` |
+| `cert-path` | Path to save the leaf certificate PEM | No | `./cert.pem` |
+| `chain-path` | Path to save the intermediate chain PEM | No | `./chain.pem` |
+| `fullchain-path` | Path to save the full chain PEM (leaf + intermediates) | No | `./fullchain.pem` |
 | `key-path` | Path to save the private key PEM (issue only) | No | `./key.pem` |
 | `csr-path` | Path to save the CSR PEM (issue only) | No | `./csr.pem` |
 | `cli-version` | `krakenkey-cli` version to use (e.g., `v0.1.0`, or `latest`) | No | `latest` |
@@ -54,7 +56,9 @@ Issue, renew, or download TLS certificates from [KrakenKey](https://krakenkey.io
 | `fingerprint` | SHA-256 fingerprint |
 | `key-type` | Key type used (e.g., `ECDSA`) |
 | `key-size` | Key size (e.g., `256`, `2048`) |
-| `cert-path` | Absolute path to the saved certificate PEM |
+| `cert-path` | Absolute path to the saved leaf certificate PEM |
+| `chain-path` | Absolute path to the saved intermediate chain PEM |
+| `fullchain-path` | Absolute path to the saved full chain PEM (leaf + intermediates) |
 | `key-path` | Absolute path to the saved private key PEM (issue only) |
 | `csr-path` | Absolute path to the saved CSR PEM (issue only) |
 
@@ -62,19 +66,19 @@ Issue, renew, or download TLS certificates from [KrakenKey](https://krakenkey.io
 
 ### `issue` (default)
 
-Generates a CSR locally, submits it to the KrakenKey API, waits for issuance (~4 minutes), and saves the certificate + private key to the runner filesystem.
+Generates a CSR locally, submits it to the KrakenKey API, waits for issuance (~4 minutes), and saves the certificate, intermediate chain, and full chain to the runner filesystem.
 
 **Required inputs:** `api-key`, `domain`
 
 ### `renew`
 
-Triggers renewal of an existing certificate by ID, waits for completion, and downloads the new certificate.
+Triggers renewal of an existing certificate by ID, waits for completion, and downloads the new certificate along with its chain files.
 
 **Required inputs:** `api-key`, `cert-id`
 
 ### `download`
 
-Downloads an already-issued certificate by ID. No issuance, no waiting.
+Downloads an already-issued certificate by ID. Saves the leaf cert, intermediate chain (`chain-path`), and full chain (`fullchain-path`). No issuance, no waiting.
 
 **Required inputs:** `api-key`, `cert-id`
 
@@ -112,6 +116,27 @@ jobs:
 
 </details>
 
+<details>
+<summary>Deploy with full chain (nginx, HAProxy)</summary>
+
+```yaml
+      - name: Issue TLS certificate
+        id: cert
+        uses: krakenkey/cert-action@v1
+        with:
+          api-key: ${{ secrets.KRAKENKEY_API_KEY }}
+          domain: api.example.com
+
+      - name: Deploy fullchain + key
+        run: |
+          # Use fullchain.pem for nginx ssl_certificate directive
+          scp ${{ steps.cert.outputs.fullchain-path }} server:/etc/ssl/certs/fullchain.pem
+          scp ${{ steps.cert.outputs.key-path }} server:/etc/ssl/private/key.pem
+          ssh server 'systemctl reload nginx'
+```
+
+</details>
+
 <details>
 <summary>Multi-domain certificate with SANs</summary>
 
@@ -158,6 +183,8 @@ jobs:
           command: download
           cert-id: '42'
           cert-path: ./cert.pem
+          chain-path: ./chain.pem
+          fullchain-path: ./fullchain.pem
 ```
 
 </details>
@@ -237,6 +264,18 @@ jobs:
 
 </details>
 
+## Certificate Chain Files
+
+Every `issue`, `renew`, and `download` operation produces three certificate files:
+
+| File | Input | Content | Use case |
+|------|-------|---------|----------|
+| `cert-path` | `cert-path` | Leaf certificate only | Peer verification, inspection |
+| `chain-path` | `chain-path` | Intermediate CA chain only | Stapling, manual chain assembly |
+| `fullchain-path` | `fullchain-path` | Leaf + intermediates (concatenated) | nginx `ssl_certificate`, HAProxy, most servers |
+
+Most web servers (nginx, Caddy, HAProxy) expect the **full chain** in the certificate file. Use `${{ steps.cert.outputs.fullchain-path }}` for these deployments.
+
 ## Security
 
 - **API key masking** — The API key is masked with `::add-mask::` as the very first operation, ensuring it is redacted from all log output.