Skip to content

SKILL.md

Latest commit

 

History

History
189 lines (136 loc) · 5.85 KB

SKILL.md

File metadata and controls

189 lines (136 loc) · 5.85 KB
Raw
name gpd-auth
description Authenticate and manage gpd (Google Play Developer CLI) credentials — service accounts, named profiles, auth doctor/check/status, list/switch/delete/logout. Use when setting up CI keys, diagnosing invalid credentials, switching teams/apps, or verifying package access before publish/reviews/vitals calls.

gpd-auth

Service-account and multi-profile authentication for gpd.

When to use

  • First-time setup or CI credential wiring
  • “Permission denied” / auth failures before API calls
  • Multiple service accounts (teams, apps, environments)
  • Verifying the active profile can reach a package
  • Clearing or deleting stored profiles

Do not invent OAuth browser flows for automation. Prefer service accounts.

Safe defaults

Practice Guidance
Output Prefer --output json (default in pipes/CI). Use --pretty only for humans.
Package Always pass --package <appId> for auth check and for doctor network probes.
CI storage Use --store-tokens never (or env without secure storage) so keys are not written to keychain.
Key material Prefer --key-path / GOOGLE_APPLICATION_CREDENTIALS / GPD_SERVICE_ACCOUNT_KEY over interactive login.
Destructive Prefer auth logout --name … before auth delete; use --force only when deleting the active profile.
Source of truth Run gpd auth <cmd> --help if unsure; do not invent flags.

Global flags (all commands)

-p, --package=STRING
    --output="json"          # json|table|markdown|csv|excel
    --pretty
    --timeout=30s
    --store-tokens="auto"    # auto|never|secure
    --fields=STRING
    --quiet
-v, --verbose
    --key-path=STRING        # service account key file
    --profile=STRING         # profile for this invocation
    --cache-dir=STRING       # $GPD_CACHE_DIR

Profile resolution order

  1. --profile
  2. GPD_AUTH_PROFILE
  3. config activeProfile
  4. default

Useful env vars

Env Role
GPD_AUTH_PROFILE Profile override
GPD_SERVICE_ACCOUNT_KEY Inline JSON key
GOOGLE_APPLICATION_CREDENTIALS ADC key path
GPD_CLIENT_ID / GPD_CLIENT_SECRET Device-flow OAuth (optional)

Commands (exact help surface)

Status / list / switch

# Check whether credentials load and look valid
gpd auth status --output json

# List stored profiles (active marker in output)
gpd auth list --output json

# Make a profile active for subsequent commands
gpd auth switch <profile> --output json

# One-off profile without switching active
gpd --profile team-b auth status --output json

Login / init (service account)

auth init is an alias of auth login.

# Store credentials under a named profile
gpd auth login ci --key ./sa.json --output json
# equivalent:
gpd auth login ci --key-path ./sa.json --output json

gpd auth init ci --key ./sa.json --output json

# CI: authenticate without persisting tokens to secure storage
gpd auth login ci --key ./sa.json --store-tokens never --output json

# Device-flow OAuth only when client ID/secret are configured (not preferred for CI)
gpd auth login ops --output json

Command-specific flags on login/init:

Flag Meaning
--key Path to service account key file (command-local; --key-path also works globally)

Package permission check

Requires global --package.

gpd auth check --package com.example.app --output json
gpd --profile ci auth check --package com.example.app --output json

Doctor / diagnose

auth diagnose is an alias of auth doctor.

# Local diagnostics (no network probe)
gpd auth doctor --output json

# Attempt credential/token load refresh path
gpd auth doctor --refresh-check --output json

# Network package probe (requires --package + credentials)
gpd auth doctor --refresh-check --network --package com.example.app --output json

gpd auth diagnose --refresh-check --output json

Command-specific flags:

Flag Meaning
--refresh-check Attempt token refresh / credential load
--network Lightweight network permission probe (requires --package)

Also available (config-level): gpd config doctor — prefer auth doctor for credential health.

Logout / delete

# Sign out active profile
gpd auth logout --output json

# Sign out a named profile
gpd auth logout --name ci --output json

# Sign out all profiles
gpd auth logout --all --output json

# Delete a stored profile (refuses active unless --force)
gpd auth delete staging --output json
gpd auth delete staging --force --output json
Command Notable flags / args
auth logout --name=STRING (default: active), --all
auth delete <profile> --force (allow deleting active; switches to default)

Recommended agent workflow

  1. gpd auth status --output json — is anything loaded?
  2. If empty / broken: gpd auth login <profile> --key ./sa.json --output json
  3. Multi-account: gpd auth list → gpd auth switch <profile> (or --profile per call)
  4. Before write ops: gpd auth check --package com.example.app --output json
  5. On mystery failures: gpd auth doctor --refresh-check --network --package com.example.app --output json
  6. Cleanup: gpd auth logout --name <profile> or gpd auth delete <profile>

Exit codes (shared)

0 success · 1 API · 2 Auth · 3 Permission · 4 Validation · 5 Rate limit · 6 Network · 7 Not found · 8 Conflict

Related skills

  • gpd-release — validate / upload / publish play / rollout after auth works
  • gpd-reviews-vitals — reviews and Android vitals queries

Notes

  • Prefer live gpd auth --help / gpd auth <cmd> --help over memorized flags.
  • Play Console must grant the service account access to the app; API enablement alone is not enough.
  • For broader operator docs see docs/auth-parity-guide.md in the gpd repo.