pp-google-photos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Photos — Printing Press CLI

Google Photos — Printing Press CLI工具

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

google-photos-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press install google-photos --cli-only

Verify:
```
google-photos-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-cli@latest

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

google-photos-pp-cli

二进制文件运行。在调用本技能的任何命令前，必须确认CLI已安装。如果未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

npx -y @mvanhorn/printing-press install google-photos --cli-only

验证安装：
```
google-photos-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可改用Go直接安装（要求Go 1.23及以上版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-cli@latest

如果安装后执行

--version

提示“command not found”，说明安装程序未将二进制文件添加到

$PATH

中。请在验证成功后再执行技能命令。

Command Reference

命令参考

albums — Manage app-created Google Photos albums.

```
google-photos-pp-cli albums add-enrichment
```
— Add text, location, or map enrichment to an app-created album.
```
google-photos-pp-cli albums batch-add-media-items
```
— Add app-created media items to an app-created album.
```
google-photos-pp-cli albums batch-remove-media-items
```
— Remove app-created media items from an app-created album.
```
google-photos-pp-cli albums create
```
— Create an album in the user's Google Photos library.
```
google-photos-pp-cli albums get
```
— Get an app-created album by ID.
```
google-photos-pp-cli albums list
```
— List albums created by this app.
```
google-photos-pp-cli albums patch
```
— Update title or cover photo on an app-created album.

media-items — Manage app-created Google Photos media items.

google-photos-pp-cli media-items batch-create

— Create media items from upload tokens.

```
google-photos-pp-cli media-items batch-get
```
— Get multiple app-created media items by ID.
```
google-photos-pp-cli media-items get
```
— Get an app-created media item by ID.
```
google-photos-pp-cli media-items list
```
— List media items created by this app.
```
google-photos-pp-cli media-items patch
```
— Update the description on an app-created media item.
```
google-photos-pp-cli media-items search
```
— Search app-created media items by album or filters.

picker — Create, poll, clean up, and read Google Photos Picker sessions.

```
google-photos-pp-cli picker create-session
```
— Create a Picker session and return the picker URI.
```
google-photos-pp-cli picker delete-session
```
— Delete a Picker session after selected media bytes have been retrieved.
```
google-photos-pp-cli picker get-session
```
— Get Picker session status.
```
google-photos-pp-cli picker list-media-items
```
— List media items picked by the user during a Picker session.

Hand-written commands

```
google-photos-pp-cli upload file <path>
```
— Upload raw photo or video bytes and print the upload token for media-items batch-create.
```
google-photos-pp-cli picker wait <session-id>
```
— Poll a Picker session until selected media items are ready.
```
google-photos-pp-cli schema --pretty
```
— Emit machine-readable command, flag, auth, and safety-policy metadata.
```
google-photos-pp-cli auth list
```
— List stored OAuth accounts.

google-photos-pp-cli auth use <account-email>

— Set the default OAuth account.

google-photos-pp-cli auth remove <account-email>

— Remove a stored OAuth account.

albums — 管理应用创建的Google Photos相册。

```
google-photos-pp-cli albums add-enrichment
```
— 为应用创建的相册添加文本、位置或地图附加信息。
```
google-photos-pp-cli albums batch-add-media-items
```
— 批量将应用创建的媒体项添加到应用创建的相册中。
```
google-photos-pp-cli albums batch-remove-media-items
```
— 从应用创建的相册中批量移除应用创建的媒体项。
```
google-photos-pp-cli albums create
```
— 在用户的Google Photos图库中创建相册。
```
google-photos-pp-cli albums get
```
— 通过ID获取应用创建的相册。
```
google-photos-pp-cli albums list
```
— 列出本应用创建的所有相册。
```
google-photos-pp-cli albums patch
```
— 更新应用创建的相册的标题或封面照片。

media-items — 管理应用创建的Google Photos媒体项。

google-photos-pp-cli media-items batch-create

— 通过上传令牌创建媒体项。

```
google-photos-pp-cli media-items batch-get
```
— 通过ID批量获取多个应用创建的媒体项。
```
google-photos-pp-cli media-items get
```
— 通过ID获取应用创建的媒体项。
```
google-photos-pp-cli media-items list
```
— 列出本应用创建的所有媒体项。
```
google-photos-pp-cli media-items patch
```
— 更新应用创建的媒体项的描述信息。
```
google-photos-pp-cli media-items search
```
— 按相册或筛选条件搜索应用创建的媒体项。

