First Secret

Goal

Store an encrypted secret in your vault and configure a shell plugin to automatically load it when you enter a project directory.

Prerequisites

• dotsecenv installed (Installation)
• GPG key available
• Basic setup complete (Getting Started)

Steps

1. Verify your setup

   Make sure you’re logged in:

   dotsecenv vault describe

   You should see your identity listed. If not, complete the Getting Started guide first.

2. Store a secret

   Let’s store a database password:

   echo "super-secret-db-password" | dotsecenv secret put DATABASE_PASSWORD

   Tip

   Secrets are read from stdin to avoid them appearing in shell history.

   Verify it was stored:

   dotsecenv secret get DATABASE_PASSWORD
   # Output: super-secret-db-password

3. Store a namespaced secret

   Use namespaces to organize secrets by environment:

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

   List all secrets:

   dotsecenv vault describe

4. Install the shell plugin

   Bash

   Add to ~/.bashrc:

   # dotsecenv shell plugin
   eval "$(dotsecenv completion bash)"
   
   # Auto-load .secenv files
   _dotsecenv_hook() {
     if [[ -f .secenv ]]; then
       eval "$(dotsecenv env load)"
     fi
   }
   if ! [[ "${PROMPT_COMMAND:-}" =~ _dotsecenv_hook ]]; then
     PROMPT_COMMAND="_dotsecenv_hook${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
   fi

   Zsh

   Add to ~/.zshrc:

   # dotsecenv shell plugin
   eval "$(dotsecenv completion zsh)"
   
   # Auto-load .secenv files
   autoload -U add-zsh-hook
   _dotsecenv_hook() {
     if [[ -f .secenv ]]; then
       eval "$(dotsecenv env load)"
     fi
   }
   add-zsh-hook chpwd _dotsecenv_hook

   Fish

   Add to ~/.config/fish/config.fish:

   # dotsecenv completions
   dotsecenv completion fish | source
   
   # Auto-load .secenv files
   function _dotsecenv_hook --on-variable PWD
     if test -f .secenv
       dotsecenv env load | source
     end
   end

   Reload your shell:

   source ~/.bashrc  # or ~/.zshrc

5. Create a .secenv file

   In your project directory, create a .secenv file:

   cd ~/my-project
   
   cat > .secenv << 'EOF'
   # Secrets loaded from dotsecenv vault
   DATABASE_PASSWORD={dotsecenv}
   API_KEY={dotsecenv/prod::API_KEY}
   EOF

   The syntax is:

   • VAR={dotsecenv} — Load secret with same name as variable
   • VAR={dotsecenv/SECRET_NAME} — Load specific secret into variable
   • VAR={dotsecenv/namespace::SECRET_NAME} — Load namespaced secret

6. Test automatic loading

   Leave and re-enter the directory:

   cd ~
   cd ~/my-project
   # You may see a prompt: "Load secrets? [y]es / [n]o / [a]lways"
   # Type 'y' or 'a'
   
   echo $DATABASE_PASSWORD
   # Output: super-secret-db-password

Expected Result

• Secrets stored encrypted in your vault
• When you cd into a directory with .secenv, secrets auto-load
• When you leave the directory, secrets are unloaded (environment cleared)

cd ~/my-project
echo $DATABASE_PASSWORD
# super-secret-db-password

cd ~
echo $DATABASE_PASSWORD
# (empty)

Variations

Using with .env files

You can use both .env and .secenv together:

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

# .secenv - Sensitive secrets
DATABASE_PASSWORD={dotsecenv}

Interactive secret input

For sensitive secrets, avoid piping to prevent history leaks:

dotsecenv secret put API_KEY
# Type or paste your secret, then Ctrl+D

Reading from files

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

Multiple vaults

Store secrets in a project-specific vault:

dotsecenv init vault -v ./secrets/vault
echo "local-secret" | dotsecenv secret put -v ./secrets/vault LOCAL_SECRET

Caution

Remember to add project vaults to your .gitignore if they contain secrets that shouldn’t be shared:

.gitignore

secrets/vault

Or commit them if you want to share encrypted secrets with your team (more secure).

---

Troubleshooting

Secret not loading?

1. Check the .secenv syntax
2. Ensure the secret exists: dotsecenv vault describe
3. Verify you’re logged in: dotsecenv vault describe should show your identity

Wrong secret value?

Secrets are versioned. Get the latest:

dotsecenv secret get --last DATABASE_PASSWORD

---

Next Steps

• Share a Secret — Share secrets with teammates
• Revoke Access — Remove someone’s access to secrets