@certchip/signer 0.1.19 → 0.1.27

package/README.md

@@ -2,9 +2,11 @@
 
 Cross-platform code and document signing CLI tool with SSH key authentication.
 
+> **Note:** This program module can be used in environments where Certchip Signer Server is deployed.
+
 ## Features
 
-- **Cross-platform** - Windows, Linux, macOS (x64, arm64)
+- **Cross-platform** - Windows (x64), Linux (x64), macOS (coming soon)
 - **SSH Key Authentication** - Ed25519, ECDSA, RSA support
 - **Code Signing** - PE executables (EXE, DLL, SYS, OCX), MSI, MSP, CAB
 - **Document Signing** - PDF with visual signature (watermark, box, barcode, QR code)
@@ -13,6 +15,9 @@ Cross-platform code and document signing CLI tool with SSH key authentication.
 - **Hash-based Signing** - Default mode: only hash sent to server, not the file
 - **Windows KSP** - Native Windows crypto integration (Windows only)
 - **Structured Output** - JSON, table, or CSV output for scripting and automation
+- **Certificate Distribution** - Remote certificate download, renewal, and sync for SSL/TLS, device, and signing certificates (`-cert-dist`)
+- **Let's Encrypt Management** - Direct access to Let's Encrypt SSL certificates stored on the server (`-letsencrypt`)
+- **Certificate Management API** - Upload, download, delete certificates/keys, CSR generation (`-cert`, `-privkey`, `-pubkey`, `-csr`)
 
 ## Installation
 
@@ -32,8 +37,9 @@ npm install @certchip/signer
 # Login with SSH key authentication
 signercli -login https://signer.example.com username
 
-# Sign a file
-signercli myapp.exe
+# Sign a file (two equivalent forms)
+signercli myapp.exe              # Implicit form
+signercli -sign myapp.exe        # Explicit form
 
 # Verify signature
 signercli -verify myapp.exe
@@ -48,8 +54,9 @@ signercli -logout
 # Login (certificate is installed to Windows certificate store)
 signer -login https://signer.example.com username
 
-# Sign directly with signer (same options as signercli)
-signer myapp.exe                              # Default: hash-only mode
+# Sign directly with signer (two equivalent forms, same options as signercli)
+signer myapp.exe                              # Implicit form (default: hash-only mode)
+signer -sign myapp.exe                        # Explicit form
 signer myapp.exe -o myapp_signed.exe          # Specify output file
 signer myapp.exe -file-upload -save-signed    # Upload file, save with _signed suffix
 
@@ -74,26 +81,100 @@ npx signer myapp.exe
 
 ## CLI Commands
 
-This package provides two CLI tools with different purposes:
+This package provides two CLI tools with different capabilities:
+
+### Tool Comparison Overview
 
 | | signercli | signer |
 |---|-----------|--------|
-| **Purpose** | Direct file signing | Direct signing + Windows signtool integration |
+| **Purpose** | Full-featured signing and certificate management | Windows signtool.exe integration + direct signing |
 | **Platform** | Windows, Linux, macOS | Windows only |
-| **How it works** | Signs files directly via server API | Signs files directly OR provides certificates to Windows crypto system |
-| **Best for** | CI/CD, cross-platform, simple signing | Windows developers, signtool.exe integration |
-
-### When to use which tool?
-
-| Scenario | Recommended |
-|----------|-------------|
-| CI/CD pipeline (any platform) | signercli |
-| Linux/macOS development | signercli |
-| Simple file signing | signercli or signer |
-| Windows direct signing | signer or signercli |
-| Using Windows signtool.exe | signer |
-| Windows certificate store integration | signer |
-| Visual Studio post-build signing | signercli or signer |
+| **How it works** | Signs files directly via server API | Registers certificates in Windows store for signtool.exe integration |
+| **Best for** | CI/CD, automation, cross-platform, certificate management | Windows developers, signtool.exe, Visual Studio integration |
+
+### Feature Comparison
+
+| Feature | signercli | signer |
+|---------|:---------:|:------:|
+| **Platform Support** | | |
+| Windows | ✅ | ✅ |
+| Linux | ✅ | ❌ |
+| macOS | ✅ | ❌ |
+| ARM64 support | ✅ | ❌ |
+| **Authentication** | | |
+| SSH key (Ed25519, ECDSA, RSA) | ✅ | ✅ |
+| Password authentication | ✅ | ✅ |
+| API key (no login required) | ✅ | ❌ |
+| Profile-based configuration | ✅ | ✅ |
+| **File Signing** | | |
+| PE executables (.exe, .dll, .sys, .ocx) | ✅ | ✅ |
+| Installers (.msi, .msp, .cab) | ✅ | ✅ |
+| PDF documents | ✅ | ✅ |
+| Scripts (.ps1, .vbs) | ✅ | ✅ |
+| Source code (JS, Python, Go, Rust, etc.) | ✅ | ✅ |
+| JAR files | ✅ | ✅ |
+| Hash-only signing (default) | ✅ | ✅ |
+| File upload signing | ✅ | ✅ |
+| **PDF Signature Options** | | |
+| Watermark style | ✅ | ✅ |
+| Box style | ✅ | ✅ |
+| Barcode style | ✅ | ✅ |
+| QR code style | ✅ | ✅ |
+| Position/opacity control | ✅ | ✅ |
+| **Certificate Management** | | |
+| List certificates | ✅ | ✅ |
+| Get/Set certificate ID | ✅ | ✅ |
+| Get certificate PEM | ✅ | ✅ |
+| Set private key password | ✅ | ✅ |
+| Upload certificates | ✅ | ❌ |
+| Download certificates (PEM/DER/PFX) | ✅ | ❌ |
+| Delete certificates | ✅ | ❌ |
+| Update certificate metadata | ✅ | ❌ |
+| **Private Key Management** | | |
+| List private keys | ✅ | ❌ |
+| Upload private keys | ✅ | ❌ |
+| Download private keys | ✅ | ❌ |
+| Delete private keys | ✅ | ❌ |
+| Link/Unlink to certificates | ✅ | ❌ |
+| **CSR & Public Key** | | |
+| Generate CSR | ✅ | ❌ |
+| Public key management | ✅ | ❌ |
+| **Certificate Distribution** | | |
+| Let's Encrypt SSL certificates | ✅ | ❌ |
+| Let's Encrypt direct management | ✅ | ❌ |
+| Device certificates | ✅ | ❌ |
+| Signing certificates | ✅ | ❌ |
+| Auto-renewal check | ✅ | ❌ |
+| Multiple download formats | ✅ | ❌ |
+| **Windows Integration** | | |
+| signtool.exe integration | ❌ | ✅ |
+| Windows certificate store | ❌ | ✅ |
+| KSP provider registration | ❌ | ✅ |
+| Key container management | ❌ | ✅ |
+| **Output & Automation** | | |
+| Classic output | ✅ | ✅ |
+| JSON output | ✅ | ❌ |
+| Table output | ✅ | ❌ |
+| CSV output | ✅ | ❌ |
+| Log level control | ✅ | ✅ |
+
+### When to Use Which Tool?
+
+| Scenario | Recommended Tool |
+|----------|------------------|
+| CI/CD pipeline (any platform) | **signercli** - Cross-platform, JSON output, API key auth |
+| Linux/macOS development | **signercli** - Only option for non-Windows |
+| Simple file signing | **signercli** or **signer** - Both work equally |
+| Windows signtool.exe integration | **signer** - Registers cert to Windows store |
+| Visual Studio post-build signing | **signer** - signtool.exe compatible |
+| Windows certificate store integration | **signer** - KSP provider support |
+| Certificate upload/download/delete | **signercli** - `-cert` with API key |
+| Let's Encrypt certificate distribution | **signercli** - `-cert-dist` command |
+| Let's Encrypt direct management | **signercli** - `-letsencrypt` command |
+| Private key management | **signercli** - `-privkey` command |
+| CSR generation | **signercli** - `-csr` command |
+| Automation without SSH keys | **signercli** - API key authentication |
+| Parsing output in scripts | **signercli** - `-format json` option |
 
 ---
 
