poenv

Your configs and secrets in one encrypted vault on your machine. Switch a repo's .env between environments with one command, and let AI agents use your secrets without poenv ever showing them the values.

cd my-app
poenv init                 # import the env file into the vault
poenv use staging          # the env file is now on staging
poenv add OPENAI_API_KEY   # pull in a key you share across apps
poenv run -- npm test     # inject the env without writing a file

Install

No sudo or admin rights. Installs to ~/.local/bin (Windows: %LOCALAPPDATA%\poenv\bin), checks the SHA-256 and adds that folder to your PATH.

Installer options

Pass flags through sh -s --:

curl -fsSL https://poenv.pogi.codes/install.sh | sh -s -- --version 0.6.1

On Windows, set the env vars before running the installer. You can also download a binary from Releases (macOS, Linux and Windows, x64 and arm64).

Update

Run the installer again. It replaces the binary and leaves your vault, PATH and repos alone. poenv --version shows what you have; --version X pins or rolls back.

Uninstall

1. poenv lock, so the unlocked key leaves your temp folder.
2. Delete the binary: rm ~/.local/bin/poenv (Windows: %LOCALAPPDATA%\poenv\bin\poenv.exe).
3. Remove the line ending in # added by poenv installer from your shell rc file (Windows: remove the folder from your user Path).
4. Optional and permanent: delete the vault in ~/.poenv (Windows: %APPDATA%\poenv). Run poenv backup first if you might want your secrets back.

Repos keep working: each env file still holds the env it was last switched to. Delete .poenv and the poenv section in AGENTS.md if you like.

Quick start

1. Check your setup.

   poenv doctor

   It checks PATH, the vault and the current repo, and prints the exact command for anything to fix.
2. Set up a repo.

   cd your-repo
   poenv init

   The first time on a machine, init asks you to choose a master password, then shows a 24-word recovery phrase, once. Save the phrase in your password manager: it's the only way back in if you forget the password, and it opens your backups.

   init then imports your existing env file into the local env, creates staging and prod (protected), writes .poenv, gitignores it and the env file, and adds poenv notes to AGENTS.md or CLAUDE.md.

3. Fill in another env and switch to it.

   poenv set DATABASE_URL --env staging   # asks for the value, hidden
   poenv use staging

   Or paste KEY=VALUE lines into the env file and run poenv import --env staging, or run poenv on its own to edit everything in the TUI.

Concepts

Switching envs

poenv use staging

✓ my-app: local → staging  (.env.local)
  ~ DATABASE_URL
  ~ STRIPE_SECRET_KEY
  + SENTRY_DSN

poenv rewrites the managed block of the repo's env file and lists what changed, by key name only. With no argument, poenv use opens a picker. Running apps need a restart unless they reload .env themselves.

Manage envs

poenv env new preview --from staging   # copy an env (or omit --from for an empty one)
poenv env rename preview qa            # the env file and .poenv follow
poenv ls                               # apps, envs and key names

Show the env in your prompt

poenv status --short prints my-app:staging. It never opens the vault, so it's instant and safe to run on every prompt.

Shared keys

Keys you use in many apps, like an API key, belong in the shared pool. Set it once, then reference it from each app:

poenv set OPENAI_API_KEY --shared              # once
poenv add OPENAI_API_KEY                       # in each repo: a live reference
poenv add OPENAI_API_KEY --as NEXT_PUBLIC_OPENAI_KEY   # under another name

Rotating it with poenv set OPENAI_API_KEY --shared rewrites the env file of every repo on this machine that uses it, and lists those files.

To copy a value once instead, with no link, take it from another app: poenv add STRIPE_KEY --from other-app/staging.

When init finds a key with the same name and value in another app, it offers to move it into the shared pool and turn each copy into a reference.

Removing a shared key

poenv never leaves dangling references. If apps still use the key, choose:

• poenv rm KEY --shared --keep-copies: each app keeps its own copy, with history. This is how you undo sharing.
• poenv rm KEY --shared --everywhere: the references go too.

Protected envs

prod is protected from the start. Switching to a protected env, running with it, or copying or renaming it asks a person to type a confirmation. Agents and scripts are refused with exit 4, and --yes doesn't skip it. Toggle protection on any env with P in the TUI.

Running without a file

poenv run -- npm test                 # the current env
poenv run staging -- npm run migrate  # another env

poenv run injects the env as variables into one command and leaves the env file alone. Nothing is written to disk and no quoting applies, so use it for tools that don't read .env, for values a loader can't parse, or when you'd rather not have secrets in a file at all. It passes through the command's output and exit code. Anything after --, including --json, belongs to your command.

Frameworks & formats

poenv works with anything that reads a .env-style file. init picks the file and quoting format from the repo:

If the repo's env files already hold keys, init uses the file that has them (and asks when several do). Override with --file and --format, or edit .poenv.

The format only matters for values containing $ or escapes, which loaders read differently. Each format is checked in CI against the real Node dotenv, Next.js and python-dotenv loaders.

A few values can't be written exactly in some formats (for example ${…} for python). poenv writes them as best it can, lists the keys, and suggests poenv run.

Java & Spring Boot

Spring Boot doesn't read .env files, so poenv use alone changes nothing for it. Inject the env with poenv run:

poenv run -- ./mvnw spring-boot:run
poenv run staging -- ./gradlew bootRun

Spring reads environment variables natively: reference them in application.properties (spring.datasource.password=${DB_PASSWORD}), or name keys for relaxed binding (SPRING_DATASOURCE_URL sets spring.datasource.url).

