GPC Setup

When to use

Use this skill when the task involves:

• Installing GPC (npm install -g @gpc-cli/cli or standalone binary)
• Authenticating with Google Play Developer API (service account, OAuth, ADC)
• Managing auth profiles (gpc auth profiles, gpc auth switch)
• Configuring GPC (.gpcrc.json, env vars, gpc config init)
• Diagnosing setup issues (gpc doctor)
• Setting up GPC in a new project or CI environment

Inputs required

• Whether this is local development or CI/CD setup
• Auth method: service account JSON, OAuth, or Application Default Credentials
• Package name of the Android app (e.g., com.example.app)
• If CI: which CI platform (GitHub Actions, GitLab, etc.)

Procedure

0) Install GPC

Via npm (recommended):

npm install -g @gpc-cli/cli

Via npx (zero-install trial):

npx @gpc-cli/cli --version

Via standalone binary (no Node.js needed):

curl -fsSL https://raw.githubusercontent.com/yasserstudio/gpc/main/scripts/install.sh | bash

1) Authenticate

Three auth strategies, in order of recommendation:

A) Service Account (recommended for CI/CD)

New to Google Cloud or setting up for the first time? Use the interactive GCP setup guide:

gpc auth setup-gcp

This fully interactive wizard walks through every step required to connect GPC to the Play Developer API:

1. Enabling the Google Play Developer API in your GCP project
2. Creating a service account in the GCP Console
3. Granting the service account access in Google Play Console (Settings → API access)
4. Downloading the JSON key file to your machine
5. Running gpc auth login with the downloaded key

No flags needed -- just run the command and follow the prompts. Ideal for first-time setup on any machine.

Already have a key file? Skip the wizard with --key:

gpc auth setup-gcp --key /path/to/service-account.json

This validates the JSON, authenticates, and saves to config in one step.

Once the wizard completes, or if you already have a key file:

gpc auth login --service-account path/to/key.json

Or via environment variable (preferred in CI):

export GPC_SERVICE_ACCOUNT=path/to/key.json
# or inline JSON:
export GPC_SERVICE_ACCOUNT='{"type":"service_account","project_id":"..."}'

Read:

• references/service-account.md

B) OAuth (for local development)

Interactive OAuth device flow — no key file needed:

gpc auth login

Tokens are cached in the OS keychain (macOS Keychain, Linux libsecret) or file fallback.

C) Application Default Credentials (for GCP environments)

Works automatically in Cloud Build, Cloud Run, GKE — no configuration needed:

# ADC is auto-detected when no other auth is configured
gpc apps list

1b) One-command guided setup (v0.9.68+)

For new users or new machines, gpc setup is the fastest path to a working configuration:

gpc setup

This interactive wizard covers the full onboarding flow in a single command:

1. Authenticates (service account, OAuth, or ADC — prompted interactively)
2. Picks a default app from your Play Console (lists available apps)
3. Writes .gpcrc.json with the chosen app, profile, and output format
4. Installs shell completion for your current shell (bash/zsh/fish)
5. Runs gpc doctor automatically to verify the result

CI/headless mode — skip all prompts with --auto:

gpc setup --auto

In --auto mode, gpc setup uses GPC_SERVICE_ACCOUNT + GPC_APP env vars and skips interactive steps. Ideal for bootstrapping a fresh CI runner from a single pipeline step.

2) Configure defaults

Interactive setup wizard:

gpc config init

Guided wizard that:

1. Selects auth method (service-account / adc / skip)
2. For service account: validates the file exists (retries if path is wrong)
3. Prompts for default package name (warns if format is invalid)
4. Writes .gpcrc.json and prints a post-init summary
5. Ends with: Run \gpc doctor` to verify your setup.`

Manual config file (.gpcrc.json in project root or ~/.config/gpc/config.json):

{
  "app": "com.example.myapp",
  "output": "table",
  "profile": "default"
}

Environment variables:

Variable	Description
GPC_APP	Default package name
GPC_OUTPUT	Default output format (table/json/yaml/markdown/csv/tsv)
GPC_PROFILE	Auth profile name
GPC_NO_COLOR	Disable color output
GPC_NO_INTERACTIVE	Disable interactive prompts
GPC_SKIP_KEYCHAIN	Skip OS keychain, use file storage

Read:

• references/configuration.md

3) Manage auth profiles

For managing multiple Google Play accounts:

gpc auth profiles              # List profiles
gpc auth switch production     # Switch active profile
gpc auth whoami                # Show current identity
gpc auth status                # Show auth state details

Use --profile flag to override per-command:

gpc apps list --profile staging

4) Verify setup

gpc doctor

Checks (22 total):

