How-To Guides

Quick solutions for common tasks. Each section is a self-contained guide.

---

Work with .env Files

dotsecenv works seamlessly alongside .env files. Use .env for non-sensitive config and .secenv for secrets.

Recommended Setup

# .env — Non-sensitive configuration
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=myapp
LOG_LEVEL=debug

# .secenv — Encrypted secrets from vault
DATABASE_PASSWORD={dotsecenv}
API_KEY={dotsecenv/prod::API_KEY}

Loading Both Files

With the shell plugin installed, both files load automatically when you cd into the directory:

1. .env loads first (plain values)
2. .secenv loads second (decrypted secrets)

Variables from .secenv can override .env if names match.

---

Migrate Secrets from .env

Move sensitive values from a plaintext .env to encrypted storage.

1. Identify sensitive values

   Common sensitive values:

   • Passwords: DATABASE_PASSWORD, ADMIN_PASSWORD
   • API keys: API_KEY, SECRET_KEY, AUTH_TOKEN
   • Connection strings with credentials
   • Private keys or certificates

2. Store each secret

   # From .env: DATABASE_PASSWORD=super-secret
   echo "super-secret" | dotsecenv secret store DATABASE_PASSWORD
   
   # From .env: API_KEY=sk-abc123
   echo "sk-abc123" | dotsecenv secret store API_KEY

3. Create .secenv file

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

4. Update .env

   Remove the sensitive values:

   # .env (updated)
   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   # DATABASE_PASSWORD=  ← Removed, now in .secenv

5. Add .env to .gitignore (if not already)

   echo ".env" >> .gitignore

6. Commit .secenv (safe—it contains no secrets)

   git add .secenv
   git commit -m "Move secrets to dotsecenv"

---

Create a Secret

Store a new encrypted secret in your vault.

From stdin (recommended)

echo "my-secret-value" | dotsecenv secret store SECRET_NAME

Interactive input

dotsecenv secret store SECRET_NAME
# Type or paste the value
# Press Ctrl+D when done

From a file

cat ~/.ssh/private_key | dotsecenv secret store SSH_PRIVATE_KEY

With a namespace

echo "prod-password" | dotsecenv secret store prod::DATABASE_PASSWORD
echo "dev-password" | dotsecenv secret store dev::DATABASE_PASSWORD

To a specific vault

echo "value" | dotsecenv secret store -v ./project/vault PROJECT_SECRET

Tip

Reading from stdin prevents the secret from appearing in shell history.

---

Retrieve a Secret

Get a decrypted secret value.

Basic retrieval

dotsecenv secret get DATABASE_PASSWORD
# Output: my-secret-value

As JSON

dotsecenv secret get DATABASE_PASSWORD --json
# {"name":"DATABASE_PASSWORD","value":"my-secret-value","available_to":["..."]}

Get all versions

dotsecenv secret get DATABASE_PASSWORD --all
# Lists all historical values

Get latest version only

dotsecenv secret get DATABASE_PASSWORD --last

From a specific vault

dotsecenv secret get -v 2 DATABASE_PASSWORD  # Vault index (1-based)
dotsecenv secret get -v ./path/to/vault DATABASE_PASSWORD

---

Share a Secret

Give another identity access to decrypt a secret.

1. Import their GPG public key

   gpg --import teammate-public.asc

2. Share the secret

   The secret share command automatically adds the identity to the vault if needed:

   dotsecenv secret share DATABASE_PASSWORD THEIR_FINGERPRINT

3. Commit and push

   git add vault
   git commit -m "Share DATABASE_PASSWORD with teammate"
   git push

Share all secrets at once

dotsecenv secret share "*" THEIR_FINGERPRINT --all

---

Revoke Access to a Secret

Remove someone’s ability to decrypt future values.

dotsecenv secret revoke DATABASE_PASSWORD THEIR_FINGERPRINT

Important

Revoking access does NOT prevent them from decrypting the old value. Always rotate the secret after revoking:

echo "new-value" | dotsecenv secret store DATABASE_PASSWORD

Revoke from all secrets

dotsecenv secret revoke "*" THEIR_FINGERPRINT --all

---

Validate Configuration and Vault

Check for issues with your config and vault files.

Breaking Change in v0.4

v0.4 changed the hash computation format to improve security (prevents value transplantation attacks). Secrets created with v0.3.x will fail validation with “hash mismatch” errors.

To migrate your vault:

1. Re-sign your secret values

   Each user must re-sign their own values—you cannot edit another user’s secret values:

   # List all secrets
   dotsecenv vault describe
   
   # For each secret you created, re-sign it
   dotsecenv secret get DATABASE_PASSWORD | dotsecenv secret store DATABASE_PASSWORD
   dotsecenv secret get API_KEY | dotsecenv secret store API_KEY
   # ... repeat for each secret

2. Remove old values from the vault file

   Edit the vault file manually and delete the old value entries that no longer validate. Each secret may have multiple values—keep only the newly signed ones.

3. Commit the updated vault

   git add vault
   git commit -m "Migrate vault to v0.4 hash format"

This is a one-time migration. New secrets created with v0.4+ will validate correctly.

Basic validation

dotsecenv validate

Output:

✓ Config file: valid
✓ Vault header: valid
✓ Identity entries: 2 valid
✓ Secret entries: 5 valid
✓ All signatures verified

