Shell wrapper for Bitwarden Secrets Manager CLI (bws).
Simplifies local development by letting you manage secrets by name (not UUID), run commands with secrets injected, and migrate to/from .env files.
- bws - Bitwarden Secrets Manager CLI
- jq - JSON processor
- age - Modern encryption tool, for the local cache that
get,export,run --onlyandbwsh_loadread - A Bitwarden Secrets Manager account with an access token
git clone https://github.com/hex/bwsh.git
cd bwsh
./install.shcurl -fsSL https://raw.githubusercontent.com/hex/bwsh/main/install.sh | bash
⚠️ Always review scripts (install.sh) before running them from the internet.
The installer:
- Adds
bwshto~/.local/bin/ - Installs shell completions for bash and zsh
- Optionally runs credential setup
After installation, run the setup command to configure your credentials:
bwsh setupThis will prompt you for:
- Your BWS access token (stored securely in
~/.config/bwsh/token) - Your default project ID (optional - stored in
~/.config/bwsh/project)
If you skip setting a default project, you'll be prompted to select one interactively when needed, or you can specify one with the --project flag. You can also set BWS_DEFAULT_PROJECT_ID in the environment.
The access token is only read from the token file. bwsh passes it to each bws call and never exports it, so it never reaches your shell or the commands you run. An exported BWS_ACCESS_TOKEN is ignored; remove it from your shell rc file.
Give a command only the secrets it needs with --only:
bwsh run --only OPENAI_API_KEY -- python app.py
bwsh run --only OPENAI_API_KEY,GEMINI_API_KEY -- ./eval.sh
# Also drop everything else from the environment (keeps PATH, HOME, USER,
# LOGNAME, SHELL, TMPDIR, TERM, LANG, LC_*)
bwsh run --clean --only OPENAI_API_KEY -- ./provider.shWithout --only, every secret in the project is injected:
bwsh run npm start
bwsh run -p <project_id> npm start--onlyreads the local cache (or the project live, with-p). If any named secret is missing, or the list is empty, the command does not start and every missing name is reported.- Without
--only, the project is read live from bws. - The command never receives
BWS_ACCESS_TOKEN, and values are set inside bwsh before it runs, so they never appear on a command line (ps).
No .env file needed - secrets are injected directly into the subprocess.
OPENAI_API_KEY="$(bwsh get OPENAI_API_KEY)" || exit 1bwsh get reads the local cache and exits 1 with an error on stderr if the secret doesn't exist. Command substitution strips trailing newlines, so use it for single-line values such as API keys.
# Export secrets to .env format
bwsh env export > .env.local
# Import secrets from .env file
bwsh env import .env
# Import to a specific project
bwsh env import .env -p <project_id>
# Preview what would be imported
bwsh env import .env --dry-run# Store a secret (prompts for value if omitted)
bwsh set API_KEY
bwsh set API_KEY sk-abc123 # Value lands in shell history; prefer the prompt
# Retrieve a secret (from the local cache; add -p to read a project live)
bwsh get API_KEY
# Use a specific project (overrides default)
bwsh set DB_PASS secret --project abc123
bwsh get DB_PASS -p abc123
# List all secrets
bwsh list
# Delete a secret
bwsh delete API_KEYSource the script to get shell functions:
# Add to ~/.bashrc or ~/.zshrc
source ~/.local/bin/bwshThen use the functions directly:
bwkey API_KEY # Store
bwgetkey API_KEY # Retrieve
bwkeys # List
bwdelkey API_KEY # Delete
bwrun npm start # Run with secrets
bwenv export # Export .env
bwsh_load OPENAI_API_KEY # Export named secrets into this shellEach function runs the bwsh command, so bwsh must be on your PATH. bwsh_load is the only one that changes your shell.
Every variable your shell exports is inherited by every program it starts, so export only the secrets you need everywhere, by name:
# ~/.zshrc or ~/.bashrc
source ~/.local/bin/bwsh
bwsh_load OPENAI_API_KEY GEMINI_API_KEY- If any named secret is missing,
bwsh_loadexports nothing and fails, naming the missing ones. - With no names, it fails instead of loading everything. To load every secret, ask for it:
bwsh_load --all. Every program the shell starts then inherits all of them (the access token is never included). - For anything else, use
bwsh run --onlyorbwsh getat the point of use.
bwsh export NAME... (or --all) prints the export lines that bwsh_load evaluates, for use in scripts (eval "$(bwsh export NAME)").
get, export, run --only and bwsh_load read a local cache encrypted with age, so they need no API call.
First, install age:
brew install ageHow it works:
- First read: fetches every secret the token can read, encrypts them with age, stores them locally
- Later reads: decrypt the local cache (instant)
- The cache refreshes when older than the TTL (default: 1 hour), and after
bwsh setorbwsh delete - Secret names must be valid environment variable names.
BWS_ACCESS_TOKENand names starting with_bwsh_are reserved; a cache refresh fails, naming the offender, if the vault has one. - A secret name that exists in more than one project keeps the last copy bws lists, with a warning when the cache refreshes. Use
-pto pick a project.
Cache management:
bwsh cache status # Check cache state
bwsh cache refresh # Force refresh now
bwsh cache clear # Delete local cacheConfiguration:
export BWSH_CACHE_TTL=7200 # 2 hour TTL (default: 3600)Security:
- Cache is encrypted with age (ChaCha20-Poly1305)
- Age key stored at
~/.config/bwsh/age.key(chmod 600) - Cache stored at
~/.cache/bwsh/secrets.age - If bws is unavailable, stale cache is used with a warning
- A cache from bwsh 2026.4.0 or earlier (shell
exportlines) is replaced on the next read
After installation, enable completions in your shell:
Bash - Add to ~/.bashrc:
[[ -f ~/.bash_completion.d/bwsh.bash ]] && source ~/.bash_completion.d/bwsh.bashZsh - Add to ~/.zshrc (before compinit):
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinitCommands that create secrets (set, env import) and run without --only need a project. Projects are resolved in this order:
- Explicit flag (
--projector-p) - highest priority - Default project from config (
BWS_DEFAULT_PROJECT_ID) - Interactive selection - if no default is set, you'll be prompted to choose
If you have only one project, it will be auto-selected without prompting.
bwsh uninstall # Remove bwsh, keep config and cache
bwsh uninstall --force # Remove everything including credentialsAfter uninstalling, remove these lines from your shell rc file:
source ~/.local/bin/bwsh
bwsh_load ...| Variable | Description | Default |
|---|---|---|
BWS_DEFAULT_PROJECT_ID |
Default project ID for creating secrets | (from config file) |
BWSH_TOKEN_FILE |
Path to token file | ~/.config/bwsh/token |
BWSH_PROJECT_FILE |
Path to project ID file | ~/.config/bwsh/project |
BWSH_CACHE_DIR |
Cache directory | ~/.cache/bwsh |
BWSH_CACHE_TTL |
Cache TTL in seconds | 3600 |
~/.local/bin/bwsh # Main script
~/.config/bwsh/token # Access token (chmod 600)
~/.config/bwsh/project # Default project ID
~/.config/bwsh/age.key # Age encryption key (chmod 600)
~/.cache/bwsh/secrets.age # Encrypted secrets cache
~/.bash_completion.d/bwsh.bash # Bash completions
~/.zsh/completions/_bwsh # Zsh completions
MIT