Getting Started

Get up and running with Envi in minutes.

Do You Need This Tool?

Envi is designed for managing .env files across local development environments, git worktrees, and team collaboration. However, you might not need it if:

• Your platform has built-in secret management - Services like Vercel, Netlify, Railway, and similar platforms often provide their own environment variable management through their dashboard or CLI
• You use cloud-native secret managers - Tools like AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault may already cover your needs for production environments

Envi shines when you need to:

• Manage local development .env files across multiple projects
• Handle .env.local overrides and other gitignored environment files that don't get checked into version control
• Restore environment configurations to fresh git worktrees or checkouts
• Share encrypted environment configurations with team members
• Keep a version-controlled backup of your local development settings

Installation

Envi can be installed either globally or as a development dependency in your project.

Global Installation (Recommended)

Install globally to use envi across all your projects:

pnpm

pnpm add -g @codecompose/envi

npm

npm install -g @codecompose/envi

yarn

yarn global add @codecompose/envi

Project Development Dependency

Alternatively, install as a dev dependency within a specific project:

pnpm

pnpm add -D @codecompose/envi

npm

npm install --save-dev @codecompose/envi

yarn

yarn add -D @codecompose/envi

When installed as a dev dependency, run commands using:

# Using npx
npx envi capture

# Using pnpm
pnpm envi capture

# Using yarn
yarn envi capture

# Or add to package.json scripts
{
  "scripts": {
    "env:capture": "envi capture",
    "env:restore": "envi restore"
  }
}

Requirements

• Node.js 20 or higher
• GitHub CLI (optional, for GitHub integration)

Basic Workflow

1. Capture Environment Files

Navigate to your project and capture all .env files:

cd /path/to/your/project
envi capture

This will:

• Find your project root (looks for version control markers: .git, .jj, .hg, .svn, or prompts you to confirm the current directory)
• Discover all .env and .env.* files
• Store them in ~/.envi/store/ organized by package name

2. Restore Environment Files

On a new machine or fresh checkout:

cd /path/to/your/project
envi restore

This will:

• Look up your stored configuration
• Restore all .env files to their original locations
• Preserve all comments (full-line and inline)

Per-Repo Shared Key (Optional)

By default, captured env values are stored in plaintext in ~/.envi/store/, and envi pack derives its encryption key from your manifest file (package.json, Cargo.toml, etc.).

You can opt in to a per-repo shared key by generating one and committing it to the source repository:

cd /path/to/your/project
envi create-key
git add envi.config.maml && git commit -m "Add envi encryption key"

Two things change after envi.config.maml exists:

• envi pack / envi unpack use this key instead of the manifest-derived one, so shared blobs don't break the next time someone runs pnpm install (or any other dependency change).
• envi capture writes encrypted entries to ~/.envi/store/ instead of plaintext. This mostly only matters when you also use the GitHub integration — a leak of the GitHub backup alone won't expose env values without also leaking the source repo.

WARNING

envi.config.maml is a shared secret. Only commit it to private repositories — anyone with read access can decrypt. On a public repo, envi.config.maml (and the manifest fallback) give no confidentiality; use a custom secret with envi pack instead. See envi create-key for details.

Protecting Personal Tokens

Envi includes a variable redaction feature to prevent accidentally sharing personal tokens with your team.

Quick Start

By default, GITHUB_PAT (GitHub Personal Access Token) is automatically redacted because it's tied to your individual GitHub account, not your organization. Each developer should have their own GITHUB_PAT for local development.

Add more variables as needed:

# Add variables to redaction list
envi config redact add SLACK_WEBHOOK_URL
envi config redact add GITLAB_TOKEN

# View redacted variables
envi config redact list

When you capture or pack environment files, redacted variables will:

• Be replaced with __envi_redacted__ in storage and blobs
• Preserve their real values when you restore or unpack

Example:

$ envi capture
⚠ Redacted 2 variable(s): GITHUB_PAT, SLACK_WEBHOOK_URL
ℹ These values will be stored as __envi_redacted__
✔ Captured 3 file(s) to storage

Learn more in the Sharing Configurations guide.

Storage Location

Envi stores your environment configurations in:

~/.envi/
├── store/           # Environment file storage
│   ├── @org/
│   │   └── package.maml
│   └── unscoped.maml
└── config.maml      # Global configuration (machine-wide)

Files are stored in human-readable MAML format. See the File Format documentation for technical details.

If you've opted into the per-repo shared key, each repo also has an envi.config.maml at its root holding the encryption_key (and any future per-repo Envi config). Unlike ~/.envi/config.maml, envi.config.maml is meant to be committed alongside source.

Next Steps

• Learn about all available commands
• Understand variable redaction and how to protect personal tokens
• Add a per-repo shared key so envi pack blobs survive dependency updates
• Learn about sharing configurations with your team
• Understand the file format and how comments are preserved
• Set up GitHub integration for automatic version control
• Explore monorepo usage