envelope

envelope is a modern environment variables manager.

A modern environment variables manager

Usage: envelope [COMMAND]

Commands:
  add        Add environment variables to a specific environment
  check      Check which environment is currently exported
  delete     Delete environment variables
  drop       Drop environment
  duplicate  Create a copy of another environment
  diff       Diff two existing environments
  edit       Edit environment variables in editor
  history    Display the historical values of a specific key in a given environment
  init       Initialize envelope
  import     Import environment variables
  list       List saved environments and/or their variables
  lock       Encrypt envelope
  revert     Revert environment variable
  run        Run a command with environment variables from a specific environment
  unlock     Decrypt the envelope
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Installation

Brew

You can install envelope from homebrew-core:

$ brew install envelope

Binary

You can download the envelope binary in the latest release and copy the binary to a folder in your $PATH

Cargo

You can install envelope with cargo, make sure that your ~/.cargo folder is in your $PATH

$ cargo install --git https://github.com/mattrighetti/envelope
$ envelope --version
envelope 0.3.11

Arch

There is an aur package that packages the binary, called envelope-bin:

yay -S envelope-bin

Building

envelope is written in Rust, so you'll need the Rust compiler.

To build envelope:

$ git clone https://github.com/mattrighetti/envelope
$ cd envelope
$ cargo build --release
$ ./target/release/envelope --version
envelope 0.3.11

How it works

envelope is a command line utility that leverages an SQLite database to keep track of your environment variables so you can easily switch between different configurations.

Quick Start

Initialize envelope in your project directory:

$ cd my-project
$ envelope init

Import your existing .env file:

$ envelope import dev .env

Export variables to your shell:

$ export $(envelope list dev)

Verify which environment is active:

$ envelope check
dev

Usage

Init

Initialize envelope in your current directory. This creates a .envelope database file.

$ envelope init

[!NOTE] You must run envelope init before using any other commands. The .envelope file should be added to your .gitignore to avoid committing sensitive environment variables.

Pretty print

Pipe .env files to envelope to get a pretty format representation of the file

$ cat .env | envelope

+-------------------+----------------------------------------------+
| VARIABLE          | VALUE                                        |
+-------------------+----------------------------------------------+
| DATABASE_URL      | postgres://user:password@localhost:5432/mydb |
+-------------------+----------------------------------------------+
| SECRET_KEY        | mysecretkey123                               |
+-------------------+----------------------------------------------+
| API_KEY           | your_api_key_here                            |
+-------------------+----------------------------------------------+
| DEBUG_MODE        | true                                         |
+-------------------+----------------------------------------------+
| SMTP_HOST         | smtp.example.com                             |
+-------------------+----------------------------------------------+
| AWS_ACCESS_KEY_ID | your_access_key_id                           |
+-------------------+----------------------------------------------+

Import

Import from .env file

$ envelope import dev .env
$ envelope list dev
API_KEY=your_api_key_here
AWS_ACCESS_KEY_ID=your_access_key_id
DATABASE_URL=postgres://user:password@localhost:5432/mydb
DEBUG_MODE=true
SECRET_KEY=mysecretkey123
SMTP_HOST=smtp.example.com

It's also possible to import directly from stdin

$ cat .env | envelope import prod

List

List all saved environments:

$ envelope list
dev
staging
prod

List environment variables of a particular environment:

$ envelope list dev
API_KEY=your_api_key
DATABASE_URL=postgres://user:password@localhost:5432/mydb
DEBUG_MODE=true
SECRET_KEY=mysecretkey123
SMTP_HOST=smtp.example.com

Pretty print with a table format:

$ envelope list dev --pretty-print
+-------------+----------------------------------------------+-------+
| ENVIRONMENT | VARIABLE                                     | VALUE |
+-------------+----------------------------------------------+-------+
| dev         | DATABASE_URL                                 | pos.. |
+-------------+----------------------------------------------+-------+
| dev         | SECRET_KEY                                   | mys.. |
+-------------+----------------------------------------------+-------+
...

