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

# bw CLI Quirks & Gotchas

Encountered during the May 29, 2026 Vaultwarden setup session.

## Option Naming Inconsistency

`bw` is inconsistent with dashes vs no-dashes in multi-word options:

| Expected            | Actual             |
| ------------------- | ------------------ |
| `--collection-id`   | `--collectionid`   |
| `--organization-id` | `--organizationid` |

Always check `bw <command> --help | grep <keyword>` before assuming flag format.

## `--apikey` Interactive Prompt

`bw login --apikey` uses an interactive prompt that doesn't work with `<<<` heredoc or piped input.
The `readline` interface crashes with `ERR_USE_AFTER_CLOSE` when stdin closes early.

**Only use `BW_CLIENTID` + `BW_CLIENTSECRET` env vars.**

## Organization API Keys Rejected

`bw login --apikey` with `organization.xxx` client_id returns:

```
Invalid API Key; Organization API Key currently not supported
```

Must use a **personal** API key (`user.xxx`) from Account Settings → Security → Keys → View API Key.
The personal user then accesses org data through their org membership.

## `--passwordenv` vs `--raw`

- `bw unlock --passwordenv BW_PASSWORD` — prints a human-friendly message with the session key embedded
- `bw unlock --passwordenv BW_PASSWORD --raw` — prints ONLY the session key (for scripts)
- Prefer `--session` flag on individual commands over `BW_SESSION` env var for explicitness

## `bw create item` Limitations

- No `--collectionid` or `--organizationid` flags (despite docs suggesting otherwise)
- Items created by org members go to personal vault by default
- Must use `bw encode` pipe pattern for full JSON control
- Move to collection after creation with `bw edit item`

## Vaultwarden Session Behavior

Unlike Bitwarden Cloud, Vaultwarden requires explicit `bw logout && bw login --apikey` to refresh expired sessions.
The `bw unlock --raw` approach returns a fresh session key each time.

## `npm install -g` Browser Extension Prompt

During `npm install -g @bitwarden/cli`, npm may show:

```
You can't autofill passwords without the browser extension
Are you sure you don't want to add the extension now?
```

Skip it. The `bw` CLI is headless — browser extension is irrelevant for agent use.