Gpc Metadata Sync

GPC Metadata Sync

When to use

Use this skill when the task involves:

• Viewing or updating store listings (title, description, short description)
• Syncing metadata between local files and Google Play Console
• Managing screenshots and images (upload, delete, list)
• Working with Fastlane-compatible metadata directory structure
• Multi-language listing management
• Pulling listings to local for version control
• Pushing local listings to Play Console

Inputs required

• Package name (or configured default via GPC_APP)
• Language code(s) (e.g., en-US, ja-JP)
• For push/pull: local directory path for metadata files
• For images: image type and file paths

Procedure

0) View current listings

# Default language listing
gpc listings get

# Specific language
gpc listings get --lang ja-JP

# All languages at once
gpc listings get --all-languages

# JSON output for scripting
gpc listings get --output json

1) Update listings inline

gpc listings update --lang en-US \
  --title "My App" \
  --short-desc "A great app for great things" \
  --full-desc "Full description here..."

Or from a metadata directory:

gpc listings update --lang en-US --file metadata/en-US/

1a) Validate listings locally (lint)

Local validation with no API call — checks character limits before pushing:

gpc listings lint

# Point at a specific metadata directory
gpc listings lint --dir metadata/
gpc listings lint --dir fastlane/metadata/android/

Output table:

Field             Chars  Limit   %    Status
────────────────────────────────────────────
title              28     30    93%    ✓
shortDescription   76     80    95%    ✓
fullDescription   3820   4000   96%    ✓
video URL          0      256    0%    ✓

Character limits enforced: title = 30, shortDescription = 80, fullDescription = 4000, video URL = 256.

Returns exit code 1 if any field exceeds its limit. Use as a pre-commit or pre-push gate.

1b) Validate live listings (analyze)

Fetches the live listings from Play Store and runs the same character-limit check:

gpc listings analyze

# Compare against an expected set of locales
gpc listings analyze --expected en-US,ja-JP,de-DE

# JSON output
gpc listings analyze --json

Same output table as lint but reflects what is currently live on the Play Store. The --expected flag will flag any locales present in your list but missing from Play Console (or vice versa).

2) Pull/Push workflow (bidirectional sync)

This is the recommended workflow for version-controlling your listings.

Pull (download from Play Console to local):

gpc listings pull --dir metadata/

Creates a directory structure:

metadata/
├── en-US/
│   ├── title.txt
│   ├── short_description.txt
│   ├── full_description.txt
│   └── changelogs/
│       └── 142.txt
├── ja-JP/
│   ├── title.txt
│   ├── short_description.txt
│   └── full_description.txt
└── ...

Push (upload local files to Play Console):

gpc listings push --dir metadata/

# Prevent changes from being auto-submitted for review
gpc listings push --dir metadata/ --changes-not-sent-for-review

# Fail if the app is currently in review or rejected
gpc listings push --dir metadata/ --error-if-in-review

# Preview changes without applying
gpc listings push --dir metadata/ --dry-run

# Bypass the preflight lint gate (not recommended)
gpc listings push --dir metadata/ --force

Preflight lint gate: gpc listings push automatically runs gpc listings lint before uploading. If any field exceeds its character limit the push is aborted with exit code 1. Pass --force to skip the gate and push anyway.

Read:

• references/directory-structure.md

3) Fastlane compatibility

GPC reads and writes the Fastlane metadata directory format. If you're migrating from Fastlane:

# Your existing Fastlane metadata/ directory works as-is
gpc listings push --dir fastlane/metadata/android/

# Pull into Fastlane-compatible structure
gpc listings pull --dir fastlane/metadata/android/

Read:

• references/fastlane-migration.md

4) Image management

List existing images:

gpc listings images list --lang en-US --type phoneScreenshots

Image types: phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, tvScreenshots, wearScreenshots, icon, featureGraphic, tvBanner, promoGraphic.

Upload images:

# Single image
gpc listings images upload --lang en-US --type phoneScreenshots screenshot.png

# Multiple images (glob)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png

# Preview what would be uploaded without making API calls (v0.9.74+)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run

Delete images:

