1password

1Password CLI

使用 1Password CLI（op）获取和管理机密，避免以明文形式暴露。

获取机密

请用户提供其 1Password 机密引用（在 1Password 中右键点击字段 →“复制机密引用”）：

# Read a secret value
op read "op://Vault/Item/field"

# Use in a command (secret never shown in shell history)
some-cli --token "$(op read 'op://Vault/Item/api-key')"

# Use as environment variable
export API_KEY="$(op read 'op://Vault/Item/api-key')"

常见模式

# CLI auth
toggl auth "$(op read 'op://Employee/Toggl/api key')"
gh auth login --with-token < <(op read 'op://Personal/GitHub/token')

# Docker login
docker login -u $(op read op://Vault/Docker/username) -p $(op read op://Vault/Docker/password)

引用格式

op://vault-name/item-name/field-name
op://vault-name/item-name/section-name/field-name

特殊字段：

op read "op://Vault/Item/one-time password?attribute=otp"      # TOTP
op read "op://Vault/Item/private key?ssh-format=openssh"        # SSH key

创建条目

字段类型语法

"Field Name[text]=value"        # Plain text (visible)
"Field Name[concealed]=value"   # Password/secret (hidden)
"Field Name[url]=https://..."   # Clickable URL
"Field Name[delete]"            # Remove a field

默认（无后缀）= 隐藏。务必明确指定字段类型。

原则

1. 仅隐藏真正的机密——密码、API 密钥、令牌。URL、用户名、客户端 ID、主机名、端口和其他非敏感标识符必须使用 [text] 或 [url]。如果可以在会议上大声读出，就不算机密。
2. 使用清晰、描述性强的字段名称——与来源中的术语保持一致
3. 补充上下文——添加账户信息、备注和详细信息
4. 清理模板残留内容——删除模板中的默认字段，或为其设置默认值

OAuth API 凭据

op item create --category="API Credential" --title="Service Name - App Name" --vault="VaultName" \
  "Client ID[text]=ABC123" \
  "Client Secret[concealed]=secret-value-here" \
  "Account[text][email protected]" \
  "Redirect URL[text]=http://localhost:8080" \
  "Authorization URL[text]=https://service.com/oauth2/authorize" \
  "Token Request URL[text]=https://api.service.com/oauth2/token" \
  "Developer Portal[url]=https://developer.service.com" \
  "notesPlain=Context about this credential and any gotchas."

简单 API 密钥

op item create --category="API Credential" --title="Service Name API" --vault="VaultName" \
  "API Key[concealed]=sk-xxxxxxxxxxxx" \
  "Account[text][email protected]" \
  "Documentation[url]=https://docs.service.com/api" \
  "notesPlain=Used for X purpose. Rate limit: 1000/day."

数据库凭据

op item create --category="Database" --title="Production DB - ServiceName" --vault="VaultName" \
  "type[text]=postgresql" \
  "server[text]=db.example.com" \
  "port[text]=5432" \
  "database[text]=myapp_production" \
  "username[text]=app_user" \
  "password[concealed]=secret-password" \
  "notesPlain=Read replica. Primary is on port 5433."

编辑现有条目

使用 op item edit 为现有条目添加字段时，同样适用这些类型规则——务必明确指定字段类型：

# WRONG — defaults to concealed, hides the URL and username
op item edit "My Item" "Section.URL=https://example.com" "Section.username=admin"

# RIGHT — only the password is concealed
op item edit "My Item" "Section.URL[url]=https://example.com" "Section.username[text]=admin" "Section.password[concealed]=secret"

处理模板字段

某些类别会添加 valid from 和 expires 等默认字段，其值设为 epoch 0。

# Delete if not applicable
op item edit "Item Name" --vault="VaultName" "valid from[delete]" "expires[delete]"

# Set if applicable
op item edit "Item Name" --vault="VaultName" "valid from=2026-01-27" "expires=2027-01-27"

字段命名

不佳	良好
credential	Client ID
token_uri	Token Request URL
secret	Client Secret 或 API Key

使用服务文档中的术语。

前提条件

• 已安装 1Password 应用，并启用 CLI 集成
• 桌面应用集成会处理登录：运行实际的 op read/op item 命令，并由应用提示操作
• 查看保管库：op vault list
• 通过 SSH 连接到另一台 Mac 时，op 会使用那台 Mac 上的 1Password 应用：运行 ssh <mac> 'op ...'。Touch ID 提示会显示在那台 Mac 的屏幕上。当用户在另一台 Mac 上而 Agent 位于当前设备时，可使用此方式，让用户在所在位置批准操作，而无需重新登录
• 文档：https://developer.1password.com/docs/cli