Getting Started

This guide takes you from zero to an encrypted, auto-loading secret in about 5 minutes. By the end you will have dotsecenv installed, a vault with your identity, and a .secenv file that loads secrets automatically when you enter your project directory.

Prerequisites

You need a GPG key. Most developers already have one for signing git commits. If not:

Using dotsecenv (easier)

# Generate a new GPG key with dotsecenv (after install below)
dotsecenv identity create
# Enter your name and email when prompted

This uses FIPS-compliant defaults (P-384 curve, 2-year expiration). See identity create for algorithm options.

Using GPG directly

gpg --full-generate-key
# Select: (1) RSA and RSA, 4096 bits, key does not expire
# Enter your name and email

Setup

1. Install dotsecenv

   Install Script

   curl -fsSL https://get.dotsecenv.com/install.sh | bash

   The installer downloads the binary, verifies signatures, and installs the shell plugin, completions, and man pages. See the installation reference for all options.

   macOS (Homebrew)

   brew tap dotsecenv/tap
   brew install dotsecenv

   Linux (apt)

   curl -fsSL https://get.dotsecenv.com/key.asc | \
     sudo gpg --dearmor -o /etc/apt/keyrings/dotsecenv.gpg
   echo "deb [signed-by=/etc/apt/keyrings/dotsecenv.gpg] \
     https://get.dotsecenv.com/apt/ ./" | \
     sudo tee /etc/apt/sources.list.d/dotsecenv.list
   sudo apt-get update && sudo apt-get install dotsecenv

   Verify installation:

   dotsecenv version

2. Activate the shell plugin

   Add the source line the installer printed to your shell configuration:

   Zsh

   echo 'source ~/.local/share/dotsecenv/plugin/dotsecenv.plugin.zsh' >> ~/.zshrc

   Bash

   echo 'source ~/.local/share/dotsecenv/plugin/dotsecenv.plugin.bash' >> ~/.bashrc

   Fish

   The installer links the plugin automatically for Fish. If it did not, run:

   ln -sf ~/.local/share/dotsecenv/plugin/conf.d/dotsecenv.fish ~/.config/fish/conf.d/dotsecenv.fish

   Reload your shell:

   exec $SHELL

   Tip

   If you use Oh My Zsh, Zinit, Fisher, or Oh My Bash, the installer auto-links the plugin. Just add dotsecenv to your plugins list in your rc file.

3. Initialize and login

   dotsecenv init config
   dotsecenv init vault
   dotsecenv login   # select your GPG key interactively

   Shortcut: Init + Login in one step

   You can combine initialization and login into one command:

   dotsecenv init config --login YOUR_FINGERPRINT

4. Store a secret

   echo "s3cr3t-db-pass" | dotsecenv secret store DATABASE_PASSWORD

5. Create a .secenv file

   mkdir -p ~/my-project
   echo 'DATABASE_PASSWORD={dotsecenv}' > ~/my-project/.secenv

   This tells the shell plugin to fetch DATABASE_PASSWORD from your vault whenever you enter the directory.

6. Watch it auto-load

   cd ~/my-project
   # dotsecenv: found .secenv in /home/you/my-project
   # Load secrets? [y]es / [n]o / [a]lways: a
   # dotsecenv: loaded 1 secret(s) from .secenv: DATABASE_PASSWORD
   
   echo $DATABASE_PASSWORD
   # Output: s3cr3t-db-pass
   
   cd ~
   # dotsecenv: unloaded 1 secret(s): DATABASE_PASSWORD
   
   echo $DATABASE_PASSWORD
   # Output: (empty)

What just happened

• Your secret is encrypted at rest in the vault using your GPG key (AES-256-GCM)
• The shell plugin auto-loads secrets when you cd into a directory with a .secenv file
• Secrets are auto-unloaded when you leave the directory tree
• The vault file is safe to commit to git — it’s just encrypted JSONL

Verification checklist

Before moving on, verify:

• dotsecenv version shows version info
• dotsecenv vault describe shows your vault with your identity
• dotsecenv secret get DATABASE_PASSWORD returns your secret

What’s next

• Reloading Secrets — What to do when vault updates don’t appear in your shell
• Migrate from .env — Move existing secrets from plaintext .env files
• Share a Secret — Share encrypted secrets with teammates
• Shell Plugins — Trust system, dse up, nested .secenv files
• Security Model — Understand how encryption works
• CLI Reference — Full command documentation