$gpc listings

--json--dry-run--locale

Manage store listings, metadata, images, and country availability. Fastlane supply compatible.

usagegpc listings <subcommand> [options]

Commands

Command	Description
listings get	Get store listing(s)
listings update	Update a store listing
listings delete	Delete a store listing for a language
listings pull	Download listings to Fastlane-format directory
listings push	Upload listings from Fastlane-format directory
listings images list	List images for a language and type
listings images upload	Upload an image
listings images delete	Delete an image
listings images sync	Sync local image directory to Google Play
listings availability	Get country availability for a track

listings get

Retrieve store listing details for one language or all languages.

Synopsis

gpc listings get [options]

Options

Flag	Short	Type	Default	Description
--lang		string		Language code (BCP 47). Omit to get all languages.

Example

Get the default language listing:

gpc listings get --app com.example.myapp

Get a specific language:

gpc listings get --app com.example.myapp --lang ja-JP

{
  "language": "ja-JP",
  "title": "My App",
  "shortDescription": "Short description in Japanese",
  "fullDescription": "Full description in Japanese",
  "video": ""
}

---

listings update

Update a store listing for a specific language.

Synopsis

gpc listings update --lang <language> [options]

Options

Flag	Short	Type	Default	Description
--lang		string	(required)	Language code (BCP 47)
--title		string		App title (max 30 chars)
--short		string		Short description (max 80 chars)
--full		string		Full description (max 4000 chars)
--full-file		string		Read full description from a file
--video		string		YouTube video URL
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Example

Update title and short description:

gpc listings update \
  --app com.example.myapp \
  --lang en-US \
  --title "My App" \
  --short "The best app for productivity"

Update full description from a file:

gpc listings update \
  --app com.example.myapp \
  --lang en-US \
  --full-file ./metadata/en-US/full_description.txt

Preview changes without applying:

gpc listings update \
  --app com.example.myapp \
  --lang en-US \
  --title "New Title" \
  --dry-run

---

listings delete

Delete a store listing for a specific language.

Synopsis

gpc listings delete --lang <language>

Options

Flag	Short	Type	Default	Description
--lang		string	(required)	Language code (BCP 47)
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Example

gpc listings delete --app com.example.myapp --lang fr-FR

---

listings pull

Download all store listings to a local Fastlane-compatible directory structure.

Synopsis

gpc listings pull [options]

Options

Flag	Short	Type	Default	Description
--dir		string	metadata	Output directory path

Example

gpc listings pull --app com.example.myapp --dir ./metadata

Text metadata only. This command downloads titles, short descriptions, full descriptions, and video URLs for every locale. It does NOT pull images — use gpc listings images export for those (they write to a separate directory layout). See the Store Listings & Screenshots guide for the full story and how to sync both.

metadata/
  en-US/
    title.txt
    short_description.txt
    full_description.txt
    video.txt
  ja-JP/
    title.txt
    short_description.txt
    full_description.txt
    video.txt

{
  "directory": "./metadata",
  "languages": ["en-US", "ja-JP"],
  "count": 2
}

---

listings push

Upload store listings from a local Fastlane-compatible directory structure. Text metadata only (titles, descriptions, video URLs). Does NOT upload images — for screenshots and graphics, use gpc listings images sync --dir (one committed edit for the whole image tree). See the Store Listings & Screenshots guide for the full round-trip pattern.

Synopsis

gpc listings push [options]

Options

Flag	Short	Type	Default	Description
--dir		string	metadata	Source directory path
--dry-run		boolean	false	Preview changes without applying
--force		flag		Push even if fields exceed character limits
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Example

Push all metadata:

gpc listings push --app com.example.myapp --dir ./metadata

Preview what would change:

gpc listings push --app com.example.myapp --dir ./metadata --dry-run

{
  "dryRun": true,
  "changes": [
    { "language": "en-US", "field": "title", "action": "update" },
    { "language": "ja-JP", "field": "fullDescription", "action": "update" }
  ]
}

---

listings images list

List all images for a specific language and image type.

Synopsis

gpc listings images list --lang <language> --type <type>

Options

Flag	Short	Type	Default	Description
--lang		string	(required)	Language code (BCP 47)
--type		string	(required)	Image type (see below)

