envpkt shell-hook

Generate a shell function that, on every directory change, loads the credentials for the directory you’re in and restores your environment when you leave. It resolves the nearest envpkt.toml (walking up from the current directory), injects that package, and prints a one-line credential-health warning.

Usage

envpkt shell-hook <shell>              # shell: zsh | bash
envpkt shell-hook <shell> --no-audit   # omit the on-cd health-check line

--no-audit drops step 4 (the audit spawn) from the emitted hook — useful on slower machines where you don’t want the per-package-entry health check.

Setup

# zsh (~/.zshrc)
eval "$(envpkt shell-hook zsh)"

# bash (~/.bashrc)
eval "$(envpkt shell-hook bash)"

Behavior

On each cd the hook:

1. Resolves the package for the new directory via envpkt config-path (walks up to the nearest envpkt.toml, like git/direnv). If it’s the same package as before — e.g. you moved between subdirectories of one project — it does nothing.
2. Restores the previous package’s variables to their prior values (or unsets them if they had none), so leaving a project never leaks its credentials into the next one.
3. Injects the new package via envpkt env export --track. Env defaults are always loaded; secret values load only when the package sets scope = "shell" — otherwise use envpkt exec.
4. Warns on credential health via envpkt audit --format minimal.

Decryption happens only when the resolved package changes (not on every cd), and only the resolve step runs in subdirectories of the same project — so the hook stays cheap.

Ambient loading needs an unlocked key

Because the hook decrypts on cd, it can’t prompt for a passphrase. A scope = "shell" package must use a key that resolves non-interactively (a plain 0600 key file, or ENVPKT_AGE_KEY/ ENVPKT_AGE_KEY_FILE). Passphrase- or manager-locked keys are for bootstrapping or for scope = "exec" packages, where you launch deliberately. If a shell-scope package’s key is missing, the hook surfaces a clear error on cd and injects nothing (see fail-fast key handling).

Related: envpkt config-path

The hook gates on envpkt config-path, a resolve-only command that prints the envpkt.toml path for the current directory (empty if none) — no decryption, no boot. It’s handy in scripts too:

envpkt config-path            # /Users/me/proj/envpkt.toml   (from anywhere in proj/)

See the Shell Hooks integration for the full setup.