pp-1password

1Password — Printing Press CLI

前提条件：安装 CLI

此技能使用 1password-pp-cli 二进制文件。**调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install 1password --cli-only
   

2. 验证：1password-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、离线等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/auth/1password/cmd/1password-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 访问二进制文件目录。验证成功之前，请勿继续运行此技能的命令。

让 Agent 使用 1Password，而无需每项任务都暴露机密。CLI 会将模糊请求解析为精确的 op:// 引用、审计元数据、检查策略，并且只有在明确制定计划后才调用 op read、op inject 或 op run。

何时不应使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预约、购买或更改远程状态的请求，请勿启用此 CLI。此 CLI 仅用于机密引用规划、元数据审计、策略检查，以及严格设限的本地 op read / op inject 工作流。

独特功能

这些功能无法通过此 API 的其他工具使用。

机密

• secrets resolve — 将 Agent 的模糊请求解析为精确的 op:// 保管库/项目/字段引用，不打印值。

  防止意外读取过多内容，并为后续命令提供精确引用。

  1password-pp-cli secrets resolve --query "token" --json
  

• secrets read — 仅读取精确的 op:// 引用；执行策略检查，并要求显式通过 --reveal 才会打印值。

  将值访问转变为范围明确、可审计的操作，而非模糊搜索。

  1password-pp-cli secrets read op://Engineering/GitHub/token --dry-run --json
  

• secrets explain — 说明为何为某项任务选择特定项目和字段，不会暴露字段值。

  1password-pp-cli secrets explain --query "token" --json
  

• secrets preflight — 检查计划中的任务或命令是否似乎需要机密值、文档、卡片或写入权限。

  1password-pp-cli secrets preflight --task "deploy using op run --env-file .env" --json
  

环境

• env plan — 解析 .env、配置文件或 shell 文件，找出缺失变量，并将其映射到安全的 op:// 引用。

  1password-pp-cli env plan API_TOKEN= --json
  

• env inject — 先生成脱敏计划，再封装 op inject；必须提供 --write 才会生成输出文件。

  1password-pp-cli env inject --in-file README.md --out-file injected.env --json
  

项目

• items classify — 查找看起来像 API 凭据、登录信息、SSH 密钥、卡片或文档的安全备注。

  1password-pp-cli items classify --json
  

• items duplicates — 检测不同保管库中的重复标题、URL、用户名和疑似复制的凭据，不打印机密值。

  1password-pp-cli items duplicates --json
  

• items ownership — 标记缺少所有者、用途、轮换或环境标签的共享凭据或服务凭据。

  1password-pp-cli items ownership --json
  

卡片

• cards audit — 查找存储为备注或登录信息的卡片、缺少所有者/用途标签的卡片，或类似 CVV 的字段，不打印卡片值。

  1password-pp-cli cards audit --json
  

• cards resolve — 返回卡片项目和字段引用，不打印卡号、有效期或 CVV。

  1password-pp-cli cards resolve --query "card" --json
  

文档

• documents inventory — 列出文档元数据和精确引用，不下载文档内容。

  1password-pp-cli documents inventory --json
  

• documents audit — 标记敏感文件名、超大文档、类似私钥/证书的文档，以及共享保管库中的文档。

  1password-pp-cli documents audit --json
  

• documents read — 仅在通过策略检查并明确使用 --reveal 后，流式读取一个精确的文档或附件引用。供内存中的使用方使用；切勿将文档字节放入客户端配置文件。

  1password-pp-cli documents read op://Engineering/Google-Analytics/service-account.json --reveal --agent
  

分享

• share preflight —— 分享条目前，显示接收者、条目类别、包含的字段、过期时间和风险。

  1password-pp-cli share preflight --ref op://Engineering/GitHub/token --recipient recipient --expires-in 1d --json
  

• share audit —— 报告是否支持通过 op 或 SDK 检查现有或可分享的条目链接，并明确说明不支持的状态。

  1password-pp-cli share audit --json
  

策略

• policy check —— 强制执行相关规则，例如绝不读取信用卡值、生产环境必须使用精确引用，以及必须添加所有者标签。

  1password-pp-cli policy check --ref op://Production/API/token --require-exact --json
  

访问权限

• access scope —— 按保管库、类别和数量汇总当前服务账号或 op 会话可以访问的内容，不包含具体值。

  1password-pp-cli access scope --json
  

• rate-limit status —— 封装 op 服务账号的速率限制状态，让 Agent 避免耗尽配额。

  1password-pp-cli rate-limit status --json
  

Agent

• agent grant-plan —— 建议任务所需的最小服务账号保管库权限。

  1password-pp-cli agent grant-plan --task "read staging deploy token" --json
  

运行时

• run plan —— 检查 op 运行命令或环境文件，并在执行前显示将解析的密钥引用。

  1password-pp-cli run plan --command "npm test" --json
  

审计

• audit stale —— 根据元数据标记可能已过期、未添加标签、重复或可能不再使用的条目。

  1password-pp-cli audit stale --days 180 --json
  

• audit misplaced —— 查找存储在错误 1Password 类别中的 API 密钥、卡片、文档或 SSH 材料。

  1password-pp-cli audit misplaced --json
  

