EnvSimple CLI

Git for environment configuration.

Version your env state. Pull and push changes. Roll back safely. Stop sharing .env files in Slack.

---

The Problem

Developer onboarding takes hours because environment setup is undocumented chaos.

Configuration lives in Slack threads, wikis, and stale .env.example files.

Local changes drift from production. No one knows what changed or when.

There's no rollback. Production breaks, and you grep through Git history hoping someone committed the old values.

EnvSimple fixes this.

---

What It Does

EnvSimple is a CLI tool for managing environment configuration as versioned snapshots.

It works like Git, but for .env files:

• Pull the latest config from a shared environment
• Push local changes to create a new version
• Roll back to any previous snapshot
• Audit who changed what and when

Your app still reads from .env. EnvSimple just manages how that file gets there.

---

How It Works

EnvSimple is snapshot-based. Each push creates a complete, immutable version of your environment state.

No diffs. No merges. No conflicts to resolve.

When you push, you overwrite. When you pull, you sync to a specific version.

Rollback creates a new version by copying an old snapshot. History is append-only.

Base version checks prevent accidental overwrites. Backups are automatic.

---

Quick Start

1. Login

envsimple login

Visit the URL and enter the code.

2. Pull Config

envsimple pull

If no context is configured, you'll select org → project → environment interactively.

This writes your environment variables to .env.

3. Run Your App

# .env is now populated
npm start

4. Push Changes

Edit .env, then:

envsimple push

This creates a new version snapshot.

---

Core Concepts

Organization / Project / Environment

Configuration is organized hierarchically:

• Organization: Your company or team
• Project: An application or service
• Environment: dev, staging, production, etc.

Each environment has its own version history.

Snapshots and Versions

Every push creates an immutable snapshot.

Versions are numbered sequentially: v1, v2, v3.

Rollback copies a previous snapshot and creates a new version. It doesn't rewind history.

Context Resolution

EnvSimple needs to know which environment you're working with.

Priority order:

1. CLI flags: --org, --project, --environment
2. .envsimple.local (local overrides, gitignored)
3. .envsimple (shared, committed)
4. Interactive selection

Overrides

.envsimple.local can define local-only overrides:

environment: dev-alice

overrides:
  DATABASE_URL: postgresql://localhost/mydb
  DEBUG: true

Overrides are applied during pull and print.

By default, overrides are excluded from push (you'll be prompted).

This prevents local dev values from accidentally reaching production.

---

Configuration Files

.envsimple (shared, committed)

org: acme
project: payments-api
environment: production

Team-wide context. Commit this.

.envsimple.local (local, gitignored)

environment: dev-alice

overrides:
  DATABASE_URL: postgresql://localhost/mydb
  DEBUG: true

Local context and overrides. Never committed.

Use this to switch environments or override specific keys during development.

.env (generated, gitignored)

DATABASE_URL=postgresql://prod.example.com/db
API_KEY=sk_live_xyz123

Runtime configuration. Generated by envsimple pull.

Your application reads this. EnvSimple writes it.

.env.copy (backup, gitignored)

Automatic backup created before risky operations.

If content differs during pull, a timestamped backup is appended.

---

Commands

Authentication

envsimple login           # Login via device code flow
envsimple logout          # Logout and revoke session

Context

envsimple status          # Show current context and auth status
envsimple update          # Switch environment (saves to .envsimple.local)
envsimple update --shared # Switch environment (saves to .envsimple)
envsimple help-config     # Show config file documentation

Sync

envsimple pull            # Pull latest snapshot to .env
envsimple push            # Push .env to remote (creates new version)
envsimple push --force    # Force push (skip base version check)

CI/CD Mode

For automated workflows, use service tokens:

# Set service token in environment
export ENVSIMPLE_SERVICE_TOKEN=esv1_xxx

# Pull with service token
envsimple pull --token

# Push with service token
envsimple push --token

Requirements:

• .envsimple file must exist (service tokens don't support interactive mode)
• Only pull and push operations are allowed subject to authorization.
• No access to other resources (users, orgs, audit logs, etc.)

CI Example:

# GitHub Actions
- name: Pull environment config
  run: envsimple pull --token
  env:
    ENVSIMPLE_SERVICE_TOKEN: ${{ secrets.ENVSIMPLE_SERVICE_TOKEN }}

View

envsimple print           # Print env vars (masked by default)
envsimple print --raw     # Print unmasked values
envsimple versions        # List all version snapshots
envsimple log             # Show recent version history
envsimple audit           # Show audit logs with actor and timestamp

Version Control

envsimple rollback --target <version>  # Roll back to specific version

Rollback creates a new version by copying the target snapshot.

Your .env is backed up to .env.copy before rollback.

Environment Management

envsimple env list                          # List environments
envsimple env create <name>                 # Create new environment
envsimple env clone <source> <destination>  # Clone environment
envsimple env delete                        # Soft delete environment
envsimple env delete --permanent            # Permanently delete

Telemetry

envsimple telemetry status   # Check telemetry status
envsimple telemetry disable  # Disable telemetry
envsimple telemetry enable   # Enable telemetry

Global Flags

--org <slug>               # Override organization
--project <name>           # Override project
--environment <name>       # Override environment
--json                     # Output JSON
--debug                    # Enable debug output

---

Safety Model

Snapshot Isolation

Each push creates a complete, immutable snapshot.

There are no diffs, patches, or merges. You can't corrupt history.

Base Version Checks

Before pushing, EnvSimple checks if the remote has changed since your last pull.

If the remote is newer, you'll be warned and prompted to pull first.

Use --force to bypass this check (creates a forced push marker).

Automatic Backups

.env.copy is created before risky operations.

If .env.copy already exists, new backups are appended with timestamps.

Confirmations

Destructive actions require confirmation:

• Environment deletion
• Pulling empty environments (might overwrite local config)
• Forced push on conflict

Override Exclusion

Local overrides (from .envsimple.local) are excluded from push by default.

You'll be prompted if your .env contains override keys:

⚠ Local .env contains keys defined in .envsimple.local overrides:
  - DATABASE_URL

If you say "yes", the values from your .env will be pushed to remote.
If you say "no", these keys will be excluded from the push.

Include these keys in push? (y/N)

This prevents accidental promotion of local dev values.

---

Telemetry

EnvSimple collects anonymous usage telemetry to improve the product.

What's collected:

• Command names
• Execution success/failure
• CLI version
• OS type

What's NOT collected:

• Environment variable keys or values
• Organization/project names
• User email or identity
• File paths

Opt out anytime:

envsimple telemetry disable

---

Security

Report security vulnerabilities to: contact@envsimple.com

Please do not open public issues for security concerns.

---

Contributing

Contributions are welcome.

EnvSimple CLI is open source under the Apache 2.0 License.

By contributing, you agree to license your work under the same terms.

---

License

Apache License 2.0

See LICENSE file for full text.

---

Trademark

EnvSimple is a trademark of EnvSimple.

Forks and derivatives may not use the EnvSimple name or logo in a way that suggests official affiliation.