pp-cloud-run-admin

Google Cloud Run — Printing Press CLI

前置条件：安装 CLI

此技能通过 cloud-run-admin-pp-cli 二进制文件运行。在调用此技能中的任何命令前，必须确认 CLI 已安装。 如果尚未安装，请先安装：

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

   npx -y @mvanhorn/printing-press-library install cloud-run-admin --cli-only
   

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

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/cloud/cloud-run-admin/cmd/cloud-run-admin-pp-cli@latest

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

何时使用此 CLI

当 Agent 或脚本需要专门访问 Cloud Run Admin API，而无需浏览完整的 gcloud 命令集时，请使用此 CLI。它最适合以读取为主的检查、本地资源清单同步、搜索、按字段选择 JSON，以及关联服务、作业、执行、修订版本、任务和操作的工作流。

独特功能

其他任何用于此 API 的工具都不具备这些功能。

面向 Agent 的 Cloud Run 操作

• services list — 通过 Admin API 列出 Cloud Run 服务，并提供适合 Agent 使用的 JSON、紧凑输出和字段选择功能。

  当 Agent 需要查看某个项目和区域中的 Cloud Run 服务简要清单时使用。

  cloud-run-admin-pp-cli services list projects/PROJECT_ID/locations/REGION --agent --select services.name,services.uri,nextPageToken
  

本地状态与分析

• sync — 将 Cloud Run 资源同步到本地 SQLite 存储，以便搜索服务、作业、修订版本、执行、任务和操作，而无需重复调用每个 API。

  在离线搜索、SQL 检查或重复进行多资源分析之前使用。

  cloud-run-admin-pp-cli sync --json
  

• search — 在本地搜索已同步的 Cloud Run 资源清单，或根据数据源模式回退到实时 API 调用。

  当需要根据记忆中的片段查找 Cloud Run 资源时使用。

  cloud-run-admin-pp-cli search "api" --type services --json --select resource_type,title
  

• analytics — 基于已同步的 Cloud Run 数据进行本地分析，以回答资源清单和状态相关问题。

  同步后，如果问题涉及趋势或资源清单健康状况，而非单个资源，请使用此命令。

  cloud-run-admin-pp-cli analytics --json
  

工作流状态检查

• workflow — 提供组合多个 Cloud Run Admin API 操作的复合工作流，方便操作人员使用。

  当任务涉及多种 Cloud Run 资源类型时使用。

  cloud-run-admin-pp-cli workflow --help
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输方式访问面向浏览器的端点。执行常规 API 调用无需常驻浏览器进程。

命令参考

cloud-run-admin-jobs — 管理 Cloud Run 管理作业

• cloud-run-admin-pp-cli cloud-run-admin-jobs create — 创建作业。
• cloud-run-admin-pp-cli cloud-run-admin-jobs list — 列出作业。
• cloud-run-admin-pp-cli cloud-run-admin-jobs run — 触发此作业的新执行实例的创建。

executions — 管理执行实例

operations — 管理操作

• cloud-run-admin-pp-cli operations list — 列出与请求中指定筛选条件匹配的操作。如果服务器不支持此方法，它...
• cloud-run-admin-pp-cli operations wait — 等待指定的长时间运行操作完成，或达到指定的最长超时时间，然后返回...

services — 管理服务

• cloud-run-admin-pp-cli services create — 在指定项目和位置创建新服务。
• cloud-run-admin-pp-cli services get-iam-policy — 获取当前对指定 Cloud Run 服务生效的 IAM 访问控制策略。此结果不包含...
• cloud-run-admin-pp-cli services list — 列出服务。
• cloud-run-admin-pp-cli services patch — 更新服务。
• cloud-run-admin-pp-cli services set-iam-policy — 为指定服务设置 IAM 访问控制策略。覆盖任何现有策略。
• cloud-run-admin-pp-cli services test-iam-permissions — 返回调用方在指定项目上拥有的权限。调用此方法不需要任何权限...

查找合适的命令

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

cloud-run-admin-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示无法确信有匹配项——请改用 --help，或尝试更具体的查询。

操作指南

查找合适的 Cloud Run 命令

cloud-run-admin-pp-cli which "show service revisions" --json

调用特定的 Cloud Run Admin 命令前，先使用意图搜索。

以精简的 Agent 输出列出服务

cloud-run-admin-pp-cli services list projects/PROJECT_ID/locations/REGION --agent --select services.name,services.uri,nextPageToken

结合 Agent 默认设置与字段选择，让 Agent 无需解析大型服务负载。

搜索已同步的清单

cloud-run-admin-pp-cli search "api" --type services --json --select resource_type,title

同步后搜索本地 Cloud Run 清单。

身份验证设置

Cloud Run Admin 使用带有 cloud-platform 范围的 Google OAuth bearer token。在本地使用时，运行 gcloud auth print-access-token 并将值导出为 CLOUD_RUN_ADMIN_OAUTH2C；请勿提交此令牌或将其粘贴到文档中。

运行 cloud-run-admin-pp-cli doctor 以验证设置。

Agent 模式

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

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

• 可筛选 — --select 可保留字段子集。带点路径可深入嵌套结构；数组会逐元素遍历。对于内容冗长的 API，此功能对于缩小上下文至关重要：

  cloud-run-admin-pp-cli cloud-run-admin-jobs list mock-value --agent --select id,name,status
  

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

• 支持离线 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不显示提示，每项输入都通过标志传入

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

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

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

解析 .results 获取数据，并检查 .meta.source 以确认数据来自实时 API 还是本地存储。只有当 stdout 连接到终端时，才会将便于人类阅读的 N results (live) 摘要输出到 stderr；通过管道传递的内容和 Agent 消费者会在 stdout 上收到纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有什么不对劲时，请记录下来：

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

条目会保存在本地的 ~/.cloud-run-admin-pp-cli/feedback.jsonl 中。除非设置了 CLOUD_RUN_ADMIN_FEEDBACK_ENDPOINT，并且传入 --send 或设置 CLOUD_RUN_ADMIN_FEEDBACK_AUTO_SEND=true，否则不会发送任何 POST 请求。默认情况下仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是逐渐积累价值的关键。

输出传递

每条命令都接受 --deliver <sink>。输出除了写入标准输出（或代替标准输出）外，还会发送到指定目标，因此 Agent 无需手动通过管道传递，就能路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入标准输出
file:<path>	原子性地将输出写入 <path>（先写入临时文件，再重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

对于未知方案，系统会拒绝请求，并返回指出受支持方案的结构化错误。Webhook 请求失败时会返回非零状态，并在标准错误中记录 URL 和 HTTP 状态。

命名配置

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

cloud-run-admin-pp-cli profile save briefing --json
cloud-run-admin-pp-cli --profile briefing cloud-run-admin-jobs list mock-value
cloud-run-admin-pp-cli profile list --json
cloud-run-admin-pp-cli profile show briefing
cloud-run-admin-pp-cli profile delete briefing --yes

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

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	受到速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/cloud/cloud-run-admin/cmd/cloud-run-admin-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add cloud-run-admin-pp-mcp -- cloud-run-admin-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   cloud-run-admin-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：cloud-run-admin-pp-cli <command> --help。