penvhq

One static binary. Works before you have an account. The cloud is the upgrade.

Install · First minute · With a team · Coding agents · Commands ·

penv reads the .env you already have, writes a small committed schema next to it, validates every value before your process starts, generates types for your language, and configures your coding agent's harness so it cannot read the file. When you are ready for a team, one command moves the values to penv.cloud and deletes the file.

Install

curl -fsSL https://penv.cloud/install | sh   # macOS, Linux

irm https://penv.cloud/install.ps1 | iex     # Windows

npm i -g @penvhq/cli@next                         # any of them, when npm should own it

The first two put one static binary in ~/.penv/bin, or %USERPROFILE%\.penv\bin on Windows, and print the line that adds it to your PATH; no rc file is edited and nothing else is written. PENV_INSTALL_DIR moves it, PENV_VERSION pins a tag, and every download is checked against the digest the release publishes before it lands. The PowerShell one writes your user PATH when you ask: -AddToPath when you run the file, $env:PENV_ADD_TO_PATH = '1' when you pipe it through iex, which has no flags to pass. Builds: linux and macOS on x86_64 and arm64, Windows on x86_64 and arm64.

Every release signs its checksum file with penv's Ed25519 release key. A build that carries a release key refuses a download whose signature does not hold; a build carrying none cannot upgrade at all and is replaced by running an installer above. The shell installer checks the signature wherever OpenSSL 1.1.1 or newer is on PATH, and the PowerShell one says so and installs on the digest, since .NET has no Ed25519.

penv upgrade replaces the binary those two installers placed. It refuses on an npm install, where the binary lives inside node_modules and npm i -g @penvhq/cli is the upgrade, and likewise under Homebrew, Nix, winget and Scoop.

The first minute

No account, no sign-in.

penv init                 # reads .env, writes .env.schema, gitignores .env
penv run -- pnpm dev      # validates, injects, masks

init writes this, and only this, into your repository:

# @schema=1

# @type=url
DATABASE_URL=

# @type=string
STRIPE_SECRET_KEY=

# @type=port @sensitive=false
PORT=3000

# @type=boolean @sensitive=false
DEBUG=true

Every key is sensitive and required unless a bundler prefix like NEXT_PUBLIC_ or a dull value like 3000 or us-east-1 says otherwise, and a key named for what it holds, such as STRIPE_SECRET_KEY or NEXT_PUBLIC_SUPABASE_ANON_KEY, keeps its value out whatever the value looks like and whatever prefix it carries. No value that could be a secret is ever copied into the schema. Edit the file if a guess is wrong; the decorators follow the @env-spec vocabulary, so a varlock user reads it on sight.

With a team

penv login          # device code in the browser
penv push           # values go to the cloud, .env is deleted

From then on the cloud is the store and .env is a view you can regenerate with penv pull. A teammate clones the repo and types penv run -- pnpm dev; that is the whole onboarding. CI presents its OIDC token and gets a fifteen minute credential. A server with nothing to present enrols a keypair once.

Typed access

penv gen ts        # a typed cast over your runtime's env plus a Standard Schema validator
penv gen py        # penv_env.py on the standard library, or pydantic when your project uses it

penv asks where the file goes, once, and never guesses:

where should env.ts go? [apps/web/src/env.ts] (Enter, number, path, none):

The suggestions come from the directories that hold a package.json, a pyproject.toml and so on, shallowest first, with the repository root last so Enter in a monorepo lands on a package. Enter takes the first, a number takes another, a path is your own, and none skips. The answer is remembered in .penv/targets/<name>/target.toml, which you commit, so nobody is asked twice. --out <PATH> answers it up front, and is what a script or CI passes: without a flag or a remembered answer, a non-interactive run writes nothing and says which flag to pass.

ts reads through one accessor, process.env by default and import.meta.env or Deno.env.get when a vite.config.* or a deno.json sits beside it. penv never edits your tsconfig.json: it prints the import line to paste, following extends and using an alias from your paths map when one already reaches the file.

Each target takes a few options, and penv gen <target> --options prints them with what they are set to now:

They live in the [options] table of .penv/targets/<name>/target.toml, the file penv wrote when it remembered where your file goes, each under a comment saying what it changes. Edit a value there and the next penv gen uses it.

A language target is a folder holding a target.toml and a template. Drop one into .penv/targets/go/ and penv gen go works; a folder holding only a target.toml inherits the rest. The binary knows no language by name.

Coding agents

An agent runs as you, so it can read what you can read. penv narrows that:

• Nothing at rest once pushed. There is no .env to cat.
• penv run injects into the child process only, and scrubs every sensitive value, in raw, hex, base64 and URL-encoded forms, from the child's output whenever an agent session is detected.
• penv guard writes what each harness actually enforces, from the schema: deny rules and a sandbox block for Claude Code, a permission profile for Codex, deny rules and fail-closed hooks for Cursor, and the equivalents for Copilot, Gemini, Cline, Windsurf and Amp. The hook is the penv binary itself, never a script that fails open.
• reveal needs a person to approve in the console. An agent can ask; a human clicks.

The claim penv makes, printed by penv guard --check, is only what is true: it keeps secrets out of the files, the repo, the shell history and the captured output an agent reads. It cannot stop a process running as you from looking, so every value the cloud issues is short-lived, scoped and attributable to the session that used it.

Commands

JSON when stdout is not a terminal. Exit codes: 0 ok, 1 error, 2 auth, 3 validation, 4 confirmation required, 5 no credential, 6 environment refused.

Completions

penv completions bash > ~/.local/share/bash-completion/completions/penv
penv completions zsh > ~/.zfunc/_penv                  # a directory on your $fpath
penv completions fish > ~/.config/fish/completions/penv.fish
penv completions powershell >> $PROFILE
penv completions elvish >> ~/.config/elvish/rc.elv

The scripts are generated from the same manifest penv help --json publishes, so they never fall behind the commands.

MIT.