layered-soul/skills/vaultwarden-secrets/SKILL.md

name	description	version	author	platforms
vaultwarden-secrets	Self-hosted Vaultwarden + Bitwarden CLI for agent secrets management — storing passwords, API tokens, and SSH passphrases programmatically.	1.0.0	Sam & Hermes	linux

Vaultwarden Agent Secrets

Self-hosted Vaultwarden server with bw CLI for headless agent access to secrets. Replaces pasting tokens into chat.

Setup

Server (Docker)

docker run -d --name vaultwarden \
  -v /vw-data:/data \
  -p 8080:80 \
  vaultwarden/server:latest

Put it behind nginx + Let's Encrypt. Admin page at /admin.

First Account

First account created via web UI (https://vault.<domain>) becomes admin.

Organization + Collections

Organization: Clawdie
  Collection: agent-secrets    → day-to-day tokens, passwords
  Collection: bootstrap        → admin tokens, setup keys (admin only)
  Collection: deploy           → deploy secrets (per-host access)

CLI Install

npm install -g @bitwarden/cli
bw config server https://vault.<domain>

On systems where node/npm aren't on default PATH (e.g. nvm-managed), use the full path:

~/.nvm/versions/node/v24.16.0/bin/npm install -g @bitwarden/cli
export PATH="$HOME/.nvm/versions/node/v24.16.0/bin:$PATH"

Auth — Personal API Key (NOT Organization)

Organization API keys (organization.xxx) do NOT work with bw login --apikey (returns "Organization API Key currently not supported"). Generate a personal API key from web vault → Account Settings → Security → Keys → View API Key. This gives a user.xxx client_id.

export BW_CLIENTID="user.xxx"
export BW_CLIENTSECRET="xxx"
bw login --apikey

After login, bw status shows "status":"locked". Unlock with master password via env var:

export BW_PASSWORD="<master-password>"
bw unlock --passwordenv BW_PASSWORD
# Outputs a session key — use it with every command:
bw list organizations --session "QyeGJoqVLttR..."

The --session flag is more explicit than BW_SESSION env var — avoids leaking session into other commands.

Sync After Web UI Changes

Collections/items created via web UI don't appear in CLI until synced:

bw sync --session "..."
bw list collections --organizationid <org-id> --session "..."

Creating Items (Piped JSON Pattern)

The simple --username/--password flags on bw create item don't accept org items reliably. Use bw encode + pipe:

echo '{"type":1,"name":"item-name","notes":"description","login":{"username":"user","password":"pass","uris":[{"uri":"https://example.com","match":0}]},"organizationId":"<org-guid>"}' | bw encode | bw create item --session "..."

Moving Items Between Collections

bw create item has no --collectionid flag. Items default to the personal vault. To assign to an org collection after creation:

bw get item <item-guid> --session "..." | python3 -c "
import sys,json
d=json.load(sys.stdin)
d['collectionIds']=['<collection-guid>']
print(json.dumps(d))
" | bw encode | bw edit item <item-guid> --session "..."

Retrieving Secrets

bw get item "item-name" --session "..." | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['login']['password'])"

Pitfalls

• Organization API keys don't work for bw login. Must use personal API key from user account settings.
• bw login --apikey is interactive — doesn't accept stdin piping. Use BW_CLIENTID + BW_CLIENTSECRET env vars.
• Session expires. After login, run bw unlock --raw to get a session key, export as BW_SESSION. On Vaultwarden you must first log out then log in: bw logout && bw login --apikey.
• Vaultwarden admin page is separate from the web vault at /admin. First user is auto-admin.
• Self-signed certs require NODE_TLS_REJECT_UNAUTHORIZED=0 — but prefer Let's Encrypt.

Multi-Agent Usage

Each agent host gets its own Bitwarden account (e.g. hermes-debby@clawdie.si). Add them to the Clawdie organization and grant collection access per need. Agents authenticate via bw login --apikey with their own personal API key. No shared credentials, no master passwords in automation.

References

Topic	File	Description
bw CLI Reference	references/bw-cli-reference.md	Full bw CLI command reference with pitfalls
bw CLI Quirks	references/bw-cli-quirks.md	Option naming gotchas, --apikey pitfall, session behavior
Instance Details	references/instance-details.md	vault.smilepowered.org: org/collection IDs, login flow
Instance Config	references/vault.smilepowered.org.md	Server setup and configuration details

• Vaultwarden: https://github.com/dani-garcia/vaultwarden
• Bitwarden CLI: https://bitwarden.com/help/cli/