Securely interact with Bitwarden/Vaultwarden vaults using rbw CLI. Use when retrieving credentials, managing vault items, or integrating secrets into scripts/systemd services. Handles authentication, field access, and non-interactive operation patterns.

快速参考

rbw unlock                                          # 解锁密码库
rbw list                                            # 列出所有条目
rbw list --fields "name,folder"                     # 显示文件夹信息的列表
rbw get item_name                                   # 获取密码
rbw get --folder folder_name item_name              # 从指定文件夹获取
rbw get --folder folder_name item_name --field url  # 获取特定字段
rbw sync                                            # 同步密码库

命令语法

get

rbw get [OPTIONS] <NAME> [USER]

选项：
  --folder <FOLDER>  指定搜索的文件夹
  --field <FIELD>    指定要检索的字段（不指定则默认为密码）
  --full             输出中包含备注内容
  --raw              以 JSON 格式输出
  --clipboard        将结果复制到剪贴板

<NAME> 是位置参数。[USER] 用于在多个条目名称相同时进行区分。所有选项标志（如 --folder、--field 等）必须位于位置参数之前。

rbw get --folder homelab portainer
rbw get --folder homelab portainer --field url
rbw get my_password
rbw get --folder work email user@example.com   # 使用 USER 进行名称歧义解析

list

rbw list [OPTIONS]

选项：
  --fields <FIELDS>  指定显示的字段：id, name, user, folder, type
  --raw              以 JSON 格式输出

注意：rbw list 不支持 --folder 过滤。如需按文件夹筛选，可使用 rbw list --fields "name,folder" 配合 grep 实现。

rbw list --fields "name,folder"
rbw list --raw | jq

add

rbw add [OPTIONS] <NAME> [USER]

选项：
  --folder <FOLDER>  新条目所属的文件夹
  --uri <URI>        条目的网址

rbw 会提示输入密码。如有备注内容，则会在 $EDITOR 中打开编辑。

rbw add --folder homelab my_service admin_user
rbw add --folder homelab --uri https://example.com my_service

字段名称

字段名称 区分大小写，必须与 Vaultwarden 中定义的完全一致。

rbw get --folder homelab item                      # 密码（不使用 --field）
rbw get --folder homelab item --field Username     # 默认的用户名字段（首字母大写）
rbw get --folder homelab item --field database     # 自定义字段
rbw get --folder homelab item --field api_key      # 自定义字段

若需查看某条目所有字段，可使用：

rbw get --folder homelab item --raw | jq

认证方式

交互式认证

# 检查解锁状态（已解锁返回 0，锁定返回非零）
rbw unlocked

# 解锁（提示输入主密码）
rbw unlock

非交互式认证（适用于 systemd/脚本）

安全提示：此方法将主密码存储在明文文件中。即使设置为 600 权限并由 root:root 拥有，仍存在安全风险。在高安全性环境中，建议使用 systemd 的原生 LoadCredential= 机制替代。

1. 创建 pinentry 包装脚本（~/.local/bin/pinentry-rbw-systemd）：

#!/usr/bin/env bash
if [ -n "$RBW_MASTER_PASSWORD" ]; then
    echo "OK Pleased to meet you"
    while IFS= read -r line; do
        case "$line" in
            GETPIN)
                echo "D $RBW_MASTER_PASSWORD"
                echo "OK"
                ;;
            BYE)
                echo "OK closing connection"
                exit 0
                ;;
            *)
                echo "OK"
                ;;
        esac
    done
else
    exec /usr/bin/pinentry-curses "$@"
fi

2. 配置 rbw 使用该脚本：

chmod +x ~/.local/bin/pinentry-rbw-systemd
rbw config set pinentry ~/.local/bin/pinentry-rbw-systemd
rbw config show   # 验证配置

3. 存储主密码（文件：/etc/systemd/rbw-credentials.conf，权限 root:root，chmod 600）：

RBW_MASTER_PASSWORD=your_master_password_here

4. systemd 服务配置示例：

[Service]
User=tripleight
EnvironmentFile=/etc/systemd/rbw-credentials.conf
ExecStart=/path/to/script.sh

5. 脚本使用模式：

#!/usr/bin/env bash
set -euo pipefail

if ! rbw unlocked 2>/dev/null; then
    rbw unlock || { echo "ERROR: Failed to unlock rbw" >&2; exit 1; }
fi

rbw sync

USERNAME=$(rbw get --folder homelab service_name --field Username 2>/dev/null \
  || { echo "ERROR: Cannot read username (homelab/service_name)" >&2; exit 1; })
PASSWORD=$(rbw get --folder homelab service_name 2>/dev/null \
  || { echo "ERROR: Cannot read password (homelab/service_name)" >&2; exit 1; })

curl -u "$USERNAME:$PASSWORD" https://api.example.com

Vaultwarden 条目设置示例

一个常用于 rbw 的典型条目：

文件夹：   homelab
名称：     postgres_backup
类型：     登录项
用户名：   postgres          ← 通过 --field Username 访问
密码：     **********        ← 不使用 --field 即可访问

自定义字段：
  database  production      ← 通过 --field database 访问
  host      db.example.com
  port      5432

对应的脚本访问方式：

USERNAME=$(rbw get --folder homelab postgres_backup --field Username)
PASSWORD=$(rbw get --folder homelab postgres_backup)
DATABASE=$(rbw get --folder homelab postgres_backup --field database)
HOST=$(rbw get --folder homelab postgres_backup --field host)
PORT=$(rbw get --folder homelab postgres_backup --field port)

错误处理

始终检查退出码，并提供可操作的错误信息：

VALUE=$(rbw get --folder homelab item --field field 2>/dev/null \
  || { echo "ERROR: Cannot read 'field' from vault (homelab/item)" >&2; exit 1; })

if [ -z "$VALUE" ]; then
    echo "ERROR: Field is empty in vault" >&2
    exit 1
fi

故障排查

“agent is locked” — 执行 rbw unlock 解锁。

“field not found” — 字段名称区分大小写。请使用 rbw get item --raw | jq 检查实际字段名。确认后运行 rbw sync 以确保密码库为最新状态。

Systemd 服务无法解锁：

1. 确认 /etc/systemd/rbw-credentials.conf 存在且包含正确的主密码
2. 检查权限：sudo ls -l /etc/systemd/rbw-credentials.conf（期望值为 root:root 600）
3. 验证 pinentry 配置：rbw config show
4. 手动测试：sudo -u tripleight bash -c 'export RBW_MASTER_PASSWORD=...; rbw unlock'

项目未找到 — 使用 rbw list --fields "name,folder" 检查文件夹和项目名称，然后执行 rbw sync。

最佳实践

始终在读取前同步以确保获取最新的库状态。在尝试读取前始终检查解锁状态，避免不必要的提示。显式处理错误并提供有意义的提示信息。绝不硬编码密钥——所有操作均使用 rbw。确保 systemd 凭据文件权限为 600，所有者为 root:root。使用文件夹对跨环境的项目进行组织（如生产、预发布、家庭实验室等）。