Quick Start Guide
Get envv running in under 5 minutes. This guide assumes you're part of our design partner program.
Design Partners Only: envv is currently in private beta. If you don't have an invite code, request access here.
Installation
Prerequisites
# Install SOPS and Age (required)
brew install sops age
# Or on Linux, download from:
# - https://github.com/getsops/sops/releases
# - https://github.com/FiloSottile/age/releases
Install envv CLI
# Clone and build (requires Go 1.21+)
git clone https://github.com/envv-cli/envv-cli.git
cd envv-cli
make install-envv-user
# Add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Verify installation
envv --help
Basic Usage
1. Register and Create Organization
# Create your account
$ envv auth register
Email: you@company.com
Password: ••••••••
Name: Your Name
🔑 Generating age keypair...
✓ Private key saved to ~/.config/sops/age/keys.txt
✓ Public key: age1ql3z7hjy54pw3h...
✅ Registered as you@company.com
# Create your organization
$ envv org create --name="My Company"
✅ Created org: org_abc123
2. Create and Initialize Project
# Create a project in your org
envv project create --org-id=org_xxx --name="My App"
# Initialize in your project directory
cd your-project
envv project init --org-id=org_xxx --project-id=proj_xxx
3. Push Your Secrets
# Create your environment file
cat > .env.development << EOF
DATABASE_URL=postgres://localhost/mydb
STRIPE_API_KEY=sk_live_...
JWT_SECRET=super-secret-key
EOF
# Push encrypted secrets to backend
envv push .env --env development
4. Run Your App (Zero Plaintext on Disk)
# Pull + decrypt in memory + run (nothing written to disk)
envv run npm start
# Specify environment explicitly
envv run --env staging -- vercel dev --port 3000
✓ Zero plaintext on disk. Secrets are pulled from the backend, decrypted in memory, and injected into your process. Nothing is ever written unencrypted.
Team Setup
Invite Team Members
# Invite teammates to your organization
envv org invite --org-id=org_xxx --email=alice@acme.com --role=member
# View project members
envv project members
Join a Team (New Member)
# New member registers (generates their own age keypair)
envv auth register
# Clone and initialize project
git clone your-repo && cd your-repo
envv project init --org-id=org_xxx --project-id=proj_xxx
# Pull encrypted secrets (cached in .envv/)
envv pull --env development
# Run with secrets (decrypts in memory)
envv run npm start
Rotate Keys for New Members
# Re-encrypt secrets for updated team membership
envv rotate --env development
# This fetches all member public keys and re-encrypts
How it works: Each team member has their own age keypair. Secrets are encrypted for all team member public keys locally, then synced via the backend. The backend stores only encrypted data — it can never decrypt your secrets.
Command Reference
Authentication
envv auth register # Create account + generate keys
envv auth login # Login to envv
envv auth logout # Logout
envv auth whoami # Show current user
Organizations
envv org create --name=NAME # Create new organization
envv org list # List your organizations
envv org invite --email=... # Invite member
Projects
envv project create # Create new project
envv project init # Initialize current directory
envv project status # Show project configuration
envv project members # List project members
Running (Primary Workflow)
envv run COMMAND # Pull + decrypt in memory + run
envv run -- npm start # Use -- when command has flags
envv run -e staging CMD # Specify environment
Secrets
envv push .env --env prod # Encrypt and upload
envv pull --env prod # Download to .envv/ (encrypted)
envv pull --env prod --decrypt # Also write plaintext (escape hatch)
envv rotate --env prod # Re-encrypt for all members
Single Secret Updates
envv secrets set KEY "value" # Add/update one secret atomically
envv secrets set KEY "val" -e prod # Specify environment
envv secrets unset KEY # Remove a secret atomically
How set/unset work: These commands pull → decrypt in memory → update → re-encrypt → push. Zero plaintext on disk, fully atomic.
⚠️ About --decrypt: This writes a plaintext .env file to disk. Only use when absolutely necessary (legacy tool compatibility). You'll see a warning:
⚠️ Writing plaintext to .envv/.env.production
This defeats the purpose of encrypted secrets.
Consider using: envv run -- your-command
Offline Mode
envv pull --env prod # Cache encrypted file first
envv run --offline npm start # Works without network
Integrations
CI/CD (GitHub Actions)
# .github/workflows/deploy.yml
- name: Install envv
run: |
brew install sops age
git clone https://github.com/envv-cli/envv-cli.git
cd envv-cli && make install-envv-user
- name: Run tests
run: envv run --env production -- npm test
env:
SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
Docker / Vercel / Any Command
# Same pattern as Doppler and Infisical
envv run -- vercel dev
envv run -- docker compose up
envv run -- npm start
# With environment flag
envv run --env production -- npm run build
File Structure
project/
├── .envv/
│ ├── config.yaml # Project config
│ ├── .env.development.encrypted # Cached (ciphertext)
│ ├── .env.staging.encrypted
│ └── .env.production.encrypted
├── .env # Your local file (gitignored)
└── .gitignore
Configuration
# .envv/config.yaml
organization_id: org_xxx
project_id: proj_xxx
default_environment: development
# Age keys (auto-configured on register)
~/.config/sops/age/keys.txt
Troubleshooting
Command not found: envv
Make sure envv is in your PATH:
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
sops: command not found
Install SOPS and Age (required dependencies):
# macOS
brew install sops age
# Linux - download from GitHub releases
Failed to decrypt
Make sure your private key exists and you're a project member:
# Check your key exists
cat ~/.config/sops/age/keys.txt
# Ask admin to re-encrypt for you
envv rotate --env development
Secrets not loading in app
Make sure you're using
envv exec:
# ✗ Wrong - secrets not loaded
npm start
# ✓ Correct - secrets loaded in memory
envv exec npm start
Team member can't access secrets
Verify they're actually invited:
# Check team members
envv team list --members
# Re-invite if needed
envv team invite alice@acme.com
Need More Help?
Design Partner Support:
- Slack: #envv-design-partners
- GitHub Issues: Report bugs