EnvRune keeps secret values in an encrypted vault and lets projects refer to
them by name. A small, versionable envrune.yml describes which reference is
injected into which environment variable; the secret value never belongs in
that file.
It is designed for a calm workflow: unlock once in an interactive session,
manage references without printing their values, and launch the command that
needs them directly.
What it gives you
| Capability | What it means in practice |
|---|
| Vault | Encrypted secret storage | Store values behind readable references such as payments.development. |
| Projects | Versionable bindings | Keep variable-to-reference mappings in envrune.yml, with no plaintext values. |
| Runtime | Direct process launch | Inject an environment into one child process with envrune run, a named command such as envrune dev, or several services at once with envrune up. |
| Unlock | One password a day | envrune unlock --ttl 8h or the system keychain unlocks every terminal, editor, and hook. |
| Teams | Shared secrets without a server | Commit envrune.team.json, encrypted to each member's key; CI gets its own identity. |
| Cloud | End-to-end encrypted sharing, on a server you run | Roles, machine tokens for CI, guided rotation when someone leaves, and an audit log. The server stores ciphertext and never sees a value. Optional: everything else works without it. |
| Managed keys | Replace a key in one place; let people use one they never receive | A replaced value reaches every device and running command by itself. A key marked sensitive stays off the developer's machine: their program's requests go through the server, which adds it. Works for any service. |
| Safety net | Recovery, history, doctor | A recovery key, encrypted backups, rotation with rollback, and envrune doctor for forgotten .env files. |
| Overview | Local dashboard | Inspect references and project bindings without exposing values in the browser. |
Get started
1. Install the CLI
Download the installer for your system from the
latest release:
| System | Download | How to install |
|---|
| Windows | envrune_<version>_windows_setup.exe | Run it. It installs for your user (no administrator prompt) and adds envrune to your PATH. |
| macOS | envrune_<version>_macos_universal.pkg | Open it and follow the installer. Works on Apple Silicon and Intel. |
| Debian / Ubuntu | envrune_<version>_linux_<arch>.deb | sudo apt install ./envrune_<version>_linux_amd64.deb |
| Fedora / RHEL | envrune_<version>_linux_<arch>.rpm | sudo dnf install ./envrune_<version>_linux_amd64.rpm |
Or with a package manager:
brew install --cask yagolagrottibracco/tap/envrune # macOS
scoop bucket add envrune https://github.com/YagoLagrottiBracco/scoop-bucket && scoop install envrune
winget install YagoLagrottiBracco.EnvRune # Windows, once Microsoft accepts the package
On Debian and Ubuntu, add EnvRune's apt repository once, and apt upgrade
keeps it up to date:
curl -fsSL https://yagolagrottibracco.github.io/envrune/apt/envrune.gpg \
| sudo tee /usr/share/keyrings/envrune.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/envrune.gpg] https://yagolagrottibracco.github.io/envrune/apt ./" \
| sudo tee /etc/apt/sources.list.d/envrune.list
sudo apt update && sudo apt install envrune
On macOS or Linux you can also install with one command:
curl -fsSL https://raw.githubusercontent.com/YagoLagrottiBracco/envrune/main/install.sh | sh
Then open a new terminal and check it:
envrune --help
The installers are not code-signed yet. On Windows, SmartScreen may ask you to
choose More info → Run anyway; on macOS, a blocked .pkg can be allowed
from System Settings → Privacy & Security → Open Anyway. Portable archives
(.zip / .tar.gz) and a checksums.txt file are attached to every release.
Or build from a source checkout with Go 1.27:
go build -trimpath -o bin/envrune ./cmd/envrune
Run it from the repository root. Before managing another project, place the
binary on your PATH or use the absolute path to this bin/envrune file. The
examples below use envrune so they work from the project directory.
If your Go binary directory is already on PATH, Go can install the command
for you instead:
go install github.com/YagoLagrottiBracco/envrune/cmd/envrune@latest
envrune --help
2. Create your vault
Run EnvRune with no command and follow the secure terminal prompts:
envrune
It asks for explicit confirmation before creating a vault, then asks you to
set and confirm a master password. That password is not stored. EnvRune then
shows a recovery key once: write it down and keep it offline, because it
is the only way back in if you forget the password.
3. Bind a project
From the root of a project, create an envrune.yml. It contains only
metadata:
envrune project init
version: 1
project: example-service
default_env: development
environments:
development: {}
Unlock for the day, bind a variable (EnvRune offers to store the value when
the reference is new), and run your application:
envrune unlock --ttl 8h
envrune link SERVICE_TOKEN service.development
envrune run -- ./your-application
Name the commands you run often in envrune.yml and start them with
envrune dev, or start several at once with envrune up. See
Getting started and
Daily workflow.
A focused workflow
secret value ──> encrypted vault ──> named reference ──> envrune.yml ──> child process
never a plaintext value
The vault is the source of truth for values. Project files only map a process
variable, such as SERVICE_TOKEN, to a vault reference, such as
service.development. This makes project configuration reviewable without
turning it into a secret-bearing file.
Commands at a glance
| Command | Use it for |
|---|
unlock [--ttl 8h] / lock | Unlock the vault for new terminals for a while, or forget the key now. |
keychain enable | Unlock through Windows Credential Manager, the macOS Keychain, or libsecret. |
shell | Open one foreground session and enter the master password once. |
set <reference> | Store or replace a value through a hidden prompt, asked twice. |
list [--long] / info / usage <reference> | Review references, their metadata, and where they are bound. |
link <VAR> <reference> [--env e] | Add a binding to the nearest envrune.yml, and offer to store a new value. |
migrate [--siblings] | Move .env files into the vault and envrune.yml, after showing the plan. |
setup [--env e] | Walk through the variables documented in envrune.yml, storing and linking each one. |
diff <env> <env> | Compare the variables two environments define, by name only. |
types [ts|python] | Generate env.d.ts or a pydantic Settings class from variables:. |
run [--env e] [--no-redact] -- <command> | Start one direct child process with resolved variables; values it prints show as ****. |
<name> / up | Run a command from commands: in envrune.yml, or several at once. |
copy <reference> | Copy a value to the clipboard; cleared after 30 seconds. |
rotate / rollback / history | Replace a value and keep the previous ones. |
doctor | Find missing references, forgotten .env files, pasted values, and secrets nobody uses. |
check [name...] | Run the project's own checks that its secrets still work. |
Run envrune help for every command and option. Every command also works
inside envrune shell. Set NO_COLOR=1 for plain terminal output; redirected
output is already plain.
Documentation
| Guide | Read it when you want to… |
|---|
| Why EnvRune | Migrate in two minutes, and an honest comparison with dotenv, 1Password CLI, Doppler, and Infisical. |
| Getting started | Build EnvRune, create a vault, and connect a first project. |
| Moving from .env files | Import every .env file of a project, or of several, with envrune migrate. |
| Daily workflow | Unlock once, use a default environment, named commands, up, copy, doctor, rotation, and recovery. |
| Advanced usage | Work with environments, imports, exports, generated values, and sessions. |
| Integrations | Use EnvRune from VS Code (extension, tasks, debugging), Docker Compose, and a direnv-style terminal hook. |
| Vault state in your prompt | Show locked or unlocked in Starship, Oh My Posh, or any prompt. |
| More in envrune.yml | Environments that extend each other, a personal override, workspaces, secrets as files, templates, and checks. |
| Documented variables |
Security at a glance
- The vault uses Argon2id for password derivation and XChaCha20-Poly1305 for
authenticated encryption.
- The master password is never persisted. Values are encrypted under a random
data key, wrapped by the password and by a recovery key shown once.
- Unlocking for later is opt-in: the agent keeps the data key in memory for a
time limit you choose, and the keychain stores it under your system login.
run launches the requested child process directly, without a shell in the
middle. On Linux, the runner marks itself non-dumpable immediately before
exec.run and up replace any value a child prints with ****, which keeps
values out of terminals, screen recordings, and logs by accident. It does
not stop a program that leaks a value on purpose; see
Output redaction.- EnvRune Cloud is optional and end-to-end encrypted: values are encrypted
and decrypted on your devices, every key a device encrypts to is reached
through signatures that end at keys your team pinned, and the server stores
ciphertext and names. It can refuse service or see who fetched what; it
cannot read a value. See its design.
- The one exception is a secret its owner marks sensitive, so that members
use it without receiving it: the server reads that one to put it into
their requests. It is chosen per secret, after a warning, and only on a
server set up for it. See managed keys.
- The dashboard listens only on loopback, exposes metadata rather than values,
and uses one-time session material, Host/Origin checks, CSRF protection, and
no-store headers.
export is intentionally different: it writes plaintext. EnvRune names the
variables, warns before writing, asks for YES, and asks again for a
destination inside a Git worktree.
Security is also operational. Do not paste values into terminals, issue
trackers, or configuration files; do not treat an exported dotenv file as a
safe long-term copy. Read the security model before using
EnvRune for sensitive credentials.
Building from source
EnvRune currently builds with Go 1.27.
go test ./...
go build -trimpath -o bin/envrune ./cmd/envrune
./bin/envrune --help
The build guide describes the expected toolchain, local
verification, and the distinction between a source build and a release asset.
Releases
Prebuilt binaries for Linux, macOS, and Windows (amd64 and arm64) are
published on the releases page.
Releases are built by GitHub Actions whenever a v* tag is pushed:
git tag v1.0.0
git push origin v1.0.0
Versions follow Semantic Versioning: a release with
only fixes raises the patch number, a release with a new feature raises the
minor number, and the major number changes only when something that worked
before stops working.
Treat main as active development.
License
EnvRune is available under the Apache License 2.0.