@@ -130,10 +211,12 @@ signercli -logout [url]
 
 ```bash
 # Basic signing (default: hash-only mode)
-signercli <file>
+signercli <file>                          # Implicit form
+signercli -sign <file>                    # Explicit form (same result)
 
 # Signing options
 signercli <file> -o <output>              # Specify output file
+signercli -sign <file> -o <output>        # Explicit form
 signercli <file> -save-signed             # Save with _signed suffix (preserve original)
 signercli <file> -hash-only               # Hash-based signing (default)
 signercli <file> -file-upload             # Upload entire file to server
@@ -142,6 +225,8 @@ signercli <file> -timestamp-url <url>     # Timestamp server URL
 signercli <file> -profile <name>          # Use config profile
 ```
 
+> **Note:** Both `signercli <file>` (implicit) and `signercli -sign <file>` (explicit) forms are equivalent. The explicit form makes intent clearer in scripts and automation.
+
 > **Note:** Hash-only signing is the default mode. Only the file hash is sent to the server, not the entire file.
 
 #### Signature Verification
@@ -175,9 +260,17 @@ signercli -codesign-set <password>
 
 ```bash
 # List certificates (with purpose filter)
-signercli -cert -list                     # List all certificates
-signercli -cert -list codesign            # List code signing certificates
-signercli -cert -list docsign             # List document signing certificates
+signercli -cert list                      # List all certificates with private keys (default)
+signercli -cert list any                  # List all certificates (including without private keys)
+signercli -cert list codesign             # List code signing certificates
+signercli -cert list docsign              # List document signing certificates
+signercli -cert list serverauth           # List server authentication (SSL/TLS) certificates
+signercli -cert list clientauth           # List client authentication certificates
+signercli -cert list ca                   # List CA certificates
+signercli -cert list timestamp            # List timestamping certificates
+signercli -cert list ocsp                 # List OCSP signing certificates
+signercli -cert list encrypt              # List encryption certificates
+signercli -cert list verify               # List verification certificates
 
 # Get/Set certificate ID
 signercli -cert -id                       # Show current configuration
@@ -195,37 +288,151 @@ signercli -cert -password <password>
 
 #### Configuration
 
-Profiles store connection settings. The `default` profile is used when no profile is specified. Other profiles inherit missing settings from `default`.
+The configuration file allows you to store connection settings, authentication credentials, and signing options in reusable profiles. This eliminates the need to specify the same options repeatedly on the command line.
+
+> **Detailed guide:** See [docs/CONFIG-FILE-GUIDE.md](docs/CONFIG-FILE-GUIDE.md) for complete configuration options and examples.
+
+**Why Use Configuration Profiles:**
+
+- **Convenience:** Store server URL, API key, and other settings once
+- **Multiple Environments:** Switch between production, staging, and development servers
+- **CI/CD Integration:** Pre-configure settings for automated signing workflows
+- **Security:** Keep credentials out of command history and scripts
+
+**Understanding the Default Profile:**
+
+The `[default]` profile is special - it serves as the base configuration for all operations:
+
+1. **Automatic loading:** When no `-profile` option is specified, SignerCLI automatically uses `[default]`
+2. **Inheritance:** Named profiles (like `[production]` or `[staging]`) inherit all settings from `[default]`
+3. **Override behavior:** Named profiles only need to specify settings that differ from `[default]`
+
+This inheritance model means you should:
+- Store **common settings** (server URL, API key) in `[default]`
+- Store **environment-specific settings** (certificate ID, timestamp URL) in named profiles
+
+```
+┌─────────────────────────────────────────────────────┐
+│ [default]                                           │
+│   host = https://signer.example.com:7443            │
+│   api_key = cdk_xxx...                              │
+│   hash_algorithm = sha256                           │
+├─────────────────────────────────────────────────────┤
+│ [production]              │ [staging]               │
+│   cert_id = prod-001      │   host = https://stg:7443│
+│   (inherits host,         │   cert_id = stg-001     │
+│    api_key, hash_alg)     │   (inherits api_key,    │
+│                           │    hash_alg)            │
+└───────────────────────────┴─────────────────────────┘
+```
+
+**Config File Location:**
+
+| OS | Path |
+|----|------|
+| Linux/macOS | `~/.signer/config` |
+| Windows | `%USERPROFILE%\.signer\config` |
+
+**Basic Commands:**
 
 ```bash
 # View configuration
-signercli -config                         # Show config file
+signercli -config                         # Show entire config file
 signercli -config list                    # List all profiles
-signercli -config show <name>             # Show profile details
+signercli -config show <name>             # Show specific profile details
 
-# Create/Update profile
-signercli -config set <name> [options]
+# Create/Update profile (profile name defaults to 'default' if omitted)
+signercli -config set [name] [options]
 
-# Delete profile
+# Remove specific settings from profile
+signercli -config unset [name] <options>
+
+# Delete entire profile
 signercli -config delete <name>
 ```
 
+**Removing Settings (`-config unset`):**
+
+```bash
+# Remove api_key from default profile
+signercli -config unset -api-key
+
+# Remove multiple settings
+signercli -config unset -api-key -host
+
+# Remove from named profile
+signercli -config unset production -cert-id
+```
+
+**API Key Authentication (No Login Required):**
+
+Store an API key in a profile to use `-cert`, `-privkey`, `-pubkey`, `-csr`, `-cert-dist` commands without login.
+
+```bash
+# Set API key in default profile (profile name omitted = 'default')
+signercli -config set \
+    -host https://signer.example.com:7443 \
+    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
+
+# Same as above (explicit 'default')
+signercli -config set default \
+    -host https://signer.example.com:7443 \
+    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
+
+# Use commands without login (API key auto-applied)
+signercli -cert list
+signercli -cert get <id>
+signercli -cert upload cert.pem -name "My Cert"
+signercli -cert-dist list
+```
+
 **Profile Inheritance Example:**
 
 ```bash
-# Set common settings in 'default' profile
-signercli -config set default -host https://signer.example.com -username admin
+# Set common settings in default profile (profile name optional)
+signercli -config set \
+    -host https://signer.example.com:7443 \
+    -api-key cdk_common_api_key \
+    -hash-algorithm sha256
 
-# Create 'production' profile (inherits host and username from default)
+# Create production profile (inherits host, api_key, hash-algorithm)
 signercli -config set production -cert-id prod-cert-001
 
-# Create 'staging' profile with different host (overrides default)
-signercli -config set staging -host https://staging.example.com -cert-id staging-cert
+# Create staging profile (overrides host, inherits others)
+signercli -config set staging \
+    -host https://staging.example.com:7443 \
+    -cert-id staging-cert-001
 
 # Usage
