Migrate from .env

Goal

Take an existing .env file, move the sensitive values into your dotsecenv vault, and set up .secenv so everything still loads automatically.

Prerequisites

• Getting Started completed

Mental model

.env file	dotsecenv
One file per project, plain text	One vault file per project, encrypted
Edit a line to change a value	secret store NAME writes a new entry; old values stay as history
Cannot commit safely	Vault file commits safely to git
No history of who could read what	Append-only; recipients tracked per entry
Loaded by source .env at runtime	Loaded by the shell plugin on cd

The unit of encryption and audit is the individual secret, not the file. There is no bulk-import command for that reason; the loop below loops the single-secret store call over your .env lines.

Steps

1. Start with your .env file

   A typical project .env looks like this:

   .env

   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_NAME=myapp
   DATABASE_PASSWORD=super-secret-password
   API_KEY=sk-live-abc123xyz

   Three of these are non-sensitive configuration. Two are secrets you would not want in a public repo.

2. Identify the secrets

   Ask yourself: would I panic if this value appeared on a public GitHub repo? If yes, it belongs in the vault.

   In this example: DATABASE_PASSWORD and API_KEY.

3. Store the secrets in your vault

   echo "super-secret-password" | dotsecenv secret store DATABASE_PASSWORD
   echo "sk-live-abc123xyz" | dotsecenv secret store API_KEY

4. Create a .secenv file

   cat > .secenv << 'EOF'
   DATABASE_PASSWORD={dotsecenv}
   API_KEY={dotsecenv}
   EOF

   The {dotsecenv} syntax tells the shell plugin to fetch the secret with the same name as the variable.

5. Remove the secrets from .env

   Your .env now contains only non-sensitive values:

   .env

   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_NAME=myapp

6. Verify everything loads

   cd ~
   cd ~/my-project
   # dotsecenv: loaded 2 secret(s) from .secenv: DATABASE_PASSWORD, API_KEY
   
   echo $DATABASE_HOST
   # Output: localhost
   
   echo $DATABASE_PASSWORD
   # Output: super-secret-password
   
   echo $API_KEY
   # Output: sk-live-abc123xyz

   All five variables are available. Only three are on disk in plaintext.

7. Update version control

   echo ".env" >> .gitignore
   git add .secenv .gitignore
   git commit -m "chore: move secrets to dotsecenv vault"

   Tip

   .secenv is safe to commit — it contains only variable names and {dotsecenv} references, never actual secret values.

Expected result

Variable	Source	On disk in plaintext?
DATABASE_HOST	.env	Yes
DATABASE_PORT	.env	Yes
DATABASE_NAME	.env	Yes
DATABASE_PASSWORD	vault via .secenv	No
API_KEY	vault via .secenv	No

Variations

Bulk migration from a large .env

For a .env with many keys, a shell loop is faster than copy-pasting:

while IFS='=' read -r name value; do
  case "$name" in ''|\#*) continue ;; esac
  printf '%s' "$value" | dotsecenv secret store "$name"
done < .env

Inspect any quoted or multi-line values manually before relying on this; IFS='=' splits on the first = only and does not handle escapes.

What changes about your workflow

• Editing values. Instead of editing a line in .env, run echo NEW | dotsecenv secret store NAME. The old value is preserved in the vault history. See Vault Format: append-only semantics.
• Sharing values. Instead of sending the secret over a chat, add a teammate as a recipient: dotsecenv secret share NAME <THEIR_FINGERPRINT> --all.
• Rotating values. See Offboard a Departing Team Member for planned exits, or Rotate a Compromised GPG Key for compromise scenarios.

Next steps

• Reloading Secrets — what to do when you rotate a secret
• Share a Secret — share the encrypted secrets with teammates