• Node.js version (≥ 20)
• Configuration loaded
• Default app set and valid Android package name format
• Authentication valid
• API connectivity (googleapis.com + playdeveloperreporting.googleapis.com)
• Proxy configuration (if set)
• GPC version (suggests update if outdated)
• HTTPS probe
• App access verification
• Service account key age
• Unknown config keys
• Token cache health
• Disk space
• CI detection
• Developer verification status
• API quota proximity (warns at >80% daily or per-minute usage, v0.9.71+)
• Plugin health (discovers, loads, reports each configured plugin, v0.9.71+)

Use gpc doctor --fix to auto-remediate fixable issues (version, auth, config keys).

JSON output is supported: gpc doctor --json or gpc doctor --output json.

5a) Check developer verification (v0.9.66+)

gpc verify              # Account-aware status with app info, signing enrollment, days until enforcement
gpc verify --open       # Open verification page in browser
gpc verify checklist    # Interactive 7-step readiness walkthrough (markdown report for CI)

Google's Android developer verification enforcement begins September 30, 2026 for BR, ID, SG, TH. gpc doctor includes this as a verification-deadline check.

Signing key verification

gpc doctor --verify                                       # API-side signing cert check
gpc doctor --verify --keystore release.jks --store-pass x # Compare local keystore against API cert
gpc preflight signing                                     # Cert consistency across two most recent bundles

gpc doctor --verify pulls your app's signing certificate from Google Play via generatedApks and optionally compares it against a local keystore (requires keytool from JDK). gpc preflight signing compares certs across your two most recent bundle versions and exits 6 on mismatch (CI-friendly).

5b) Browse documentation from CLI (v0.9.64+ embedded docs)

Since v0.9.64, GPC ships 99 documentation pages embedded in the binary. No network required.

gpc docs list                     # List all 99 embedded topics
gpc docs show authentication      # Render a guide in the terminal (ANSI-formatted)
gpc docs show auth                # Fuzzy slug matching
gpc docs search "staged rollout"  # Full-text search across all pages
gpc docs init                     # Write GPC.md quick-reference into repo (for AI agents)
gpc docs web                      # Open docs site in browser (previous default behavior)

gpc docs show pipes through $PAGER for long pages. gpc docs list --json and gpc docs search --json for machine-readable output.

5) Network configuration (if needed)

For corporate proxies or custom CA certificates:

export HTTPS_PROXY=http://proxy.example.com:8080
export GPC_CA_CERT=/path/to/ca-bundle.crt

Retry configuration:

export GPC_MAX_RETRIES=3
export GPC_TIMEOUT=30000
export GPC_BASE_DELAY=1000
export GPC_MAX_DELAY=60000

Shell completion (v0.9.58+ walker, v0.9.60+ dynamic values)

GPC ships shell completion for bash, zsh, fish, and PowerShell. The completion tree is introspection-based (v0.9.58+) -- new commands and plugin-registered commands auto-complete without generator edits. Flags declared with .choices() surface their candidate list at TAB time.

# One-time setup (macOS/Linux)
gpc completion bash >> ~/.bash_completion      # or source in ~/.bashrc
gpc completion zsh  >> ~/.zshrc
gpc completion fish > ~/.config/fish/completions/gpc.fish

# Homebrew auto-installs completion files -- no eval step needed
brew install yasserstudio/tap/gpc

Dynamic values (v0.9.60+)

The completion scripts fill in live values for several flags at TAB time, backed by a hidden gpc __complete <ctx> subcommand. No API call -- reads your config and ~/.cache/gpc/status-*.json cache, returns in under 150ms cold.

Flag	Source
--profile	Profile names from ~/.config/gpc/config.json
--app / --apps	Package names from config + status cache
--track	Track names for the current app (from status cache)

If your package/track completions are stale, run any command that touches gpc status (or gpc status directly) to refresh the cache.

Verification

• gpc doctor shows all checks passing
• gpc auth status shows authenticated identity
• gpc apps list returns real app data
• gpc config show displays resolved configuration

Failure modes / debugging

Symptom	Likely Cause	Fix
AUTH_EXPIRED	Access token expired	gpc auth login to re-authenticate
AUTH_INVALID	Wrong service account or missing permissions	Check Google Play Console → Settings → API access
NETWORK_ERROR	Proxy or firewall blocking	Set HTTPS_PROXY and/or GPC_CA_CERT
CONFIG_NOT_FOUND	No config file	Run gpc config init or set GPC_APP env var
Doctor fails on "API connectivity"	Service account not granted Play Console access	Add service account in Play Console API access settings

Read:

• references/troubleshooting.md

Escalation

• For Google Play Console API access setup, refer to: https://developers.google.com/android-publisher/getting_started
• For service account creation, refer to: https://cloud.google.com/iam/docs/service-accounts-create