Skip to content
envless

Quickstart

envless is a Zig binary that shells out to age and sops. You need all three. Once they are on PATH, the entire init-set-exec loop is four commands.

Install

Requirements

  • age ≥ 1.2
  • sops ≥ 3.9
  • macOS or Linux (Windows untested)

macOS (Homebrew)

Terminal window
brew install age sops

Linux

Terminal window
# Debian / Ubuntu
sudo apt-get install age
curl -sSfL -o /tmp/sops https://github.com/getsops/sops/releases/latest/download/sops-v3.9.4.linux.amd64
sudo install -m 0755 /tmp/sops /usr/local/bin/sops


# Arch
sudo pacman -S age sops

envless itself

Homebrew (macOS + Linux):

Terminal window
brew tap biliboss/envless https://github.com/biliboss/envless
brew install biliboss/envless/envless

The tap lives in the main repo (no separate homebrew-envless repo) — the URL after brew tap is what tells brew where to look. age and sops are formula dependencies so the line above installs the full toolchain.

Pre-built tarball:

Download from GitHub Releases. The tarballs are named envless_v<version>_<triple>.tar.gz for each of aarch64-macos, x86_64-macos, aarch64-linux-gnu, x86_64-linux-gnu. Extract and put the envless binary on PATH. dist/checksums.txt accompanies each release.

From source:

Terminal window
git clone https://github.com/biliboss/envless.git
cd envless/zig
zig build -Doptimize=ReleaseSmall
sudo install -m 0755 zig-out/bin/envless /usr/local/bin/envless

Building requires Zig 0.13.0 — pinned in zig/.zigversion.

Verify

Terminal window
envless --version       # → v0.0.1
age --version           # → v1.3.x
sops --version          # → 3.x

If all three print, you’re ready.

60-second walkthrough

Terminal window
cd my-project


envless init                                 # creates .envless/identity.key
echo "sk-test-xyz" | envless set OPENAI_API_KEY


envless list                                 # → OPENAI_API_KEY
envless exec -- node server.js               # process.env.OPENAI_API_KEY populated

That’s it. Your code keeps using process.env.OPENAI_API_KEY. No library import. No .env on disk.

Multi-env

dev is the default. Add prod:

Terminal window
echo "sk-prod-xyz" | envless set OPENAI_API_KEY --env=prod
envless exec --env=prod -- npm run deploy

Recipients per env are deferred to v0.1 (.envless/team.yaml). For v0.0.1, all envs share the local identity.

Migrate from .env

Terminal window
envless migrate .env
# → encrypts .env → secrets/dev.env.enc
# → removes .env
# → adds .env to .gitignore

Keep the plaintext for reference (e.g. mid-migration):

Terminal window
envless migrate .env --keep

Read a value back

get requires --confirm to print plaintext. Prevents accidental shell-history leaks.

Terminal window
envless get OPENAI_API_KEY --confirm

For programmatic use, prefer envless exec — the plaintext stays inside the child process’s env array, never on stdout.

What gets committed

.envless/
  recipients          # public keys (commit)
  identity.key        # YOUR SECRET KEY — gitignored


secrets/
  dev.env.enc         # commit (encrypted)
  prod.env.enc        # commit (encrypted)


.env                  # gitignored after migrate

identity.key is on .envless/ ignore list automatically. Triple-check with git status.

Next