-signercli -login                          # Uses 'default' profile
-signercli -login -profile production      # Uses 'production' (inherits from default)
-signercli -login -profile staging         # Uses 'staging' (overrides host)
+signercli -cert list                      # Uses default profile
+signercli -cert list -profile production  # Uses production profile
+signercli -cert list -profile staging     # Uses staging profile
+```
+
+**Inheritance Display:**
+
+```
+$ signercli -config show production
+Profile: [production]
+----------------------------------------
+  host              = https://signer.example.com:7443 (default)
+  api_key           = cdk_common_api_key (default)
+  cert_id           = prod-cert-001
+  hash_algorithm    = sha256 (default)
+```
+> The `(default)` marker indicates the value is inherited from the `[default]` profile.
+
+**Authentication Priority:**
+
+1. **Command-line arguments** (`-api-key`, `-host`) - Highest priority
+2. **Specified profile** (`-profile <name>`)
+3. **Default profile**
+4. **Login token** (if available)
+
+```bash
+# Command-line args override profile settings
+signercli -cert list -profile production -host https://other:7443
+# → Uses other:7443 (ignores production's host)
 ```
 
 **Profile Options:**
@@ -235,14 +442,15 @@ signercli -login -profile staging         # Uses 'staging' (overrides host)
 | `-host <url>` | Server URL |
 | `-ssh-key-path <path>` | SSH private key path |
 | `-username <name>` | SSH username |
-| `-user <id>` | Password auth user ID |
+| `-user <id>` | User ID for password auth |
+| `-api-key <key>` | API key (bypasses login) |
 | `-cert-id <id>` | Default certificate ID |
 | `-cert-serial <sn>` | Certificate serial number |
 | `-expires <time>` | Token expiration (24h, 7d, 1w) |
 | `-include-chain` | Include certificate chain |
 | `-timestamp-url <url>` | Timestamp server URL |
-| `-hash-algorithm <alg>` | Default hash algorithm |
-| `-output-format <type>` | Default output format (classic, json, table, csv) |
+| `-hash-algorithm <alg>` | Hash algorithm (sha256, sha384, sha512) |
+| `-output-format <type>` | Output format (classic, json, table, csv) |
 
 **Document Signing Options:**
 
@@ -251,9 +459,34 @@ signercli -login -profile staging         # Uses 'staging' (overrides host)
 | `-doc-style <style>` | watermark, box, barcode, qrcode |
 | `-doc-position <pos>` | bottom-right, bottom-left, top-right, top-left, center |
 | `-doc-sig-position <pos>` | left, center, right (for barcode/qrcode) |
-| `-doc-font-size <size>` | Font size for signature |
+| `-doc-font-size <size>` | Signature font size |
 | `-doc-opacity <value>` | Opacity (0.0-1.0 or 0-100) |
 
+**Config File Example (`~/.signer/config`):**
+
+```ini
+[default]
+host=https://signer.example.com:7443
+api_key=cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
+hash_algorithm=sha256
+output_format=classic
+
+[production]
+cert_id=prod-codesign-001
+timestamp_url=http://timestamp.digicert.com
+include_chain=true
+
+[ci-automation]
+api_key=cdk_ci_specific_api_key
+output_format=json
+cert_id=automation-cert-001
+```
+
+**Security Notes:**
+
+- API keys are stored in plain text in the config file
+- Set appropriate file permissions: `chmod 600 ~/.signer/config` (Linux/macOS)
+
 #### Windows DLL Installation
 
 ```bash
@@ -282,17 +515,17 @@ The `-version` command displays comprehensive version information:
 
 ```
 # signercli -version
-Certchip Signer CLI v0.1.18
+Certchip Signer CLI v0.1.27
 Cross-platform code and document signing tool
 Copyright (c) 2025 Certchip. All rights reserved.
 
 DLL Versions (Local):
-  otpkey.dll:   0.1.18.0
-  Certchip.dll: 0.1.18.0
+  otpkey.dll:   0.1.27.0
+  Certchip.dll: 0.1.27.0
 
 DLL Versions (System32):
-  otpkey.dll:   0.1.18.0
-  Certchip.dll: 0.1.18.0
+  otpkey.dll:   0.1.27.0
+  Certchip.dll: 0.1.27.0
 ```
 
 | Information | Description |
@@ -394,7 +627,7 @@ $ signercli -login https://signer.example.com admin -pw secret -format json
 Windows-specific tool that integrates with the Windows cryptographic system via KSP (Key Storage Provider). It can both sign files directly (like signercli) and register certificates in the Windows certificate store for use with `signtool.exe`.
 
 **Two signing methods:**
-1. **Direct signing** - Sign files directly with `signer <file>` (same as signercli)
+1. **Direct signing** - Sign files directly with `signer <file>` or `signer -sign <file>` (same as signercli)
 2. **signtool integration** - Login to register certificate, then use Windows signtool.exe
 
 ```bash
@@ -403,7 +636,8 @@ signer -login <url> [username]            # Login and register certificate
 signer -logout                            # Logout and remove certificate
 
 # File Signing (direct - same options as signercli)
-signer <file> [options]                   # Sign a file directly
+signer <file> [options]                   # Sign a file (implicit form)
+signer -sign <file> [options]             # Sign a file (explicit form)
     -o <path>                             # Output file path
     -hash-only                            # Hash-based signing (default)
     -file-upload                          # Upload entire file to server
@@ -439,37 +673,880 @@ signtool sign /sha1 <thumbprint> /fd sha256 /tr http://timestamp.digicert.com my
 
 **Examples:**
 ```bash
-# Direct signing with output path
+# Direct signing with output path (two equivalent forms)
 signer myapp.exe -o myapp_signed.exe
+signer -sign myapp.exe -o myapp_signed.exe
 
 # Upload entire file for signing
 signer myapp.exe -file-upload -o myapp_signed.exe
 
 # Hash-only signing with _signed suffix
 signer myapp.exe -save-signed
+signer -sign myapp.exe -save-signed
 ```
 
 **Version Output:**
 
 ```
 # signer -version
-Certchip Signer v0.1.18
+Certchip Signer v0.1.27
 Windows Key Storage Provider and Code Signing Tool
 Copyright (c) 2025 Certchip. All rights reserved.
 
 DLL Versions (Local):
-  otpkey.dll:   0.1.18.0
-  Certchip.dll: 0.1.18.0
+  otpkey.dll:   0.1.27.0
+  Certchip.dll: 0.1.27.0
 
 DLL Versions (System32):
