FFFF GitHub - hex/bwsh: Shell wrapper for Bitwarden Secrets Manager CLI - manage secrets by name, run commands with secrets injected, import/export .env files · GitHub
[go: up one dir, main page]

Skip to content
hexPublic

About

Shell wrapper for Bitwarden Secrets Manager CLI - manage secrets by name, run commands with secrets injected, import/export .env files

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

24 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

bwsh

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.

Prerequisites

  • bws - Bitwarden Secrets Manager CLI
  • jq - JSON processor
  • age - Modern encryption tool, for the local cache that get, export, run --only and bwsh_load read
  • A Bitwarden Secrets Manager account with an access token

Installation

From source

git clone https://github.com/hex/bwsh.git
cd bwsh
./install.sh

Quick install

curl -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 bwsh to ~/.local/bin/
  • Installs shell completions for bash and zsh
  • Optionally runs credential setup

Setup

After installation, run the setup command to configure your credentials:

bwsh setup

This will prompt you for:

  1. Your BWS access token (stored securely in ~/.config/bwsh/token)
  2. 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.

Usage

Run Commands with Secrets

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

Without --only, every secret in the project is injected:

bwsh run npm start
bwsh run -p <project_id> npm start
  • --only reads 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.

Fetch One Secret in a Script

OPENAI_API_KEY="$(bwsh get OPENAI_API_KEY)" || exit 1

bwsh 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/Import .env Files

# 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

Manage Secrets by Name

# 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_KEY

Function Mode

Source the script to get shell functions:

# Add to ~/.bashrc or ~/.zshrc
source ~/.local/bin/bwsh

Then 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 shell

Each function runs the bwsh command, so bwsh must be on your PATH. bwsh_load is the only one that changes your shell.

Loading Secrets at Shell Startup

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_load exports 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 --only or bwsh get at 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)").

Encrypted Caching

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 age

How it works:

  1. First read: fetches every secret the token can read, encrypts them with age, stores them locally
  2. Later reads: decrypt the local cache (instant)
  3. The cache refreshes when older than the TTL (default: 1 hour), and after bwsh set or bwsh delete
  4. Secret names must be valid environment variable names. BWS_ACCESS_TOKEN and names starting with _bwsh_ are reserved; a cache refresh fails, naming the offender, if the vault has one.
  5. A secret name that exists in more than one project keeps the last copy bws lists, with a warning when the cache refreshes. Use -p to pick a project.

Cache management:

bwsh cache status    # Check cache state
bwsh cache refresh   # Force refresh now
bwsh cache clear     # Delete local cache

Configuration:

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 export lines) is replaced on the next read

Tab Completion

After installation, enable completions in your shell:

Bash - Add to ~/.bashrc:

[[ -f ~/.bash_completion.d/bwsh.bash ]] && source ~/.bash_completion.d/bwsh.bash

Zsh - Add to ~/.zshrc (before compinit):

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Project Resolution

Commands that create secrets (set, env import) and run without --only need a project. Projects are resolved in this order:

  1. Explicit flag (--project or -p) - highest priority
  2. Default project from config (BWS_DEFAULT_PROJECT_ID)
  3. 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.

Uninstall

bwsh uninstall          # Remove bwsh, keep config and cache
bwsh uninstall --force  # Remove everything including credentials

After uninstalling, remove these lines from your shell rc file:

source ~/.local/bin/bwsh
bwsh_load ...

Environment Variables

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

Files

~/.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

License

MIT

About

Shell wrapper for Bitwarden Secrets Manager CLI - manage secrets by name, run commands with secrets injected, import/export .env files

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages

0