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 put DATABASE_PASSWORD
   
   # From .env: API_KEY=sk-abc123
   echo "sk-abc123" | dotsecenv secret put 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 put SECRET_NAME

Interactive input

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

From a file

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

With a namespace

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

To a specific vault

echo "value" | dotsecenv secret put -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 put 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.

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).

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.

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