Valid image types: phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, tvScreenshots, wearScreenshots, icon, featureGraphic, tvBanner.

Example

gpc listings images list \
  --app com.example.myapp \
  --lang en-US \
  --type phoneScreenshots

{
  "images": [
    { "id": "1", "sha256": "abc123", "url": "https://lh3.googleusercontent.com/..." },
    { "id": "2", "sha256": "def456", "url": "https://lh3.googleusercontent.com/..." }
  ]
}

---

listings images upload

Upload an image file to a specific language and image type slot.

Synopsis

gpc listings images upload <file> --lang <language> --type <type>

Options

Flag	Short	Type	Default	Description
--lang		string	(required)	Language code (BCP 47)
--type		string	(required)	Image type
--ai-generated		flag		Attest that the image was generated by AI
--dry-run		boolean	false	Preview the upload without applying changes
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Example

gpc listings images upload ./screenshots/home.png \
  --app com.example.myapp \
  --lang en-US \
  --type phoneScreenshots

Google Play asks developers to declare AI-generated store imagery. Pass --ai-generated to record that attestation with the upload; leave it off and the image is uploaded without a declaration.

gpc listings images upload ./screenshots/hero.png \
  --app com.example.myapp \
  --lang en-US \
  --type phoneScreenshots \
  --ai-generated

---

listings images delete

Delete a specific image by ID.

Synopsis

gpc listings images delete --lang <language> --type <type> --id <imageId>

Options

Flag	Short	Type	Default	Description
--lang		string	(required)	Language code (BCP 47)
--type		string	(required)	Image type
--id		string	(required)	Image ID to delete
--dry-run		boolean	false	Preview the delete without applying changes
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Example

gpc listings images delete \
  --app com.example.myapp \
  --lang en-US \
  --type phoneScreenshots \
  --id 1

---

listings images export

Download all images (or a filtered subset) from Google Play to a local directory. Useful for bootstrapping a Fastlane metadata directory from your current store state, or backing up screenshots before a risky re-upload.

Synopsis

gpc listings images export [options]

Options

Flag	Short	Type	Default	Description
--dir		string	images	Output directory path
--lang		string		Language code (BCP 47). If omitted, exports all languages.
--type		string		Image type. If omitted, exports all types.

Example — export everything

gpc listings images export \
  --app com.example.myapp \
  --dir ./images

Creates the following structure (one directory per language, each containing one directory per image type, files numbered sequentially):

images/
  en-US/
    icon/
      1.png
    featureGraphic/
      1.png
    phoneScreenshots/
      1.png
      2.png
      3.png
    sevenInchScreenshots/
      1.png
    tenInchScreenshots/
      1.png
  ja-JP/
    ...

Layout note

This is not the same layout as Fastlane's metadata/android/<lang>/images/<type>/ format. GPC's image export uses <dir>/<lang>/<type>/ without the nested images/ subdirectory. The exported files are suitable for re-upload via gpc listings images sync --dir (which walks the whole tree in one edit), but cannot be round-tripped via gpc listings push (which only handles text metadata). See the Store Listings & Screenshots guide for the round-trip pattern and limitations.

Example — export only phone screenshots for one locale

gpc listings images export \
  --app com.example.myapp \
  --dir ./screens \
  --lang en-US \
  --type phoneScreenshots

---

listings images sync

Sync a local image directory to Google Play. Compares local file SHA-256 against Google's Image.sha256 field and uploads only changed files. Operates inside a single edit for efficiency. Deletes are applied before uploads to avoid per-type image count limits.

With --delete, sync also guarantees display order. The Play Developer API has no reorder endpoint and images keep their upload order, so a partial update that reconciled by hash alone would leave screenshots out of order (an unchanged image keeps its slot while a changed one is appended last). When a language/type's images differ from local in content or order, --delete clears that combo in a single request and re-uploads every local file in sorted filename order (1.png, 2.png, ...); a combo already in order is skipped. Because this happens inside the one edit, the intermediate state is never committed on its own, so the default language never trips the "too few screenshots" validation.

Synopsis

gpc listings images sync [options]

Options

