# Gpc Setup

> Use when setting up GPC (Google Play Console CLI): authentication with service accounts, OAuth, or Application Default Credentials; configuration files (.gpcrc.json, env vars, XDG paths); auth profiles; running gpc doctor; troubleshooting auth errors. Make sure to use this skill whenever the user mentions gpc auth, gpc setup, service account setup, gpc config, gpc doctor, GPC_SERVICE_ACCOUNT, gpc auth login, gpc auth clear-cache, token cache, Google Play API credentials, Play Console authentication, download bulk reports permission, reports bucket access, GPC_REPORTS_BUCKET, or wants to install/configure GPC — even if they don't explicitly say 'setup.' Also trigger when someone is troubleshooting auth failures, token expiration, keychain issues, or proxy/network configuration for GPC.

- Skill: `yasserstudio/gpc-setup` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add yasserstudio/gpc-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yasserstudio/gpc-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: yasserstudio (https://skillmd.com/u/yasserstudio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yasserstudio/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):**
```bash
npm install -g @gpc-cli/cli
```

**Via npx (zero-install trial):**
```bash
npx @gpc-cli/cli --version
```

**Via standalone binary (no Node.js needed):**
```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

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

Or via environment variable (preferred in CI):
```bash
export GPC_SERVICE_ACCOUNT=path/to/key.json
# or inline JSON:
export GPC_SERVICE_ACCOUNT='{"type":"service_account","project_id":"..."}'
```

**Extra grant for bulk reports (v0.9.93+).** The API access grant above does not cover Play's monthly bulk reports, which are delivered as CSV files in a Cloud Storage bucket rather than through the Publisher API. Play gives that bucket to your own user login automatically but never to a service account. If you plan to use `gpc reports`, open Play Console → Users and permissions → the service account → **Account permissions** and enable **"View app information and download bulk reports (read-only)"**, then allow a few minutes for it to propagate. Without it, reports commands fail with `REPORT_ACCESS_DENIED`. Verify with the `reports-bucket` check in `gpc doctor`.

Only the reports commands (and that doctor probe) request the extra `devstorage.read_only` scope, and storage-scoped tokens are cached separately, so tokens minted for every other command carry no storage access.

Read:
- `references/service-account.md`

#### B) OAuth (for local development)

Interactive OAuth device flow — no key file needed:

```bash
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:

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

### 2) Configure defaults

#### Interactive setup wizard:
```bash
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`):
```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 |

#### Config resolution precedence (v0.9.81+)

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

| Priority | Source | Example |
|----------|--------|---------|
| 1 | CLI flags | `--service-account key.json`, `--app com.example.app` |
| 2 | Environment variables | `GPC_SERVICE_ACCOUNT`, `GPC_APP` |
| 3 | Active profile | set via `gpc auth switch <name>` |
| 4 | `.gpcrc.json` | project-level or global config file |
| 5 | Defaults | built-in fallback values |

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:

```bash
gpc auth login --service-account key.json --profile production   # Create a profile (v0.9.95+)
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
gpc auth clear-cache           # Drop cached tokens, keep credentials (v0.9.93+)
```

Re-running `auth login --profile <name>` updates that profile's credentials in place and keeps its other settings (`app`, `developerId`, `reports`), so key rotation is safe. `gpc auth logout --profile <name>` clears only that profile's credentials. Both need GPC v0.9.95+; on older versions the `--profile` flag on login/logout was silently ignored — create profiles through the interactive `gpc auth login` wizard instead.

`gpc auth clear-cache` is the light-touch counterpart to `gpc auth logout`: it deletes cached access tokens so the next command mints a fresh one, without removing the configured credentials. Use it after changing permissions in Play Console (for example the bulk-reports grant) so a cached token from before the change does not mask it.

Use `--profile` flag to override per-command:
```bash
gpc apps list --profile staging
```

### 4) Verify setup

```bash
gpc doctor
```

Checks (23 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+)
- Reports bucket (`reports-bucket`): probes the Play bulk-reports bucket and warns when the service account lacks the "download bulk reports (read-only)" grant or the bucket name is wrong (v0.9.93+)

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+)

```bash
# 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

```bash
gpc verify              # Status, deadlines, resources
gpc verify --open       # Open verification page in browser
gpc verify checklist    # Interactive readiness walkthrough
```

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

`gpc verify checklist` scores 11 readiness items (v0.9.96+): 4 auto-detected from the account and the app (Play Console account active, app reachable via the API, at least one bundle uploaded, Play App Signing enrolled), and 7 that GPC cannot detect. As of v0.9.96 **every one of those 7 is answerable at the prompt**:

- Identity verification completed in Play Console
- The September 30, 2026 enforcement timeline reviewed (Brazil, Indonesia, Singapore, Thailand)
- Auto-registration results reviewed
- Every app on the account registered in Play Console (the July 15, 2026 mandate)
- The **February 2027 memory and DEX optimization quality requirements** reviewed (new in v0.9.96)
- **Zero-Tap Sign-In** implemented via the Android Restore Credentials API, required **April 2027**; games are currently exempt (new in v0.9.96)
- Additional signing keys used outside Play registered

Each item reports `✓` (done), `✗` (action needed), or `?` (not auto-detectable and unanswered). A manual item only becomes `✓` or `✗` once you answer its prompt, so under `--no-interactive`, `--json`, or CI all 7 stay at `?` -- run it interactively when you want a real score.

### 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.

```bash
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:

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

Retry configuration:
```bash
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.

```bash
# 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