-  otpkey.dll:   0.1.18.0
-  Certchip.dll: 0.1.18.0
+  otpkey.dll:   0.1.27.0
+  Certchip.dll: 0.1.27.0
 ```
 
 The version output helps diagnose DLL version mismatches between local and system-wide installations.
 
 ---
 
+### cert-dist (Certificate Distribution)
+
+Download and manage certificates from a remote server. Supports various certificate types including SSL/TLS, device, and signing certificates.
+
+**Supported Certificate Types:**
+- SSL/TLS server certificates (including Let's Encrypt)
+- Device certificates
+- Code signing certificates
+- Document signing certificates
+
+```bash
+# Check certificate status
+signercli -cert-dist status <domain> -api-key <key> -host <url>
+
+# Check if renewal is needed
+signercli -cert-dist check <domain> -api-key <key> -host <url>
+
+# Download certificate
+signercli -cert-dist download <domain> -api-key <key> -host <url> [-format <type>] [-o <dir>]
+
+# Trigger certificate renewal
+signercli -cert-dist renew <domain> -api-key <key> -host <url> [-force] [-wait|-no-wait]
+
+# List available domains
+signercli -cert-dist list -api-key <key> -host <url>
+
+# Full sync (check + renew + download)
+signercli -cert-dist sync <domain> -api-key <key> -host <url> [-reload-cmd <cmd>]
+
+# Help
+signercli -cert-dist help
+```
+
+#### API Key Permission Modes
+
+API keys support two permission modes:
+
+| Mode | Description |
+|------|-------------|
+| `explicit` | Use only the permissions explicitly assigned to the API key |
+| `inherited` | Inherit permissions from the linked user account's role and groups |
+
+**Explicit Mode:**
+- Permissions are set when creating the API key
+- Ideal for applying the principle of least privilege
+- Permissions don't change when user permissions change
+
+**Inherited Mode:**
+- Permissions come from the linked user account
+- When user permissions change, API key permissions update automatically
+- Simplifies management for users with multiple API keys
+
+#### Extended Permissions
+
+| Permission | Description | cert-dist | cert-api | letsencrypt |
+|------------|-------------|-----------|----------|-------------|
+| `read` | View certificate info | ✅ | ✅ | ✅ |
+| `renew` | Renew certificates | ✅ | - | - |
+| `download` | Download certificates | ✅ | ✅ | ✅ |
+| `upload` | Upload certificates/keys | - | ✅ | - |
+| `delete` | Delete certificates/keys | - | ✅ | - |
+| `edit` | Edit metadata | - | ✅ | - |
+| `csr` | Generate CSR | - | ✅ | - |
+| `hsm` | HSM operations (protect/unprotect) | - | ✅ | - |
+| `letsencrypt` | Let's Encrypt SSL certificate management | - | - | ✅ |
+| `all` | All permissions | ✅ | ✅ | ✅ |
+
+#### User Account Linking
+
+Link a user account to an API key for:
+- **Audit Trail**: API call logs include the linked user information
+- **Permission Inheritance**: Use `inherited` mode to automatically apply user permissions
+- **Resource Access**: Access certificates/keys owned by the linked user
+
+**Format Options by Command:**
+
+| Command | `-format json` | File Formats |
+|---------|---------------|--------------|
+| `status` | ✅ JSON output | - |
+| `check` | ✅ JSON output | - |
+| `list` | ✅ JSON output | - |
+| `renew` | ✅ JSON output | - |
+| `download` | ✅ JSON output | nginx, pem, letsencrypt, json (file) |
+| `sync` | ✅ JSON output | nginx, pem, letsencrypt |
+
+**Download File Formats:**
+
+| Format | Description | Generated Files |
+|--------|-------------|-----------------|
+| `nginx` | Nginx format (default) | `<domain>.crt`, `<domain>.key` |
+| `pem` | Standard PEM format | `<domain>.fullchain.pem`, `<domain>.privkey.pem` |
+| `letsencrypt` | Let's Encrypt style | `<domain>/cert.pem`, `<domain>/chain.pem`, `<domain>/fullchain.pem`, `<domain>/privkey.pem` |
+| `json` | JSON format | `<domain>.json` |
+
+**Examples:**
+
+```bash
+# Download in Nginx format (default)
+signercli -cert-dist download example.com -api-key cdk_xxx -host https://signer.example.com:7443
+
+# Download in Let's Encrypt style
+signercli -cert-dist download example.com -api-key cdk_xxx -host https://signer.example.com:7443 \
+    -format letsencrypt -o /etc/letsencrypt/live
+
+# Automation: renew if needed, download, and reload Nginx
+signercli -cert-dist sync example.com -api-key cdk_xxx -host https://signer.example.com:7443 \
+    -o /etc/nginx/ssl -reload-cmd "systemctl reload nginx"
+
+# Get status in JSON format (for scripting)
+signercli -cert-dist status example.com -api-key cdk_xxx -host https://signer.example.com:7443 -format json
+```
+
+**Exit Codes:**
+- `0`: Success (for check command: no renewal needed)
+- `1`: Error
+- `2`: Renewal needed (check command only)
+
+> **Detailed usage:** See [cert-dist-guide.md](docs/cert-dist-guide.md)
+
+---
+
+### cert-api (Certificate Management API)
+
+General certificate and key management commands. Uses the same API key as cert-dist.
+
+**Three Command Systems:**
+
+| Commands | Purpose | API Endpoint |
+|----------|---------|--------------|
+| `-cert-dist` | Let's Encrypt certificate distribution/renewal | `/api/cert-distribution` |
+| `-cert`, `-privkey`, `-pubkey`, `-csr` | General certificate/key management | `/api/cert-api` |
+| `-letsencrypt` | Let's Encrypt SSL certificate direct management | `/api/cert-api/letsencrypt` |
+
+#### API Key Authentication (-api-key)
+
+API keys allow direct API access without SSH key-based login.
+
+**What is an API Key?**
+
+- A unique authentication token issued by the server (format: `cdk_` prefix + 64-char hex)
+- Alternative to SSH key-based challenge-response login
+- Ideal for CI/CD pipelines, automation scripts, and programmatic access
+
+**API Key Format:**
+```
+cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
+```
+
+**Usage Methods:**
+
+```bash
+# Method 1: Specify directly on command line
+signercli -cert list -api-key cdk_xxx -host https://server:7443
+
+# Method 2: Store in profile (recommended)
+signercli -config set default -host https://server:7443 -api-key cdk_xxx
+signercli -cert list  # api-key and host auto-applied
+
+# Method 3: Use named profile
+signercli -config set production -host https://prod:7443 -api-key cdk_prod_key
+signercli -cert list -profile production
+```
+
+**Supported Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `-cert` | Certificate management (list, upload, download, delete) |
+| `-cert-dist` | Let's Encrypt certificate distribution/renewal |
+| `-letsencrypt` | Let's Encrypt SSL certificate direct management |
+| `-privkey` | Private key management |
+| `-pubkey` | Public key management |
+| `-csr` | Certificate Signing Request generation |
+
+**Login Authentication vs API Key Authentication:**
+
+| Aspect | Login Authentication | API Key Authentication |
+|--------|---------------------|------------------------|
+| Method | SSH key challenge-response | Direct API key transmission |
+| Token Expiry | Yes (default 24h) | Depends on server config |
+| Commands | All commands after `-login` | `-cert`, `-cert-dist`, etc. only |
+| Best For | Interactive use, code signing | Automation, CI/CD, scripts |
+
+**Security Notes:**
+
+- Protect API keys like passwords
+- Set config file permissions: `chmod 600 ~/.signer/config`
+- Don't hardcode API keys in scripts
+- Use secret managers in CI/CD environments
+
+#### Certificate Commands (-cert)
+
+```bash
+# List certificates
+signercli -cert list -api-key <key> [-host <url>]
+
+# Get certificate details
+signercli -cert get <id> -api-key <key>
+
+# Upload certificate (default: DB storage)
+signercli -cert upload <file> -name "Certificate Name" -api-key <key>
+
+# Upload certificate to Software HSM (no PIN required)
+signercli -cert upload <file> -name "My Cert" -storage SW_HSM -api-key <key>
+
+# Upload certificate to Hardware HSM (slot and PIN required)
+signercli -cert upload <file> -name "My Cert" -storage HW_HSM -hsm-slot 0 -hsm-pin <pin> -api-key <key>
+
+# Download certificate (PEM/DER)
+signercli -cert download <id> -format pem -o <dir> -api-key <key>
+
+# Download certificate (PFX)
+signercli -cert download-pfx <id> -password <pwd> -o <dir> -api-key <key>
+
+# Update certificate metadata
+signercli -cert update <id> -name "New Name" -desc "Description" -api-key <key>
+
+# Delete certificate
+signercli -cert delete <id> -api-key <key>
+
+# Delete certificate with related private key
+signercli -cert delete <id> -delete-related -api-key <key>
+
+# Delete HSM certificate (PIN required)
+signercli -cert delete <id> -hsm-pin <pin> -api-key <key>
+```
+
+**Storage Types:**
+
+| Type | Description | Requirements |
+|------|-------------|--------------|
+| `DB` | Database storage (default) | None |
+| `SW_HSM` | Software HSM (encrypted storage) | None |
+| `HW_HSM` | Hardware HSM (PKCS#11 device) | `-hsm-slot`, `-hsm-pin` |
+
+**Using Profile with API Key:**
+
+You can store the API key in a profile to avoid specifying it on every command:
+
+```bash
+# Configure profile with API key (one-time setup)
+signercli -config set default -host https://server:7443 -api-key cdk_xxx
+
+# Now use -cert commands without -api-key and -host
+signercli -cert list
+signercli -cert get <id>
+signercli -cert upload cert.pem -name "My Cert"
+
+# Or use a named profile
+signercli -config set myserver -host https://server:7443 -api-key cdk_xxx
+signercli -cert list -profile myserver
+```
+
+#### Creating Test Certificates (OpenSSL)
+
+For testing `-cert upload` and other certificate commands, you can create test certificates using OpenSSL.
+
+##### Linux / macOS
+
+**1. Self-Signed Certificate (Simple)**
+
+```bash
+# Generate RSA key + certificate in one command
+openssl req -x509 -newkey rsa:2048 -keyout test_key.pem -out test_cert.pem -days 365 -nodes \
+  -subj "/C=KR/ST=Seoul/L=Gangnam/O=TestOrg/OU=Dev/CN=Test Certificate"
+
+# Verify certificate
+openssl x509 -in test_cert.pem -text -noout
+```
+
+**2. Code Signing Certificate**
+
+```bash
+# Generate private key
+openssl genrsa -out codesign_key.pem 2048
+
+# Generate certificate with code signing extensions
+openssl req -new -x509 -key codesign_key.pem -out codesign_cert.pem -days 365 \
+  -subj "/C=KR/O=MyCompany/CN=Code Signing Certificate" \
+  -addext "keyUsage=digitalSignature" \
+  -addext "extendedKeyUsage=codeSigning"
+```
+
+**3. PFX/P12 Bundle (Key + Certificate)**
+
+```bash
+# Create PFX from PEM files
+openssl pkcs12 -export -out test_bundle.pfx \
+  -inkey test_key.pem -in test_cert.pem \
+  -password pass:test1234
+```
+
+**4. DER Format Certificate**
+
+```bash
+# Convert PEM to DER
+openssl x509 -in test_cert.pem -outform DER -out test_cert.der
+```
+
+**5. Complete Test Script (Linux/macOS)**
+
+```bash
+#!/bin/bash
+# create_test_certs.sh
+mkdir -p test_certs && cd test_certs
+
+# Basic test certificate
+openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
+  -subj "/CN=Test Certificate"
+
+# Code signing certificate
+openssl req -x509 -newkey rsa:4096 -keyout codesign_key.pem -out codesign_cert.pem -days 365 -nodes \
+  -subj "/C=KR/O=TestOrg/CN=Code Signing Test" \
+  -addext "keyUsage=digitalSignature" \
+  -addext "extendedKeyUsage=codeSigning"
+
+# PFX bundle
+openssl pkcs12 -export -out bundle.pfx -inkey key.pem -in cert.pem -password pass:test1234
+
+# DER format
+openssl x509 -in cert.pem -outform DER -out cert.der
+
+echo "Created files:"
+ls -la
+```
+
+##### Windows (PowerShell / CMD)
+
+> **Note:** Windows requires OpenSSL to be installed. You can install it via:
+> - [Git for Windows](https://git-scm.com/) (includes OpenSSL in Git Bash)
+> - [MSYS2](https://www.msys2.org/) (`pacman -S openssl`)
+> - [OpenSSL for Windows](https://slproweb.com/products/Win32OpenSSL.html)
+
+**1. Self-Signed Certificate (PowerShell)**
+
+```powershell
+# Using Git Bash OpenSSL (adjust path as needed)
+& "C:\Program Files\Git\usr\bin\openssl.exe" req -x509 -newkey rsa:2048 `
+  -keyout test_key.pem -out test_cert.pem -days 365 -nodes `
+  -subj "/C=KR/ST=Seoul/L=Gangnam/O=TestOrg/OU=Dev/CN=Test Certificate"
+
+# Verify certificate
+& "C:\Program Files\Git\usr\bin\openssl.exe" x509 -in test_cert.pem -text -noout
+```
+
+**2. Using Windows Native (certreq + PowerShell)**
+
+```powershell
+# Create self-signed certificate using PowerShell
+$cert = New-SelfSignedCertificate -DnsName "Test Certificate" `
+  -CertStoreLocation "Cert:\CurrentUser\My" `
+  -KeyUsage DigitalSignature `
+  -Type CodeSigningCert `
+  -NotAfter (Get-Date).AddYears(1)
+
+# Export to PFX
+$password = ConvertTo-SecureString -String "test1234" -Force -AsPlainText
+Export-PfxCertificate -Cert $cert -FilePath "test_bundle.pfx" -Password $password
+
+# Export certificate only (CER/DER format)
+Export-Certificate -Cert $cert -FilePath "test_cert.cer" -Type CERT
+
+# Show certificate info
+$cert | Format-List Subject, Thumbprint, NotAfter
+```
+
+**3. Complete Test Script (Windows CMD with Git Bash OpenSSL)**
+
+```batch
+@echo off
+REM create_test_certs.bat
+REM Requires OpenSSL (Git Bash or standalone)
+
+set OPENSSL="C:\Program Files\Git\usr\bin\openssl.exe"
+mkdir test_certs 2>nul
+cd test_certs
+
+REM Basic test certificate
+%OPENSSL% req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=Test Certificate"
+
+REM Code signing certificate
+%OPENSSL% req -x509 -newkey rsa:4096 -keyout codesign_key.pem -out codesign_cert.pem -days 365 -nodes -subj "/C=KR/O=TestOrg/CN=Code Signing Test" -addext "keyUsage=digitalSignature" -addext "extendedKeyUsage=codeSigning"
+
+REM PFX bundle
+%OPENSSL% pkcs12 -export -out bundle.pfx -inkey key.pem -in cert.pem -password pass:test1234
+
+REM DER format
+%OPENSSL% x509 -in cert.pem -outform DER -out cert.der
+
+echo Created files:
+dir /b
+```
+
+**4. Complete Test Script (Windows PowerShell Native)**
+
+```powershell
+# create_test_certs.ps1
+# Uses Windows native certificate APIs (no OpenSSL required)
+
+$testDir = "test_certs"
+New-Item -ItemType Directory -Force -Path $testDir | Out-Null
+Set-Location $testDir
+
+$password = ConvertTo-SecureString -String "test1234" -Force -AsPlainText
+
+# Basic test certificate
+$basicCert = New-SelfSignedCertificate -DnsName "Test Certificate" `
+  -CertStoreLocation "Cert:\CurrentUser\My" `
+  -NotAfter (Get-Date).AddYears(1)
+
+Export-PfxCertificate -Cert $basicCert -FilePath "bundle.pfx" -Password $password
+Export-Certificate -Cert $basicCert -FilePath "cert.cer" -Type CERT
+Export-Certificate -Cert $basicCert -FilePath "cert.der" -Type CERT
+
+# Code signing certificate
+$codeCert = New-SelfSignedCertificate -Subject "CN=Code Signing Test, O=TestOrg, C=KR" `
+  -CertStoreLocation "Cert:\CurrentUser\My" `
+  -KeyUsage DigitalSignature `
+  -Type CodeSigningCert `
+  -NotAfter (Get-Date).AddYears(1)
+
+Export-PfxCertificate -Cert $codeCert -FilePath "codesign_bundle.pfx" -Password $password
+
+# Clean up from certificate store (optional)
+# Remove-Item -Path $basicCert.PSPath
+# Remove-Item -Path $codeCert.PSPath
+
+Write-Host "Created files:"
+Get-ChildItem
+```
+
+##### Upload Test Commands (All Platforms)
+
+```bash
+# Upload PEM certificate
+signercli -cert upload test_certs/cert.pem -name "Test Cert" -api-key <key> -host https://server:7443
+
+# Upload PFX bundle
+signercli -cert upload test_certs/bundle.pfx -name "PFX Bundle" -api-key <key> -host https://server:7443
+
+# Upload DER certificate
+signercli -cert upload test_certs/cert.der -name "DER Cert" -api-key <key> -host https://server:7443
+```
+
+##### File Format Summary
+
+| Format | Extension | Description | Created By |
+|--------|-----------|-------------|------------|
+| PEM | `.pem`, `.crt` | Base64 encoded, text format | OpenSSL |
+| DER | `.der`, `.cer` | Binary format | OpenSSL, Windows |
+| PFX/P12 | `.pfx`, `.p12` | Key + Certificate bundle | OpenSSL, Windows |
+
+#### Private Key Commands (-privkey)
+
+```bash
+# List private keys
+signercli -privkey list -api-key <key>
+
+# Get private key details
+signercli -privkey get <id> -api-key <key>
+
+# Upload private key (default: DB storage)
+signercli -privkey upload <file> -api-key <key>
+
+# Upload encrypted private key
+signercli -privkey upload <file> -password <pwd> -api-key <key>
+
+# Upload private key to Software HSM
+signercli -privkey upload <file> -storage SW_HSM -api-key <key>
+
+# Upload private key to Hardware HSM
+signercli -privkey upload <file> -storage HW_HSM -hsm-slot 0 -hsm-pin <pin> -api-key <key>
+
+# Delete private key
+signercli -privkey delete <id> -api-key <key>
+
+# Delete HSM private key (PIN required)
+signercli -privkey delete <id> -hsm-pin <pin> -api-key <key>
+
+# Link private key to certificate
+signercli -privkey link <key-id> <cert-id> -api-key <key>
+
+# Unlink private key from certificate
+signercli -privkey unlink <key-id> -api-key <key>
+```
+
+#### Public Key Commands (-pubkey)
+
+```bash
+# List public keys
+signercli -pubkey list -api-key <key>
+
+# Extract public key from certificate
+signercli -pubkey extract <cert-id> -api-key <key>
+
+# Extract with custom name
+signercli -pubkey extract <cert-id> -name "Public Key Name" -api-key <key>
+```
+
+#### CSR Commands (-csr)
+
+```bash
+# Generate CSR
+signercli -csr generate -cn <common-name> -api-key <key>
+
+# Generate CSR with full subject
+signercli -csr generate \
+  -cn example.com \
+  -c KR \
+  -st Seoul \
+  -l Gangnam \
+  -org "Example Corp" \
+  -ou "IT Department" \
+  -email admin@example.com \
+  -keysize 4096 \
+  -api-key <key>
+
+# Save CSR to file
+signercli -csr generate -cn example.com -o <dir> -api-key <key>
+```
+
+#### Let's Encrypt Commands (-letsencrypt)
+
+Direct management of Let's Encrypt SSL certificates stored on the server. Requires `SYSTEM_ADMIN` role or explicit `letsencrypt` permission.
+
+> **Note:** This command directly accesses Let's Encrypt certificates stored on the server, while `-cert-dist` is for distributing certificates to external servers/devices.
+
+**Authentication:**
+
+You can authenticate using either method:
+1. **Login first** - Use JWT token from login session (no API key needed)
+2. **API key** - Provide API key directly
+
+```bash
+# Method 1: Login first, then use commands without API key
+signercli -login https://signer.example.com:7443 admin
+signercli -letsencrypt list
+
+# Method 2: Use API key directly
+signercli -letsencrypt list -api-key <key>
+```
+
+**Access Control:**
+
+| Authentication | Condition | Access |
+|---------------|-----------|--------|
+| JWT | role = `SYSTEM_ADMIN` | ✅ Allowed |
+| JWT | role = `OPERATION_MANAGER` or `USER` | ❌ Denied |
+| API Key (inherited) | linkedUserRole = `SYSTEM_ADMIN` | ✅ Allowed |
+| API Key (inherited) | linkedUserRole ≠ `SYSTEM_ADMIN` | ❌ Denied |
+| API Key (explicit) | permissions includes `letsencrypt` or `all` | ✅ Allowed |
+| API Key (explicit) | permissions excludes `letsencrypt` | ❌ Denied |
+
+**Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `list` | List Let's Encrypt certificates |
+| `get <id>` | Get certificate details |
+| `download <id>` | Download certificate files |
+| `request` | Request new certificate (HTTP-01 or DNS-01) |
+| `dns-request` | Start DNS-01 challenge (outputs challenge ID) |
+| `dns-request -interactive` | DNS-01 challenge (interactive mode) |
+| `dns-complete` | Complete DNS-01 challenge |
+| `dns-providers` | List available DNS providers |
+| `renew <id>` | Renew certificate (automatic) |
+| `renew-dns <id>` | Start manual DNS-01 renewal (outputs challenge ID) |
+| `renew-dns <id> -interactive` | Manual DNS-01 renewal (interactive mode) |
+| `delete <id>` | Delete certificate |
+| `auto-renewal <id>` | Enable/disable auto-renewal |
+| `activate <id>` | Set certificate as Signer server's SSL certificate |
+
+**List/Get/Download Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-api-key <key>` | API key (optional if logged in) | - |
+| `-host <url>` | Server URL | `https://localhost:7443` |
+| `-format <type>` | Output format: text, json | text |
+| `-env <environment>` | Filter by environment: staging, production | - |
+| `-domain <pattern>` | Filter by domain (supports `*` wildcard, e.g., `*.example.com`) | - |
+| `-type <type>` | Download type: cert, chain, fullchain, key, all | fullchain |
+| `-o <dir>` | Output directory for downloads | Current directory |
+| `-naming <style>` | Filename style: `letsencrypt` or `domain` | letsencrypt |
+
+**Request Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-domain <domain>` | Domain name for the certificate (required) | - |
+| `-email <email>` | Contact email for Let's Encrypt account (required) | - |
+| `-agree-tos` | Agree to Let's Encrypt Terms of Service (required) | - |
+| `-env <environment>` | Environment: staging, production | staging |
+| `-key-type <type>` | Key type: RSA, ECDSA | RSA |
+| `-keysize <bits>` | Key size: 2048, 4096, etc. | 2048 |
+| `-san <domains>` | Subject Alternative Names (comma-separated) | - |
+| `-challenge <type>` | Challenge type: http-01, dns-01 | http-01 |
+| `-dns-provider <mode>` | DNS provider mode: auto, selected (for dns-01) | auto |
+| `-provider-id <id>` | DNS Provider ID (auto-sets -dns-provider to 'selected') | - |
+
+**DNS-01 Challenge Options (for dns-request/dns-complete):**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-interactive, -i` | Interactive mode: wait for Enter, then complete (dns-request) | - |
+| `-challenge-id <id>` | Challenge ID from dns-request (for dns-complete) | - |
+
+**Auto-Renewal Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-enable` | Enable auto-renewal |
+| `-disable` | Disable auto-renewal |
+
+```bash
+# List Let's Encrypt certificates
+signercli -letsencrypt list                          # Using login token
+signercli -letsencrypt list -api-key <key>           # Using API key
+
+# Filter by environment
+signercli -letsencrypt list -env production
+signercli -letsencrypt list -env staging
+
+# Filter by domain (partial match or wildcard)
+signercli -letsencrypt list -domain example.com
+signercli -letsencrypt list -domain api              # Matches api.example.com, etc.
+signercli -letsencrypt list -domain "*.example.com"  # Matches wildcard certificates
+
+# Combine filters
+signercli -letsencrypt list -env production -domain example.com
+
+# Get certificate details
+signercli -letsencrypt get <id>
+
+# Download certificate (fullchain by default)
+signercli -letsencrypt download <id>
+
+# Download specific type
+signercli -letsencrypt download <id> -type cert      # Certificate only
+signercli -letsencrypt download <id> -type chain     # Chain only
+signercli -letsencrypt download <id> -type fullchain # Full chain (default)
+signercli -letsencrypt download <id> -type key       # Private key
+signercli -letsencrypt download <id> -type all       # All files
+
+# Download to specific directory (default: cert.pem, privkey.pem, etc.)
+signercli -letsencrypt download <id> -type all -o /etc/ssl
+
+# Download with domain-based naming (<domain>.crt, <domain>.key, etc.)
+signercli -letsencrypt download <id> -type all -o /etc/ssl -naming domain
+```
+
+**Download Types:**
+
+| Type | Description | Let's Encrypt (default) | Domain Style |
+|------|-------------|-------------------------|--------------|
+| `cert` | Certificate only | `cert.pem` | `<domain>.crt` |
+| `chain` | Intermediate chain | `chain.pem` | `<domain>.chain.crt` |
+| `fullchain` | Certificate + chain (default) | `fullchain.pem` | `<domain>.fullchain.crt` |
+| `key` | Private key | `privkey.pem` | `<domain>.key` |
+| `all` | All files | All above files | All above files |
+
+**Output Options:**
+
+```bash
+# JSON format output
+signercli -letsencrypt list -format json
+
+# Table format output
+signercli -letsencrypt list -format table
+```
+
+**Examples:**
+
+```bash
+# Login first (recommended for interactive use)
+signercli -login https://signer.example.com:7443 admin
+
+# List all production certificates
+signercli -letsencrypt list -env production
+
+# List certificates for a specific domain
+signercli -letsencrypt list -domain example.com
+
+# Get specific certificate details
+signercli -letsencrypt get 6789abcd
+
+# Download fullchain to /etc/nginx/ssl
+signercli -letsencrypt download 6789abcd -type fullchain -o /etc/nginx/ssl
+
+# Download all files for Nginx configuration
+signercli -letsencrypt download 6789abcd -type all -o /etc/nginx/ssl
+
+# Using API key (for automation/scripts)
+signercli -letsencrypt list -env production -api-key cdk_xxx -host https://signer.example.com:7443
+
+# --- HTTP-01 Challenge (default) ---
+# Request new certificate (staging environment - for testing)
+signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos
+
+# Request production certificate
+signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos -env production
+
+# Request certificate with Subject Alternative Names
+signercli -letsencrypt request -domain example.com -san "www.example.com,api.example.com" -email admin@example.com -agree-tos
+
+# --- DNS-01 Challenge with DNS Provider ---
+# Auto-detect DNS provider for domain (default when using dns-01)
+signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos \
+    -challenge dns-01
+
+# Use specific DNS provider (provider-id auto-sets mode to 'selected')
+signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos \
+    -challenge dns-01 -provider-id 6789abc
+
+# Wildcard certificate with DNS provider (auto mode)
+signercli -letsencrypt request -domain "*.example.com" -email admin@example.com -agree-tos \
+    -challenge dns-01 -env production
+
+# --- DNS-01 Challenge (Manual - Two-step process) ---
+# Step 1: Start DNS challenge (get TXT records to add)
+signercli -letsencrypt dns-request -domain example.com -email admin@example.com -agree-tos
+# Step 2: After adding TXT records to DNS, complete the challenge
+signercli -letsencrypt dns-complete -challenge-id <challenge-id>
+
+# --- DNS-01 Challenge (Manual - Interactive mode) ---
+# Single command that waits for Enter and completes automatically
+signercli -letsencrypt dns-request -domain example.com -email admin@example.com -agree-tos -interactive
+
+# --- DNS Provider Management ---
+# List available DNS providers
+signercli -letsencrypt dns-providers
+
+# --- Certificate Renewal ---
+# Renew certificate (automatic - for HTTP-01 or auto DNS-01)
+signercli -letsencrypt renew 6789abcd
+
+# --- Manual DNS-01 Renewal (Two-step process) ---
+# Step 1: Start renewal (get DNS records and challenge ID)
+signercli -letsencrypt renew-dns 6789abcd
+# Step 2: After adding TXT records to DNS, complete the renewal
+signercli -letsencrypt dns-complete -challenge-id <challenge-id>
+
+# --- Manual DNS-01 Renewal (Interactive mode) ---
+# Single command that waits for Enter and completes automatically
+signercli -letsencrypt renew-dns 6789abcd -interactive
+
+# Delete certificate
+signercli -letsencrypt delete 6789abcd
+
+# Enable auto-renewal
+signercli -letsencrypt auto-renewal 6789abcd -enable
+
+# Disable auto-renewal
+signercli -letsencrypt auto-renewal 6789abcd -disable
+
+# --- Activating Server SSL Certificate ---
+# Activate certificate for HTTPS server
+signercli -letsencrypt activate 6789abcd
+```
+
+> **Important: About the 'activate' command**
+>
+> The `activate` command sets the specified Let's Encrypt certificate as the **Signer server's own SSL certificate**.
+> This means that after activation:
+> - The Signer server will use this certificate for HTTPS connections
+> - Clients connecting to the Signer server will see this certificate
+>
+> **This does NOT mean:**
+> - ❌ Enabling or disabling the certificate itself
+> - ❌ Making the certificate "active" vs "inactive"
+> - ❌ Publishing or unpublishing the certificate
+>
+> All issued certificates remain valid and usable regardless of activation status.
+> The `activate` command is only for configuring which certificate the Signer server uses for its own HTTPS endpoint.
+
+**Certificate Issuance/Renewal Notes:**
+
+| Scenario | Command | Description |
+|----------|---------|-------------|
+| **New Certificate** | | |
+| DNS-01 manual (scripted) | `dns-request` + `dns-complete` | Two-step process for automation |
+| DNS-01 manual (interactive) | `dns-request -interactive` | Single command with Enter prompt |
+| **Certificate Renewal** | | |
+| HTTP-01 challenge | `renew` | Automatic renewal via HTTP validation |
+| DNS-01 with provider | `renew` | Automatic renewal via DNS API |
+| DNS-01 manual (scripted) | `renew-dns` + `dns-complete` | Two-step process for automation |
+| DNS-01 manual (interactive) | `renew-dns -interactive` | Single command with Enter prompt |
+| Renewal failed | `renew-dns` | Use when `renew` shows "Manual DNS renewal required" |
+
+**Challenge Types:**
+
+| Challenge | Description | Use Case |
+|-----------|-------------|----------|
+| HTTP-01 | Validates via HTTP on port 80 | Standard domains, internet-accessible servers |
+| DNS-01 | Validates via DNS TXT record | Wildcard certs, internal servers, port 80 blocked |
+
+**DNS Provider Modes:**
+
+| Mode | Description |
+|------|-------------|
+| `auto` | Auto-detect DNS provider based on domain (default for dns-01) |
+| `selected` | Use specific provider (auto-set when `-provider-id` is provided) |
+| Manual | Use `dns-request`/`dns-complete` commands |
+
+> **Note:** When using `-challenge dns-01`:
+> - If `-dns-provider` is not specified, it defaults to `auto`
+> - If `-provider-id` is specified, `-dns-provider` is automatically set to `selected`
+
+**Supported DNS Providers:**
+- Cloudflare
+- AWS Route 53
+- GoDaddy
+- Custom Script
+
+**Notes:**
+- HTTP-01 challenge (default) requires port 80 to be accessible from the internet.
+- DNS-01 challenge is required for wildcard certificates (e.g., `*.example.com`).
+- DNS-01 with DNS provider enables full automation including auto-renewal.
+- Production environment has rate limits. Test with staging first.
+- SYSTEM_ADMIN role is required for all Let's Encrypt operations.
+
+#### cert-api Common Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-api-key <key>` | API key (optional for `-letsencrypt` if logged in) | - |
+| `-host <url>` | Signer Server URL | `https://localhost:7443` |
+| `-profile <name>` | Use settings from config profile | default |
+| `-format <type>` | Output format (json, pem, der) | text |
+| `-o <dir>` | Output directory | Current directory |
+| `-name <name>` | Name for upload/create | Filename |
+| `-desc <text>` | Description | - |
+| `-password <pwd>` | PFX/encrypted key password | - |
+| `-storage <type>` | Storage type: DB, SW_HSM, HW_HSM | DB |
+| `-hsm-slot <id>` | HSM slot ID (required for HW_HSM) | - |
+| `-hsm-pin <pin>` | HSM PIN (for HSM objects) | - |
+| `-include-chain` | Include certificate chain | - |
+| `-delete-related` | Delete related private key | - |
+
+---
+
 ### DLL System Installation (Windows)
 
 For system-wide DLL access (required for signtool integration), install DLLs to System32:
