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

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).