direnv: Per-Directory Environment

The problem direnv solves

You want OPENAI_API_KEY set when you're in ~/projects/ai-app and not set when you leave. Manually export-ing and unset-ing is error-prone. direnv automates it: create .envrc in the directory, allow it once, and direnv loads/unloads on every cd.

Setup

brew install direnv
# Add to ~/.zshrc, end of file
eval "$(direnv hook zsh)"

Use

# inside ~/projects/ai-app
echo 'export OPENAI_API_KEY=sk-...' > .envrc
echo 'PATH_add bin' >> .envrc      # adds ./bin to PATH
direnv allow                              # one-time approval
echo $OPENAI_API_KEY                      # set
cd /tmp
echo $OPENAI_API_KEY                      # empty

The direnv allow step is the security gate — random .envrc files don't auto-execute when you cd into them.

Common .envrc patterns

• export DATABASE_URL=postgres://...
• PATH_add ./bin — prepend a project bin directory.
• source_env ../shared.envrc — share a parent's envs.
• layout python3 — auto-create and activate a venv.
• use mise — bridge to a project-pinned mise tool stack.

Why this beats alternatives

Compared to manual export, direnv never forgets to unset on exit. Compared to dotfile-loader frameworks, it's tiny (one binary). Compared to docker-compose for env, it's instant — no container start. The Pippa stack uses direnv to auto-activate the conda env when you cd into cwkPippa, for the same reason.