# Password Manager CLI {% hint style="success" %} 对应的[官方文档地址](https://bitwarden.com/help/article/cli/) {% endhint %} Bitwarden 命令行界面 (CLI) 是一个强大且功能齐全的工具，用于访问和管理您的密码库。您在其他 Bitwarden 客户端应用程序（桌面、浏览器扩展等）能找到的许多功能也可以通过 CLI 实现。 {% embed url="" %} Bitwarden CLI {% endembed %} Bitwarden CLI 是自带文档的。在命令行中，使用以下命令了解可用的命令： ```shellscript bw --help ``` 或者，在任何 `bw` 命令上传递 `--help` 选项，以查看命令可用的选项和示例： ```shellscript bw list --help bw share --help ``` 您所需要的大部分信息都可以通过 `--help` 来获取，然而这篇文章复制了所有这些信息，并对一些主题进行了更深入的探讨。 ## 下载和安装 可以在 Windows、macOS 和 Linux 发行版上跨平台使用 CLI。要下载和安装 Bitwarden CLI： {% hint style="info" %} 对于 arm64 设备，请使用 `npm` 安装 CLI。 {% endhint %} {% tabs %} {% tab title="本地可执行文件" %} CLI 的本地打包版本可用于每个平台，并且无须依赖。使用以下链接下载： * [Windows x64](https://vault.bitwarden.com/download/?app=cli\&platform=windows) * [macOS x64](https://vault.bitwarden.com/download/?app=cli\&platform=macos) * [Linux x64](https://vault.bitwarden.com/download/?app=cli\&platform=linux) 请注意，当使用下载的本机可执行文件时，您需要将可执行文件添加到您的 PATH 中，或者从文件下载到的目录运行命令。 {% hint style="success" %} 在 Linux 和 UNIX 系统中，您可能会收到 `Permission denied` （权限被拒绝）的消息。通过运行下面的命令授予权限： ```shellscript chmod +x ``` {% endhint %} 对于 GitHub 上提供的每个 Password Manager CLI 捆绑包，都有一个 OSS 版本（例如 `bw-oss-windows-2024.12.0.zip`）和非 OSS 版本（例如 `bw-windows-2024.12.0.zip`）。非 OSS 版本是分发平台上默认发布的软件包，包含非 OSS 许可下的功能，例如 OSS 版本所缺少的[设备批准](#device-approval)命令。 {% endtab %} {% tab title="NPM" %} 如果您的系统上已安装了 Node.js，则可以使用 NPM 安装 CLI。使用 NPM 进行安装是使安装保持最新的最简单方式，并且**对于已经熟悉 NPM 的用户来说，它应该是首选的方式**： ```shellscript npm install -g @bitwarden/cli ``` 在 [npmjs.org](https://www.npmjs.com/package/@bitwarden/cli) 上查看该软件包。 {% hint style="info" %} 使用 `npm` 在 Linux 系统上安装 Bitwarden CLI 可能需要首先安装构建必需的依赖项（或等效的发行版）。例如： ```shellscript apt install build-essential ``` {% endhint %} {% endtab %} {% tab title="Chocolatey" %} 要使用 Chocolatey 进行安装： ```shellscript choco install bitwarden-cli ``` 在 [community.chocolatey.org](https://chocolatey.org/packages/bitwarden-cli) 上查看该软件包。 {% endtab %} {% tab title="Snap" %} 要使用 Snap 进行安装： ```shellscript sudo snap install bw ``` 在 [snapcraft.io](https://snapcraft.io/bw) 上查看该软件包。 {% endtab %} {% tab title="Flatpak" %} Bitwarden CLI 包含在 Flatpak 桌面 App 下载中。安装 Flatpak： ```shellscript flatpak install flathub com.bitwarden.desktop ``` 在 [Flathub](https://flathub.org/apps/com.bitwarden.desktop) 上查看该软件包。 运行 C​​LI 命令： ```shellscript flatpak run --command=bw com.bitwarden.desktop # use a shell alias to authorize a session alias bw="flatpak run --command=bw com.bitwarden.desktop" bw ``` {% endtab %} {% endtabs %} ## 登录 登录之前，请确保您的 CLI 使用 `config` 命令连接到了正确的服务器（例如 [EU 云](https://help.ppgg.in/docs/security/server-geographies)或自托管）（[了解更多](#confirm)）。使用 `login` 命令登录 Bitwarden CLI 共有三种方式，每种方式适用于不同的场景。请查看以下选项以确定使用哪种方式： * [使用电子邮箱和密码](#using-email-and-password) * [使用 API 密钥](#using-an-api-key) * [使用 SSO](#using-sso) {% hint style="success" %} 无论您使用哪个选项，都要求使用主密码来 `unlock` 客户端，以便使用[会话密钥](#unlock)访问数据。[电子邮箱和主密码](#using-email-and-password)选项将验证您的身份并同时生成会话密钥，但如果使用 [API 密钥](#using-an-api-key)或 [SSO](#using-sso)，则需要您后续使用 `unlock` 命令来生成会话密钥（如果您要直接操作数据）。 [使用受信任设备加入组织](https://help.ppgg.in/admin-console/login-with-sso/trusted-devices/about-trusted-devices#impact-on-master-passwords)的用户将无法通过 CLI 访问数据。但是，有一些命令不需要解密数据，因此无需主密码也可使用，包括 `config`、`encode`、`generate`、`update` 以及 `status`。 {% endhint %} ### 使用电子邮箱和密码 电子邮箱和密码方式的登录**建议用于交互式会话场景**。要使用电子邮箱和密码登录： ```shellscript bw login ``` 此命令将提示您输入**电子邮箱地址**、**主密码**和**两步登录代码**（若[已启用](https://help.ppgg.in/docs/account/two-step-login/setup-two-step-login/two-step-login-methods)）。CLI 目前支持[身份验证器](https://help.ppgg.in/docs/account/two-step-login/setup-two-step-login/two-step-login-via-authenticator)、[电子邮箱](https://help.ppgg.in/docs/account/two-step-login/setup-two-step-login/two-step-login-via-email)或 [YubiKey](https://help.ppgg.in/docs/account/two-step-login/setup-two-step-login/two-step-login-via-yubikey) 方式的两步登录。 您可以像如下的示例那样将这些因素组合成一个命令，但是出于安全原因不建议这样操作。 ```shellscript bw login [email] [password] --method --code ``` 有关两步登录的 `` 值，请参阅[附录 → 枚举](#enums)。 {% hint style="success" %} **提示进行额外的身份验证**或收到 `Your authentication request appears to be coming from a bot.` 的错误提示？请使用您的 API 密钥 `client_secret` 回答身份验证挑战。[了解更多](https://help.ppgg.in/docs/password-manager/developer-tools/cli/cli-authentication-challenges)。 {% endhint %} ### 使用 API 密钥 [个人 API 密钥](https://help.ppgg.in/docs/password-manager/developer-tools/cli/personal-api-key)方式的登录**建议用于自动化工作流程或对外部应用程序提供访问的场景**。要使用 API ​​密钥方式登录： ```shellscript bw login --apikey ``` 此命令将提示您输入个人 `client_id` 和 `client_secret`。使用这些值对您的会话进行身份验证后，您就可以使用 `unlock` 命令了（[了解更多](#unlock)）。 {% hint style="success" %} 如果您的组织[要求 SSO](https://help.ppgg.in/admin-console/oversight-visibility/enterprise-policies#single-sign-on-authentication)，您仍然可以使用 `--apikey` 登录 CLI。 {% endhint %} #### 使用 API 密钥环境变量 在使用 Bitwarden CLI 完成自动化工作的场景中，您可以保存环境变量以避免在身份验证时需要手动介入。
环境变量名称要求的值
BW_CLIENTIDclient_id
BW_CLIENTSECRETclient_secret
### 使用 SSO [SSO](https://help.ppgg.in/docs/admin-console/login-with-sso/about-sso) 方式的登录**建议用于组织要求 SSO 身份验证的场景**。要使用 SSO 方式登录： ```shellscript bw login --sso ``` 此命令将在您的 Web 浏览器中启动 SSO 身份验证流程。您的会话通过身份验证后，您就可以使用 `unlock` 命令了（[了解更多](#unlock)）。 {% hint style="success" %} 如果您的组织[要求 SSO](https://help.ppgg.in/admin-console/oversight-visibility/enterprise-policies#single-sign-on-authentication)，您仍然可以使用 `--apikey` 登录 CLI。 {% endhint %} ### 登录到多个账户 与其他 Bitwarden App 的[账户切换](https://help.ppgg.in/docs/account/log-in-and-unlock/more-log-in-options/account-switching)功能类似，CLI 可以通过 `BITWARDENCLI_APPDATA_DIR` 环境变量同时登录多个账户，该环境变量指向一个 `bw` 配置文件（通常名为 `data.json`）的位置。例如，您可以在 `.bashrc` 配置文件中为两个不同的配置设置别名： ```shellscript alias bw-personal="BITWARDENCLI_APPDATA_DIR=~/.config/Bitwarden\ CLI\ Personal /path/to/bw $@" alias bw-work="BITWARDENCLI_APPDATA_DIR=~/.config/Bitwarden\ CLI\ Work /path/to/bw $@" ``` 使用此示例，您可以通过先运行 `source /path/to/.bashrc`，然后运行 ​​`bw-personal login` 和 `bw-work login` 来登录两个帐户。 ## 解锁 如果您直接使用密码库数据，则[使用 API 密钥](#using-an-api-key)或 [SSO](#using-sso) 方式将要求您在 `login` 命令后紧接着使用显式 `bw unlock` 命令。 解锁密码库会生成一个**会话密钥**，此会话密钥作为解密密钥用于与密码库中的数据进行交互。[会话密钥必须用于](#using-a-session-key)执行任何涉及密码库数据的命令（例如：`list`、`get`、`edit`）。您可以在任何时候使用以下方法生成一个新的会话密钥： ```shellscript bw unlock ``` ### 解锁选项 您可以像如下的示例那样为 `bw unlock` 添加 `--passwordenv ` 选项或 `--passwordfile ` 选项来使用您的主密码，而不需要手动输入： ```shellscript bw unlock --passwordenv BW_PASSWORD ``` 将查找环境变量 `BW_PASSWORD`。如果 `BW_PASSWORD` 为非空且具有正确的值，则 CLI 将成功解锁并返回一个会话密钥。 ```shellscript bw unlock --passwordfile ~/Users/Me/Documents/mp.txt ``` 将查找文件 `~Users/Me/Documents/mp.txt`（必须将您的主密码作为第一行）。如果文件非空且具有正确的值，CLI 将成功解锁并返回一个会话密钥。 {% hint style="warning" %} 如果您使用 `--passwordfile` 选项，请通过将访问权限锁定到仅需要运行 `bw unlock` 的用户并仅向该用户提供读取访问权限来保护您的密码文件。 {% endhint %} ### 使用会话密钥 当您使用电子邮箱和密码方式的 `bw login` 或 `bw unlock` 解锁您的密码库时，CLI 将同时返回 `export BW_SESSION`（Bash）和 `env:BW_SESSION`（PowerShell）命令，其中包含了您的会话密钥。复制并粘贴相关条目以保存所需的环境变量。 如果设置了 `BW_SESSION` 环境变量，`bw` 命令将引用该变量，以干净清爽地运行，例如： ```shellscript export BW_SESSION="5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w==" bw list items ``` 另外，如果您未设置环境变量，则可以在每个 `bw` 命令中将会话密钥作为选项传递： ```shellscript bw list items --session "5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w==" ``` {% hint style="success" %} `BW_SESSION` 环境变量仅绑定到活动的终端会话，因此关闭终端窗口等同于锁定密码库。您也可以通过运行以下命令来销毁一个活动会话密钥以锁定您的密码库： ```shellscript bw lock ``` {% endhint %} ## 核心命令 ### create `create` 命令用于在您的密码库中创建一个新的对象（ `item`，`attachment` 等）： ```shellscript bw create (item|attachment|folder|org-collection) [options] ``` `create` 命令使用已编码的 JSON。创建一个对象的典型工作流程大致为： 1. 使用 `get template` 命令（请参阅[详细信息](#get-template)）为对象类型输出适当的 JSON 模板。 2. 使用 [jq 之类的命令行 JSON 处理器](https://stedolan.github.io/jq/)根据需要操作已输出的模板。 3. 使用 `encode` 命令（请参阅[详细信息](#encode)）对已操作的 JSON 进行编码。 4. 使用 `create` 命令从已编码的 JSON 创建一个对象。 示例： ```shellscript bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder ``` 或： ```shellscript bw get template item | jq ".name=\"My Login Item\" | .login=$(bw get template item.login | jq '.username="jdoe" | .password="myp@ssword123"')" | bw encode | bw create item ``` 创建成功后，新创建的对象将作为 JSON 返回。 #### create 其他项目类型 `create` 命令默认创建登录项目，但您可以使用 [jq 之类的命令行 JSON 处理器](https://stedolan.github.io/jq/)更改 `.type=` 属性以创建其他项目类型： | 名称 | 值 | | ---- | --------- | | 登录 | `.type=1` | | 安全笔记 | `.type=2` | | 支付卡 | `.type=3` | | 身份 | `.type=4` | 例如，以下命令将创建一个安全笔记： ```shellscript bw get template item | jq '.type = 2 | .secureNote.type = 0 | .notes = "Contents of my Secure Note." | .name = "My Secure Note"' | bw encode | bw create item ``` {% hint style="info" %} 请注意，在上面的示例中，安全笔记需要一个子模板（`.secureNote.type`）。您可以使用 `bw get template` 查看项目类型的子模板（详细见[此处](#get)）。 {% endhint %} #### **create** attachment `create attachment` 命令用于将一个文件附加到一个**现有的**项目上。 与其他 `create` 操作不同，您无需使用 JSON 处理器或 `encode` 即可创建附件。相反，它使用 `--file` 选项指定要附加的文件，使用 `--itemid` 选项指定要附加到的项目。例如： ```shellscript bw create attachment --file ./path/to/file --itemid 16b15b89-65b3-4639-ad2a-95052a6d8f66 ``` {% hint style="success" %} 如果您不知道您要使用的确切的 `itemid`，请使用 `bw get item ` 以返回该项目（请参阅[详细信息](#get)），包括它的 `id`。 {% endhint %} ### get `get` 命令用于从您的密码库中检索单个对象（ `item`、`username`、`password`等）： ```shellscript bw get (item|username|password|uri|totp|exposed|attachment|folder|collection|organization|org-collection|template|fingerprint) [options] ``` `get` 命令使用项目 `id` 或字符串作为它的参数。如果你使用一个字符串（即除确切的 `id` 以外的任何东西），`get` 将检索您的密码库以寻找一个具有匹配值的对象。例如，下面的命令将返回一个 Github 密码： ```shellscript bw get password Github ``` {% hint style="info" %} `get` 命令**只能返回一个结果**，因此您应该使用明确的搜索词。如果找到多个结果，CLI 将返回错误。 {% endhint %} #### **get attachment** `get attachment` 命令用于下载文件附件： ```shellscript bw get attachment --itemid ``` `get attachment` 命令使用一个 `filename` 和**确切的** `id`。默认情况下，`get attachment` 将附件下载到当前工作目录。你可以使用 `--output` 选项来指定一个不同的输出目录，例如： ```shellscript bw get attachment photo.png --itemid 99ee88d2-6046-4ea7-92c2-acac464b1412 --output /Users/myaccount/Pictures/ ``` {% hint style="info" %} 使用 `--output` 时，路径必须以正斜杠（`/`）结尾，以指定一个目录或者一个文件名（`/Users/myaccount/Pictures/photo.png`）。 {% endhint %} #### **get template** `get template` 命令用于返回对象预期的 JSON 格式（`item`、`item.field`、`item.login` 等）： ```shellscript bw get template (item|item.field|item.login|item.login.uri|item.card|item.identity|item.securenote|folder|collection|item-collections|org-collection) ``` 虽然你*可以*使用 `get template` 将格式输出到你的屏幕上，但最常见的用法是将输出的数据输送到 `bw create` 操作中，使用 [jq 之类的命令行 JSON 处理器](https://stedolan.github.io/jq/)和 `bw encode` 来处理从模板获取的值，例如： ```shellscript bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder ``` {% hint style="info" %} 任何 `item.xxx` 模板都应作为 `item` 模板的子对象使用，例如： ```shellscript bw get template item | jq ".name=\"My Login Item\" | .login=$(bw get template item.login | jq '.username="jdoe" | .password="myp@ssword123"')" | bw encode | bw create item ``` {% endhint %} ### edit `edit` 用于编辑密码库中的对象（ `item`、`item-collections` 等）： ```shellscript bw edit (item|item-collections|folder|org-collection) [encodedJson] [options] ``` `edit` 命令使用一个**确切的** `id`（要编辑的对象）和编码的 JSON（要进行的编辑）。典型的工作流程大致为： 1. 使用 `get` 命令（请参阅[详细信息](#get)）输出对象用于编辑。 2. 使用 [jq 之类的命令行 JSON 处理器](https://stedolan.github.io/jq/)根据需要操作已输出的模板。 3. 使用 `encode` 命令（请参阅[详细信息](#encode)）对已操作的 JSON 进行编码。 4. 使用 `edit` 命令（包括对象 `id`）编辑对象。 示例： ```shellscript bw get item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 | jq '.login.password="newp@ssw0rd"' | bw encode | bw edit item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 ``` 或者，编辑一个集合： ```shellscript bw get collection ee9f9dc2-ec29-4b7f-9afb-aac8010631a1 | jq '.name="My Collection"' | bw encode | bw edit item-collections ee9f9dc2-ec29-4b7f-9afb-aac8010631a1 ``` `edit` 命令将对对象执行**替换**操作。成功后，更新后的对象将作为 JSON 返回。 ### list `list` 命令用于从您的密码库中检索一组对象（ `items`、`folders`、`collections` 等）： ```shellscript bw list (items|folders|collections|organizations|org-collections|org-members) [options] ``` `list` 命令的选项是**筛选器**，其决定了返回的内容，其包括 `--url `、`--folderid `、`--collectionid `、`--organizationid ` 以及 `--trash`。任何筛选器都接受 `null` 或 `notnull`。在一个命令中组合多个筛选器将执行逻辑 OR 运算，例如： ```shellscript bw list items --folderid null --collectionid null ``` 此命令将返回*不属于*任何文件夹或集合的项目。 另外，您可以使用 `--search ` 来搜索明确的对象。将筛选器和搜索结合在一个命令中将执行逻辑 AND 运算，例如： ```shellscript bw list items --search github --folderid 9742101e-68b8-4a07-b5b1-9578b5f88e6f ``` 此命令将在指定的文件夹中搜索具有字符串为 `github` 的项目。 ### delete `delete` 命令用于从您的密码库中删除一个对象。`delete` 仅使用确切的 `id` 作为其参数。 ```shellscript bw delete (item|attachment|folder|org-collection) [options] ``` 默认情况下，delete 将「软删除」一个项目（即将其发送到回收站）。您可以使用 `-p`，`--permanent` 选项永久删除项目。 ```shellscript bw delete item 7063feab-4b10-472e-b64c-785e2b870b92 --permanent ``` 要删除 `org-collection`，您还需要指定 `--organizationid ` 。请参阅[组织 ID](#organization-ids)。 {% hint style="warning" %} 使用 `delete` 「软删除」的项目可以使用 `restore` 命令恢复（请参阅[详细信息](#restore)），但是使用 `delete --permanent` 删除的项目**将被完全删除并且无法恢复**。 {% endhint %} ### restore `restore` 命令用于从回收站中恢复已删除的对象。`restore` 仅使用确切的 `id` 作为其参数。 ```shellscript bw restore (item) [options] ``` 例如： ```shellscript bw restore item 7063feab-4b10-472e-b64c-785e2b870b92 ``` ### send `send` 命令用于创建一个 [Bitwarden Send](https://help.ppgg.in/docs/password-manager/bitwarden-send/about-send) 对象进行短暂的共享。本节将详细介绍简单的 `send` 操作，然而 Send 是一个高度灵活的工具，我们建议参阅 [CLI 上的 Send](https://help.ppgg.in/docs/password-manager/bitwarden-send/send-from-cli) 这篇专门的文章。 要创建一个简单的文本 Send： ```shellscript bw send -n "My First Send" -d 7 --hidden "The contents of my first text Send." ``` 要创建一个简单的文件 Send： ```shellscript bw send -n "A Sensitive File" -d 14 -f /Users/my_account/Documents/sensitive_file.pdf ``` ### receive `receive` 命令用于访问 [Bitwarden Send](https://help.ppgg.in/docs/password-manager/bitwarden-send/about-send) 对象。要接收 Send 对象： ```shellscript bw receive --password passwordforaccess https://vault.bitwarden.com/#/send/yawoill8rk6VM6zCATXv2A/9WN8wD-hzsDJjfnXLeNc2Q ``` ## 组织命令 ### 组织 ID 从 CLI 访问组织经常需要知道组织的 ID 以及单个[成员](https://help.ppgg.in/docs/admin-console/manage-members/user-management)的 ID 和[集合](https://help.ppgg.in/docs/admin-console/manage-shared-items/collections/about-collections)的 ID。 使用 `bw list` 命令从 CLI 直接检索这些信息，例如： ```shellscript bw list organizations bw list org-members --organizationid 4016326f-98b6-42ff-b9fc-ac63014988f5 bw list org-collections --organizationid 4016326f-98b6-42ff-b9fc-ac63014988f5 ``` {% hint style="success" %} 您可以同时 `bw list` `collections` 和 `org-collections`。`bw list collections` 将列出*所有*集合，而与它们所属的组织无关。`bw list org-collections` 将*仅*列出属于使用 `--organizationid` 指定的组织的集合。 {% endhint %} ### move {% hint style="info" %} **2021 年 8 月**：`share` 命令已被更改为 `move`。[了解更多](https://help.ppgg.in/docs/release-notes)。 {% endhint %} `move` 命令用于将密码库项目[转移到组织](https://help.ppgg.in/docs/password-manager/organization-members/sharing)： ```shellscript bw move [encodedJson] ``` `move` 命令要求您 `encode` 集合 ID，并使用一个**确切的** `id`（要共享的对象）和一个**确切的** `organizationid`（要与之共享对象的组织）。例如： ```shellscript echo '["bq209461-4129-4b8d-b760-acd401474va2"]' | bw encode | bw move ed42f44c-f81f-48de-a123-ad01013132ca dfghbc921-04eb-43a7-84b1-ac74013bqb2e ``` 成功后，将返回更新后的项目。 ### confirm `confirm` 命令用于确认已接受邀请的[受邀成员](https://help.ppgg.in/admin-console/manage-members/user-management#confirm)加入您的组织： ```shellscript bw confirm org-member --organizationid ``` `confirm` 命令使用**确切的**成员 `id` 和**确切的**组织 `id`，例如： ```shellscript bw confirm org-member 7063feab-4b10-472e-b64c-785e2b870b92 --organizationid 310d5ffd-e9a2-4451-af87-ea054dce0f78 ``` ### 设备批准 允许管理员和所有者在用户已请求管理员批准时管理设备批准请求。 {% hint style="info" %} 目前，批量设备批准仅适用于从 Bitwarden.com 下载的 Bitwarden CLI 客户端。 {% endhint %} {% hint style="danger" %} 在大多数情况下，用户可以批准自己的登录请求，不需要管理员设备批准。请参阅[添加受信任设备](https://help.ppgg.in/docs/account/log-in-and-unlock/using-single-sign-on/add-a-trusted-device)。自动或批量批准管理员设备批准请求会忽略管理员为确保请求合法而执行的验证步骤，例如检查用户报告的指纹短语。 Bitwarden 建议在启用和使用批量设备批准之前，先审查重要的安全控制措施，例如 IdP 凭证标准、IdP MFA 以及 IdP 设备注册和信任。 {% endhint %} `list` 命令用于显示组织内所有待处理的设备批准请求： ```shellscript bw device-approval list --organizationid ``` `approve` 命令用于批准组织内待处理的设备授权请求： ```bash bw device-approval approve --organizationid ``` 同理， `approve-all` 命令用于批准所有当前待处理的请求： ```bash bw device-approval approve-all --organization ``` `deny` 用于拒绝待处理的授权请求： ```bash bw device-approval deny --organizationid ``` `deny-all` 用于拒绝所有待处理的授权请求： ```bash bw device-approval deny-all --organizationid ``` ## 其他命令 ### config `config` 命令用于指定 Bitwarden CLI 说使用的设置： ```shellscript bw config server [value] ``` `bw config` 的主要用途是[将 CLI 连接到自托管 Bitwarden 服务器](https://help.ppgg.in/self-hosting/connect-clients/connect-individual-clients#cli)： ```shellscript bw config server https://your.bw.domain.com ``` {% hint style="success" %} 您可以通过传递不带值的 `bw config server` 来读取当前已连接的服务器。 {% endhint %} 具有唯一设置的用户可以选择使用以下方法单独指定每一个服务的 URL： ```shellscript bw config --web-vault bw config --api bw config --identity bw config --icons bw confbw config server --web-vault bw config server --api bw config server --identity bw config server --icons bw config server --notifications bw config server --events bw config server --key-connector ``` {% hint style="info" %} 如果您的组织使用 [Key Connector](https://help.ppgg.in/docs/self-hosting/key-connector/about-key-connector) 并且您在[移除您的主密码](https://help.ppgg.in/account/log-in-and-unlock/using-single-sign-on/using-login-with-sso#login-using-sso)后使用 `--apikey` 选项登录，则需要运行 `bw config server --key-connector` 命令。 联系组织所有者以获取所需的 URL。 {% endhint %} ### sync `sync` 命令用于从 Bitwarden 服务器下载加密的密码库。[登录](#log-in) CLI 后，您又在其他客户端应用程序（例如网页密码库、浏览器扩展、移动应用程序）上对 Bitwarden 密码库进行了某些更改时，此命令很有用。 ```shellscript bw sync ``` 您可以传递 `--last` 选项，以仅返回上次执行同步的时间戳（[ISO 8601](https://zh.wikipedia.org/wiki/ISO_8601)）。 {% hint style="success" %} 重要的是要知道 `sync` **仅从服务器执行拉取操作**。任何时候您更改密码库时（例如 `create`、`edit`、`delete`），数据都会自动推送到服务器。 {% endhint %} ### encode `encode` 命令用于对 stdin（标准输入） 进行 Base 64 编码。在执行 `create` 和 `edit` 操作时，此命令通常与 [json 这样的命令行 JSON 处理器](https://stedolan.github.io/jq/)结合使用，例如： ```shellscript bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder bw get item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 | jq '.login.password="newp@ssw0rd"' | bw encode | bw edit item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 ``` ### import `import` 命令用于从之前的 Bitwarden 导出或[其他受支持的密码管理应用程序](https://help.ppgg.in/docs/password-manager/import-and-export/import-data)中导入数据。该命令必须指向一个**文件**并包含如下参数： ```shellscript bw import ``` 例如： ```shellscript bw import lastpasscsv /Users/myaccount/Documents/mydata.csv ``` {% hint style="success" %} Bitwarden 支持多种导入格式，太多了而无法在这里一一列出！使用 `bw import --formats` 在 CLI 中返回列表，或[参阅这里](https://help.ppgg.in/docs/import-and-export/import-and-export-faqs#q-what-file-formats-does-bitwarden-support-for-import)。 {% endhint %} ### export `export` 命令用于将密码库数据导出为 `.json` 或 `.csv` 或[加密的 .json](https://help.ppgg.in/docs/password-manager/import-and-export/encrypted-exports) 文件： ```shellscript bw export [--output ] [--format ] [--password ] [--organizationid ] ``` 默认情况下，`export` 命令将在当前工作目录下生成一个 `.csv`（相当于指定 `--format csv`）文件，但您也可以指定： * `--format json`：导出为 `.json` 文件 * `--format encrypted_json`：导出为[加密的 .json](https://help.ppgg.in/docs/password-manager/import-and-export/encrypted-exports) 文件 * `--password `：指定用于加密 `encrypted_json` 导出的密码，而不是您的[账户加密密钥](https://help.ppgg.in/docs/security/encryption/encryption-key-rotation) * `--output `：指定导出位置 * `--raw`：将导出返回到 stdout（标准输出）而不是文件 #### 导出组织密码库 使用带有 `--organizationid` 选项的 `export` 命令，可以导出组织密码库： ```shellscript bw export myp@ssw0rd --organizationid 7063feab-4b10-472e-b64c-785e2b870b92 --format json --output /Users/myaccount/Downloads/ ``` ### generate `generate` 命令用于生成一个强密码或[密码短语](#generate-a-passphrase)： ```shellscript bw generate [--lowercase --uppercase --number --special --length --passphrase --separator --words ] ``` 默认情况下，`generate` 命令将生成一个包含 14 个字符的密码，其中包含大写字符、小写字符和数字。其等效于： ```shellscript bw generate -uln --length 14 ``` 您可以使用该命令可用的选项来生成更复杂的密码，选项包括： * `--uppercase` 或 `-u`（包含大写字符） * `--lowercase` 或 `-l`（包含小写字符） * `--number` 或 `-n`（包含数字） * `--special` 或 `-s`（包含特殊字符） * `--length `（密码长度，最小值为 5） #### 生成密码短语 使用带有 `--passphrase` 选项的 `generate` 命令，可以生成一个密码短语而不是密码： ```shellscript bw generate --passphrase --words --separator ``` 默认情况下，`bw generate --passphrase` 命令将生成一个 3 个单词的密码短语，并用破折号（-）分隔。这等效于： ```shellscript bw generate --passphrase --words 3 --separator - ``` 您可以使用该命令可用的选项来生成更复杂的密码短语，选项包括： * `--words `（单词数量） * `--separator `（分隔符） * `--capitalize, -c`（密码短语中首字母大写） * `--includeNumber`（密码短语中包含数字） ### update `update` 命令用于检查您的 Bitwarden CLI 是否正在运行最新版本。`update` **不会为您自动更新 CLI**。 ```shellscript shbw update ``` 如果检测到新的版本，则需要使用打印的可执行文件 URL 来下载新版本的 CLI，或使用用于[下载 CLI](#download-and-install) 的程序包管理器工具（例如 `npm install -g @bitwarden/cli`）来下载新版本的 CLI。 ### status `status` 命令用于返回 Bitwarden CLI 的状态信息，包括[已配置](#config)的服务器 URL、最后一次同步的时间戳（[ISO 8601](https://zh.wikipedia.org/wiki/ISO_8601)）、用户电子邮箱和 ID，以及密码库状态。 ```shellscript bw status ``` 状态将以 JSON 对象的形式返回信息，例如： ```yaml { "serverUrl": "https://bitwarden.example.com", "lastSync": "2020-06-16T06:33:51.419Z", "userEmail": "user@example.com", "userId": "00000000-0000-0000-0000-000000000000", "status": "unlocked" } ``` `status` 的值可能是以下之一： * `"unlocked"`：表示您已登录并且您的密码库已解锁（即保存了含活动[会话密钥](#using-a-session-key)的 `BW_SESSION` 密钥环境变量）。 * `"locked"`：表示您已登录但是您的密码库已锁定（即**没有**保存含活动[会话密钥](#using-a-session-key)的 `BW_SESSION` 密钥环境变量）。 * `"unauthenticated"`：表示您尚未登录。 {% hint style="success" %} 当使用 `"status": "unauthenticated"` 时，`lastSync`、`userEmail` 和 `userID` 将始终返回 `null`。 {% endhint %} ### serve `serve` 命令用于启动一个本地紧急 Web 服务器，该服务器用于执行所有可从 CLI 访问的操作，这些操作以来自 HTTP 接口的 RESTful API 调用的形式。 ```shellscript bw serve --port --hostname ``` 默认情况下，`serve` 将在 8087 端口启动 Web 服务器，但您可以使用 `--port` 选项指定备用端口。 默认情况下，`serve` 会将您的 API Web 服务器绑定到 `localhost`，但您可以使用 `--hostname` 选项指定备用主机名。API 请求只能从绑定的主机名发出。 默认情况下，`serve` 将阻止任何带有 Origin 标头的请求。您可以使用 `--disable-origin-protection` 选项绕过此保护，但**不建议这样做**。 {% hint style="danger" %} 您可以指定 `--hostname all` 以不绑定主机名，但这将允许网络上的任何机器发出 API 请求。 {% endhint %} [查看 API 规范](https://bitwarden.com/help/vault-management-api/)以获取使用 `serve` 进行调用的帮助。 ### 调试 可以添加调试环境变量以获取其他故障排除信息。 ```shellscript export BITWARDENCLI_DEBUG=true ``` ## 附录 ### 全局选项 以下选项全局可用： | 选项 | 描述 | | --------------------- | ----------------------- | | `--pretty` | 格式化输出。JSON 使用两个空格的制表符。 | | `--raw` | 返回原始输出，而不是描述性消息。 | | `--response` | 返回响应输出的 JSON 格式版本。 | | `--quiet` | 不要将任何东西返回 stdout（标准输出）。 | | `--nointeraction` | 对于输入交互式用户，不做提示。 | | `--session ` | 传递会话密钥，而不是从环境变量中读取会话密钥。 | | `-v, --version` | 输出 Bitwarden CLI 的版本号。 | | `-h, --help` | 显示命令的帮助文本。 | ### ZSH Shell 补全 Bitwarden CLI 支持 ZSH Shell 补全。要设置 Shell 补全，请使用下面的方法之一： 1、**Vanilla ZSH**：将下面行添加到您的 `.zshrc` 文件中： ```shellscript eval "$(bw completion --shell zsh); compdef _bw bw;" ``` 2、**Vanilla (vendor-completions)**：运行如下命令： ```shellscript bw completion --shell zsh | sudo tee /usr/share/zsh/vendor-completions/_bw ``` 3、[**zinit**](https://github.com/zdharma/zinit)：运行如下命令： ```shellscript bw completion --shell zsh > ~/.local/share/zsh/completions/_bw zinit creinstall ~/.local/share/zsh/completions ``` ### 使用自签名证书 如果您的自托管 Bitwarden 服务器公开为自签名 TLS 证书，请指定 Node.js 环境变量 [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file)： Bash： ```shellscript export NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" ``` PowerShell： ```powershell $env:NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem" ``` ### 枚举 下面的表格列举了在自文档情景下所需要的值： #### 两步登录方式 用于指定在[登录](#log-in)时使用哪一种[两步登录方式](https://help.ppgg.in/docs/account/two-step-login/setup-two-step-login/two-step-login-methods)： | 名称 | 值 | | ------- | - | | 验证器 | 0 | | 电子邮箱 | 1 | | Yubikey | 3 | {% hint style="info" %} CLI 不支持 FIDO2 和 Duo。 {% endhint %} #### 项目类型 与 `create` 命令一起使用以指定[项目的类型](https://help.ppgg.in/docs/password-manager/your-vault/vault-items/vault-items)： | 名称 | 值 | | ---- | - | | 登录 | 1 | | 安全笔记 | 2 | | 支付卡 | 3 | | 身份 | 4 | #### 登录 URI 匹配类型 与 `create` 和 `edit` 命令一起使用以指定 [URI 匹配检测](https://help.ppgg.in/docs/password-manager/autofill/troubleshoot-autofill/forming-uris-for-autofill)行为： | 名称 | 值 | | ----- | - | | 基础域 | 0 | | 主机 | 1 | | 开始于 | 2 | | 精确 | 3 | | 正则表达式 | 4 | | 从不 | 5 | #### 字段类型 与 `create` 和 `edit` 命令一起使用以配置[自定义字段](https://help.ppgg.in/docs/password-manager/your-vault/vault-items/custom-fields)： | 名称 | 值 | | --- | - | | 文本 | 0 | | 隐藏 | 1 | | 布尔型 | 2 | #### 组织用户类型 指示[用户的类型](https://help.ppgg.in/docs/admin-console/manage-members/member-roles)： | 名称 | 值 | | --- | - | | 所有者 | 0 | | 管理员 | 1 | | 用户 | 2 | | 经理 | 3 | #### 组织用户状态类型 指示[用户在组织内的状态](https://help.ppgg.in/docs/admin-console/manage-members/user-management)： | 名称 | 值 | | --- | - | | 受邀 | 0 | | 已接受 | 1 | | 已确认 | 2 |