gpc listings images delete --lang en-US --type phoneScreenshots --id <image-id>

# Preview what would be deleted without making API calls (v0.9.74+)
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run

New in v0.9.74: Both gpc listings images upload and gpc listings images delete respect --dry-run. In dry-run mode, the commands print what would happen (files that would be uploaded, image IDs that would be deleted) without calling the Play API.

Sync images from a local directory (v0.9.69+)

gpc listings images sync uses SHA-256 content hashing to deduplicate images — it only uploads files that are not already on Play Store, and optionally deletes remote images that have no local counterpart.

# Sync all phone screenshots for en-US from a local directory
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/

# Sync all image types for a language
gpc listings images sync --lang en-US --dir ./screenshots/en-US/

# Delete remote images that no longer exist locally
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/ --delete

# Preview what would change without touching the API
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/ --dry-run

Key behaviors:

• SHA-256 hash of each local file is compared against the remote image hash. Already-matching images are skipped (no re-upload).
• --delete removes remote images that have no matching local file. Without this flag, extra remote images are left in place.
• --dry-run prints a diff table (add / skip / delete) without making any API calls.
• Supports the same image types as gpc listings images upload: phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, tvScreenshots, wearScreenshots, icon, featureGraphic, tvBanner, promoGraphic.

5) Multi-language workflow

For apps with many languages:

# Pull all languages
gpc listings pull --dir metadata/

# Edit locally (use your preferred text editor or translation tools)

# Push all languages back
gpc listings push --dir metadata/ --dry-run  # Preview first
gpc listings push --dir metadata/ --changes-not-sent-for-review  # Apply without auto-submitting for review

Tip: For generating per-locale "What's new" release notes text (not the full listing fields), see gpc changelog generate --target play-store (v0.9.62+) — it takes your git log and emits per-locale output with the 500-char Play Store budget enforced. Add --ai (v0.9.63+) to translate non-source locales via your own LLM key (auto-detects AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY).

6) Preview with dry-run

All write operations support --dry-run:

gpc listings update --lang en-US --title "New Title" --dry-run
gpc listings push --dir metadata/ --dry-run
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/ --dry-run

In dry-run mode no API calls are made. The output describes what would change: files that would be uploaded, image IDs that would be deleted, and fields that would be updated.

Verification

• gpc listings get --lang <lang> shows updated content
• gpc listings get --all-languages confirms all languages are correct
• gpc listings images list --lang <lang> --type <type> shows uploaded images
• Play Console UI reflects the changes (may take a few minutes)

Security notes (v0.9.74+)

Symlink traversal protection in --notes-dir

When --notes-dir is used to load release notes (e.g. gpc releases upload --notes-dir changelogs/), GPC now calls lstat() on every entry and rejects symbolic links before reading file contents. This prevents directory traversal attacks where a crafted symlink inside the notes directory points to sensitive files outside the tree (e.g. /etc/passwd, SSH keys).

If a symlink is encountered, the command exits with a descriptive error identifying the offending path. Use real files in your notes directories.

CSV formula injection prevention in review exports

