envpkt audit

Audit all secrets in envpkt.toml against lifecycle policies. Reports expiration status, staleness, missing metadata, and orphaned keys. Automatically resolves catalog references before auditing.

Usage

envpkt audit [options]

Options

| Option | Description | Default | | --------------------- | ----------------------------------------------------------------------------------------------------------- | ------------- | | -c, --config <path> | Path to envpkt.toml | Auto-detected | | --format <format> | Output format: table, json, minimal | table | | --expiring <days> | Show secrets expiring within N days | — | | --status <status> | Filter by status: healthy, expiring_soon, expired, stale, missing, missing_metadata, external | — | | --strict | Exit non-zero on any non-healthy secret | false | | --all | Show both secrets and [env.*] defaults drift | false | | --env-only | Show only [env.*] defaults (drift detection) | false | | --sealed | Show only secrets with encrypted_value (sealed packets) | false | | --unsealed | Show only secrets without encrypted_value (resolved at runtime, or external = true) | false | | --sort | Sort secrets alphabetically within each status bucket (no file mutation) | false |

--unsealed and --status external answer different questions. --unsealed lists every secret with no sealed value, whether envpkt resolves it at runtime (env, fnox) or it is declared external = true. --status external lists only the external = true entries: values managed entirely outside envpkt, such as a Cloudflare Worker secret or Vault.

Examples

# Standard audit
envpkt audit

# JSON output for CI
envpkt audit --format json

# Secrets expiring within 2 weeks
envpkt audit --expiring 14

# Only show expired secrets
envpkt audit --status expired

# Strict mode for CI pipelines
envpkt audit --strict

# Specify config path
envpkt audit -c path/to/envpkt.toml

# Include env defaults drift alongside secrets
envpkt audit --all

# Show only env defaults drift
envpkt audit --env-only

# Show only sealed (encrypted) secrets
envpkt audit --sealed

# Show only unsealed secrets (no encrypted_value)
envpkt audit --unsealed

# Show only secrets declared external = true (managed outside envpkt)
envpkt audit --status external

Exit Codes

| Code | Status | Description | | ---- | -------- | --------------------------------------- | | 0 | healthy | All secrets pass audit | | 1 | degraded | Some secrets are expiring soon or stale | | 2 | critical | Expired or missing secrets detected |

With --strict, any non-healthy secret causes a non-zero exit.

Secret Statuses

| Status | Meaning | | ------------------ | ---------------------------------------------------------------------------------------------------- | | healthy | Secret is valid and within policy | | expiring_soon | Secret expires within stale_warning_days | | expired | Secret has passed its expiration date | | stale | Secret is older than stale_warning_days without updates | | missing | Secret key exists in config but has no metadata | | missing_metadata | Required fields (service, expiration) are absent | | external | external = true: value managed outside envpkt. Shown only when no other non-healthy status applies |

Aliases

Entries with from_key (see Aliases) appear as separate rows in audit output with an alias_of field identifying their target. Their status, expires, and days_remaining are inherited from the target — an alias is healthy if and only if its target is. The audit response also includes an aliases count alongside total, healthy, etc.