Truncate long values in pretty print mode:

$ envelope list dev --pretty-print --truncate

Sorting Options

You can specify the sorting order using the --sort option:

key or k: Sort by key in ascending order
value or v: Sort by value in ascending order
date or d: Sort by creation date in ascending order
kd: Sort by key in descending order
vd: Sort by value in descending order
dd: Sort by creation date in descending order (default)

Example:

$ envelope list dev --sort kd
SMTP_HOST=smtp.example.com
SECRET_KEY=mysecretkey123
DEBUG_MODE=true
DATABASE_URL=postgres://user:password@localhost:5432/mydb
API_KEY=your_api_key

Add

Add environment variables to an environment:

$ envelope add dev api_key sk_test_123456789
$ envelope list dev
API_KEY=sk_test_123456789

Variable names are automatically uppercased:

$ envelope add dev database_url postgres://localhost/mydb
$ envelope list dev
DATABASE_URL=postgres://localhost/mydb

Read value from stdin for sensitive data:

$ envelope add dev secret_token --stdin
Enter value for env secret_token:
my-super-secret-token

Add a variable with an empty value:

$ envelope add dev optional_var
$ envelope list dev
OPTIONAL_VAR=

Delete

Delete a specific variable from an environment:

$ envelope delete --env dev --key API_KEY
$ envelope list dev
# API_KEY will no longer appear

Delete a variable across all environments:

$ envelope delete --key DEBUG_MODE
# Removes DEBUG_MODE from all environments where it exists

Delete an entire environment:

$ envelope delete --env dev
$ envelope list
# dev will no longer appear

[!NOTE] Envelope always soft deletes environment variables. They are never actually removed from the database, which allows you to view the history and revert changes. For a hard delete that permanently removes data, use the drop command.

Drop

Drops (hard deletes) an environment and permanently removes all its variables from the database:

$ envelope drop dev
$ envelope list
# dev is permanently deleted, including all its history

[!WARNING] Unlike delete, the drop command permanently removes all data. This cannot be undone and you will not be able to view history or revert changes.

Duplicate

Create a copy of an existing environment:

$ envelope add dev api_key sk_dev_12345
$ envelope add dev database_url postgres://localhost/devdb
$ envelope duplicate dev staging
$ envelope list staging
API_KEY=sk_dev_12345
DATABASE_URL=postgres://localhost/devdb

This is useful for:

Creating a new environment based on an existing one
Copying production settings to staging for testing
Creating backups before making changes

Example workflow:

# Create a backup before experimenting
$ envelope duplicate prod prod-backup

# Make changes to prod
$ envelope add prod api_key sk_new_key

# If something goes wrong, restore from backup
$ envelope duplicate prod-backup prod

Edit

Open your $EDITOR to interactively edit environment variables:

$ envelope edit dev

This opens your default editor with all variables in the format:

API_KEY=your_api_key
DATABASE_URL=postgres://localhost/mydb
DEBUG_MODE=true

Editing tips:

Modify values by changing the text after =
Delete a variable by commenting it out with #:
```
#API_KEY=your_api_key
```
Add new variables by adding new lines:
```
NEW_VAR=new_value
```

When you save and close the editor, envelope will:

Update all modified values
Delete all commented variables (soft delete)
Add all new variables

Check

Check which environment(s) are currently exported in your shell:

$ export $(envelope list dev)
$ envelope check
dev

Check works by comparing your current shell's environment variables against all stored environments. It will show all environments whose variables exactly match what's currently exported.

Multiple environments can match if they share the same variables:

$ envelope add shared-config api_key sk_12345
$ envelope duplicate shared-config also-shared
$ export $(envelope list shared-config)
$ envelope check
shared-config
also-shared

If no environment matches completely, nothing is returned:

$ envelope check
# No output means no environment is fully active

Lock

Encrypt the envelope database. You will be prompted for a password and a confirmation.

$ envelope lock
Password: ********
Confirm password: ********
database locked successfully

[!NOTE]

when the database is locked, all other c

Envelope

Install / Use

README