gpc reviews export and other commands that produce CSV output now prefix cells that begin with =, +, -, @, tab (\t), or carriage return (\r) with a single quote ('). This prevents spreadsheet applications (Excel, Google Sheets) from interpreting user-supplied content (review text, app titles) as formulas when the CSV is opened.

If you process the CSV programmatically, strip the leading ' from string values where needed.

Failure modes / debugging

Related skills

• gpc-setup: Authentication and configuration
• gpc-release-flow: Upload and release management
• gpc-ci-integration: Automated metadata sync in CI/CD

Metadata Directory Structure

Standard Layout

When you run gpc listings pull --dir metadata/, GPC creates this structure:

metadata/
├── en-US/
│   ├── title.txt                    # App title (max 50 chars)
│   ├── short_description.txt        # Short description (max 80 chars)
│   ├── full_description.txt         # Full description (max 4000 chars)
│   └── changelogs/
│       ├── 142.txt                  # Release notes for version code 142
│       └── default.txt              # Default release notes
├── ja-JP/
│   ├── title.txt
│   ├── short_description.txt
│   └── full_description.txt
├── fr-FR/
│   ├── title.txt
│   ├── short_description.txt
│   └── full_description.txt
└── ...

File Encoding

• All text files must be UTF-8 encoded
• No BOM (Byte Order Mark)
• Newlines: LF preferred, CRLF accepted

Character Limits

Language Codes

Use BCP 47 language tags as directory names. Common codes:

Push Behavior

When running gpc listings push --dir metadata/:

1. GPC reads all language directories 2. For each language, reads title, short_description, full_description 3. Compares with current Play Console content 4. Only updates languages/fields that have changed 5. Uses a single edit (atomic commit)

Use --dry-run to preview changes:

gpc listings push --dir metadata/ --dry-run

Use --changes-not-sent-for-review to prevent the edit from being auto-submitted for review:

gpc listings push --dir metadata/ --changes-not-sent-for-review

Use --error-if-in-review to abort if the app is currently in review or rejected:

gpc listings push --dir metadata/ --error-if-in-review

Migrating from Fastlane Supply

Compatibility

GPC reads and writes the same metadata directory structure that Fastlane supply uses. Migration is straightforward.

Fastlane Directory Layout

Fastlane stores Android metadata at:

fastlane/metadata/android/
├── en-US/
│   ├── title.txt
│   ├── short_description.txt
│   ├── full_description.txt
│   ├── changelogs/
│   │   └── 142.txt
│   └── images/
│       ├── phoneScreenshots/
│       │   ├── 1.png
│       │   └── 2.png
│       ├── icon.png
│       └── featureGraphic.png
├── ja-JP/
│   └── ...
└── ...

Using GPC with Existing Fastlane Metadata

Point GPC directly at your Fastlane metadata directory:

# Push existing Fastlane metadata to Play Console
gpc listings push --dir fastlane/metadata/android/

# Pull latest from Play Console into Fastlane directory
gpc listings pull --dir fastlane/metadata/android/

No conversion needed — the format is identical.

Command Mapping: Fastlane → GPC

Key Differences

Migration Checklist

1. Install GPC: npm install -g @gpc-cli/cli 2. Set up auth: gpc auth login --service-account path/to/key.json (same key file works) 3. Configure app: gpc config set app com.example.app 4. Test with existing metadata: gpc listings push --dir fastlane/metadata/android/ --dry-run 5. Update CI: Replace fastlane supply with gpc commands 6. Remove Fastlane (optional): Delete Gemfile, Fastfile, Appfile if no longer needed

Keeping Both During Migration

You can run both tools during transition. They share:

• Service account key files (same JSON format)
• Metadata directory structure (compatible)

They don't conflict because each creates its own API edit.

Google Play Image Requirements

Image specifications for each type supported by gpc listings images upload.

Image types

Screenshot aspect ratio

• Minimum: 1:2 (portrait) or 2:1 (landscape)
• Maximum: 2:1 (portrait) or 1:2 (landscape)
• Screenshots must not have alpha/transparency

File size limits

• Maximum file size per image: 15 MB
• Recommended: optimize PNGs under 5 MB for faster uploads

Commands

# List existing images
gpc listings images list --lang en-US --type phoneScreenshots

# Upload a single image
gpc listings images upload --lang en-US --type phoneScreenshots screenshot1.png

# Upload multiple images
gpc listings images upload --lang en-US --type phoneScreenshots \
  screenshot1.png screenshot2.png screenshot3.png

# Preview upload without making API calls (v0.9.74+)
gpc listings images upload --lang en-US --type phoneScreenshots screenshot1.png --dry-run

# Delete all images of a type
gpc listings images delete --lang en-US --type phoneScreenshots

# Delete a specific image by ID
gpc listings images delete --lang en-US --type phoneScreenshots --id <image-id>

# Preview deletion without making API calls (v0.9.74+)
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run

Best practices

• Upload phone screenshots first — they're the most visible in the Play Store
• Use consistent dimensions across all screenshots in a set
• Feature graphic is required for apps featured by Google
• TV banner is required for Android TV apps
• Optimize file sizes — large files slow down CI uploads