@@ -562,11 +1639,22 @@ signercli -config set automation \
     -host https://signer.example.com \
     -output-format json
 
+# Create a profile with API key (no login required)
+signercli -config set cert-api \
+    -host https://signer.example.com:7443 \
+    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
+
 # Use the profile
 signercli -login -profile production
-signercli myapp.exe -profile production
+signercli myapp.exe -profile production          # Implicit form
+signercli -sign myapp.exe -profile production    # Explicit form (same result)
 signercli document.pdf -profile pdf-signing
 signercli -verify myapp.exe -profile automation  # Outputs JSON automatically
+
+# Use API key profile (no login required)
+signercli -cert list -profile cert-api
+signercli -cert get <id> -profile cert-api
+signercli -cert upload cert.pem -profile cert-api
 ```
 
 ## Supported File Types
@@ -589,11 +1677,13 @@ signercli -verify myapp.exe -profile automation  # Outputs JSON automatically
 └── bin/
     ├── signercli.js      # Cross-platform wrapper
     ├── signer.js         # Windows KSP wrapper
+    ├── linux-x64/
+    │   └── signercli     # Fully static binary (no dynamic dependencies)
     └── win32-x64/
-        ├── signercli.exe # 9.3 MB (static build)
-        ├── signer.exe    # 420 KB (static build)
-        ├── otpkey.dll    # 6.2 MB (static linked)
-        └── Certchip.dll  # 700 KB (KSP provider)
+        ├── signercli.exe # Static build
+        ├── signer.exe    # Static build
+        ├── otpkey.dll    # Static linked
+        └── Certchip.dll  # KSP provider
 ```
 
 ### Binary Comparison
