localsecretvault 0.5.0

Local encrypted secrets vault for development workflows.

Local Secret Vault

Local Secret Vault is a small local encrypted secrets vault for development workflows.

It lets you store secrets locally, unlock them for a limited time, and run commands with those secrets injected as environment variables.

Current MVP features

• Encrypted local vault file
• Master password protection
• Timed unlock
• Local in-memory server while unlocked
• Store, list, rename, and delete secrets
• Import .env style content
• Run commands with secrets injected into the environment
• Export secrets to clipboard as .env text
• Python helper API for loading secrets into Python apps
• Windows executable build

Recommended Windows setup

Download the release archive and extract it.

After extracting, copy vault.exe to a stable folder.

Recommended folder:

mkdir $HOME\local-secret-vault

copy .\vault.exe $HOME\local-secret-vault\vault.exe

Then use the app from there:

cd $HOME\local-secret-vault

.\vault.exe --help

Do not keep running vault.exe directly from Downloads. The app starts a temporary local background process while unlocked, so using a stable folder gives a cleaner Windows experience.

Initialize a vault

.\vault.exe init

You will be asked to create a master password.

Important:

If you forget the master password, your secrets cannot be recovered.

Unlock the vault

.\vault.exe unlock --hours 8

The vault stays unlocked for the selected number of hours.

While unlocked, secrets are kept in memory by a local background process.

Check status

.\vault.exe status

Add a secret

.\vault.exe set API_KEY_DEV

The secret value is hidden while typing.

List secret names

.\vault.exe list

Only secret names are printed. Secret values are not printed.

Import .env content

.\vault.exe import-env --suffix DEV

Paste .env style content:

API_KEY=example-key
DATABASE_URL=postgres://example
REDIS_URL=redis://localhost:6379
END

The final END line tells the vault you are done pasting.

With --suffix DEV, these become:

API_KEY_DEV
DATABASE_URL_DEV
REDIS_URL_DEV

Import without saving

Use dry-run to preview names before storing anything:

.\vault.exe import-env --suffix DEV --dry-run

Overwrite existing secrets during import

.\vault.exe import-env --suffix DEV --overwrite

Run an app with secrets loaded

.\vault.exe run --suffix DEV -- python app.py

This loads matching secrets into the child process environment.

Example mapping:

API_KEY_DEV -> API_KEY
DATABASE_URL_DEV -> DATABASE_URL
REDIS_URL_DEV -> REDIS_URL

Inside Python:

import os

api_key = os.environ["API_KEY"]
database_url = os.environ["DATABASE_URL"]

Secret values are not printed by the vault.

Use from Python

You can also use Local Secret Vault from another Python project.

Install the package:

pip install localsecretvault

Then unlock the vault first:

vault unlock --hours 8

In your Python app:

from localsecretvault import load_secrets

load_secrets(suffix="DEV")

Example mapping:

API_KEY_DEV -> os.environ["API_KEY"]
DATABASE_URL_DEV -> os.environ["DATABASE_URL"]

You can also read one secret directly:

from localsecretvault import get_secret

api_key = get_secret("API_KEY_DEV")

Or list secret names:

from localsecretvault import list_secret_names

names = list_secret_names(suffix="DEV")

The vault must already be unlocked before using these helpers.

Export secrets to clipboard

To copy all secrets to clipboard as .env text:

.\vault.exe export

To copy only secrets with a suffix:

.\vault.exe export --suffix DEV

The export command:

• requires the vault to be unlocked
• shows secret names only
• asks you to type EXPORT
• copies secret values to clipboard
• does not print secret values in the terminal

Example exported format:

API_KEY_DEV=actual-secret-value
DATABASE_URL_DEV=actual-secret-value
REDIS_URL_DEV=actual-secret-value

Save the exported content somewhere else.

Rename a secret

.\vault.exe rename OLD_NAME NEW_NAME

To overwrite the target name if it already exists:

.\vault.exe rename OLD_NAME NEW_NAME --overwrite

Delete a secret

.\vault.exe delete API_KEY_DEV

You will be asked to confirm before deletion.

Change master password

First lock the vault:

.\vault.exe lock

Then run:

.\vault.exe change-password

Lock the vault

.\vault.exe lock

This stops the local background process and removes the temporary server state.

Daily usage

Typical daily flow:

cd $HOME\local-secret-vault

.\vault.exe unlock --hours 8

.\vault.exe run --suffix DEV -- python app.py

When finished:

.\vault.exe lock

Where data is stored

By default, the encrypted vault is stored under:

C:\Users\<YourUser>\.local-secrets

The main encrypted vault file is:

C:\Users\<YourUser>\.local-secrets\vault.json

The vault file is encrypted. Do not edit it manually.

Environment variable

You can override the vault storage location with:

$env:LOCAL_SECRET_VAULT_HOME = "C:\path\to\vault-folder"

Most users do not need this.

Security notes

• Secrets are encrypted on disk.
• Secrets are decrypted only while the vault is unlocked.
• While unlocked, secrets are available to the local vault process.
• vault run passes selected secrets only to the command you run.
• Python helpers load selected secrets into the current Python process.
• vault export copies decrypted secrets to the clipboard.
• Clipboard content may be visible to other apps while it remains in the clipboard.
• Lock the vault when finished.

Build from source

Install dependencies in a virtual environment, then run:

.\build.ps1

The built executable will be created at:

dist\vault.exe

Build Python package from source

Install build tools:

python -m pip install build

Build the wheel and source distribution:

python -m build

The Python package files will be created in:

dist