配方

处理密钥请求而不泄露具体值

1password-pp-cli secrets resolve --query "token" --json

返回精确的 op:// 引用和已隐藏具体值的候选元数据，以便后续步骤要求使用精确引用。

在写入输出前规划环境变量注入

1password-pp-cli env inject --in-file README.md --out-file injected.env --json

显示 op inject 将解析的引用；除非明确提供 --write，否则 will_write 保持为 false。

命令参考

op —— 检查本地 1Password CLI 身份验证状态

• 1password-pp-cli op —— 显示是否已安装并通过身份验证，不读取密钥值

查找合适的命令

知道要做什么，但不知道该用哪个命令时，可以直接询问 CLI：

1password-pp-cli which "<capability in your own words>"

which 会根据本 CLI 精选的功能索引，将自然语言功能查询映射到最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help 或使用更具体的查询。

身份验证设置

安装官方 1Password CLI（op），并在使用此封装程序前完成身份验证。

对于自动化，请设置 1Password 服务账号令牌：

export OP_SERVICE_ACCOUNT_TOKEN="<service-account-token>"

如果 Agent 需要使用多个 1Password 账号，建议使用基于 Keychain 的具名令牌：

1password-pp-cli service-accounts add team --account example-team.1password.com
1password-pp-cli service-accounts add sandbox --account example-sandbox.1password.com
1password-pp-cli --op-service-account team op --agent

使用隐藏输入提示进行设置，或使用 --token-stdin / --token-env NAME，避免将令牌放入 argv。在非 macOS 系统上，可通过 --op-service-account-token-env NAME 为单次调用指定现有环境变量。切勿将这些身份验证选择标志放入 --profile；CLI 不会将它们保存到配置文件，也不会传递给 MCP shellout。

对于 macOS 后台 Agent，请使用代码签名保持一致的 CLI。对于由旧版二进制文件创建的条目，请在本地交互式终端中运行一次 1password-pp-cli service-accounts repair-access <name> --json 进行迁移；此操作只会更改 Keychain 访问控制，不会泄露令牌。请勿在这次一次性操作中使用 --agent，因为它会有意禁用交互式批准。

对于本地桌面工作流，请通过常规 1Password CLI 或桌面应用集成登录 op。使用 --op-account 仅为子级 op 进程设置 OP_ACCOUNT。如果设置了 Connect 变量，或所选令牌不可用，具名或环境变量形式的服务账号选择将直接失败。

运行 1password-pp-cli doctor 验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐个遍历元素。在冗长的 API 中，缩小上下文至关重要：

  1password-pp-cli op --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不发送

• 适合离线使用 — 如果本地 SQLite 存储可用，同步／搜索命令可以使用它

• 非交互式 — 不会提示输入，所有输入都通过标志提供

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应信封

从本地存储或 API 读取的命令会将输出包装在一个来源信息信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

从 .results 解析数据，并查看 .meta.source 以了解数据来自实时 API 还是本地存储。只有当 stdout 指向终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将易读的 N results (live) 摘要仅输出到 stderr；通过管道传递／由 Agent 使用以及显式指定格式的运行，stdout 都只会输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有异常之处时，请记录下来：

1password-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
1password-pp-cli feedback --stdin < notes.txt
1password-pp-cli feedback list --json --limit 10

条目会本地存储在 ~/.local/share/1password-pp-cli/feedback.jsonl。除非设置了 API_1PASSWORD_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 API_1PASSWORD_FEEDBACK_AUTO_SEND=true，否则不会通过 POST 发送。默认仅在本地存储。

写下让你感到意外的地方，而不是提交 bug 报告。简短、具体，写成一行：这才是能持续积累价值的部分。

输出交付

每个命令都接受 --deliver <sink>。除了（或替代）stdout，输出还会发送到指定目标，这样 Agent 无需手动通过管道传递结果即可路由命令输出。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（--compact 时使用 application/json 或 application/x-ndjson）

对于未知方案，系统会拒绝请求，并返回结构化错误，列出支持的方案。Webhook 请求失败时会返回非零退出码，并将 URL 和 HTTP 状态记录到 stderr。

命名配置

配置是一组已保存的标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，就可以使用配置——这就是 HeyGen 的 “Beacon” 模式。

1password-pp-cli profile save briefing --json
1password-pp-cli --profile briefing op
1password-pp-cli profile list --json
1password-pp-cli profile show briefing
1password-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便进行内省的 Agent 在运行时发现它们。

配置绝不会存储或应用 --op-service-account、--op-service-account-token-env 或 --op-account；每次调用时都要使用专用的服务账号选择器。读取配置时，旧版身份验证值会在内存中移除；下次显式写入配置时，也会将它们从磁盘中移除。

退出码

代码	含义
0	成功
2	用法错误（参数不正确）
3	未找到资源
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 1password-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文“先决条件”
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附加 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/auth/1password/cmd/1password-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add 1password-pp-mcp -- 1password-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which 1password-pp-cli 如果未找到，则提供安装选项（参见本技能开头的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   1password-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，请查看子命令帮助：1password-pp-cli <command> --help。