envpkt env (add / edit / rm / rename / alias)

CRUD subcommands for [env.*] entries — the plaintext, non-secret environment defaults that live in envpkt.toml. For scan / check / export workflows, see envpkt env scan, envpkt env check, and envpkt env export.

Usage

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

env add

Create a new [env.<name>] block with a plaintext default value. Errors if <name> already exists.

Option	Description
-c, --config <path>	Path to envpkt.toml
--purpose <text>	Why this env var exists
--comment <text>	Free-form annotation
--tags <pairs>	Comma-separated key=value tags
--dry-run	Preview the TOML block without writing

envpkt env add NODE_ENV production --purpose "Runtime mode"
envpkt env add LOG_LEVEL info      --comment "Override to 'debug' locally"

env edit

Update fields on an existing env entry.

Option	Description
-c, --config <path>	Path to envpkt.toml
--value <text>	New default value
--purpose <text>	Update purpose
--comment <text>	Update comment
--tags <pairs>	Replace tags (comma-separated key=value)
--dry-run	Preview the changes without writing

envpkt env edit LOG_LEVEL --value warn
envpkt env edit NODE_ENV  --purpose "Application runtime mode (deprecated — use APP_ENV)"

env rm

Remove an env entry from the file.

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

envpkt env rm LEGACY_FLAG

env rename

Rename an env entry, preserving all fields.

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

envpkt env rename NODE_ENV APP_ENV

env alias

Create an alias entry that reuses another env entry’s resolved value. Useful for exposing the same configuration default under multiple canonical names. See Aliases for the feature overview.

Option	Description
--from <ref>	Required. Target reference, must be env.<KEY>
-c, --config <path>	Path to envpkt.toml
--purpose <text>	Why this alias exists (local metadata)
--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 — LEGACY_URL resolves to SERVICE_URL's value
envpkt env alias LEGACY_URL --from env.SERVICE_URL

# With local metadata
envpkt env alias LEGACY_URL \
  --from env.SERVICE_URL \
  --purpose "Legacy name kept for backwards compatibility"

# Overwrite protection — without --force, warns and exits if name exists
envpkt env alias LEGACY_URL --from env.SERVICE_URL --force

Rejection rules (enforced at write time)

Case	Behavior
--from missing or not env.<KEY>	Exit with error
--from points at a secret.* entry	Reject — use envpkt secret alias for secret aliases
Target doesn’t exist in config	Reject — add the target env entry 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

• [env.*] entries hold non-secret plaintext defaults. For credentials, use envpkt secret and seal the values with envpkt seal.
• 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).