Gpc Setup

GPC Setup

When to use

Use this skill when the task involves:

• Installing GPC (npm install -g @gpc-cli/cli or standalone binary)
• Running the unified setup wizard (gpc setup, v0.9.68+)
• 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) Unified setup (v0.9.68+, recommended)

The fastest way to get GPC configured from scratch:

gpc setup

gpc setup is a single command that combines authentication, configuration, and verification into one guided flow:

1. Detects existing config (resumes if partial) 2. Prompts for auth method (service account, OAuth, or ADC) 3. Validates credentials 4. Sets default package name 5. Writes .gpcrc.json 6. Runs gpc doctor to verify everything works

For CI/CD or headless environments, use the non-interactive variant:

gpc setup --auto

--auto reads from environment variables (GPC_SERVICE_ACCOUNT, GPC_APP) and skips all prompts. Exits 0 on success, non-zero with actionable errors on failure. Ideal for Docker images, GitHub Actions setup steps, and onboarding scripts.

If you need more control, use the individual commands below.

1a) 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

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:

Config resolution precedence (v0.9.81+)

When the same setting is supplied through multiple sources, GPC resolves in this order (highest priority first):

Prior to v0.9.81, an active profile silently took precedence over GPC_SERVICE_ACCOUNT and GPC_APP env vars. That bug is fixed. Env vars and CLI flags now reliably override whatever profile is active, which is important for CI environments where secrets are injected at run time.

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
• Config and cache directory permissions
• Service account file exists and permissions (not group/world-readable)
• Profile env var points to a known profile
• Proxy URL valid (if HTTPS_PROXY set)
• CA cert file exists (if GPC_CA_CERT set)
• DNS resolution (androidpublisher + playdeveloperreporting)
• Authentication valid
• API connectivity (access token obtained)
• Developer verification deadline (September 30, 2026)
• Stale cache warning (>7 days)
• Shell completion detection (bash/zsh)
• API quota proximity: warns if daily or per-minute usage exceeds 80% (v0.9.71+)
• Plugin health: verifies each configured plugin loads without errors (v0.9.71+)
• Signing key verification: --verify fetches Play signing cert and compares against local keystore (v0.9.75+)

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.

Signing key verification (v0.9.75+)

# Show Play signing certificate fingerprint
gpc doctor --verify

# Compare against a local keystore
gpc doctor --verify --keystore release.keystore --store-pass $STORE_PASSWORD

Environment variable alternatives: GPC_KEYSTORE_PATH and GPC_STORE_PASSWORD.

5a) Check developer verification

gpc verify              # Status, deadlines, resources
gpc verify --open       # Open verification page in browser

Google's Android developer verification enforcement begins September 2026 for BR, ID, SG, TH. gpc doctor includes this as check #20.

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

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

gpc docs list                     # List all 108 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.

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

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

GPC Configuration

Config File Locations

GPC searches for configuration in this order:

1. --config flag (explicit path) 2. .gpcrc.json in current directory (project-level) 3. .gpcrc.json in parent directories (walks up) 4. ~/.config/gpc/config.json (user-level, XDG-compliant)

Config File Schema

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

Environment Variable Precedence

Environment variables override config file values:

CLI flags > Environment variables > Config file > Defaults

Interactive Config Init

gpc config init

Prompts for: 1. Default package name 2. Output format preference 3. Service account path (optional)

Creates .gpcrc.json in the current directory.

Viewing Resolved Config

gpc config show    # Display all resolved settings
gpc config path    # Show config file location

Per-Command Overrides

Any config value can be overridden per-command:

gpc apps list --app com.other.app --output json --profile staging

OAuth Device Flow

Using OAuth for local development and interactive authentication with GPC.

When to use OAuth

• Local development — when you don't have a service account key file
• Personal use — managing your own Play Console account
• Quick setup — no Google Cloud Console project required
• Multiple accounts — switching between personal and team accounts

For CI/CD, always use service accounts instead. See references/service-account.md.

OAuth login

# Start OAuth device flow
gpc auth login --oauth

# GPC will display:
# 1. A URL to open in your browser
# 2. A code to enter on that page
# 3. Wait for you to authorize

Flow steps

