@nightlybuildgroup/vault
v1.9.0
Published
Store Vaultwarden/Bitwarden credentials in the macOS Keychain and read secrets back for local agents.
Readme
@nightlybuildgroup/vault (nbg-pw)
Store your Vaultwarden/Bitwarden credentials in the macOS Keychain with an interactive wizard, then let local agents and scripts read secrets back through the Bitwarden CLI. macOS only. Nothing is hardcoded — you supply the server URL and credentials at setup time.
Requirements
- macOS
- Node.js >= 18
- Bitwarden CLI:
brew install bitwarden-cli
Setup
npm i -g @nightlybuildgroup/vault
nbg-pw setupYou'll be asked for your server URL, email, API-key client id/secret, and master
password. Credentials are verified against the server before anything is saved.
If your account belongs to an organization, setup then offers to pick a default
collection to share newly added items into (or keep them in your personal
vault) — you can change this any time with nbg-pw config.
Get your API key from your Vaultwarden web vault: Settings → Security → Keys → API Key (
client_id/client_secret).
Usage
nbg-pw get "GitHub" # prints the password
nbg-pw get "GitHub" --field username # a built-in field
nbg-pw get "GitHub" --custom apiToken # a custom field, looked up by name
nbg-pw get "My Visa" --field number # a credit-card field (see below)
nbg-pw list "My Visa" # show an item's field names + types, no values
printf '%s' "$pw" | nbg-pw add "GitHub" --username octocat --password-stdin
printf '%s' "$pw" | nbg-pw edit "GitHub" --password-stdin # update an existing item
nbg-pw attach "GitHub" --file ./key.pem # add an attachment; --list/--get/--delete too
nbg-pw delete "GitHub" # soft-delete to trash (alias: rm; --permanent skips it)
nbg-pw items --search git # list item names; also: folders, collections
nbg-pw generate --length 24 --symbols # generate a password (no vault needed)
nbg-pw config set collection "Shared" # new items share into this org collection
nbg-pw serve --port 8087 # local bw REST API for fast repeated reads
nbg-pw status # presence + auth state (no secrets)
nbg-pw doctor # diagnose bw / Keychain / connectivity
nbg-pw logout # lock the session
nbg-pw reset # log out and delete stored credentialsConcurrent calls run one at a time
Every bw unlock replaces the session key of the one before it, so two overlapping
calls would break each other's session. Each call that touches the vault holds a lock
(nbg-pw.lock in bw's data directory) until it exits, and other calls wait for it, for
up to 5 minutes. A lock left behind by a killed process is taken over. A call takes
several seconds, so a script that needs one secret many times should read it once.
How an item name is resolved
Anywhere a command takes an <item> (get, list, edit, delete, attach)
you may pass a name or an id. Names match by substring, so several items can
match one query — but an exact name match wins: if the name you gave is an
exact (case-insensitive) match for exactly one item, that item is used, even when
other items' names merely contain it. This keeps prefix-shaped naming schemes
usable:
nbg-pw get steerd-s3-staging --custom access_key_id # the exact item…
nbg-pw get steerd-s3-staging-admin --custom access_key_id # …not shadowed by this oneOnly a query that matches several items and none of them exactly is an error, and it prints the candidates so you can pick one:
$ nbg-pw get steerd-s3
Error: more than one item matches "steerd-s3" — pass an id, or a name that matches exactly:
b98e50c0-… steerd-s3-staging
2f905b18-… steerd-s3-staging-admin
$ echo $?
3Exit codes: 0 success, 1 a command-level failure (including "item not
found"), 3 an ambiguous item lookup, 2 anything unexpected. 3 is separate
from 1 so a script that discards stderr can still tell a vague query from a
missing item — both print nothing on stdout.
Adding items (add)
Creates a login item. The password never goes on the command line (it would
be visible in ps) — it's read from stdin, or supplied via --json.
# Flag mode — password piped on stdin:
printf '%s' "$pw" | nbg-pw add "GitHub" \
--username octocat \
--url https://github.com \
--notes "work account" \
--folder "Agents" \
--field plan=pro \
--field-hidden token="$tok" \
--password-stdinOptions: --username, --url (repeatable), --notes, --folder (resolved by
name, created if missing), --collection / --organization (shares the item
into an org collection), --field name=value (text, repeatable),
--field-hidden name=value (hidden, repeatable), --totp. On success it prints
Created "<name>" (<id>) — never any secret value.
Note: in flag mode,
--field-hiddenvalues still pass through argv. For secret custom fields use--json(below), which keeps everything off the command line.
JSON mode — secret-safe bulk automation
nbg-pw add --json reads one entry as a JSON object on stdin, so every value
(password, hidden fields, notes) stays off argv:
jq -n --arg name GitHub --arg u octocat --arg p "$pw" --arg t "$tok" \
'{name:$name, username:$u, password:$p, uris:["https://github.com"],
folder:"Agents", fields:[{name:"token", value:$t, type:1}]}' \
| nbg-pw add --jsonAccepted keys: name (required), username, password, uris (array),
notes, totp, folder, collection, organization, and fields
([{name, value, type}]; type 0 = text, 1 = hidden).
Migrating a KeePass .kdbx to Bitwarden
Loop your KeePass entries and pipe each into add --json — secrets flow through
stdin only:
DB=~/Documents/Agents.kdbx
for path in $(keepassxc-cli ls -R -f "$DB"); do
[ "${path%/}" != "$path" ] && continue # skip groups
user=$(keepassxc-cli show -q -a UserName "$DB" "$path")
pass=$(keepassxc-cli show -q -a Password "$DB" "$path")
url=$( keepassxc-cli show -q -a URL "$DB" "$path")
group=$(dirname "$path")
jq -n --arg n "$(basename "$path")" --arg u "$user" --arg p "$pass" \
--arg url "$url" --arg f "$group" \
'{name:$n, username:$u, password:$p,
uris:(if $url=="" then [] else [$url] end),
folder:(if $f=="." then null else $f end)}' \
| nbg-pw add --json
doneSharing new items with an organization (config)
By default add creates items in the API account's personal vault, which
other org members (and your own interactive login) can't see. To make every new
item land in a shared organization collection instead, set a default — it's
stored in your Keychain, never in this repo, so nothing org-specific is baked
into the tool:
nbg-pw config set organization "Acme Inc" # by name or id
nbg-pw config set collection "Shared" # by name or id
nbg-pw config show # current defaults
nbg-pw config unset collection # back to personal-vault defaultOnce a default collection is set, every add shares the new item into it:
printf '%s' "$pw" | nbg-pw add "GitHub" --username octocat --password-stdin
# → Created "GitHub" (…) → shared to "Shared"
nbg-pw add "Personal Note" --personal # opt a single item out (personal vault)An explicit --collection/--organization on add overrides the default for
that call. status shows the active default share.
Editing items (edit)
Fetch-merge-write: only the flags you pass are changed; everything else stays.
Same secret discipline as add — the password comes from stdin.
printf '%s' "$newpw" | nbg-pw edit "GitHub" --password-stdin
nbg-pw edit "GitHub" --notes "rotated 2026-06" --field plan=enterprise
nbg-pw edit "GitHub" --folder "Agents" # move into a folder (created if missing)
nbg-pw edit "GitHub" --name "GitHub Work" # rename in placeFlags mirror add: --name, --username, --url (repeatable, replaces the
URI list), --notes, --totp, --field/--field-hidden (upsert by name),
--folder, --password-stdin.
--name renames the item in place — same id, same attachments and history — so
fixing a name collision no longer means add + delete, which would briefly
store the same secret twice. Renaming onto a name another item already uses is
allowed (Bitwarden permits duplicates) but warns, since two items sharing one
exact name cannot be told apart by name at all:
$ nbg-pw edit "GitHub" --name "Gitlab"
Warning: 1 other item is already named "Gitlab"; after this rename none of them
can be fetched by name — use ids.
Updated "Gitlab" (b98e50c0-…)Deleting (delete / rm)
nbg-pw delete "GitHub" # soft-delete to trash
nbg-pw delete "GitHub" --permanent # skip the trash
nbg-pw delete --folder "Agents" # delete a folderAttachments (attach)
nbg-pw attach "GitHub" --file ./deploy-key.pem # upload
nbg-pw attach "GitHub" --list # id, filename, size (no contents)
nbg-pw attach "GitHub" --get deploy-key.pem --output ./key.pem # download
nbg-pw attach "GitHub" --delete <attachment-id> # removeBrowsing the vault (items, folders, collections)
Names only, never values — handy for scripting and for finding the exact item
name to pass to get/edit/attach.
nbg-pw items # every item name
nbg-pw items --search git # filtered by search
nbg-pw items --folder "Agents" # filtered by folder
nbg-pw folders # folder names
nbg-pw collections # collection names
nbg-pw organizations # organization namesAdd --ids to any of them to print ids alongside names — useful for config set
or scripting. collections --ids also shows each collection's org id:
$ nbg-pw organizations --ids
dfff… Acme Inc
$ nbg-pw collections --ids
bf2b… Shared (org dfff…)(You can pass either a name or an id to config set / add --collection, so
ids are optional — handy mainly when names are ambiguous.)
Generating secrets (generate)
Pure generator — needs no vault session.
nbg-pw generate --length 24 --uppercase --number --symbols
nbg-pw generate --passphrase --words 5 --separator - --capitalizeCredit-card items
Credit cards have no username or password — just card data. bw has no native
getter for those, so nbg-pw reads them from the item and exposes each as a
--field:
nbg-pw get "My Visa" --field number # card number
nbg-pw get "My Visa" --field cvv # security code (alias: code)
nbg-pw get "My Visa" --field expiration # "MM/YYYY" (alias: exp)
nbg-pw get "My Visa" --field cardholder # cardholder name
nbg-pw get "My Visa" --field brand # e.g. VisaDiscovering fields with list
Not sure what a custom field is called, or which fields an item has? list
prints the item type, the built-in fields you can get, and every custom field
name with its type — never any values:
$ nbg-pw list "My Visa"
Type: card
Built-in: number, cvv, expiration, cardholder, brand
Custom fields:
billingZip (text)
pin (hidden)Reading custom fields over serve
serve is a thin wrapper around Bitwarden's own bw serve REST API, which has
no route for a single custom field. Built-in fields are addressable directly:
curl -s localhost:8087/object/username/GitHub | jq -r .data.dataFor a custom field, fetch the whole item and pluck it from data.fields[]:
curl -s localhost:8087/object/item/GitHub \
| jq -r '.data.fields[] | select(.name=="apiToken").value'(The CLI nbg-pw get "GitHub" --custom apiToken does this lookup for you.)
Security notes
- Credentials live in one macOS Keychain item (
service: com.nightlybuild.vault), encrypted at rest by the Keychain. - Secrets are passed to
bwvia environment variables, never command-line arguments.nbg-pwnever prints secret values instatus,doctor, logs, or errors. - Vaultwarden does not support Bitwarden Secrets Manager / machine accounts, so this uses the password-manager API-key + master-password flow.
License
MIT
Part of the cli-tools monorepo (@nightlybuildgroup/vault).
