介绍
# Proton Pass CLI
通过 Proton Pass CLI 全面管理密码和密钥。管理保险库、项目、SSH 密钥、共享凭据、注入密钥以及集成 SSH 工作流。
## 安装
### 快速安装
macOS/Linux: ```bash curl -fsSL https://proton.me/download/pass-cli/install.sh | bash ```
Windows: ```powershell Invoke-WebRequest -Uri https://proton.me/download/pass-cli/install.ps1 -OutFile install.ps1; .\install.ps1 ```
### Homebrew (macOS)
```bash brew install protonpass/tap/pass-cli ```
**注意：** 通过包管理器（如 Homebrew 等）安装不支持 `pass-cli update` 命令或切换版本通道。
### 验证安装
```bash pass-cli --version ```
## 身份验证
### Web 登录（推荐）
支持所有登录流程（SSO、U2F）的默认身份验证方法：
```bash pass-cli login # Open the URL displayed in your browser and complete authentication ```
### 交互式登录
基于终端的身份验证（支持密码 + TOTP，但不支持 SSO 或 U2F）：
```bash pass-cli login --interactive [email protected] ```
#### 用于自动化的环境变量
```bash # Credentials as plain text (less secure) export PROTON_PASS_PASSWORD='your-password' export PROTON_PASS_TOTP='123456' export PROTON_PASS_EXTRA_PASSWORD='your-extra-password'
# Or from files (more secure) export PROTON_PASS_PASSWORD_FILE='/secure/password.txt' export PROTON_PASS_TOTP_FILE='/secure/totp.txt' export PROTON_PASS_EXTRA_PASSWORD_FILE='/secure/extra-password.txt'
pass-cli login --interactive [email protected] ```
### 验证会话
```bash pass-cli info # Show session info pass-cli test # Test connection ```
### 登出
```bash pass-cli logout # Normal logout pass-cli logout --force # Force local cleanup if remote fails ```
## 保险库管理
### 列出保险库
```bash pass-cli vault list pass-cli vault list --output json ```
### 创建保险库
```bash pass-cli vault create --name "Vault Name" ```
### 更新保险库
```bash # By share ID pass-cli vault update --share-id "abc123def" --name "New Name"
# By name pass-cli vault update --vault-name "Old Name" --name "New Name" ```
### 删除保险库
⚠️ **警告：** 永久删除保险库及其所有项目。
```bash # By share ID pass-cli vault delete --share-id "abc123def"
# By name pass-cli vault delete --vault-name "Old Vault" ```
### 共享保险库
```bash # Share with viewer access (default) pass-cli vault share --share-id "abc123def" [email protected]
# Share with specific role pass-cli vault share --vault-name "Team Vault" [email protected] --role editor
# Roles: viewer, editor, manager ```
### 管理保险库成员
```bash # List members pass-cli vault member list --share-id "abc123def" pass-cli vault member list --vault-name "Team Vault" --output json
# Update member role pass-cli vault member update --share-id "abc123def" --member-share-id "member123" --role editor
# Remove member pass-cli vault member remove --share-id "abc123def" --member-share-id "member123" ```
### 转移保险库所有权
```bash pass-cli vault transfer --share-id "abc123def" "member_share_id_xyz" pass-cli vault transfer --vault-name "My Vault" "member_share_id_xyz" ```
## 项目管理
### 列出项目
```bash # List from specific vault pass-cli item list "Vault Name" pass-cli item list --share-id "abc123def"
# List with default vault (if configured) pass-cli item list ```
### 查看项目
```bash # By IDs pass-cli item view --share-id "abc123def" --item-id "item456"
# By names pass-cli item view --vault-name "MyVault" --item-title "MyItem"
# Using Pass URI pass-cli item view "pass://abc123def/item456" pass-cli item view "pass://MyVault/MyItem"
# View specific field pass-cli item view "pass://abc123def/item456/password" pass-cli item view --share-id "abc123def" --item-id "item456" --field "username"
# Output format pass-cli item view --share-id "abc123def" --item-id "item456" --output json ```
### 创建登录项目
```bash # Basic login pass-cli item create login \ --share-id "abc123def" \ --title "GitHub Account" \ --username "myuser" \ --password "mypassword" \ --url "https://github.com"
# With vault name pass-cli item create login \ --vault-name "Personal" \ --title "Account" \ --username "user" \ --email "[email protected]" \ --url "https://example.com"
# With generated password pass-cli item create login \ --share-id "abc123def" \ --title "New Account" \ --username "myuser" \ --generate-password \ --url "https://example.com"
# Custom password generation: "length,uppercase,symbols" pass-cli item create login \ --vault-name "Work" \ --title "Secure Account" \ --username "myuser" \ --generate-password="20,true,true" \ --url "https://example.com"
# Generate passphrase pass-cli item create login \ --share-id "abc123def" \ --title "Account" \ --username "user" \ --generate-passphrase="5" \ --url "https://example.com" ```
#### 登录模板
```bash # Get template structure pass-cli item create login --get-template > template.json
# Create from template pass-cli item create login --from-template template.json --share-id "abc123def"
# Create from stdin echo '{"title":"Test","username":"user","password":"pass","urls":["https://test.com"]}' | \ pass-cli item create login --share-id "abc123def" --from-template - ```
模板格式： ```json { "title": "Item Title", "username": "optional_username", "email": "[email protected]", "password": "optional_password", "urls": ["https://example.com", "https://app.example.com"] } ```
### 创建 SSH 密钥项目
#### 生成新的 SSH 密钥
```bash # Generate Ed25519 key (recommended) pass-cli item create ssh-key generate \ --share-id "abc123def" \ --title "GitHub Deploy Key"
# Using vault name pass-cli item create ssh-key generate \ --vault-name "Development Keys" \ --title "GitHub Deploy Key"
# Generate RSA 4096 key with comment pass-cli item create ssh-key generate \ --share-id "abc123def" \ --title "Production Server" \ --key-type rsa4096 \ --comment "prod-server-deploy"
# Key types: ed25519 (default), rsa2048, rsa4096
# With passphrase protection pass-cli item create ssh-key generate \ --share-id "abc123def" \ --title "Secure Key" \ --password
# Passphrase from environment PROTON_PASS_SSH_KEY_PASSWORD="my-passphrase" \ pass-cli item create ssh-key generate \ --share-id "abc123def" \ --title "Automated Key" \ --password ```
#### 导入现有的 SSH 密钥
```bash # Import unencrypted key pass-cli item create ssh-key import \ --from-private-key ~/.ssh/id_ed25519 \ --share-id "abc123def" \ --title "My SSH Key"
# Import with vault name pass-cli item create ssh-key import \ --from-private-key ~/.ssh/id_rsa \ --vault-name "Personal Keys" \ --title "Old RSA Key"
# Import passphrase-protected key (will prompt) pass-cli item create ssh-key import \ --from-private-key ~/.ssh/id_ed25519 \ --share-id "abc123def" \ --title "Protected Key" \ --password
# Passphrase from environment PROTON_PASS_SSH_KEY_PASSWORD="my-key-passphrase" \ pass-cli item create ssh-key import \ --from-private-key ~/.ssh/id_ed25519 \ --share-id "abc123def" \ --title "Automated Import" \ --password ```
**建议：** 对于导入受密码短语保护的密钥，建议先移除密码短语，因为密钥将在您的保险库中被加密：
```bash # Create unencrypted copy cp ~/.ssh/id_ed25519 /tmp/id_ed25519_temp ssh-keygen -p -f /tmp/id_ed25519_temp -N ""
# Import pass-cli item create ssh-key import \ --from-private-key /tmp/id_ed25519_temp \ --share-id "abc123def" \ --title "My SSH Key"
# Securely delete temp copy shred -u /tmp/id_ed25519_temp # Linux rm -P /tmp/id_ed25519_temp # macOS ```
### 创建邮箱别名
```bash # Create alias pass-cli item alias create --share-id "abc123def" --prefix "newsletter" pass-cli item alias create --vault-name "Personal" --prefix "shopping"
# With JSON output pass-cli item alias create --vault-name "Personal" --prefix "temp" --output json ```
### 更新项目
```bash # Update single field pass-cli item update \ --share-id "abc123def" \ --item-id "item456" \ --field "password=newpassword123"
# By vault name and item title pass-cli item update \ --vault-name "Personal" \ --item-title "GitHub Account" \ --field "password=newpassword123"
# Update multiple fields pass-cli item update \ --share-id "abc123def" \ --item-id "item456" \ --field "username=newusername" \ --field "password=newpassword" \ --field "[email protected]"
# Rename item pass-cli item update \ --vault-name "Work" \ --item-title "Old Title" \ --field "title=New Title"
# Create/update custom fields pass-cli item update \ --share-id "abc123def" \ --item-id "item456" \ --field "api_key=sk_live_abc123" \ --field "environment=production" ```
**注意：** 项目更新不支持 TOTP 或时间字段。请使用其他 Proton Pass 客户端进行这些操作。
### 删除项目
⚠️ **警告：** 永久删除。
```bash pass-cli item delete --share-id "abc123def" --item-id "item456" ```
### 共享项目
```bash # Share with viewer access (default) pass-cli item share --share-id "abc123def" --item-id "item456" [email protected]
# Share with editor access pass-cli item share --share-id "abc123def" --item-id "item456" [email protected] --role editor ```
### 生成 TOTP 代码
```bash # Generate all TOTPs for an item pass-cli item totp "pass://TOTP vault/WithTOTPs"
# Specific TOTP field pass-cli item totp "pass://TOTP vault/WithTOTPs/TOTP 1"
# JSON output pass-cli item totp "pass://TOTP vault/WithTOTPs" --output json
# Extract specific value pass-cli item totp "pass://TOTP vault/WithTOTPs/TOTP 1" --output json | jq -r '.["TOTP 1"]' ```
## 密码生成与分析
### 生成密码
```bash # Random password (default settings) pass-cli password generate random
# Custom random password pass-cli password generate random --length 20 --numbers true --uppercase true --symbols true
# Simple password without symbols pass-cli password generate random --length 16 --symbols false
# Generate passphrase pass-cli password generate passphrase
# Custom passphrase pass-cli password generate passphrase --count 5 pass-cli password generate passphrase --count 4 --separator hyphens pass-cli password generate passphrase --count 4 --capitalize true --numbers true ```
### 分析密码强度
```bash # Score a password pass-cli password score "mypassword123"
# JSON output pass-cli password score "MySecureP@ssw0rd*" --output json ```
示例 JSON 输出： ```json { "numeric_score": 51.666666666666664, "password_score": "Vulnerable", "penalties": [ "ContainsCommonPassword", "Consecutive" ] } ```
## SSH 代理集成
### 将 SSH 密钥加载到现有代理中
将 Proton Pass SSH 密钥加载到您现有的 SSH 代理中：
```bash # Load all SSH keys pass-cli ssh-agent load
# Load from specific vault pass-cli ssh-agent load --share-id MY_SHARE_ID pass-cli ssh-agent load --vault-name MySshKeysVault ```
**前提条件：** 确保已定义 `SSH_AUTH_SOCK` 环境变量。
### 将 Proton Pass CLI 作为 SSH 代理运行
将 Proton Pass CLI 作为独立的 SSH 代理启动：
```bash # Start agent pass-cli ssh-agent start
# From specific vault pass-cli ssh-agent start --share-id MY_SHARE_ID pass-cli ssh-agent start --vault-name MySshKeysVault
# Custom socket path pass-cli ssh-agent start --socket-path /custom/path/agent.sock
# Custom refresh interval (default 3600 seconds) pass-cli ssh-agent start --refresh-interval 7200 # 2 hours ```
启动后，导出 socket： ```bash export SSH_AUTH_SOCK=/Users/youruser/.ssh/proton-pass-agent.sock ```
#### 自动创建 SSH 密钥项目 (v1.3.0+)
自动保存通过 `ssh-add` 添加的 SSH 密钥：
```bash # Enable auto-creation pass-cli ssh-agent start --create-new-identities MySshKeysVault
# In another terminal export SSH_AUTH_SOCK=$HOME/.ssh/proton-pass-agent.sock ssh-add ~/.ssh/my_new_key # Key is now automatically saved to Proton Pass! ```
### SSH 故障排除
#### ssh-copy-id 因密钥过多而失败
强制使用密码身份验证： ```bash ssh-copy-id -o PreferredAuthentications=password -o PubkeyAuthentication=no user@server ```
## Pass URI 语法（密钥引用）
使用格式引用密钥：`pass://vault/item/field`
### 语法
``` pass://<vault-identifier>/<item-identifier>/<field-name> ```
- **vault-identifier：** 保险库的共享 ID 或名称 - **item-identifier：** 项目的 ID 或标题 - **field-name：** 要检索的特定字段（必需）
### 示例
```bash # By names pass://Work/GitHub Account/password pass://Personal/Email Login/username
# By IDs pass://AbCdEf123456/XyZ789/password pass://ShareId123/ItemId456/api_key
# Mixed (vault by name, item by ID) pass://Work/XyZ789/password
# Custom fields (case-sensitive) pass://Work/API Keys/api_key pass://Production/Database/connection_string ```
### 常用字段
- `username` - 用户名/登录名 - `password` - 密码 - `email` - 电子邮件地址 - `url` - 网站 URL - `note` - 附加备注 - `totp` - TOTP 密钥（用于 2FA） - 任何名称的自定义字段（区分大小写）
### 规则
- 所有三个组件（vault/item/field）都是必需的 - 支持带空格的名称 - 解析区分大小写 - 如果存在重复项，则使用第一个匹配项（为精确起见，建议使用 ID）
**无效格式：** ```bash pass://vault/item # Missing field name pass://vault/item/ # Trailing slash pass://vault/ # Missing item and field ```
## 密钥注入
### 使用密钥运行命令 (`run`)
执行命令时，将 Proton Pass 中的密钥作为环境变量注入。
**概要：** ```bash pass-cli run [--env-file FILE]... [--no-masking] -- COMMAND [ARGS...] ```
**工作原理：** 1. 从当前进程和 `.env` 文件中收集环境变量 2. 扫描变量值中的 `pass://` URI 3. 从 Proton Pass 解析密钥 4. 将 URI 替换为实际密钥值 5. 在输出中屏蔽密钥（除非使用 `--no-masking`） 6. 使用解析后的环境执行命令 7. 转发 stdin/stdout/stderr 和信号 (SIGTERM/SIGINT)
**参数：** - `--env-file FILE` - 从 dotenv 文件加载环境变量（可指定多个，按顺序处理） - `--no-masking` - 禁用输出中的自动密钥屏蔽 - `COMMAND [ARGS...]` - 要执行的命令（必须位于 `--` 之后）
#### 基本用法
```bash # Set secret reference in environment export DB_PASSWORD='pass://Production/Database/password'
# Run application with injected secret pass-cli run -- ./my-app ```
#### 使用 .env 文件
创建 `.env`： ```bash DB_HOST=localhost DB_PORT=5432 DB_USERNAME=admin DB_PASSWORD=pass://Production/Database/password API_KEY=pass://Work/External API/api_key ```
运行： ```bash pass-cli run --env-file .env -- ./my-app
# Multiple env files (later override earlier) pass-cli run \ --env-file base.env \ --env-file secrets.env \ --env-file local.env \ -- ./my-app ```
#### 单个值中的多个密钥
```bash # Mix secrets with plain text DATABASE_URL="postgresql://user:pass://vault/db/password@localhost/db" API_ENDPOINT="https://api.example.com?key=pass://vault/api/key" ```
#### 密钥屏蔽
**默认（已屏蔽）：** ```bash pass-cli run -- ./my-app # If app logs: API_KEY: sk_live_abc123 # Output shows: API_KEY: <concealed by Proton Pass> ```
**未屏蔽：** ```bash pass-cli run --no-masking -- ./my-app ```
#### 带参数运行
```bash pass-cli run -- ./my-app --config production --verbose ```
#### CI/CD 集成
```bash #!/bin/bash # Load production secrets pass-cli run --env-file .env.production -- ./deploy.sh ```
### 将密钥注入到模板 (`inject`)
处理模板文件，并使用 handlebars 风格的语法将密钥引用替换为实际值。
**概要：** ```bash pass-cli inject [--in-file FILE] [--out-file FILE] [--force] [--file-mode MODE] ```
**工作原理：** 1. 从 `--in-file` 或 stdin 读取模板 2. 查找 `{{ pass://vault/item/field }}` 模式 3. 从 Proton Pass 解析密钥 4. 将引用替换为实际值 5. 输出到 `--out-file` 或 stdout 6. 设置文件权限
**参数：** - `--in-file`, `-i` - 模板文件路径（或 stdin） - `--out-file`, `-o` - 写入输出的路径（或 stdout） - `--force`, `-f` - 覆盖输出文件而不提示 - `--file-mode` - 设置文件权限（Unix，默认：`0600`）
#### 模板语法
**重要：** 使用双大括号 `{{ }}`（与使用裸露的 `pass://` 的 `run` 不同）
```yaml # config.yaml.template database: host: localhost username: {{ pass://Production/Database/username }} password: {{ pass://Production/Database/password }}
api: key: {{ pass://Work/API Keys/api_key }} secret: {{ pass://Work/API Keys/secret }}
# This comment with pass://fake/uri is ignored # Only {{ }} wrapped references are processed ```
#### 注入到 stdout
```bash pass-cli inject --in-file config.yaml.template ```
#### 注入到文件
```bash pass-cli inject \ --in-file config.yaml.template \ --out-file config.yaml
# Overwrite existing pass-cli inject \ --in-file config.yaml.template \ --out-file config.yaml \ --force ```
#### 从 stdin 读取
```bash cat template.txt | pass-cli inject
# Or with heredoc pass-cli inject << EOF { "database": { "password": "{{ pass://Production/Database/password }}" } } EOF ```
#### 自定义文件权限
```bash pass-cli inject \ --in-file template.txt \ --out-file config.txt \ --file-mode 0644 ```
#### JSON 模板示例
```json { "database": { "host": "localhost", "password": "{{ pass://Production/Database/password }}" }, "api": { "key": "{{ pass://Work/API/key }}" } } ```
## 设置管理
配置持久性首选项：
### 查看设置
```bash pass-cli settings view ```
### 设置默认保险库
```bash # By name pass-cli settings set default-vault --vault-name "Personal Vault"
# By share ID pass-cli settings set default-vault --share-id "3GqM1RhVZL8uXR_abc123" ```
**受影响的命令：** `item list`、`item view`、`item totp`、`item create`、`item update` 等。
### 设置默认输出格式
```bash pass-cli settings set default-format human pass-cli settings set default-format json ```
**受影响的命令：** `item list`、`item view`、`item totp`、`vault list` 等。
### 取消设置默认值
```bash pass-cli settings unset default-vault pass-cli settings unset default-format ```
## 共享管理
### 列出所有共享
```bash pass-cli share list pass-cli share list --output json ```
显示与您共享的所有资源（保险库和项目）以及您的角色。
## 邀请管理
### 列出待处理的邀请
```bash pass-cli invite list pass-cli invite list --output json ```
### 接受邀请
```bash pass-cli invite accept --invite-token "abc123def456" ```
### 拒绝邀请
```bash pass-cli invite reject --invite-token "abc123def456" ```
## 用户与会话信息
### 查看会话信息
```bash pass-cli info ```
显示：版本通道、用户 ID、用户名、电子邮件。
### 查看详细用户信息
```bash pass-cli user info pass-cli user info --output json ```
显示：帐户详细信息、订阅、存储使用情况。
### 测试连接
```bash pass-cli test ```
验证会话有效性和 API 连接。
## 更新
**注意：** 仅适用于手动安装（不适用于包管理器）。
### 更新到最新版本
```bash pass-cli update pass-cli update --yes # Skip confirmation ```
### 更改版本通道
```bash # Switch to beta pass-cli update --set-track beta pass-cli update
# Switch back to stable pass-cli update --set-track stable pass-cli update ```
### 禁用自动更新检查
```bash export PROTON_PASS_NO_UPDATE_CHECK=1 ```
## 对象类型
### 共享 (Share)
共享代表用户与资源（保险库或项目）之间的关系。定义访问权限。
- **保险库共享：** 访问整个保险库及其中的所有项目 - **项目共享：** 仅访问单个特定项目 - **角色：** - **查看者：** 只读访问 - **编辑者：** 读写访问，可以管理项目（但不能共享或管理成员） - **管理者：** 完全控制，包括共享和成员管理 - **所有者：** 创建了保险库，唯一可以删除保险库的人
### 保险库 (Vault)
组织项目的容器。项目仅存在于一个保险库中。
### 项目类型
- **登录：** 带有 URL 和 TOTP 支持的用户名/密码凭据 - **备注：** 安全文本备注 - **信用卡：** 付款卡信息（已加密） - **身份：** 关于个人的个人信息 - **别名：** 用于隐私保护的邮箱别名 - **SSH 密钥：** 用于身份验证的 SSH 私钥 - **WiFi：** 访问 WiFi 网络的凭据
**注意：** 项目由项目 ID 标识，但此 ID 只有在与共享 ID 结合时才是唯一的（ShareID + ItemID = 全局唯一）。
## 最佳实践
### 安全性
- 使用 Web 登录以获得最大的兼容性 (SSO, U2F) - 为每个帐户生成唯一的密码 - 使用存储在 Pass 中的 SSH 密钥，而不是本地文件系统 - 在共享系统上登出 - 定期审查共享权限
### 组织结构
- 为不同的上下文（工作、个人）创建单独的保险库 - 为项目和保险库使用描述性标题 - 为常用保险库设置默认保险库 - 配置默认输出格式（脚本使用 JSON，交互使用人性化格式）
### 自动化
- 将凭据存储在文件中（而不是环境变量）以提高安全性 - 使用 Pass URI 进行程序化密钥访问 - 利用 JSON 输出进行脚本编写 - 在自动化清理中包含 `pass-cli logout`
### 共享
- 使用最小权限原则（从查看者开始） - 对于持续协作，首选保险库共享 - 对于特定的、有限的访问，使用项目共享 - 定期审计成员和权限
## Docker 用法
在 Docker 容器中运行需要文件系统密钥存储（密钥环不可用）：
```bash # 1. Ensure logged out pass-cli logout --force
# 2. Set filesystem key provider export PROTON_PASS_KEY_PROVIDER=fs
# 3. Login as normal pass-cli login ```
**为什么使用文件系统存储？** - 容器无法访问内核密钥服务 - 无头环境中 D-Bus 不可用 - 文件系统存储是唯一的选择
⚠️ **安全提示：** 密钥与加密数据存储在一起。请确保您的容器环境安全。
## 故障排除
### 身份验证问题
```bash # Check session status pass-cli info pass-cli test
# Re-authenticate pass-cli logout pass-cli login ```
### 网络问题
- 验证互联网连接 - 检查 Proton 域的防火墙设置 - 使用 `pass-cli test` 测试
### 权限错误
- 验证您的角色：`pass-cli share list` - 确保您拥有操作所需的权限 - 联系保险库所有者调整权限
### 资源缺失
- 检查您查看的保险库是否正确 - 验证资源未被删除 - 确认访问权限未被撤销 - 检查待处理的邀请：`pass-cli invite list`
### 密钥引用解析错误
**"无效的引用格式" (Invalid reference format)：** - 确保格式为 `pass://vault/item/field` - 检查是否存在尾部斜杠 - 验证所有三个部分都存在
**"密钥引用需要字段名" (Secret reference requires a field name)：** - 添加字段名：`pass://vault/item/field`（而非 `pass://vault/item`）
**"未找到字段" (Field not found)：** - 验证字段是否存在：`pass-cli item view --share-id <id> --item-id <id>` - 检查字段名拼写（区分大小写）
**未找到引用：** 1. 检查保险库访问权限：`pass-cli vault list` 2. 验证项目是否存在：`pass-cli item list --share-id <id>` 3. 确认字段名：`pass-cli item view <uri>`
## 配置
### 日志记录
```bash # Levels: trace, debug, info, warn, error, off export PASS_LOG_LEVEL=debug ```
**注意：** 日志发送到 `stderr`（不会干扰管道/命令集成）。
### 会话存储
**默认位置：** - macOS: `~/Library/Application Support/proton-pass-cli/.session/` - Linux: `~/.local/share/proton-pass-cli/.session/`
**覆盖：** ```bash export PROTON_PASS_SESSION_DIR='/custom/path' ```
### 密钥存储提供程序
使用 `PROTON_PASS_KEY_PROVIDER` 控制加密密钥的存储方式：
#### 1. 密钥环存储（Keyring storage，默认，最安全）
```bash export PROTON_PASS_KEY_PROVIDER=keyring # or unset ```
使用操作系统安全存储： - **macOS：** macOS 钥匙串 - **Linux：** 基于内核的秘密存储（内核密钥环） - **Windows：** Windows 凭据管理器
**工作原理：** - 首次运行时生成随机的 256 位密钥 - 存储在系统密钥环中 - 后续运行时检索 - 如果密钥环不可用但会话存在，出于安全考虑强制注销
**Linux 说明：** 使用内核密钥环（不需要 D-Bus），可在无头环境中工作。**重启时清除机密。**
**Docker 限制：** 容器无法访问内核密钥服务。请改用文件系统存储。
#### 2. 文件系统存储
⚠️ **警告：** 安全性较低 - 密钥与加密数据存储在一起。
```bash export PROTON_PASS_KEY_PROVIDER=fs ```
将密钥存储在 `<session-dir>/local.key` 中，权限为 `0600`。
**优点：** - 适用于所有环境（无头、容器） - 重启后仍然存在 - 不依赖系统服务
**何时使用：** - Docker 容器 - 开发/测试 - 系统密钥环不可用时
#### 3. 环境变量存储
⚠️ **警告：** 同一会话中的其他进程可以看到密钥。
```bash export PROTON_PASS_KEY_PROVIDER=env export PROTON_PASS_ENCRYPTION_KEY=your-secret-key ```
从 `PROTON_PASS_ENCRYPTION_KEY` 派生加密密钥（必须已设置且非空）。
**生成安全密钥：** ```bash dd if=/dev/urandom bs=1 count=2048 2>/dev/null | sha256sum | awk '{print $1}' ```
**优点：** - 可跨所有环境移植 - 不依赖文件系统/密钥环 - 用户控制密钥值 - 适用于 CI/CD、容器、无头环境
**何时使用：** - CI/CD 流水线 - 不希望持久化文件系统的容器 - 自动化脚本 - 需要显式控制加密密钥
### 遥测
**禁用遥测：** ```bash export PROTON_PASS_DISABLE_TELEMETRY=1 ```
或在全局禁用：[账户安全设置](https://account.proton.me/pass/security) → 禁用“收集使用情况诊断数据”
**发送内容：** 匿名使用数据（例如，“创建了笔记类型的项目”）- **绝不**包含个人/敏感数据。
## 环境变量
### 登录凭据（交互式登录）
```bash export PROTON_PASS_PASSWORD='password' export PROTON_PASS_PASSWORD_FILE='/path/to/file' export PROTON_PASS_TOTP='123456' export PROTON_PASS_TOTP_FILE='/path/to/file' export PROTON_PASS_EXTRA_PASSWORD='extra-password' export PROTON_PASS_EXTRA_PASSWORD_FILE='/path/to/file' ```
### SSH 密钥密码
```bash export PROTON_PASS_SSH_KEY_PASSWORD='passphrase' export PROTON_PASS_SSH_KEY_PASSWORD_FILE='/path/to/file' ```
### 更新检查
```bash export PROTON_PASS_NO_UPDATE_CHECK=1 ```
### 安装
```bash export PROTON_PASS_CLI_INSTALL_DIR=/custom/path export PROTON_PASS_CLI_INSTALL_CHANNEL=beta ```
## 常见工作流
### 创建并填充新的保险库
```bash # Create vault pass-cli vault create --name "Project Alpha"
# List to get share ID pass-cli vault list
# Create login items pass-cli item create login \ --share-id "new_vault_id" \ --title "API Key" \ --username "api_user" \ --generate-password \ --url "https://api.example.com"
# Share with team pass-cli vault share --share-id "new_vault_id" [email protected] --role editor ```
### 导入和使用 SSH 密钥
```bash # Import existing key pass-cli item create ssh-key import \ --from-private-key ~/.ssh/id_ed25519 \ --vault-name "SSH Keys" \ --title "GitHub Key"
# Load into SSH agent pass-cli ssh-agent load --vault-name "SSH Keys"
# Or start Pass as SSH agent pass-cli ssh-agent start --vault-name "SSH Keys" export SSH_AUTH_SOCK=$HOME/.ssh/proton-pass-agent.sock ```
### 脚本化访问密钥
```bash #!/bin/bash # Automated login export PROTON_PASS_PASSWORD_FILE="$HOME/.secrets/pass-password" pass-cli login --interactive [email protected]
# Retrieve secret DB_PASSWORD=$(pass-cli item view "pass://Production/Database/password" --output json | jq -r '.password')
# Use secret connect-to-db --password "$DB_PASSWORD"
# Cleanup pass-cli logout ```
### 使用密钥进行应用部署
```bash #!/bin/bash # Create .env.production with secret references cat > .env.production << EOF NODE_ENV=production DATABASE_URL=pass://Production/Database/connection_string API_KEY=pass://Production/API/key STRIPE_SECRET=pass://Production/Stripe/secret_key EOF
# Deploy application with secrets injected pass-cli run --env-file .env.production -- npm start
# Or generate config file from template pass-cli inject \ --in-file config.yaml.template \ --out-file config.yaml \ --force
# Then run app with generated config ./app --config config.yaml ```
### CI/CD 流水线集成
```bash #!/bin/bash # Login with environment variable key storage export PROTON_PASS_KEY_PROVIDER=env export PROTON_PASS_ENCRYPTION_KEY="${CI_PASS_ENCRYPTION_KEY}" export PROTON_PASS_PASSWORD_FILE=/run/secrets/pass-password
pass-cli login --interactive [email protected]
# Run tests with secrets pass-cli run --env-file .env.test -- npm test
# Deploy with secrets pass-cli run --env-file .env.production -- ./deploy.sh
# Cleanup pass-cli logout ```
## 注意事项
- **Beta 状态：** Proton Pass CLI 目前处于 Beta 阶段 - **切换轨道：** 仅适用于手动安装（不适用于包管理器） - **项目更新限制：** 无法通过 CLI 更新 TOTP 或时间字段 - **密码短语建议：** 生成的密钥可选密码短语（已在保险库中加密） - **SSH 代理刷新：** 默认 1 小时，可通过 `--refresh-interval` 自定义 - **Docker 容器：** 必须使用文件系统密钥存储（`PROTON_PASS_KEY_PROVIDER=fs`） - **Linux 密钥环：** 使用内核密钥环（无 D-Bus），重启时清除机密 - **遥测：** 仅匿名（无个人数据），可禁用 - **密钥屏蔽：** 自动屏蔽 `run` 命令输出中的密钥 - **模板语法：** `inject` 需要 `{{ }}` 大括号，`run` 使用原始 `pass://` URI - **项目 ID 唯一性：** 项目 ID 仅在与 Share ID 结合时才唯一
## 命令参考快速列表
**身份验证：** - `login`, `logout`, `info`, `test`
**保险库：** - `vault list`, `vault create`, `vault update`, `vault delete`, `vault share`, `vault member`, `vault transfer`
**项目：** - `item list`, `item view`, `item create`, `item update`, `item delete`, `item share`, `item totp`, `item alias`, `item attachment`
**密钥注入：** - `run` - 执行命令并将密钥作为环境变量注入 - `inject` - 使用密钥引用处理模板文件
**密码：** - `password generate`, `password score`
**SSH：** - `ssh-agent load`, `ssh-agent start`
**设置：** - `settings view`, `settings set`, `settings unset`
**分享与邀请：** - `share list`, `invite list`, `invite accept`, `invite reject`
**用户：** - `user info`
**更新：** - `update`