Auto-fix issues

dotsecenv validate --fix

This can fix:

• Regenerate corrupted header indexes
• Remove orphaned entries
• Update outdated format versions

Validate specific vault

dotsecenv validate -v ./project/vault

---

List All Secrets

View identities and secrets in your vaults.

Describe vaults

dotsecenv vault describe

Output:

Vault 1 (~/.config/dotsecenv/vault):
  Identities:
    - Alice <alice@example.com> (E60A1740...)
    - Bob <bob@example.com> (ABC12345...)
  Secrets:
    - DATABASE_PASSWORD
    - API_KEY
    - prod::API_KEY

JSON output

dotsecenv vault describe --json

Filter by namespace

dotsecenv vault describe | grep "prod::"

---

Use Multiple Vaults

Work with secrets from different vaults.

Configure multiple vaults

~/.config/dotsecenv/config

vault:
  - name: personal
    path: ~/.config/dotsecenv/vault
  - name: work
    path: ~/work/secrets/vault

Access by name

dotsecenv secret get -v personal DATABASE_PASSWORD
dotsecenv secret get -v work CORP_API_KEY

Access by index

dotsecenv secret get -v 1 DATABASE_PASSWORD  # personal (1-based)
dotsecenv secret get -v 2 CORP_API_KEY       # work

---

Set Up Shell Completions

Enable tab completion for dotsecenv commands.

Bash

# Add to ~/.bashrc
eval "$(dotsecenv completion bash)"

# Or install system-wide
dotsecenv completion bash | sudo tee /etc/bash_completion.d/dotsecenv

Zsh

# Add to ~/.zshrc
eval "$(dotsecenv completion zsh)"

Fish

# Add to ~/.config/fish/config.fish
dotsecenv completion fish | source

Reload your shell to activate:

source ~/.bashrc  # or ~/.zshrc

---

Export Secrets as Environment Variables

Export all secrets for a shell session or script.

Install shell plugins

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

Auto-load secrets

/path/to/directory/.secenv

# the secret(s) will be auto-loaded on cd
cd /path/to/directory

# and your app can use them
./my-app

Export specific secrets

export DATABASE_PASSWORD=$(dotsecenv secret get DATABASE_PASSWORD)
export API_KEY=$(dotsecenv secret get API_KEY)

---

Run Vault Health Checks

Run health checks on vaults and the GPG environment, and fix any issues.

Run doctor

dotsecenv vault doctor

Output:

Health checks:
  [✓] gpg-agent is available
  [✓] ~/.config/dotsecenv/vault: format v2 (latest)
  [✓] ~/.config/dotsecenv/vault: 0.0% fragmentation

Status: healthy

All vaults are up to date.

Doctor checks and fixes

The doctor command performs these checks:

• GPG agent availability — verifies gpg-agent is running
• Vault format version — checks if vaults need upgrading
• Vault fragmentation — checks if defragmentation is needed

After displaying health check results, doctor offers to fix any issues found (upgrade outdated vaults, defragment fragmented vaults).

Auto-fix without prompting

Use --fix to automatically apply all fixes without interactive confirmation:

dotsecenv vault doctor --fix

This is useful in scripts or when you already know fixes are safe to apply.

JSON output (for CI)

dotsecenv vault doctor --json

Note

In CI environments (CI=true, GITHUB_ACTIONS, GITLAB_CI, etc.), interactive prompts are automatically skipped to avoid blocking pipelines. You can also use --fix to explicitly auto-fix in any environment.

Caution

Defragmenting removes historical values. Make sure you don’t need the history before confirming.

---

Use with CI/CD

Access secrets in CI/CD pipelines.

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dotsecenv
        run: |
          curl -LO https://get.dotsecenv.com/linux/dotsecenv_latest_Linux_x86_64.tar.gz
          tar -xzf dotsecenv_*.tar.gz
          sudo mv dotsecenv /usr/local/bin/

      - name: Import GPG key
        run: echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --import

      - name: Deploy
        run: |
          export DATABASE_PASSWORD=$(dotsecenv secret get DATABASE_PASSWORD)
          ./deploy.sh

GitLab CI

deploy:
  script:
    - apt-get update && apt-get install -y gpg
    - curl -LO https://get.dotsecenv.com/linux/dotsecenv_latest_Linux_x86_64.tar.gz
    - tar -xzf dotsecenv_*.tar.gz && mv dotsecenv /usr/local/bin/
    - echo "$GPG_PRIVATE_KEY" | gpg --import
    - export API_KEY=$(dotsecenv secret get API_KEY)
    - ./deploy.sh

---

Troubleshooting Quick Reference

Problem	Solution
”Not logged in”	dotsecenv login FINGERPRINT
”Secret not found”	Check vault: dotsecenv vault describe
”Cannot decrypt”	Verify you’re in available_to
”GPG error”	Check key: gpg --list-secret-keys
”Config not found”	Run: dotsecenv init config
”Vault not found”	Run: dotsecenv init vault
”Permission denied” on vault	Check file permissions: ls -la /path/to/vault
Config error running as root	Use: sudo dotsecenv init config
Config error in SUID mode	Contact your system administrator
Vault path not in config	Add path to config or use restrict_to_configured_vaults: false