⚡

Documentation

Zero-knowledge encrypted .env management for teams.

Installation

Install boltenv globally. Requires Node.js 22+.

Terminal

npm install -g @boltenv.dev/cli

Or via the install script:

Terminal

curl -fsSL https://boltenv.dev/install | sh

Quickstart

Get your team synced in 60 seconds.

Terminal

# 1. Authenticate with GitHub (one time)
boltenv login
# 2. Push your .env (encrypted locally, key never leaves your machine)
boltenv push
# 3. Share the key with a teammate (via a secure channel)
boltenv key export
# 4. Teammates import the key and pull
boltenv key import <base64-key>
boltenv pull

That's it. Your teammate now has the same .env — decrypted on their machine, never visible to the server.

Zero-knowledge encryption

boltenv uses a zero-knowledge architecture. Your encryption key is generated locally and never transmitted to the server. The server only stores ciphertext and a key fingerprint.

Algorithm:     AES-256-GCM (NIST standard)
Key derivation: HKDF-SHA256 (separate subkeys for encryption and HMAC)
IV:            12 bytes (random per encryption)
Auth tag:      16 bytes (tamper detection)
Key stored at: ~/.boltenv/keys/{owner}/{repo}.key
Server sees:   ciphertext + fingerprint (NOT the key)

A fresh random IV is generated for every push, so encrypting the same data twice produces different ciphertext. The GCM auth tag ensures integrity — any tampering is detected on pull.

Authentication

boltenv uses GitHub as its identity layer. No new accounts — your GitHub repo access determines who can push and pull secrets.

Terminal

# Log in via GitHub Device Flow (opens browser)
boltenv login
# Check who you're logged in as
boltenv whoami
# Log out (removes stored token)
boltenv logout

Your GitHub token is stored at ~/.boltenv/auth.json with 0600 permissions. You need write (push) access to the repository on GitHub to push or pull secrets.

Pushing secrets

Push encrypts your .env file locally and uploads only the ciphertext to the server.

Terminal

# Push .env from the current directory
boltenv push
# Push a specific file
boltenv push .env.production
# Push to a specific environment
boltenv push -e production
# Skip confirmation prompt
boltenv push -y
# Push to a specific repo (no .git needed)
boltenv push -r myorg/myapp

The first push auto-generates an encryption key and saves it locally. Share it with teammates using boltenv key export.

Pulling secrets

Pull downloads and decrypts secrets using your local key. The server never sees the key.

Terminal

# Pull .env (auto-detects environment from branch)
boltenv pull
# Pull from a specific environment
boltenv pull -e staging
# Pull a specific version (rollback)
boltenv pull --revision 3
# Print to stdout instead of writing a file
boltenv pull --stdout
# Output as JSON or shell exports
boltenv pull --format json
boltenv pull --format shell

ℹ Note: Files are written atomically (temp file + rename) with 0600 permissions. Existing .env files will prompt for confirmation before overwriting.

Key management

Every repo has one encryption key. The first person to push auto-generates it. Everyone else imports it.

Terminal

# Export your key as base64 (share via secure channel)
boltenv key export
# Import a key from a teammate
boltenv key import dGhpcyBpcyBhIDMyIGJ5dGUga2V5...
# Check if you have the key for this repo
boltenv key status

⚠ Warning: Never share your key in group chats, email threads, or commit it to git. Use a secure, private channel.

Environments

boltenv auto-detects the environment from your git branch:

main, master     → production
staging          → staging
develop          → development
anything else    → development (default)

Override with the -e flag on any command: boltenv push -e production

CI/CD

For CI pipelines, Docker, and headless servers — use environment variables instead of interactive login.

Terminal

# Set these in your CI environment:
export BOLTENV_TOKEN="ghp_xxxxxxxxxxxx"   # GitHub PAT with repo scope
export BOLTENV_KEY="dGhpcyBpcyBhIDMy..."  # From: boltenv key export
export BOLTENV_REPO="myorg/myapp"          # Skip git detection
# Pull secrets in CI
boltenv pull -y

All three env vars are required for non-interactive usage. BOLTENV_TOKEN must be a GitHub personal access token with repo scope.

Security model

boltenv is designed so the server can never see your secrets.

YOUR MACHINE                        BOLTENV CLOUD
┌─────────────────────────┐       ┌─────────────────────────┐
│ AES-256-GCM encryption  │       │ Stores ciphertext only  │
│ 256-bit random key      │       │ Cannot decrypt           │
│ Fresh IV per push       │       │ No keys stored           │
│ GCM auth tag (tamper)   │       │ Validates GitHub auth    │
│ Plaintext stays here    │       │                          │
└─────────────────────────┘       └─────────────────────────┘

All filenames from the server are validated against a strict allowlist. Path traversal, absolute paths, and shell metacharacters are rejected. Files are written atomically with 0600 permissions.

Project setup

Initialize boltenv in your project. It detects your framework, package manager, and env files automatically.

Terminal

# Interactive setup
boltenv init
# Use defaults (no prompts)
boltenv init -y

This creates a .boltenv.yaml config and adds .env to your .gitignore. Commit the config so your teammates have the same setup.

Diagnostics

If something isn't working, doctor checks every dependency in order and tells you exactly what to fix.

Terminal

$ boltenv doctor
  ✓ Git remote         myorg/myapp
  ✓ GitHub token       Loaded for alice
  ✓ GitHub API         alice — scopes: repo
  ✓ Token scope        repo scope present
  ✓ Repo access        write access to myorg/myapp
  ✓ Encryption key     32-byte key (fp: 509f94d5b2d0e38b)
  ✓ boltenv API        https://boltenv.dev (120ms)
  Summary: 7 ok
  Next:    everything looks good

Each check tells you the exact next action if it fails — no guessing.