gpc-metadata-sync（GPC 元数据同步）

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

Delete images:

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

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

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)

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