With Docker Compose, env_file: .env reads the file poenv writes. Avoid spring.config.import=optional:file:.env[.properties]: properties files don't strip quotes, so any value poenv quotes keeps its quotes.

The TUI

Run poenv on its own in a terminal to browse and edit apps, envs and keys. Values stay masked until you press v. Inside a repo it opens on that repo's app. Lowercase keys act on the selected key, uppercase on the whole env.

Locking & CI

poenv stays unlocked for 12 hours at a time, across every terminal on the machine. When it's locked, commands and the TUI ask for your password.

poenv unlock --for 8h   # any duration: 30m, 8h, 2d
poenv lock              # close it early
poenv status            # shows the lock state

Agents can't type the password, so while locked they get exit 5 and ask you to run poenv unlock.

On CI and servers, pipe the password in from your secret store:

printf '%s' "$VAULT_PASSWORD" | poenv unlock --stdin

Set POENV_HOME to keep the vault somewhere other than the default folder.

Backup & recovery

poenv backup backup.enc    # encrypted copy of the vault
poenv restore backup.enc   # restore it, on this machine or another

A backup plus your recovery phrase restores everything on any machine: on a new machine, restore asks for the phrase, then for a password for that machine. Restoring over an existing vault asks first and keeps the old one as store.enc.bak-<time>.

Commands

Every command takes --json for machine-readable output, except poenv run. Values are never accepted as arguments: set asks for them hidden, or reads them from stdin.

Daily

Setup & management

Just for you

These reveal values or touch the whole vault, so they're refused for agents and scripts (exit 4).

history, rollback and rm also take --shared and --env ENV.

Exit codes

Stable, so scripts and agents can act on them. Errors always say the command that fixes them.

The env file

poenv owns one block at the top of the env file and never touches anything else (except during init and import, which move the keys they import into the block):

# >>> poenv >>> (managed: edits here are overwritten)
# app: my-app  env: staging
DATABASE_URL=postgres://staging-db/app
OPENAI_API_KEY='sk-…'
# <<< poenv <<<

DEBUG=true   # yours: kept as-is, and it wins over the block

Because the block is at the top, your own lines below it override it in every loader. A key set in both places is reported as a conflict.

A change made anywhere (set, add, rm, rollback, or the TUI) also rewrites the block in every other repo on this machine whose current env it affects. Each repo stays on its own env.

The .poenv file

Written by init at the repo root. It holds names only, never secrets.

app    = "my-app"
env    = "local"        # the env the file is on
file   = ".env.local"   # the env file poenv writes
format = "next"         # dotenv | next | python

It's gitignored by default. You can commit it instead: a teammate's poenv init in a fresh clone then adopts its settings, and poenv leaves a tracked .poenv alone.

Files & settings

For AI agents

Agents can do the daily work: check status, list key names, switch envs and run commands with secrets injected. poenv never prints a value to them, never accepts one as an argument, and keeps values out of --json.

poenv status --json              # which app/env this repo is on
poenv ls --json                  # envs and key names, never values
poenv use staging --json         # switch the env file
poenv run staging -- npm test    # run with an env injected
poenv doctor --json              # when something is off: follow each "fix"

Agents are refused (exit 4) for get, history, rollback, backup, restore, recover and protected envs, and can't create the vault (exit 5), since that shows the recovery phrase.

poenv init adds a short section to AGENTS.md / CLAUDE.md telling agents these rules. To have an agent install poenv, point it at llms.txt or the agent install guide, or say:

The /poenv skill

Install the poenv agent skill once and every coding agent on your machine knows these rules in any repo: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and more.

Then type /poenv setup or /poenv use staging ($poenv in Codex). Agents also reach for it on their own when you ask about env vars.

How poenv tells people from agents

A person has an interactive terminal on stdin and stdout and none of the markers coding agents set (CLAUDECODE, CODEX_SANDBOX, CURSOR_AGENT, GEMINI_CLI, AI_AGENT, …). A CI variable counts as a script too.

Security model

• While locked, nothing can read your secrets: not other programs, not agents. The master key is stored only encrypted with your password (scrypt).
• While unlocked, the master key sits in an owner-only session file until the session expires. Programs running as you can read it then, which is what lets agents work. poenv lock ends it early.
• Encryption protects the vault file against being copied: backups, sync folders, a stolen disk. It is not a sandbox against programs running as you.
• Values are never printed by agent-usable commands, never accepted as arguments (so they stay out of shell history), and never in --json output.
• Once a value is written to an env file, anything that can read that file can read it, and a command run with secrets injected can print them. poenv run avoids writing files at all.

Troubleshooting

Start with poenv doctor. It checks PATH, the vault, the lock, your saved phrase, gitignore, agent notes, dangling shared references and whether the env file is up to date, and names the fix for each. poenv doctor --fix applies the safe ones; it never runs sudo.

poenv: command not found after installing

Open a new terminal so the PATH change applies, or use the full path the installer printed.

My app still sees the old values

Restart it: most dev servers read .env only at startup. Also check you don't set the same key below the poenv block, since your lines win.

A value with $ comes out wrong

Your loader expands variables. Switch the format (--format next escapes $), or use poenv run. See Frameworks & formats.

An agent keeps getting exit 5

poenv is locked, or the vault doesn't exist yet. Run poenv unlock (or the first poenv init) in your own terminal. Never give the agent your password.