mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 19:31:31 +00:00
shankar0123
2ea5d5ec57
Operator policy: docs in the public repo must help (a) a user
deploying certctl or (b) the product story. Internal engineering
process documentation belongs in cowork/ scratchpads or in git
commit history, not docs/.
Removed (docs/contributor/, 8 files, 2,323 lines):
- release-sign-off.md — internal release-day checklist
- ci-pipeline.md — what runs in CI (internal)
- ci-guards.md — what the guards are (internal)
- testing-strategy.md — internal testing strategy
- qa-test-suite.md — internal QA reference (445 lines)
- qa-prerequisites.md — internal QA setup
- gui-qa-checklist.md — manual GUI QA checklist
- test-environment.md — 1,103-line redundant with
docs/getting-started/quickstart.md +
docs/getting-started/advanced-demo.md
Removed supporting script:
- scripts/qa-doc-seed-count.sh — CI guard for the deleted
qa-test-suite.md seed-data table
Cross-reference cleanup:
- README.md: dropped the Contributor audience row + footer
pointer to docs/contributor/.
- Makefile: dropped `verify-docs` target + qa-stats comment refs.
- .github/workflows/ci.yml: dropped the QA-doc seed-count drift
CI step + dead comment refs.
- docs/reference/cli.md: repointed qa-prerequisites.md → quickstart.md.
- docs/operator/performance-baselines.md: dropped ci-pipeline.md
cross-ref.
- scripts/ci-guards/README.md: dropped the 'Guards explicitly
NOT here' section that referenced the deleted QA-doc guards.
G-3 env-docs-drift guard improvements (a real consequence: deleting
the contributor docs surfaced that some env vars only had a home
there). Refit the guard to the new doc topology:
- Defined-scan widened from `config.go + cmd/*` to all of `cmd/ +
internal/` (production code), excluding `*_test.go` — catches
service-layer env vars like CERTCTL_STEPCA_ROOT_CERT and
CERTCTL_ZEROSSL_EAB_URL that were previously invisible to the
guard.
- Docs-scan widened to include deploy/ENVIRONMENTS.md (the
canonical env-var inventory table — should have been in scope
from day one). Kept narrow to README + docs/ + deploy/helm/ +
ENVIRONMENTS.md to avoid pulling in compose/test fixtures.
- ALLOWED filter now applies to both DOCS_ONLY and CONFIG_ONLY
directions, so dynamic per-profile dispatch surfaces
(CERTCTL_SCEP_PROFILE_<NAME>_*, CERTCTL_EST_PROFILE_<NAME>_*,
CERTCTL_QA_*) don't need static doc entries.
- Added CERTCTL_SCEP_PROFILE_[A-Z_]+ and CERTCTL_EST_PROFILE_[A-Z_]+
to ALLOWED for the same reason.
deploy/ENVIRONMENTS.md: added CERTCTL_ZEROSSL_EAB_URL row — real
operator override (overrides the ZeroSSL EAB-credentials endpoint;
read at internal/connector/issuer/acme/acme.go:372) that was
defined in Go source but never documented. G-3 caught it after the
defined-scan widened.
scripts/ci-guards/S-1-hardcoded-source-counts.sh: removed dead
WORKSPACE-CHANGELOG.md allowlist entry (the file was deleted in
the prior workspace cleanup).
Verified:
All 35 scripts/ci-guards/*.sh green (FAIL=0).
No remaining references to docs/contributor/ or qa-doc-seed-count
in tracked files.
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
# certctl CLI
|
|
|
|
> Last reviewed: 2026-05-05
|
|
|
|
`certctl-cli` is the command-line interface to certctl. It wraps the REST API as terminal commands so operators and CI/CD pipelines can drive certctl without writing curl invocations.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
go install github.com/certctl-io/certctl/cmd/cli@latest
|
|
```
|
|
|
|
The binary lands at `$GOBIN/cli` (or `$HOME/go/bin/cli` if `GOBIN` is unset). Rename to `certctl-cli` if you prefer.
|
|
|
|
## Configure
|
|
|
|
The CLI reads three environment variables:
|
|
|
|
```bash
|
|
export CERTCTL_SERVER_URL=https://localhost:8443
|
|
export CERTCTL_API_KEY=your-api-key
|
|
export CERTCTL_SERVER_CA_BUNDLE_PATH=/path/to/ca.crt
|
|
```
|
|
|
|
Or pass them per-invocation:
|
|
|
|
```bash
|
|
certctl-cli --server https://localhost:8443 --api-key your-key --ca-bundle ca.crt certs list
|
|
```
|
|
|
|
For local development against a self-signed bootstrap cert, `--insecure` skips TLS verification. **Never set this in production.**
|
|
|
|
## Command groups
|
|
|
|
The CLI is organized by resource:
|
|
|
|
```
|
|
certctl-cli certs [list|get|renew|revoke]
|
|
certctl-cli agents [list|get]
|
|
certctl-cli jobs [list|get|cancel]
|
|
certctl-cli import [bulk PEM import]
|
|
certctl-cli est [enroll|reenroll]
|
|
certctl-cli status [server health + summary stats]
|
|
certctl-cli version [CLI + server version]
|
|
```
|
|
|
|
## Common workflows
|
|
|
|
### List + filter certificates
|
|
|
|
```bash
|
|
# All certs
|
|
certctl-cli certs list
|
|
|
|
# Filter by environment
|
|
certctl-cli certs list --env production
|
|
|
|
# JSON output (default is table)
|
|
certctl-cli certs list --format json
|
|
|
|
# Sort + paginate
|
|
certctl-cli certs list --sort -expires_at --limit 50
|
|
|
|
# Time-range filter (RFC 3339)
|
|
certctl-cli certs list --expires-before 2026-06-01T00:00:00Z
|
|
|
|
# Sparse fields — only return the columns you need
|
|
certctl-cli certs list --fields id,common_name,expires_at,status
|
|
```
|
|
|
|
### Trigger renewal
|
|
|
|
```bash
|
|
certctl-cli certs renew mc-api-prod
|
|
# Returns the job id; track with: certctl-cli jobs get <job-id>
|
|
|
|
# Recovery: clear a stuck in-flight renewal so a new one can start
|
|
certctl-cli certs renew mc-api-prod --force
|
|
```
|
|
|
|
`--force` clears the server-side `RenewalInProgress` block — used when a previous renewal job hung without releasing the status flag. `--force` does NOT override `Archived` or `Expired` (those are terminal states; archived = decommissioned, expired = issue a new cert instead of renewing a dead one).
|
|
|
|
### Revoke
|
|
|
|
```bash
|
|
# Single revoke — --reason is REQUIRED (no silent fallback to 'unspecified')
|
|
certctl-cli certs revoke mc-api-prod --reason keyCompromise
|
|
|
|
# snake_case is accepted and normalised to camelCase before dispatch
|
|
certctl-cli certs revoke mc-api-prod --reason key_compromise
|
|
|
|
# Bulk revoke by filter
|
|
certctl-cli certs revoke --profile prof-deprecated --reason superseded
|
|
certctl-cli certs revoke --team t-payments --reason cessationOfOperation
|
|
certctl-cli certs revoke --issuer iss-old-vault --reason caCompromise
|
|
```
|
|
|
|
`--reason` is mandatory: omitting it prints the canonical RFC 5280 §5.3.1 menu and exits non-zero. Compliance reporting (PCI-DSS §3.6, HIPAA §164.312) relies on the reason code being meaningful, so the CLI no longer falls back silently. Valid camelCase set: `unspecified`, `keyCompromise`, `caCompromise`, `affiliationChanged`, `superseded`, `cessationOfOperation`, `certificateHold`, `removeFromCRL`, `privilegeWithdrawn`, `aaCompromise`. snake_case variants (`key_compromise`, `cessation_of_operation`, etc.) are accepted and normalised.
|
|
|
|
### Bulk import
|
|
|
|
```bash
|
|
# Import a directory of PEMs
|
|
certctl-cli import /etc/letsencrypt/live/
|
|
|
|
# Import a single concatenated bundle
|
|
certctl-cli import certs.pem
|
|
```
|
|
|
|
Each cert lands in the inventory as `Unmanaged` (per the discovery model). Triage from the dashboard or via `certctl-cli certs claim <id>` once you've decided to actively manage it.
|
|
|
|
### EST enrollment
|
|
|
|
```bash
|
|
# Enroll a new device cert via EST simpleenroll
|
|
certctl-cli est enroll --csr device.csr --output device.crt
|
|
|
|
# Re-enroll (renew) an existing device cert
|
|
certctl-cli est reenroll --csr device.csr --client-cert device.crt --client-key device.key
|
|
```
|
|
|
|
### Server status
|
|
|
|
```bash
|
|
certctl-cli status
|
|
# Health: ok
|
|
# Total certificates: 145
|
|
# Expiring (30d): 12
|
|
# Active jobs: 3
|
|
# Pending renewals: 8
|
|
```
|
|
|
|
## Output formats
|
|
|
|
- `--format table` (default) — human-readable terminal output
|
|
- `--format json` — JSON for piping into `jq`, scripts, dashboards
|
|
|
|
The CLI is built with Go's standard library only — no external dependencies. The binary is small (~10MB) and statically linked.
|
|
|
|
## Wiring into CI/CD
|
|
|
|
Common pattern: a CI step that issues a cert from your internal CA, deploys it via certctl, and verifies the deploy:
|
|
|
|
```bash
|
|
certctl-cli certs renew mc-api-prod --wait
|
|
certctl-cli jobs get $(certctl-cli certs renew mc-api-prod --json | jq -r '.job_id') --wait
|
|
certctl-cli certs get mc-api-prod --json | jq -r '.expires_at'
|
|
```
|
|
|
|
The `--wait` flag blocks until the job reaches a terminal state (Completed / Failed / Cancelled), which is what CI scripts actually need.
|
|
|
|
## Related docs
|
|
|
|
- [`docs/reference/api.md`](api.md) — the OpenAPI 3.1 spec the CLI wraps
|
|
- [`docs/reference/mcp.md`](mcp.md) — the MCP server that exposes the same surface to AI assistants
|
|
- [`docs/getting-started/quickstart.md`](../getting-started/quickstart.md) — local environment setup before the CLI can talk to a server
|