@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 setup

You'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 credentials

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-stdin

Options: --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-hidden values 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 --json

Accepted 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
done

Sharing 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 default

Once 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)

Flags mirror add: --username, --url (repeatable, replaces the URI list), --notes, --totp, --field/--field-hidden (upsert by name), --folder, --password-stdin.

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 folder

Attachments (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>    # remove

Browsing 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 names

Add --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 - --capitalize

Credit-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. Visa

Discovering 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.data

For 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 bw via environment variables, never command-line arguments. nbg-pw never prints secret values in status, 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