Skip to content
logo dotsecenv
Blog

First Secret

Goal

Section titled “Goal”

Create a vault, log in with your GPG key, store an encrypted secret, and read it back. By the end you will have a working vault and know the core secret store / secret get commands.

Prerequisites

Section titled “Prerequisites”
  • dotsecenv installed (Installation)
  • A GPG key available (run dotsecenv identity create if you need one)

Steps

Section titled “Steps”

  1. Initialize the config

    The config records where your vault lives and which identity you log in as:

    Terminal window
    dotsecenv init config

    To point at a specific vault path, pass -v:

    Terminal window
    dotsecenv init config -v ./vault

  2. Initialize the vault

    Create the encrypted vault file:

    Terminal window
    dotsecenv init vault

  3. Log in

    Record a signed login proof in the config. Always log in by fingerprint:

    Terminal window
    dotsecenv login <FINGERPRINT>

    To find your fingerprint:

    Terminal window
    gpg --list-keys --with-colons you@example.com | awk -F: '/^fpr:/ { print $10; exit }'

  4. Store a secret

    Store a database password. Values are read from stdin, the only way to write to a vault:

    Terminal window
    echo "super-secret-db-password" | dotsecenv secret store DATABASE_PASSWORD

  5. Read it back

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

    Run secret get with no name to list keys (never values):

    Terminal window
    dotsecenv secret get

  6. Store a namespaced secret

    Use namespaces to organize secrets by environment. The namespace lowercases and the key uppercases on store:

    Terminal window
    echo "prod-password" | dotsecenv secret store prod::DATABASE_PASSWORD
    echo "staging-password" | dotsecenv secret store staging::DATABASE_PASSWORD

  7. Inspect and validate

    vault describe shows identities and secret keys:

    Terminal window
    dotsecenv vault describe

    validate runs a structural sanity check on the vault and config:

    Terminal window
    dotsecenv validate

Expected Result

Section titled “Expected Result”
  • A vault file holding your secrets, encrypted at rest with your GPG key
  • dotsecenv secret get DATABASE_PASSWORD returns the value
  • dotsecenv vault describe lists your identity and the secret keys, including the namespaced ones
  • dotsecenv validate exits cleanly

Auto-loading into your shell

Section titled “Auto-loading into your shell”

To export these secrets automatically when you cd into a project, add a .secenv file and install the shell plugin. That flow lives in Reloading Secrets and Getting Started; a minimal .secenv looks like:

Terminal window
DATABASE_PASSWORD={dotsecenv}

Variations

Section titled “Variations”

Interactive secret input

Section titled “Interactive secret input”

For sensitive secrets, avoid piping to prevent history leaks:

Terminal window
dotsecenv secret store API_KEY
# Type or paste your secret, then Ctrl+D

Reading from files

Section titled “Reading from files”
Terminal window
dotsecenv secret store SSH_PRIVATE_KEY < ~/.ssh/private_key

Multiple vaults

Section titled “Multiple vaults”

Store secrets in a project-specific vault:

Terminal window
dotsecenv init vault -v ./secrets/vault
echo "local-secret" | dotsecenv secret store -v ./secrets/vault LOCAL_SECRET

Troubleshooting

Section titled “Troubleshooting”

secret get fails to decrypt?

Your GPG fingerprint must be a recipient. Confirm you logged in with the right key:

Terminal window
dotsecenv vault describe

Wrong secret value?

Secrets are versioned. Get the latest:

Terminal window
dotsecenv secret get --last DATABASE_PASSWORD

Next Steps

Section titled “Next Steps”