Flag	Short	Type	Default	Description
--dir		string	images	Local image directory path
--lang		string		Filter to a single language code (BCP 47). If omitted, syncs all languages found in --dir.
--type		string		Filter to a single image type. If omitted, syncs all types. See valid types below.
--delete		flag		Remove remote images missing locally and guarantee display order (full-replaces a language/type when it differs in content or order). Opt-in; no deletions without this flag.
--ai-generated		flag		Attest that every image uploaded by this run was generated by AI.
--dry-run		boolean	false	Preview uploads and deletes without executing any changes.
--changes-not-sent-for-review		flag		Commit without sending for review
--error-if-in-review		flag		Fail if changes are already in review

Valid image types: icon, featureGraphic, tvBanner, phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, tvScreenshots, wearScreenshots.

The command expects the same <dir>/<lang>/<type>/ layout produced by gpc listings images export.

--delete only manages the types you keep locally

A type directory that is absent is left untouched, so syncing only your screenshots never removes a remote icon or feature graphic. A type directory that is present but empty is an explicit "clear this type" and its remote images are deleted. Scope a run with --type when you want to touch a single image type. Name files so they sort in display order (1.png, 2.png, ...); zero-pad (01.png) if a type ever approaches Google's per-type cap.

Example — sync all images

gpc listings images sync \
  --app com.example.myapp \
  --dir ./images

Synced 18 images: 14 skipped (unchanged), uploaded 4

Example — sync one locale with deletions

gpc listings images sync \
  --app com.example.myapp \
  --dir ./images \
  --lang en-US \
  --delete

Example — preview changes without applying

gpc listings images sync \
  --app com.example.myapp \
  --dir ./images \
  --dry-run

{
  "dryRun": true,
  "changes": [
    { "lang": "en-US", "type": "phoneScreenshots", "file": "1.png", "action": "upload" },
    { "lang": "en-US", "type": "phoneScreenshots", "file": "5.png", "action": "upload" },
    { "lang": "ja-JP", "type": "featureGraphic", "file": "1.png", "action": "skip" }
  ]
}

---

Image requirements

Google Play validates every image at upload time. GPC does not run pre-upload validation (yet), so malformed images surface as opaque API errors. Meet these specs locally before calling gpc listings images upload or gpc listings push:

Type	Format	Dimensions	Aspect ratio	Max size
icon	32-bit PNG (with alpha)	exactly 512 × 512	1:1	1 MB
featureGraphic	PNG or JPEG	exactly 1024 × 500	2048:1000	1 MB
phoneScreenshots	PNG or JPEG	320–3840 px per side, min dimension 320	16:9 or 9:16	8 MB
sevenInchScreenshots	PNG or JPEG	same as phone	any	8 MB
tenInchScreenshots	PNG or JPEG	same as phone	any	8 MB
tvScreenshots	PNG or JPEG	1280×720 or 1920×1080 recommended	16:9 landscape	8 MB
wearScreenshots	PNG or JPEG	384×384 recommended	1:1 square	8 MB
tvBanner	PNG or JPEG	1280×720	16:9	8 MB

Per-listing limits:

• Up to 8 phone screenshots per locale (minimum 2 for new apps)
• Up to 8 seven-inch tablet screenshots per locale
• Up to 8 ten-inch tablet screenshots per locale
• Up to 8 TV screenshots per locale
• Up to 8 Wear OS screenshots per locale

A quick local check before upload:

# macOS / Linux
identify ./screens/home.png
# Verify: width, height, format, and file size

Authoritative spec: Google Play Console image requirements.

Bulk workflow: text AND images

listings pull / listings push handle text metadata only. For images, use listings images export to download and listings images sync to upload with SHA-256 deduplication (skips unchanged files, optionally deletes remote-only images with --delete). There is no single "sync everything" command that handles both text and images today. See the Store Listings & Screenshots guide for the full round-trip pattern.

---

listings availability

Get country availability for a specific track.

Synopsis

gpc listings availability [options]

Options

Flag	Short	Type	Default	Description
--track		string	production	Track name

Example

gpc listings availability --app com.example.myapp --track production

{
  "countries": [
    { "countryCode": "US", "available": true },
    { "countryCode": "JP", "available": true },
    { "countryCode": "DE", "available": true }
  ]
}

Related

• publish -- End-to-end release workflow
• releases -- Release management
• Migration from Fastlane -- Fastlane directory compatibility