1. GPC generates a device code and verification URL 2. You open the URL in any browser (can be a different device) 3. Enter the code shown in your terminal 4. Sign in with your Google account 5. Grant GPC access to Google Play Developer API 6. GPC receives the token and stores it securely

Token storage

OAuth tokens are stored in your OS keychain:

Fallback: ~/.config/gpc/credentials.json (file-based, less secure).

Token refresh

• Access tokens expire after 1 hour
• GPC automatically refreshes using the stored refresh token
• If the refresh token is revoked, re-run gpc auth login --oauth

OAuth with profiles

Use named profiles for multiple accounts:

# Login with a profile name
gpc auth login --oauth --profile personal
gpc auth login --oauth --profile work

# Switch between profiles
gpc auth switch personal
gpc auth switch work

# Use a profile for a single command
gpc releases list --profile work

Revoking access

# Revoke OAuth token
gpc auth logout

# Revoke a specific profile
gpc auth logout --profile personal

You can also revoke from Google Account settings: Security > Third-party apps > GPC.

Troubleshooting

OAuth vs Service Account

Service Account Setup

Creating a Service Account

1. Go to Google Cloud Console 2. Select or create a project 3. Navigate to IAM & Admin → Service Accounts 4. Click Create Service Account 5. Name it (e.g., gpc-release-manager) 6. No roles needed at this step — permissions are granted in Play Console 7. Click Done 8. Click the service account → Keys tab → Add Key → Create New Key → JSON 9. Download the key file — this is your key.json

Granting Play Console Access

1. Go to Google Play Console 2. Navigate to Settings → API access 3. Link your Google Cloud project (if not already linked) 4. Find your service account in the list 5. Click Grant access 6. Set permissions:

• App access: Select specific apps or all apps
• Account permissions: Set based on what GPC will do
• App permissions: Release management, store listing, etc.

Recommended Permissions by Use Case

Security Best Practices

• Never commit key files to git. Add *.json key files to .gitignore.
• Use environment variables in CI. Store the JSON content as a secret, not a file.
• Rotate keys periodically. Delete old keys after creating new ones.
• Principle of least privilege. Grant only the permissions GPC needs.
• Use separate service accounts for development vs production.

Environment Variable Formats

# File path
export GPC_SERVICE_ACCOUNT=/path/to/key.json

# Inline JSON (useful in CI where you can't write files)
export GPC_SERVICE_ACCOUNT='{"type":"service_account","project_id":"my-project",...}'

# Base64 encoded (alternative for CI)
export GPC_SERVICE_ACCOUNT=$(echo '{"type":"service_account",...}' | base64)

Troubleshooting

GPC Setup Troubleshooting

Authentication Issues

AUTH_EXPIRED — Token expired

Error: Access token has expired
Suggestion: Run 'gpc auth login' to re-authenticate

Fix: Re-authenticate:

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

AUTH_INVALID — Invalid credentials

Error: Invalid authentication credentials

Possible causes: 1. Service account key file is malformed or truncated 2. Key has been deleted in Google Cloud Console 3. Service account not linked in Play Console

Fix:

# Verify key file is valid JSON
cat key.json | jq .type  # Should output "service_account"

# Re-download key from Google Cloud Console
# Re-grant access in Play Console → Settings → API access

Permission denied — Missing Play Console access

Fix: 1. Go to Play Console → Settings → API access 2. Find the service account 3. Click Manage → Grant required permissions 4. Wait up to 48 hours for propagation (usually instant)

Network Issues

NETWORK_ERROR — Cannot reach API

Behind a proxy:

export HTTPS_PROXY=http://proxy.company.com:8080

Custom CA certificate:

export GPC_CA_CERT=/path/to/corporate-ca.crt

Increase timeout:

export GPC_TIMEOUT=60000  # 60 seconds

Rate limiting

# Increase delays between retries
export GPC_BASE_DELAY=2000
export GPC_MAX_DELAY=120000
export GPC_MAX_RETRIES=5

Configuration Issues

Config file not found

# Check where GPC looks for config
gpc config path

# Create one interactively
gpc config init

# Or set via env var
export GPC_APP=com.example.app

Wrong app being used

# Check resolved config
gpc config show

# Override per-command
gpc apps list --app com.correct.app

gpc doctor Failures