envpkt secret

CRUD subcommands for [secret.*] entries. All writes preserve file formatting and can be previewed with --dry-run.

Usage

envpkt secret add    <name> [options]
envpkt secret edit   <name> [options]
envpkt secret rm     <name> [options]
envpkt secret rename <old> <new> [options]
envpkt secret alias  <name> --from secret.<TARGET> [options]

secret add

Create a new [secret.<name>] block with metadata. Errors if <name> already exists.

| Option | Description | | --------------------- | ------------------------------------------------- | | -c, --config <path> | Path to envpkt.toml | | --service <name> | Service this secret authenticates to | | --purpose <text> | Why this secret exists | | --comment <text> | Free-form annotation | | --expires <date> | Expiration date (YYYY-MM-DD) | | --capabilities <cs> | Comma-separated capabilities (e.g., read,write) | | --rotates <sched> | Rotation schedule (e.g., 90d, quarterly) | | --rate-limit <info> | Rate limit info (e.g., 1000/min) | | --model-hint <hint> | Suggested model or tier | | --source <origin> | Where the value comes from (e.g., vault, ci) | | --rotation-url <u> | URL for rotation procedure | | --tags <pairs> | Comma-separated key=value tags | | --required | Mark secret as required | | --dry-run | Preview the TOML block without writing |

envpkt secret add STRIPE_API_KEY \
  --service stripe \
  --purpose "Payment processing" \
  --expires 2026-06-30 \
  --capabilities "charges,refunds" \
  --rotates 90d \
  --required

secret edit

Update fields on an existing secret. Supports every secret add option plus --no-required to unset the required flag. Errors if <name> doesn’t exist. Use --dry-run to preview.

envpkt secret edit STRIPE_API_KEY --expires 2026-12-31 --rotates 60d
envpkt secret edit STRIPE_API_KEY --no-required

Removing optional fields with --unset

Setting a field is reversible: --unset <field> removes an optional metadata field entirely. It’s repeatable, and the field names are the TOML keys you see in the file (e.g. rate_limit, not rate-limit). You can unset any field you can set with a flag — structural/managed fields (created, encrypted_value, from_key) are owned by seal/rotate/alias and are not unsettable here. An unknown field name is rejected rather than silently ignored.

# Drop a single field
envpkt secret edit STRIPE_API_KEY --unset expires

# Drop several at once
envpkt secret edit STRIPE_API_KEY --unset expires --unset rate_limit

--dry-run runs the same schema validation as the real write, so a preview never shows a result the write would reject.

secret rm

Remove a secret entry from the file.

| Option | Description | | --------------------- | ---------------------------------- | | -c, --config <path> | Path to envpkt.toml | | --dry-run | Preview the result without writing |

envpkt secret rm STRIPE_API_KEY
envpkt secret rm STRIPE_API_KEY --dry-run

secret rename

Rename a secret, preserving all metadata.

| Option | Description | | --------------------- | ---------------------------------- | | -c, --config <path> | Path to envpkt.toml | | --dry-run | Preview the result without writing |

envpkt secret rename STRIPE_API_KEY STRIPE_SECRET_KEY

secret alias

Create an alias entry that reuses another secret’s resolved value — useful when a consumer hardcodes a different env var name than the one you govern canonically. See Aliases for the feature overview.

| Option | Description | | --------------------- | ------------------------------------------------------ | | --from <ref> | Required. Target reference, must be secret.<KEY> | | -c, --config <path> | Path to envpkt.toml | | --purpose <text> | Why this alias exists (local metadata, not inherited) | | --comment <text> | Free-form annotation | | --tags <pairs> | Comma-separated key=value tags | | --force | Overwrite the entry if <name> already exists | | --dry-run | Preview the TOML block without writing |

# Basic alias — STRIPE_LEGACY_KEY resolves to STRIPE_API_KEY's value
envpkt secret alias STRIPE_LEGACY_KEY --from secret.STRIPE_API_KEY

# With local metadata
envpkt secret alias STRIPE_LEGACY_KEY \
  --from secret.STRIPE_API_KEY \
  --purpose "Legacy env var name the older SDK still reads"

# Overwrite protection — without --force, warns and exits if name exists
envpkt secret alias STRIPE_LEGACY_KEY --from secret.STRIPE_API_KEY
# Warning: secret "STRIPE_LEGACY_KEY" already exists. Pass --force to overwrite.

envpkt secret alias STRIPE_LEGACY_KEY --from secret.STRIPE_API_KEY --force

Rejection rules (enforced at write time)

| Case | Behavior | | ----------------------------------------- | ------------------------------------------------------------------------- | | --from missing or not secret.<KEY> | Exit with error | | --from points at an env.* entry | Reject — use envpkt env alias for env aliases | | Target doesn’t exist in config | Reject — add the target secret first | | Target is itself an alias | Reject — chained aliases are not supported | | <name> equals the target key | Reject — self-reference | | <name> already exists without --force | Warn and exit; report whether existing entry was regular or another alias |

At runtime the load-time validator re-checks these rules, so configs hand-edited to bypass the CLI checks still fail to boot with a clear AliasError (see Error Types).

Notes

• Secret values are not stored by any secret subcommand — only metadata. Use envpkt seal to encrypt values into encrypted_value, or let boot() resolve them from fnox at runtime.
• Every subcommand supports --dry-run to preview the resulting file without writing.
• -c, --config <path> defaults to the standard discovery chain (CWD → ENVPKT_CONFIG → ~/.envpkt/ → cloud storage).