Google Photos Library and Picker APIs for app-created media, albums, uploads, and user-selected media.
Learn more at Google Photos.
Quick Start
1. Install
See Install above.
2. Authenticate
Authorize via your browser:
google-photos-pp-cli auth login --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
This opens a browser window to complete the OAuth2 flow. Your tokens are stored locally and refreshed automatically.
For multiple Google accounts, pass an account email and select it later:
google-photos-pp-cli auth login you@example.com --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
google-photos-pp-cli auth list
google-photos-pp-cli auth use you@example.com
google-photos-pp-cli --account you@example.com albums list
3. Verify Setup
google-photos-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
google-photos-pp-cli albums list
Usage
Run google-photos-pp-cli --help for the full command reference and flag list.
Commands
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.google-photos-pp-cli picker wait <session-id> - Poll a Picker session until selected media items are ready.
upload
Upload media bytes and create upload tokens.
google-photos-pp-cli upload file <path> - Upload raw photo or video bytes and print the upload token for media-items batch-create.
auth
Manage OAuth accounts and token storage.
google-photos-pp-cli auth login [account-email] - Authenticate via OAuth2 and store tokens, optionally under an account email.google-photos-pp-cli auth list - List stored OAuth accounts.google-photos-pp-cli auth status - Show authentication status for the selected account.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.google-photos-pp-cli auth logout - Remove the selected account token, or legacy token when no account is selected.
schema
Emit machine-readable command, flag, auth, and safety-policy metadata.
google-photos-pp-cli schema --pretty - Print the same structured contract agents use for discovery.
Google Photos Scope Limits
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.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
google-photos-pp-cli albums list
# JSON for scripting and agents
google-photos-pp-cli albums list --json
# Filter to specific fields
google-photos-pp-cli albums list --json --select id,name,status
# Dry run — show the request without sending
google-photos-pp-cli albums list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
google-photos-pp-cli albums list --agent
# Command guard — permit only selected command families
google-photos-pp-cli --enable-commands albums.list albums list --agent
# Command guard — block specific risky commands
google-photos-pp-cli --disable-commands picker.delete-session picker delete-session SESSION_ID --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Retryable - creates return "already exists" on retry, deletes return "already deleted"
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
- Guarded -
--enable-commands and --disable-commands restrict runtime command execution with dotted command paths
- Introspectable -
schema and agent-context expose commands, flags, auth account selection, and safety policy as JSON
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Safety Profiles
The stock binary allows every command unless runtime guards are provided:
google-photos-pp-cli --enable-commands albums.list,media-items.get albums list --agent
google-photos-pp-cli --disable-commands picker.delete-session picker delete-session SESSION_ID --agent
For agent or MCP deployments that need stronger local guardrails, build a baked profile. Baked profiles are compiled into the binary and cannot be loosened by command-line flags:
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.
Health Check
google-photos-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/google-photos-pp-cli/config.toml
Environment variables:
GOOGLE_PHOTOS_TOKENGOOGLE_PHOTOS_ACCOUNTGOOGLE_PHOTOS_ENABLE_COMMANDSGOOGLE_PHOTOS_DISABLE_COMMANDS
OAuth account selection order:
--account <email>GOOGLE_PHOTOS_ACCOUNTdefault_account from auth use- legacy single-token fields in the config file
Troubleshooting
Authentication errors (exit code 4)
- Run
google-photos-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $GOOGLE_PHOTOS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press