@@ -789,14 +1879,59 @@ On Linux/macOS, ensure the binary is executable:
 chmod +x node_modules/@certchip/signer/bin/*/signercli
 ```
 
+## Build from Source
+
+### Linux x64 (Fullstatic)
+
+Build a fully static binary for Linux distribution (no dynamic library dependencies):
+
+```bash
+cd core/signer-cli
+
+# Fullstatic build (auto-builds libcurl.a if missing)
+./build_fullstatic_linux_x64.sh
+
+# Or step by step:
+./build_fullstatic_linux_x64.sh --check       # Check static library dependencies
+./build_fullstatic_linux_x64.sh --build-curl   # Build static libcurl if missing
+./build_fullstatic_linux_x64.sh               # Build fullstatic binary
+
+# Output: bin/linux-x64/signercli (fully static, no dynamic dependencies)
+```
+
+Required static libraries (in `../../libs/`):
+- OpenSSL 3.4.1 (`libssl.a`, `libcrypto.a`)
+- cJSON (`libcjson.a`)
+- json-c (`libjson-c.a`)
+- libcurl (`libcurl.a`)
+- libotpkey (`libotpkey.a`)
+
+### Windows x64 (MSYS2)
+
+```bash
+cd core/signer-cli
+
+# Static build for npm package
+make -f Makefile.msys2 STATIC_CURL=1 RELEASE=1
+
+# Build + copy dependencies for npm
+make -f Makefile.msys2 npm-package
+```
+
+### Debug Build (any platform)
+
+```bash
+cd core/signer-cli
+make              # Debug build (auto-detects platform)
+make RELEASE=1    # Release build
+```
+
 ## Requirements
 
 - **Node.js** >= 14.0.0
-- **Platforms**: Windows x64 (Linux x64/arm64, macOS x64/arm64 coming soon)
+- **Platforms**: Windows x64, Linux x64 (macOS x64/arm64 coming soon)
 - **Server**: Certchip Signer API compatible server
 
-> **Note:** The current npm package includes Windows x64 binaries only. Linux and macOS binaries will be added in a future release.
-
 ## License
 
 Copyright (c) 2025 Certchip. All rights reserved.
@@ -806,3 +1941,10 @@ Copyright (c) 2025 Certchip. All rights reserved.
 - [Homepage](https://certchip.com/signer)
 - [Documentation](https://certchip.com/signer/help)
 - [Issues](https://github.com/certchip/signer-cli/issues)
+
+## Additional Documentation
+
+- [Configuration File Guide](docs/CONFIG-FILE-GUIDE.md) - Profile and config file options
+- [cert-dist Guide](docs/cert-dist-guide.md) - Let's Encrypt certificate distribution
+- [Server API Key Auth Guide](docs/SERVER-API-KEY-AUTH-GUIDE.md) - Server-side API key implementation
+- [Server Cert API Endpoints](docs/SERVER-CERT-API-ENDPOINTS.md) - Certificate API specification