picker — 创建、轮询、清理和读取Google Photos Picker会话。

```
google-photos-pp-cli picker create-session
```
— 创建Picker会话并返回选择器URI。
```
google-photos-pp-cli picker delete-session
```
— 在获取到所选媒体字节后删除Picker会话。
```
google-photos-pp-cli picker get-session
```
— 获取Picker会话状态。
```
google-photos-pp-cli picker list-media-items
```
— 列出用户在Picker会话中选择的媒体项。

手动编写的命令

```
google-photos-pp-cli upload file <path>
```
— 上传原始照片或视频字节，并打印用于media-items batch-create的上传令牌。
```
google-photos-pp-cli picker wait <session-id>
```
— 轮询Picker会话，直到所选媒体项准备就绪。
```
google-photos-pp-cli schema --pretty
```
— 输出机器可读的命令、标志、认证和安全策略元数据。
```
google-photos-pp-cli auth list
```
— 列出已存储的OAuth账户。

google-photos-pp-cli auth use <account-email>

— 设置默认OAuth账户。

google-photos-pp-cli auth remove <account-email>

— 删除已存储的OAuth账户。

Google Photos Scope Limits

Google Photos范围限制

Google Photos Library API read and edit scopes are limited to app-created albums and media. Use Library API commands here for app-created content, uploads, and album/media management. Use Picker commands when a user needs to select media from their broader Google Photos library.

Google Photos Library API的读取和编辑权限仅限于应用创建的相册和媒体。使用此处的Library API命令管理应用创建的内容、上传以及相册/媒体。当用户需要从其更广泛的Google Photos图库中选择媒体时，请使用Picker命令。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

google-photos-pp-cli which "<capability in your own words>"

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要执行的操作但不确定使用哪个命令时，可直接询问CLI：

bash

google-photos-pp-cli which "<用你自己的话描述的功能>"

which

命令会将自然语言的功能查询解析为该CLI精选功能索引中最匹配的命令。退出码

表示至少有一个匹配项；退出码

表示没有匹配项——此时可改用

--help

或更精准的查询。

Auth Setup

认证设置

Authenticate via the browser:

bash

google-photos-pp-cli auth login --client-id "$GOOGLE_PHOTOS_CLIENT_ID"

Tokens are stored locally and refreshed automatically.

For multiple Google accounts, store tokens under account emails and select the account explicitly:

bash

google-photos-pp-cli auth login you@example.com --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
google-photos-pp-cli auth list --json
google-photos-pp-cli auth use you@example.com
google-photos-pp-cli --account you@example.com albums list --agent

Account selection order:

--account

GOOGLE_PHOTOS_ACCOUNT

auth use

default, then legacy single-token config.

Run

google-photos-pp-cli doctor

to verify setup.

通过浏览器进行认证：

bash

google-photos-pp-cli auth login --client-id "$GOOGLE_PHOTOS_CLIENT_ID"

令牌会存储在本地并自动刷新。

对于多个Google账户，可按账户邮箱存储令牌并明确选择账户：

bash

google-photos-pp-cli auth login you@example.com --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
google-photos-pp-cli auth list --json
google-photos-pp-cli auth use you@example.com
google-photos-pp-cli --account you@example.com albums list --agent

账户选择优先级：

--account

参数 >

GOOGLE_PHOTOS_ACCOUNT

环境变量 >

auth use

设置的默认账户 > 旧版单令牌配置。

执行

google-photos-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
google-photos-pp-cli albums list --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Offline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag

Guarded — use

--enable-commands

--disable-commands

with dotted command paths:

bash

google-photos-pp-cli --enable-commands albums.list albums list --agent
google-photos-pp-cli --disable-commands picker.delete-session picker delete-session SESSION_ID --agent

Introspectable — use
```
schema --pretty
```
or
```
agent-context --pretty
```
for the full JSON command contract.

在任何命令后添加

--agent

参数。等效于：

--json --compact --no-input --no-color --yes

。

