Getting Started

This guide gets you from zero to encrypted secrets in about 5 minutes. By the end, you’ll have:

• dotsecenv installed
• A vault configured with your GPG identity
• Your first secret stored and retrieved

Prerequisites

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

Using dotsecenv (easier)

# Generate a new GPG key with dotsecenv
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

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

Quick Setup

1. Install dotsecenv

   macOS

   brew tap dotsecenv/tap
   brew install dotsecenv

   Linux

   # Debian/Ubuntu
   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. Initialize configuration

   Create a config file:

   dotsecenv init config

   This creates ~/.config/dotsecenv/config with default settings.

   Shortcut: Init + Login in one step

   You can combine initialization and login into one command:

   dotsecenv init config --login YOUR_FINGERPRINT

3. Create a vault

   dotsecenv init vault

   This creates an encrypted vault file at ~/.config/dotsecenv/vault.

4. Login with your GPG key

   dotsecenv login

   This lists your available GPG keys and prompts you to select one. You can also specify a fingerprint directly:

   dotsecenv login YOUR_FINGERPRINT

   The login creates a cryptographically signed proof that you control the secret key.

5. Store your first secret

   echo "my-secret-database-password" | dotsecenv secret store DATABASE_PASSWORD

   The secret is now encrypted in your vault.

6. Retrieve the secret

   dotsecenv secret get DATABASE_PASSWORD
   # Output: my-secret-database-password

What Just Happened?

1. Config file (~/.config/dotsecenv/config) stores your settings and vault location
2. Vault file (~/.config/dotsecenv/vault) is an encrypted JSONL file containing:
   • Your identity (GPG public key fingerprint)
   • Encrypted secrets
3. Login associated your GPG key with dotsecenv so it knows which key to use for encryption/decryption

Next: Shell Integration

The real power comes from automatic secret loading. Install the shell plugin:

curl -fsSL https://raw.githubusercontent.com/dotsecenv/plugin/main/install.sh | bash

Then create a .secenv file in your project:

# .secenv - secrets loaded automatically when you cd into the directory
DATABASE_PASSWORD={dotsecenv}
API_KEY={dotsecenv/MY_API_KEY}

When you cd into the directory, dotsecenv prompts you to load the secrets.

---

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?

• Your First Secret — Deeper dive into secrets and shell plugins
• Share a Secret — Share secrets with teammates
• Security Model — Understand how encryption works
• CLI Reference — Full command documentation