pp-google-photos

Google Photos — Printing Press CLI

前提条件：CLI のインストール

このスキルは google-photos-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

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

2. 次のコマンドで確認します。google-photos-pp-cli --version
3. 報告されたインストール先が、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールが失敗した場合（Node がない、オフラインなど）は、Go を直接インストールしてください（Go 1.26.6 以降が必要です）。

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 経由で参照できていません。確認が成功するまで、スキルのコマンドを実行しないでください。

コマンドリファレンス

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 セッションを作成し、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 のスコープ制限

Google Photos Library API の読み取りおよび編集スコープは、アプリで作成したアルバムとメディアに限られます。アプリで作成したコンテンツの操作、アップロード、アルバム／メディアの管理には、ここに記載された Library API コマンドを使用してください。ユーザーが自身の Google Photos ライブラリ全体からメディアを選択する必要がある場合は、Picker コマンドを使用してください。

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

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

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最も適したコマンドに対応付けます。終了コード 0 は少なくとも 1 件一致したことを示し、終了コード 2 は確信を持てる一致がなかったことを示します。その場合は --help にフォールバックするか、より範囲を絞った問い合わせを使用してください。

認証の設定

ブラウザーで認証します。

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

トークンはローカルに保存され、自動的に更新されます。

複数の Google アカウントを使用する場合は、トークンをアカウントのメールアドレスごとに保存し、使用するアカウントを明示的に選択します。

google-photos-pp-cli auth login [email protected] --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
google-photos-pp-cli auth list --json
google-photos-pp-cli auth use [email protected]
google-photos-pp-cli --account [email protected] albums list --agent

アカウントの選択順序は、--account、GOOGLE_PHOTOS_ACCOUNT、auth use のデフォルト、従来の単一トークン設定の順です。

google-photos-pp-cli doctor を実行して設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout に JSON、stderr にエラーを出力します

• フィルタ可能 — --select でフィールドの一部を保持します。ドット区切りのパスはネストされた構造をたどり、配列では各要素をたどります。詳細な API のコンテキストを小さく保つうえで重要です。

  google-photos-pp-cli albums list --agent --select id,name,status
  

• プレビュー可能 — --dry-run でリクエストを送信せずに表示します

• オフライン対応 — 同期／検索コマンドでは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力をフラグで指定します

• 制限付き — ドット区切りのコマンドパスを指定して、--enable-commands／--disable-commands を使用します。

  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 契約全体を確認できます。

組み込みの安全性プロファイル

この CLI または MCP サーバーを自律型エージェントに公開する際は、より強固なローカルガードレールを設定できます。

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

safety_readonly は、読み取り／一覧表示／検索／エクスポート／スキーマ関連のコマンドを許可し、Google Photos の変更操作をブロックします。safety_agent_safe は、読み取りとローカルのアーカイブ／検索ワークフローを許可し、認証情報の書き込み、アップロード、作成、パッチ、削除、アルバム／メディアの変更操作をブロックします。

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を来歴エンベロープで囲みます。

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

データには .results を、ライブデータかローカルデータかの確認には .meta.source を解析してください。人間が読める N results (live) という概要は、stdout が端末の場合に限り stderr に出力されます。パイプやエージェントから利用する場合、stdout には純粋な JSON が出力されます。

エージェントからのフィードバック

この 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 されることはありません。デフォルトの動作ではローカルにのみ保存されます。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で記録します。それが積み重なっていく部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は、stdout に加えて（または stdout の代わりに）指定した出力先に送られるため、エージェントはコマンド結果を手作業でパイプ処理せずに振り分けられます。対応する出力先は 3 種類です。

出力先	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してからリネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、対応するスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが stderr に記録されます。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットで、複数回の呼び出しで再利用されます。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。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 に一覧表示するため、イントロスペクションを行うエージェントは実行時にそれらを検出できます。

終了コード

コード	意味
0	成功
2	使用エラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → google-photos-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. その他の場合 → 直接使用（--agent を指定して CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

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

2. Claude Code に登録します。

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

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which google-photos-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを指定して実行します。

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

4. 不明な点がある場合は、サブコマンドのヘルプを確認します：google-photos-pp-cli <command> --help。