可管道传输 — 标准输出为JSON，错误信息输出到标准错误
可筛选 —
```
--select
```
参数保留指定字段子集。点路径可深入嵌套结构；数组会遍历每个元素。这对于在冗长API中精简上下文至关重要：
bash
```
google-photos-pp-cli albums list --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求内容但不发送
离线友好 — 同步/搜索命令在本地SQLite存储可用时可使用该存储
非交互式 — 从不提示输入，所有输入均通过标志参数提供

可管控 — 使用

--enable-commands

--disable-commands

搭配点式命令路径：

bash

google-photos-pp-cli --enable-commands albums.list albums list --agent
google-photos-pp-cli --disable-commands picker.delete-session picker delete-session SESSION_ID --agent

可自省 — 使用
```
schema --pretty
```
或
```
agent-context --pretty
```
获取完整的JSON命令契约。

Baked Safety Profiles

内置安全配置文件

Build stronger local guardrails when exposing this CLI or MCP server to autonomous agents:

bash

make build-readonly
make build-agent-safe
make build-mcp-readonly
make build-mcp-agent-safe

safety_readonly

permits read/list/search/export/schema-style commands and blocks Google Photos mutations.

safety_agent_safe

permits reads and local archive/search workflows while blocking auth writes, uploads, creates, patches, deletes, and album/media mutations.

当将此CLI或MCP服务器暴露给自主Agent时，可构建更强的本地防护：

bash

make build-readonly
make build-agent-safe
make build-mcp-readonly
make build-mcp-agent-safe

safety_readonly

允许读取/列出/搜索/导出/模式类命令，阻止Google Photos的修改操作。

safety_agent_safe

允许读取和本地归档/搜索工作流，阻止认证写入、上传、创建、补丁、删除以及相册/媒体修改操作。

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:

json

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

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

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

json

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

解析

.results

获取数据，通过

.meta.source

判断数据是实时还是本地的。仅当标准输出为终端时，才会将人类可读的

N results (live)

摘要打印到标准错误；管道/Agent消费者会在标准输出获取纯JSON。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

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

Entries are stored locally at

~/.google-photos-pp-cli/feedback.jsonl

. They are never POSTed unless

GOOGLE_PHOTOS_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

GOOGLE_PHOTOS_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当你（或Agent）发现此CLI存在问题时，可记录反馈：

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

反馈条目存储在本地

~/.google-photos-pp-cli/feedback.jsonl

文件中。除非设置了

GOOGLE_PHOTOS_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置

GOOGLE_PHOTOS_FEEDBACK_AUTO_SEND=true

，否则反馈不会被POST发送。默认行为仅存储在本地。

请记录让你感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这样的反馈更有价值。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出会发送到指定的接收端，同时保留（或替代）标准输出，以便Agent无需手动管道即可路由命令结果。支持三种接收端：

接收端	效果
`stdout`	默认；仅写入标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出主体POST到指定URL（当使用 `--compact` 时为 `application/json` 或 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误并列出支持的类型。Webhook失败时返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

google-photos-pp-cli profile save briefing --json
google-photos-pp-cli --profile briefing albums list
google-photos-pp-cli profile list --json
google-photos-pp-cli profile show briefing
google-photos-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中复用。适用于定时Agent每次运行都使用相同配置调用同一命令的场景——即HeyGen的“Beacon”模式。

google-photos-pp-cli profile save briefing --json
google-photos-pp-cli --profile briefing albums list
google-photos-pp-cli profile list --json
google-photos-pp-cli profile show briefing
google-photos-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件值；配置文件值优先于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便自省Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

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

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
google-photos-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

的规则：

为空、
help
或
--help
→ 显示
```
google-photos-pp-cli --help
```
输出
以
install
开头 → 若结尾为
```
mcp
```
→ 安装MCP；否则 → 参见上方的前提条件部分
其他情况 → 直接使用（以
```
--agent
```
标志执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-mcp@latest

bash

claude mcp add google-photos-pp-mcp -- google-photos-pp-mcp

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-mcp@latest

注册到Claude Code：

bash

claude mcp add google-photos-pp-mcp -- google-photos-pp-mcp

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which google-photos-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

google-photos-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
google-photos-pp-cli <command> --help
```
.

检查是否已安装：
```
which google-photos-pp-cli
```
若未找到，提供安装选项（参见本技能顶部的前提条件部分）。
将用户查询与上方“独特功能”和“命令参考”中最匹配的命令对应。

带

--agent

标志执行命令：

bash

google-photos-pp-cli <command> [subcommand] [args] --agent

若存在歧义，查看子命令帮助：
```
google-photos-pp-cli <command> --help
```
。