密码管理器 CLI
对应的官方文档地址
Bitwarden 命令行界面 (CLI) 是一个强大且功能齐全的工具,用于访问和管理您的密码库。您在其他 Bitwarden 客户端应用程序(桌面、浏览器扩展等)能找到的许多功能也可以通过 CLI 实现。
Bitwarden CLI 是自带文档的。在命令行中,使用以下命令了解可用的命令:
或者,在任何 bw
命令上传递 --help
选项,以查看命令可用的选项和示例:
您所需要的大部分信息都可以通过 --help
来获取,然而这篇文章复制了所有这些信息,并对一些主题进行了更深入的探讨。
下载和安装
可以在 Windows、macOS 和 Linux 发行版上跨平台使用 CLI。根据需要选择下载和安装 Bitwarden CLI 的方式:
CLI 的本地打包版本可用于每个平台,并且无须依赖。使用以下链接之一下载:
在 UNIX 系统中,您可能会收到 Permission denied
(权限被拒绝)的消息。通过运行下面的命令授予权限::
登录
使用 login
命令登录 Bitwarden CLI 共有三种方式,每种方式适用于不同的场景。请查看以下选项以确定使用哪种方式:
使用电子邮件和密码
电子邮件和密码方式的登录建议用于交互式会话场景。要使用电子邮件和密码登录:
此命令将提示您输入电子邮件地址、主密码和两步登录代码(若已启用)。CLI 目前支持身份验证器、电子邮件或 YubiKey 方式的两步登录。
您可以像如下的示例那样将这些因素组合成一个命令,但是出于安全原因不建议这样操作。
有关两步登录的 <method>
值,请参阅附录 → 枚举。
提示进行额外的身份验证或收到 Your authentication request appears to be coming from a bot.
的错误提示?请使用您的 API 密钥 client_secret
回答身份验证挑战。了解更多。
使用 API 密钥
个人 API 密钥方式的登录建议用于自动化工作流程或对外部应用程序提供访问的场景。要使用 API 密钥方式登录:
此命令将提示您输入个人 client_id
和 client_secret
。使用这些值对您的会话进行身份验证后,您就可以使用 unlock
命令了(了解更多)。
如果您的组织要求 SSO,您仍然可以使用 --apikey
登录 CLI。
使用 API 密钥环境变量
在使用 Bitwarden CLI 完成自动化工作的场景中,您可以保存环境变量以避免在身份验证时需要手动介入。
环境变量名称 | 要求的值 |
---|---|
BW_CLIENTID |
|
BW_CLIENTSECRET |
|
使用 SSO
SSO 方式的登录建议用于组织要求 SSO 身份验证的场景。要使用 SSO 方式登录:
此命令将在您的 Web 浏览器中启动 SSO 身份验证流程。您的会话通过身份验证后,您就可以使用 unlock
命令了(了解更多)。
如果您的组织要求 SSO,您仍然可以使用 --apikey
登录 CLI。
解锁
如果您直接使用密码库数据,则使用 API 密钥或 SSO 方式将要求您在 login
命令后紧接着使用显式 bw unlock
命令。
解锁密码库会生成一个会话密钥,此会话密钥作为解密密钥用于与密码库中的数据进行交互。会话密钥必须用于执行任何涉及密码库数据的命令(例如:list
、get
、edit
)。您可以在任何时候使用以下方法生成一个新的会话密钥:
解锁选项
您可以像如下的示例那样为 bw unlock
添加 --passwordenv <passwordenv>
选项或 --passwordfile <passwordfiles>
选项来使用您的主密码,而不需要手动输入:
将查找环境变量 BW_PASSWORD
。如果 BW_PASSWORD
为非空且具有正确的值,则 CLI 将成功解锁并返回一个会话密钥。
将查找文件 ~Users/Me/Documents/mp.txt
(必须将您的主密码作为第一行)。如果文件非空且具有正确的值,CLI 将成功解锁并返回一个会话密钥。
如果您使用 --passwordfile
选项,请通过将访问权限锁定到仅需要运行 bw unlock
的用户并仅向该用户提供读取访问权限来保护您的密码文件。
使用会话密钥
当您使用电子邮件和密码方式的 bw login
或 bw unlock
解锁您的密码库时,CLI 将同时返回 export BW_SESSION
(Bash)和 env:BW_SESSION
(PowerShell)命令,其中包含了您的会话密钥。复制并粘贴相关条目以保存所需的环境变量。
如果设置了 BW_SESSION
环境变量,bw
命令将引用该变量,以干净清爽地运行,例如:
另外,如果您未设置环境变量,则可以在每个 bw
命令中将会话密钥作为选项传递:
BW_SESSION
环境变量仅绑定到活动的终端会话,因此关闭终端窗口等同于锁定密码库。您也可以通过运行以下命令来销毁一个活动会话密钥以锁定您的密码库:
核心命令
create
create
命令用于在您的密码库中创建一个新的对象( item
,attachment
等):
create
命令使用已编码的 JSON。创建一个对象的典型工作流程大致为:
使用
get template
命令(请参阅详细信息)为对象类型输出适当的 JSON 模板。使用 jq 之类的命令行 JSON 处理器根据需要操作已输出的模板。
使用
encode
命令(请参阅详细信息)对已操作的 JSON 进行编码。使用
create
命令从已编码的 JSON 创建一个对象。
示例:
或:
创建成功后,新创建的对象将作为 JSON 返回。
create 其他项目类型
create
命令默认创建登录项目,但您可以使用 jq 之类的命令行 JSON 处理器更改 .type=
属性以创建其他项目类型:
名称 | 值 |
---|---|
登录 |
|
安全笔记 |
|
支付卡 |
|
身份 |
|
例如,以下命令将创建一个安全笔记:
请注意,在上面的示例中,安全笔记需要一个子模板(.secureNote.type
)。您可以使用 bw get template
查看项目类型的子模板(详细见此处)。
create attachment
create attachment
命令用于将一个文件附加到一个现有的项目上。
与其他 create
操作不同,您无需使用 JSON 处理器或 encode
即可创建附件。相反,它使用 --file
选项指定要附加的文件,使用 --itemid
选项指定要附加到的项目。例如:
如果您不知道您要使用的确切的 itemid
,请使用 bw get item <search-term>
以返回该项目(请参阅详细信息),包括它的 id
。
get
get
命令用于从您的密码库中检索单个对象( item
、username
、password
等):
get
命令使用项目 id
或字符串作为它的参数。如果你使用一个字符串(即除确切的 id
以外的任何东西),get
将检索您的密码库以寻找一个具有匹配值的对象。例如,下面的命令将返回一个 Github 密码:
get
命令只能返回一个结果,因此您应该使用明确的搜索词。如果找到多个结果,CLI 将返回错误。
get attachment
get attachment
命令用于下载文件附件:
get attachment
命令使用一个 filename
和确切的 id
。默认情况下,get attachment
将附件下载到当前工作目录。你可以使用 --output
选项来指定一个不同的输出目录,例如:
使用 --output
时,路径必须以正斜杠(/
)结尾,以指定一个目录或者一个文件名(/Users/myaccount/Pictures/photo.png
)。
get template
get template
命令用于返回对象预期的 JSON 格式(item
、item.field
、item.login
等):
虽然你可以使用 get template
将格式输出到你的屏幕上,但最常见的用法是将输出的数据输送到 bw create
操作中,使用 jq 之类的命令行 JSON 处理器和 bw encode
来处理从模板获取的值,例如:
任何 item.xxx
模板都应作为 item
模板的子对象使用,例如:
edit
edit
用于编辑密码库中的对象( item
、item-collections
等):
edit
命令使用一个确切的 id
(要编辑的对象)和编码的 JSON(要进行的编辑)。典型的工作流程大致为:
使用
get
命令(请参阅详细信息)输出对象用于编辑。使用 jq 之类的命令行 JSON 处理器根据需要操作已输出的模板。
使用
encode
命令(请参阅详细信息)对已操作的 JSON 进行编码。使用
edit
命令(包括对象id
)编辑对象。
示例:
或者,编辑一个集合:
edit
命令将对对象执行替换操作。成功后,更新后的对象将作为 JSON 返回。
list
list
命令用于从您的密码库中检索一组对象( items
、folders
、collections
等):
list
命令的选项是筛选器,其决定了返回的内容,其包括 --url <url>
、--folderid <folderid>
、--collectionid <collectionid>
、--organizationid <organizationid>
以及 --trash
。任何筛选器都接受 null
或 notnull
。在一个命令中组合多个筛选器将执行逻辑 OR 运算,例如:
此命令将返回不属于任何文件夹或集合的项目。
另外,您可以使用 --search <search-term>
来搜索明确的对象。将筛选器和搜索结合在一个命令中将执行逻辑 AND 运算,例如:
此命令将在指定的文件夹中搜索具有字符串为 github
的项目。
delete
delete
命令用于从您的密码库中删除一个对象。delete
仅使用确切的 id
作为其参数。
默认情况下,delete 将「软删除」一个项目(即将其发送到回收站)。您可以使用 -p
,--permanent
选项永久删除项目。
要删除 org-collection
,您还需要指定 --organizationid <organizationid>
。请参阅组织 ID。
使用 delete
「软删除」的项目可以使用 restore
命令恢复(请参阅详细信息),但是使用 delete --permanent
删除的项目将被完全删除并且无法恢复。
restore
restore
命令用于从回收站中恢复已删除的对象。restore
仅使用确切的 id
作为其参数。
例如:
send
send
命令用于创建一个 Bitwarden Send 对象进行短暂的共享。本节将详细介绍简单的 send
操作,然而 Send 是一个高度灵活的工具,我们建议参阅 CLI 上的 Send 这篇专门的文章。
要创建一个简单的文本 Send:
要创建一个简单的文件 Send:
receive
receive
命令用于访问 Bitwarden Send 对象。要接收 Send 对象:
组织命令
组织 ID
从 CLI 访问组织经常需要知道组织的 ID 以及单个成员的 ID 和集合的 ID。
使用 bw list
命令从 CLI 直接检索这些信息,例如:
您可以同时 bw list
collections
和 org-collections
。bw list collections
将列出所有集合,而与它们所属的组织无关。bw list org-collections
将仅列出属于使用 --organizationid
指定的组织的集合。
move
2021 年 8 月:share
命令已被更改为 move
。了解更多。
move
命令用于将密码库项目转移到组织:
move
命令要求您 encode
集合 ID,并使用一个确切的 id
(要共享的对象)和一个确切的 organizationid
(要与之共享对象的组织)。例如:
成功后,将返回更新后的项目。
confirm
confirm
命令用于确认已接受邀请的受邀成员加入您的组织:
confirm
命令使用确切的成员 id
和确切的组织 id
,例如:
设备批准
允许管理员和所有者在用户已请求管理员批准时管理设备批准请求。
目前,批量设备批准仅适用于从 Bitwarden.com 下载的 Bitwarden CLI 客户端。
在大多数情况下,用户可以批准自己的登录请求,不需要管理员设备批准。请参阅添加受信任设备。自动或批量批准管理员设备批准请求会忽略管理员为确保请求合法而执行的验证步骤,例如检查用户报告的指纹短语。
Bitwarden 建议在启用和使用批量设备批准之前,先审查重要的安全控制措施,例如 IdP 凭证标准、IdP MFA 以及 IdP 设备注册和信任。
list
命令用于显示组织内所有待处理的设备批准请求:
approve
命令用于批准组织内待处理的设备授权请求:
同理, approve-all
命令用于批准所有当前待处理的请求:
deny
用于拒绝待处理的授权请求:
deny-all
用于拒绝所有待处理的授权请求:
其他命令
config
config
命令用于指定 Bitwarden CLI 说使用的设置:
bw config
的主要用途是将 CLI 连接到自托管 Bitwarden 服务器:
您可以通过传递不带值的 bw config server
来读取当前已连接的服务器。
具有唯一设置的用户可以选择使用以下方法单独指定每一个服务的 URL:
如果您的组织使用 Key Connector 并且您在移除您的主密码后使用 --apikey
选项登录,则需要运行 bw config server --key-connector
命令。
联系组织所有者以获取所需的 URL。
sync
sync
命令用于从 Bitwarden 服务器下载加密的密码库。登录 CLI 后,您又在其他客户端应用程序(例如网页密码库、浏览器扩展、移动应用程序)上对 Bitwarden 密码库进行了某些更改时,此命令很有用。
您可以传递 --last
选项,以仅返回上次执行同步的时间戳(ISO 8601)。
重要的是要知道 sync
仅从服务器执行拉取操作。任何时候您更改密码库时(例如 create
、edit
、delete
),数据都会自动推送到服务器。
encode
encode
命令用于对 stdin(标准输入) 进行 Base 64 编码。在执行 create
和 edit
操作时,此命令通常与 json 这样的命令行 JSON 处理器结合使用,例如:
import
import
命令用于从之前的 Bitwarden 导出或其他受支持的密码管理应用程序中导入数据。该命令必须指向一个文件并包含如下参数:
例如:
Bitwarden 支持多种导入格式,太多了而无法在这里一一列出!使用 bw import --formats
在 CLI 中返回列表,或参阅这里。
export
export
命令用于将密码库数据导出为 .json
或 .csv
或加密的 .json 文件:
默认情况下,export
命令将在当前工作目录下生成一个 .csv
(相当于指定 --format csv
)文件,但您也可以指定:
--format json
:导出为.json
文件--output <path>
:指定导出位置--raw
:将导出返回到 stdout(标准输出)而不是文件
导出组织密码库
使用带有 --organizationid
选项的 export
命令,可以导出组织密码库:
generate
generate
命令用于生成一个强密码或密码短语:
默认情况下,generate
命令将生成一个包含 14 个字符的密码,其中包含大写字符、小写字符和数字。其等效于:
您可以使用该命令可用的选项来生成更复杂的密码,选项包括:
--uppercase
或-u
(包含大写字符)--lowercase
或-l
(包含小写字符)--number
或-n
(包含数字)--special
或-s
(包含特殊字符)--length <length>
(密码长度,最小值为 5)
生成密码短语
使用带有 --passphrase
选项的 generate
命令,可以生成一个密码短语而不是密码:
默认情况下,bw generate --passphrase
命令将生成一个 3 个单词的密码短语,并用破折号(-)分隔。这等效于:
您可以使用该命令可用的选项来生成更复杂的密码短语,选项包括:
--words <words>
(单词数量)--separator <separator>
(分隔符)--capitalize, -c
(密码短语中首字母大写)--includeNumber
(密码短语中包含数字)
update
update
命令用于检查您的 Bitwarden CLI 是否正在运行最新版本。update
不会为您自动更新 CLI。
如果检测到新的版本,则需要使用打印的可执行文件 URL 来下载新版本的 CLI,或使用用于下载 CLI 的程序包管理器工具(例如 npm install -g @bitwarden/cli
)来下载新版本的 CLI。
status
status
命令用于返回 Bitwarden CLI 的状态信息,包括已配置的服务器 URL、最后一次同步的时间戳(ISO 8601)、用户电子邮件和 ID,以及密码库状态。
状态将以 JSON 对象的形式返回信息,例如:
status
的值可能是以下之一:
"unlocked"
:表示您已登录并且您的密码库已解锁(即保存了含活动会话密钥的BW_SESSION
密钥环境变量)。"locked"
:表示您已登录但是您的密码库已锁定(即没有保存含活动会话密钥的BW_SESSION
密钥环境变量)。"unauthenticated"
:表示您尚未登录。
当使用 "status": "unauthenticated"
时,lastSync
、userEmail
和 userID
将始终返回 null
。
serve
serve
命令用于启动一个本地紧急 Web 服务器,该服务器用于执行所有可从 CLI 访问的操作,这些操作以来自 HTTP 接口的 RESTful API 调用的形式。
默认情况下,serve
将在 8087 端口启动 Web 服务器,但您可以使用 --port
选项指定备用端口。
默认情况下,serve
会将您的 API Web 服务器绑定到 localhost
,但您可以使用 --hostname
选项指定备用主机名。API 请求只能从绑定的主机名发出。
默认情况下,serve
将阻止任何带有 Origin 标头的请求。您可以使用 --disable-origin-protection
选项绕过此保护,但不建议这样做。
您可以指定 --hostname all
以不绑定主机名,但这将允许网络上的任何机器发出 API 请求。
查看 API 规范以获取使用 serve
进行调用的帮助。
附录
全局选项
以下选项全局可用:
选项 | 描述 |
---|---|
| 格式化输出。JSON 使用两个空格的制表符。 |
| 返回原始输出,而不是描述性消息。 |
| 返回响应输出的 JSON 格式版本。 |
| 不要将任何东西返回 stdout(标准输出)。 |
| 对于输入交互式用户,不做提示。 |
| 传递会话密钥,而不是从环境变量中读取会话密钥。 |
| 输出 Bitwarden CLI 的版本号。 |
| 显示命令的帮助文本。 |
ZSH Shell 补全
Bitwarden CLI 支持 ZSH Shell 补全。要设置 Shell 补全,请使用下面的方法之一:
1、Vanilla ZSH:将下面行添加到您的 .zshrc
文件中:
2、Vanilla (vendor-completions):运行如下命令:
3、zinit:运行如下命令:
使用自签名证书
如果您的自托管 Bitwarden 服务器公开为自签名 TLS 证书,请指定 Node.js 环境变量 NODE_EXTRA_CA_CERTS
:
枚举
下面的表格列举了在自文档情景下所需要的值:
两步登录方式
名称 | 值 |
---|---|
验证器 | 0 |
电子邮件 | 1 |
Yubikey | 3 |
CLI 不支持 FIDO2 和 Duo。
项目类型
与 create
命令一起使用以指定项目的类型:
名称 | 值 |
---|---|
登录 | 1 |
安全笔记 | 2 |
支付卡 | 3 |
身份 | 4 |
登录 URI 匹配类型
与 create
和 edit
命令一起使用以指定 URI 匹配检测行为:
名称 | 值 |
---|---|
基础域 | 0 |
主机 | 1 |
开始于 | 2 |
精确 | 3 |
正则表达式 | 4 |
从不 | 5 |
字段类型
与 create
和 edit
命令一起使用以配置自定义字段:
名称 | 值 |
---|---|
文本 | 0 |
隐藏 | 1 |
布尔型 | 2 |
组织用户类型
指示用户的类型:
名称 | 值 |
---|---|
所有者 | 0 |
管理员 | 1 |
用户 | 2 |
经理 | 3 |
组织用户状态类型
指示用户在组织内的状态:
名称 | 值 |
---|---|
受邀 | 0 |
已接受 | 1 |
已确认 | 2 |
最后更新于