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:

# 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

   Add --strict for stricter validation (treats warnings as errors).

3. Create a vault

   dotsecenv init vault

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

4. Login with your GPG key

   Find your GPG fingerprint:

   gpg --list-secret-keys --keyid-format long

   Look for the fingerprint (40-character hex string) and login:

   dotsecenv login YOUR_FINGERPRINT

   Or, if you have a single key, use this one-liner to auto-detect it:

   dotsecenv login \
      $(gpg --list-keys --with-colons | awk -F: '/^fpr/ {print $10; exit}')

5. Store your first secret

   echo "my-secret-database-password" | dotsecenv secret put 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 list 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