Quick Start
Five minutes to your first release. This guide covers the most common GPC operations: authenticate, upload, promote, check vitals, and monitor reviews. New to Play Store concepts? See the Glossary.
Try GPC without authentication
Want to see GPC in action before setting up credentials? The preflight scanner works entirely offline:
gpc preflight app.aabNo service account needed. Scans your AAB against 9 Google Play policies.
Prerequisites
- GPC installed (Installation)
- A Google Play Developer account
- A service account JSON key file with Play Console access (Authentication has full setup steps, or run
gpc auth setup-gcpfor a guided wizard)
Time estimate: 5 minutes if you have a service account key. 20 minutes if you need to create one.
One-command setup
For a guided experience that handles auth, config, and verification in one step, run gpc setup. The steps below explain each part individually.
Step 1: Authenticate
Set up authentication with a service account key file:
gpc auth login --service-account /path/to/service-account-key.jsonExpected output:
Authenticated as play-deploy@my-project.iam.gserviceaccount.com
Profile "default" saved2
Verify authentication is working:
gpc auth statusExpected output:
Profile: default
Identity: play-deploy@my-project.iam.gserviceaccount.com
Method: service-account
Token: valid (expires in 58 minutes)
Scopes: https://www.googleapis.com/auth/androidpublisher2
3
4
5
Authentication failed?
Run gpc doctor to diagnose the issue. Common causes:
- File not found — check the path to your key file
- Permission denied (403) — the service account needs access in Play Console → API access
- API not enabled — enable the Google Play Developer API in your GCP Console
Step 2: Set Your Default App
Configure a default app package name so you do not need to pass --app on every command:
gpc config set app com.example.myappExpected output:
Config updated: app = com.example.myappVerify your full configuration:
gpc config showExpected output:
app: com.example.myapp
profile: default
output: table (auto)2
3
Step 3: Upload a Release
Upload an AAB file to the internal testing track:
gpc releases upload app-release.aab --track internalExpected output:
Uploading app-release.aab (24.3 MB)
████████████████████████████████ 100%
Upload complete
Version code: 42
Track: internal
Status: completed2
3
4
5
6
7
To upload and set release notes in one command, use publish:
gpc publish app-release.aab --track internal --notes "Bug fixes and performance improvements"Expected output:
Uploading app-release.aab (24.3 MB)
████████████████████████████████ 100%
Upload complete
Version code: 42
Track: internal
Status: completed
Notes (en-US): Bug fixes and performance improvements
Edit: committed2
3
4
5
6
7
8
9
Step 4: Promote to Beta
Promote the release from internal testing to the beta track:
gpc releases promote --from internal --to betaExpected output:
Promoted version 42
From: internal
To: beta
Status: completed2
3
4
To promote to production with a staged rollout:
gpc releases promote --from beta --to production --rollout 10Expected output:
Promoted version 42
From: beta
To: production
Rollout: 10%
Status: inProgress2
3
4
5
Increase the rollout later:
gpc releases rollout increase --track production --to 50Expected output:
Rollout updated
Track: production
Version: 42
Rollout: 10% -> 50%
Status: inProgress2
3
4
5
Complete the rollout to 100%:
gpc releases rollout complete --track productionExpected output:
Rollout completed
Track: production
Version: 42
Rollout: 100%
Status: completed2
3
4
5
Step 5: Check Vitals
View crash rate and ANR metrics for your app:
gpc vitals overviewExpected output:
Vitals Overview — com.example.myapp
Metric Value Threshold Status
Crash rate (user) 0.82% 2.00% OK
ANR rate (user) 0.15% 0.47% OK
Cold startup (p50) 812ms — —
Warm startup (p50) 340ms — —
Slow frames 4.2% — —
Excessive wakeups 0.1% — —2
3
4
5
6
7
8
9
Check crash clusters for a specific version:
gpc vitals crashes --version 42Expected output:
Crash Clusters — com.example.myapp (version 42)
Cluster Count Rate
NullPointerException at MainActivity:42 127 0.31%
OutOfMemoryError at ImageLoader:88 43 0.10%2
3
4
5
Use vitals as a CI quality gate (exits with code 6 if threshold is breached):
gpc vitals crashes --threshold 2.0If the crash rate is below 2.0%, exit code is 0. If it exceeds 2.0%, exit code is 6.
Step 6: Monitor Reviews
List recent reviews:
gpc reviews listExpected output:
Reviews — com.example.myapp
Stars Date Language Review
★★★★★ 2026-03-08 en-US Great app! Love the new update.
★★☆☆☆ 2026-03-07 en-US Crashes on startup since last update.
★★★★☆ 2026-03-07 ja-JP 使いやすいです。2
3
4
5
6
Filter to low-rated reviews from the last 7 days:
gpc reviews list --stars 1-2 --since 7dExpected output:
Reviews — com.example.myapp (1-2 stars, last 7 days)
Stars Date Language Review
★★☆☆☆ 2026-03-07 en-US Crashes on startup since last update.
★☆☆☆☆ 2026-03-05 de-DE Stürzt immer ab.2
3
4
5
Reply to a review:
gpc reviews reply abc123def456 --text "Thank you for the feedback. We have fixed the crash in version 43."Expected output:
Reply sent to review abc123def456Interactive Mode
When you omit required options on write commands, GPC prompts you interactively. In CI, missing options fail fast with a clear error message — GPC never hangs waiting for input.
# No --track specified — GPC asks which track to use
gpc releases upload app.aab
# ? Select track: (Use arrow keys)
# internal
# > beta
# alpha
# production
# Destructive commands prompt for confirmation
gpc subscriptions delete premium_monthly
# ? Delete subscription "premium_monthly"? This cannot be undone. (y/N)2
3
4
5
6
7
8
9
10
11
To skip all prompts in CI, use the --yes flag or set the environment variable:
gpc releases upload app.aab --track beta --yes
# or
GPC_NO_INTERACTIVE=1 gpc releases upload app.aab --track beta2
3
Dry Run
Ship nothing. Learn everything. Preview what any write command would do against real Play Console data without making any changes:
gpc releases upload app.aab --track beta --dry-run[dry-run] Would upload app.aab (24.3 MB) to track "beta"
[dry-run] Version code: 43
[dry-run] No changes were made2
3
gpc releases promote --from beta --to production --dry-run[dry-run] Would promote version 43
[dry-run] From: beta
[dry-run] To: production
[dry-run] No changes were made2
3
4
The --dry-run flag is available on all write commands (upload, promote, create, update, delete, sync).
Full Workflow in CI
Combine these steps into a CI pipeline:
#!/bin/bash
set -euo pipefail
# Authenticate (service account JSON stored as CI secret)
gpc auth login --service-account "$GPC_SERVICE_ACCOUNT_JSON"
# Set the app
gpc config set app com.example.myapp
# Upload to internal track
gpc publish app-release.aab --track internal --notes "Build $CI_BUILD_NUMBER"
# Check vitals before promoting (exit code 6 = threshold breach)
gpc vitals crashes --threshold 2.0
gpc vitals anr --threshold 0.47
# Promote to production with staged rollout
gpc releases promote --from internal --to production --rollout 10
# Get status in JSON for downstream processing
gpc releases status --output json2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Next Steps
- Authentication — Full guide to all 4 auth methods and Play Console setup
- Configuration — Config files, environment variables, and profiles
- Commands — Complete command reference
- CI/CD Integration — GitHub Actions, GitLab CI, and more
- Migration from Fastlane — Already using Fastlane? Most commands map one-to-one