bwsf (Bitwarden Secured Files) is a CLI tool that uses Bitwarden to manage .env* files and Terraform *.tfvars / *.tfvars.json.
v0.20.0 breaking changes: global config moves to ~/.config/bwsf/config.jsonc (multi-host schema). Legacy flat config.json is migrated on first run (confirm or --yes). not_save_files is removed (use save_files with ! prefixes). The bw CLI backend and bwsf backend are removed (API only).
Login to Bitwarden may fail on v0.17.0 and v0.17.1. If you are on the v0.17 line, please upgrade to v0.17.2 or later first.
bwsf manages project files in Bitwarden: .env*, *.tfvars, and *.tfvars.json (names containing .example are excluded).
Simple usage below:
| command | |
|---|---|
| bwsf setup | Configure hosts and global save_files (API only) |
| bwsf auth login | Store API Key, verify Identity, unlock vault |
| bwsf auth logout | Remove API Key and vault session |
| bwsf unlock / lock | Persist or clear vault session (vault_unlock) |
| bwsf init | Create project .bwsf/config.jsonc |
| bwsf config show | Show current local configuration |
| bwsf push | Push managed files to your Bitwarden host |
| bwsf pull | Pull managed files from your Bitwarden host |
| bwsf list | List stored projects at your Bitwarden host |
| bwsf clean | Remove local managed files after verifying Bitwarden backup |
We use Bitwarden as our password manager long time ago. Also, we store .env files our Bitwarden host, manage them as shell scripts. This project migrates our hand-maded shell scripts to modern CLI command with Go.
No Bitwarden CLI (bw) install is required. bwsf talks to Bitwarden over the API.
You need:
- A Bitwarden account (Cloud or self-hosted / Vaultwarden)
- A Personal API Key (Account Settings → Security → Keys)
- OS secret store access (macOS Keychain / Linux secret service) for storing the API key
Homebrew is used to install bwsf itself.
- macOS
- Linux
- [Is planning] Windows
| OS | command |
|---|---|
| macOS | brew tap b4m-oss/tap && brew install bwsf |
| Linux | brew tap b4m-oss/tap && brew install bwsf |
Note: Linux requires Homebrew on Linux to be installed first.
Install a past release from the tap. Versioned formulas cover every patch of the current minor plus the latest patch of the previous minor (older formulas are pruned). Other releases remain on GitHub Releases.
brew install bwsf@0.18.0bwsf -v
# bwsf version 0.20.0bwsf setupConfigure Bitwarden hosts (skippable) and optional global save_files. Settings are saved to ~/.config/bwsf/config.jsonc.
By default, notes are stored in a Bitwarden folder named dotenvs (target_section on each host). To use a different folder name:
bwsf setup --folder my-envsChanging the folder name does not move existing notes; move them manually in Bitwarden if needed.
You can pass --host <id> on push / pull / list / clean when multiple hosts are configured.
Check saved values with:
bwsf config showcd /path/to/your_project
bwsf pullbwsf searches Bitwarden for a Note matching the current directory name. If it exists, managed files are written to the current directory. If a target file already exists locally, bwsf asks whether to overwrite it (per file).
cd /path/to/your_project
bwsf pushbwsf pushes managed files from the current directory to your Bitwarden host.
If a Note with the same project name already exists in the configured folder (default: dotenvs), bwsf updates it without an overwrite prompt.
bwsf listPrints project names from Bitwarden, one per line on stdout.
cd /path/to/your_project
bwsf cleanRemoves local managed files after verifying the remote Bitwarden backup.
bwsf setup # hosts + optional save_files (+ optional folder)
bwsf auth login # store Personal API Key; unlock vault (vault_unlock)
bwsf push # restores vault_unlock when present, else prompts MP
bwsf pull
bwsf listbwsf auth login prompts for client_id / client_secret, stores them in the OS secret store (macOS Keychain / Linux secret service), verifies Identity, then unlocks the vault and persists vault_unlock. Use bwsf auth logout to remove the stored key and session (bwsf lock clears the session only). Bare bwsf auth prints help.
Create a Personal API Key in the Bitwarden web vault under Account Settings → Security → Keys.
On each push / pull / list, bwsf restores vault_unlock when available, or prompts for your master password, then discards in-memory keys and tokens when the command exits.
Caveat: unlock uses the Community SDK password-login path with config email + master password for key material. Identity Personal API Key tokens remain separate.
On first run, legacy ~/.config/bwsf/config.json (flat schema) is detected and migrated after confirmation (or with --yes). A backup is written next to the original file. Project configs that still use not_save_files must be rewritten to save_files with ! prefixes (load error otherwise).
brew uninstall bwsfQ. I don't have Bitwarden account.
To use bwsf, you need a Bitwarden account.
You can access to Bitwarden Cloud, sign up a account.
No fee, No credit card.
Q. I'm Bitwarden self hosted user.
Ofcourse, bwsf is available for Bitwarden self hosted users.
You can input your self hosted URL when initial setup.
Q. How does my .env file store at Bitwarden host?
Your managed files are converted to JSON syntax. bwsf creates a Bitwarden Note item and puts that JSON in the Note section.
Q. Where are my Bitwarden account info
bwsf stores your config data at ~/.config/bwsf/ (formal file: config.jsonc).
But, secure information (ex. password) is never stored.
Docker is needed to be installed your development machine.
git clone https://github.com/b4moss/bwsf.git
cd bwsf
make run