Bitwarden CLI（bw）使用

[!info] related notes Bitwarden [[vaultwarden|Vaultwarden]] 命令行界面（CLI） 零知识加密架构

目标

用官方 bw 命令行工具在脚本/自动化中读写 Bitwarden 保险库：登录、解锁得到 session、增删查条目、以 JSON 输出，并可启动本地 REST 供其他程序调用。成功标准是能在无 GUI 环境用一条命令取出某条目的密码或 TOTP。

前置条件

• 已安装 bw（npm i -g @bitwarden/cli，或包管理器/独立二进制）。
• 有 Bitwarden 账户；自托管用户需先配置服务端地址。

核心心智模型

bw 有两个独立状态，别混淆：

• 登录（login）：证明你是账户所有者，得到 API 会话；跨命令持久。
• 解锁（unlock）：用主密码解开保险库，产生一个 BW_SESSION 令牌；几乎所有读写命令都要带它。

登录 ≠ 解锁：登录后仍是「锁定」状态，必须 unlock 拿到 session 才能读数据——这正是零知识的体现，密钥只在解锁时于本地存在。

步骤

1.（自托管）指向你的服务端

bw config server https://pass.example.com

官方云用户跳过此步。

2. 登录

bw login you@example.com
# 有两步验证时按提示输入；CI 场景可用 API Key 方式：
# BW_CLIENTID / BW_CLIENTSECRET 环境变量 + bw login --apikey

3. 解锁，拿到 session

export BW_SESSION=$(bw unlock --raw)
# --raw 只输出 session 令牌，便于赋值给环境变量

之后命令自动读取 BW_SESSION（或显式 --session $BW_SESSION）。

4. 常用读写

bw sync                                   # 拉取最新保险库
bw list items --search github             # 搜索条目
bw get item <id>                          # 取单条（JSON）
bw get password <id-or-name>              # 只取密码
bw get totp <id-or-name>                  # 取当前 TOTP 验证码
echo '{...}' | bw encode | bw create item # 创建条目（先 encode）
bw generate -ulns --length 24             # 生成随机密码

bw 默认输出 JSON，配合 jq 可脚本化提取字段。

5.（可选）启动本地 REST：bw serve

bw serve --port 8087
# 之后本机 http://localhost:8087 提供 REST，如：
# curl http://localhost:8087/list/object/items

适合让本机其他程序通过 HTTP 读写，而不必反复解锁。

6. 用完锁定/登出

bw lock      # 清除 session，保留登录
bw logout    # 完全登出

验证

bw get password "some-login" && echo OK

能打印出密码即说明登录、解锁、session 链路正常。

常见问题

• 命令报 You are not logged in 或 vault is locked：没设 BW_SESSION 或已过期，重新 bw unlock --raw。
• 自托管连不上：漏了 bw config server，或域名未走 HTTPS（见 vaultwarden-nginx-proxy-manager-https）。
• CI 里交互式登录卡住：改用 API Key（--apikey + BW_CLIENTID/SECRET）与 BW_PASSWORD 环境变量非交互解锁。
• 把 session 写进脚本明文：等于泄露解锁能力，应只放进进程环境变量，任务结束即 bw lock。