layered-soul/skills/vaultwarden-secrets/references/bw-cli-reference.md

# bw CLI Reference

Quick-reference for the `bw` (Bitwarden) CLI against a self-hosted Vaultwarden instance.

## Install

```sh
npm install -g @bitwarden/cli
```

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

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

## Login (headless API key)

```sh
bw config server https://vault.example.com
bw login --apikey
# Non-interactive: set BW_CLIENTID + BW_CLIENTSECRET env vars, then:
bw login --apikey
```

## Unlock (headless)

```sh
BW_PASSWORD="master-password" bw unlock --passwordenv BW_PASSWORD
# Returns session key — capture BW_SESSION from output
```

Or combine: `bw login --apikey && bw unlock --passwordenv BW_PASSWORD`

## Status

```sh
bw status  # {"status":"locked"} or {"status":"unlocked"}
```

## Organization Collections

```sh
# List
bw list collections --organizationid <org-id> --session "$BW_SESSION"

# Sync (after creating new collections in web UI)
bw sync --session "$BW_SESSION"
```

## Item CRUD

### Create

```sh
echo '{"type":1,"name":"...","login":{"username":"...","password":"..."},"organizationId":"<org-id>"}' | \
  bw encode | bw create item --session "$BW_SESSION"
```

### Get

```sh
bw get item "Item Name" --session "$BW_SESSION"
# Returns JSON including .login.password, .login.username, .login.uris
```

### Get by ID (extract password)

```sh
bw get item <id> --session "$BW_SESSION" | python3 -c "import sys,json; print(json.load(sys.stdin)['login']['password'])"
```

### Edit (e.g., move to collection)

```sh
bw get item <id> --session "$BW_SESSION" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); d['collectionIds']=['<col-id>']; print(json.dumps(d))" | \
  bw encode | bw edit item <id> --session "$BW_SESSION"
```

### List all items

```sh
bw list items --session "$BW_SESSION" | python3 -c "import sys,json; [print(i['name']) for i in json.load(sys.stdin)]"
```

## Lock

```sh
bw lock  # Locks vault, invalidates session
```

## Item Types

| type | Name                              |
| ---- | --------------------------------- |
| 1    | Login (username + password + URI) |
| 2    | Secure Note                       |
| 3    | Card                              |
| 4    | Identity                          |

## Pitfalls

- Organization API keys don't work with `bw login --apikey`. Use a personal API key (`user.xxx`).
- `--organizationid` flag is `--organizationid` not `--organization-id`.
- `--collectionids` flag doesn't exist on `bw create item` — use `organizationId` in the JSON body and set `collectionIds` via `bw edit item` after creation.
- Session tokens expire. Run `bw status` to check.
- After creating collections in the web UI, run `bw sync` before `bw list collections`.
- `bw login --apikey` is interactive — doesn't accept stdin piping. Use `BW_CLIENTID` + `BW_CLIENTSECRET` env vars for non-interactive use.
- On Vaultwarden you must first log out then log in: `bw logout && bw login --apikey`.

## Forgejo integration example

```sh
bw get item "hermes-debby Forgejo" --session "$BW_SESSION" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'user={d[\"login\"][\"username\"]} pass={d[\"login\"][\"password\"]}')"
```