gpc-setup

GPC のセットアップ

使用するタイミング

次の作業に関するタスクでは、このスキルを使用します。

• GPC のインストール（npm install -g @gpc-cli/cli またはスタンドアロンバイナリ）
• 統合セットアップウィザードの実行（gpc setup、v0.9.68 以降）
• Google Play Developer API による認証（サービスアカウント、OAuth、ADC）
• 認証プロファイルの管理（gpc auth profiles、gpc auth switch）
• GPC の設定（.gpcrc.json、環境変数、gpc config init）
• セットアップの問題の診断（gpc doctor）
• 新しいプロジェクトまたは CI 環境での GPC のセットアップ

必要な入力

• ローカル開発環境か CI/CD のセットアップか
• 認証方法：サービスアカウント JSON、OAuth、または Application Default Credentials
• Android アプリのパッケージ名（例：com.example.app）
• CI の場合：CI プラットフォーム（GitHub Actions、GitLab など）

手順

0) GPC のインストール

npm 経由（推奨）：

npm install -g @gpc-cli/cli

npx 経由（インストール不要のお試し）：

npx @gpc-cli/cli --version

スタンドアロンバイナリ経由（Node.js 不要）：

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

1) 統合セットアップ（v0.9.68 以降、推奨）

GPC を一から設定する最速の方法です。

gpc setup

gpc setup は、認証、設定、検証を 1 つのガイド付きフローにまとめた単一のコマンドです。

1. 既存の設定を検出します（途中までの場合は再開します）
2. 認証方法（サービスアカウント、OAuth、または ADC）の入力を求めます
3. 認証情報を検証します
4. デフォルトのパッケージ名を設定します
5. .gpcrc.json を書き込みます
6. gpc doctor を実行して、すべてが正常に動作することを確認します

CI/CD またはヘッドレス環境では、非対話型のオプションを使用します。

gpc setup --auto

--auto は環境変数（GPC_SERVICE_ACCOUNT、GPC_APP）から値を読み取り、すべてのプロンプトをスキップします。成功時は 0 で終了し、失敗時は対処方法を示すエラーとともに 0 以外の値で終了します。Docker イメージ、GitHub Actions のセットアップ手順、オンボーディングスクリプトに最適です。

より細かく制御する必要がある場合は、以下の個別のコマンドを使用してください。

1a) 認証

推奨順に 3 つの認証方法があります。

A) サービスアカウント（CI/CD に推奨）

Google Cloud を初めて使用する場合、または初回セットアップを行う場合： 対話型の GCP セットアップガイドを使用してください。

gpc auth setup-gcp

この完全対話型ウィザードでは、GPC を Play Developer API に接続するために必要な各手順を案内します。

1. GCP プロジェクトで Google Play Developer API を有効にする
2. GCP Console でサービスアカウントを作成する
3. Google Play Console（Settings → API access）でサービスアカウントにアクセス権を付与する
4. JSON キーファイルをマシンにダウンロードする
5. ダウンロードしたキーを使って gpc auth login を実行する

フラグは不要です。コマンドを実行して、表示されるプロンプトに従ってください。あらゆるマシンでの初回セットアップに最適です。

すでにキーファイルがある場合： --key を使用してウィザードをスキップできます。

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

JSON の検証、認証、設定への保存を 1 ステップで行います。

ウィザードが完了したら、またはすでにキーファイルがある場合は、次のようにします。

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

または、環境変数を使用します（CI ではこちらを推奨）。

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

一括レポート用の追加権限付与（v0.9.93 以降）。 上記の API アクセス権の付与では、Play の月次一括レポートは対象になりません。これらは Publisher API 経由ではなく、Cloud Storage バケット内の CSV ファイルとして配信されます。Play はそのバケットへのアクセス権をユーザー自身のログインには自動的に付与しますが、サービスアカウントには付与しません。gpc reports を使用する予定がある場合は、Play Console → Users and permissions → サービスアカウント → Account permissions を開き、「View app information and download bulk reports (read-only)」 を有効にしてから、反映まで数分待ってください。この権限がない場合、レポートコマンドは REPORT_ACCESS_DENIED で失敗します。gpc doctor の reports-bucket チェックで確認できます。

追加の devstorage.read_only スコープを要求するのはレポートコマンド（およびその doctor プローブ）のみです。また、ストレージスコープのトークンは個別にキャッシュされるため、ほかのすべてのコマンド用に発行されたトークンにはストレージへのアクセス権がありません。

参照：

• references/service-account.md

B) OAuth（ローカル開発用）

対話型の OAuth デバイスフローを使用します。キーファイルは不要です。

gpc auth login

トークンは OS のキーチェーン（macOS Keychain、Linux libsecret）にキャッシュされます。利用できない場合はファイルに保存されます。

C）アプリケーションのデフォルト認証情報（GCP 環境向け）

Cloud Build、Cloud Run、GKE で自動的に動作します。設定は不要です。

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

2）デフォルトを設定する

対話型セットアップウィザード：

gpc config init

ガイド付きウィザードでは、次の操作を行います。

1. 認証方法を選択します（service-account ／ adc ／ skip）。
2. サービスアカウントの場合、ファイルの存在を確認します（パスが誤っている場合は再試行します）。
3. デフォルトのパッケージ名を入力します（形式が無効な場合は警告します）。
4. .gpcrc.json を書き込み、初期化後の概要を表示します。
5. Run \gpc doctor` to verify your setup.` で終了します。

手動の設定ファイル（プロジェクトルートまたは ~/.config/gpc/config.json の .gpcrc.json）：

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

環境変数：

変数	説明
GPC_APP	デフォルトのパッケージ名
GPC_OUTPUT	デフォルトの出力形式（table/json/yaml/markdown/csv/tsv）
GPC_PROFILE	認証プロファイル名
GPC_NO_COLOR	色付き出力を無効にする
GPC_NO_INTERACTIVE	対話型プロンプトを無効にする
GPC_SKIP_KEYCHAIN	OS のキーチェーンをスキップし、ファイルストレージを使用する

設定の解決順序（v0.9.81 以降）

同じ設定が複数のソースから指定された場合、GPC は次の優先順位（高い順）で解決します。

優先度	ソース	例
1	CLI フラグ	--service-account key.json、--app com.example.app
2	環境変数	GPC_SERVICE_ACCOUNT、GPC_APP
3	アクティブなプロファイル	gpc auth switch <name> で設定
4	.gpcrc.json	プロジェクトレベルまたはグローバルの設定ファイル
5	デフォルト	組み込みのフォールバック値

v0.9.81 より前は、アクティブなプロファイルが GPC_SERVICE_ACCOUNT と GPC_APP の環境変数よりも暗黙に優先されていました。このバグは修正されています。環境変数と CLI フラグは、アクティブなプロファイルにかかわらず確実に優先されるようになりました。これは、実行時にシークレットが設定される CI 環境で重要です。

参照：

• references/configuration.md

3）認証プロファイルを管理する

複数の Google Play アカウントを管理する場合：

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

auth login --profile <name> を再実行すると、そのプロファイルの認証情報が更新され、その他の設定（app、developerId、reports）は保持されるため、安全に鍵をローテーションできます。gpc auth logout --profile <name> は、そのプロファイルの認証情報のみを消去します。どちらも GPC v0.9.95 以降が必要です。これより古いバージョンでは、login／logout の --profile フラグは無視されていました。その場合は、対話型の gpc auth login ウィザードでプロファイルを作成してください。

gpc auth clear-cache は、gpc auth logout に比べて影響範囲の小さい操作です。設定済みの認証情報は削除せず、キャッシュされたアクセストークンを削除するため、次のコマンドで新しいトークンが発行されます。Play Console の権限（たとえば一括レポートの権限）を変更した後に使うと、変更前のキャッシュ済みトークンによって変更が反映されないように見える事態を防げます。

コマンドごとに上書きするには、--profile フラグを使用します。

gpc apps list --profile staging

4) セットアップを検証する

gpc doctor

チェック項目（合計23項目）：

• Node.js のバージョン（≥ 20）
• 設定の読み込み
• デフォルトアプリの設定と、有効な Android パッケージ名の形式
• 設定ディレクトリとキャッシュディレクトリの権限
• サービスアカウントファイルの存在と権限（グループや他のユーザーから読み取り不可）
• プロファイルの環境変数が既知のプロファイルを指していること
• プロキシ URL の有効性（HTTPS_PROXY が設定されている場合）
• CA 証明書ファイルの存在（GPC_CA_CERT が設定されている場合）
• DNS 解決（androidpublisher + playdeveloperreporting）
• 認証の有効性
• API 接続（アクセストークンを取得）
• デベロッパー確認の期限（2026年9月30日）
• 古いキャッシュに関する警告（>7日）
• シェル補完の検出（bash/zsh）
• API クォータの逼迫度：1日または1分あたりの使用量が80%を超えると警告します（v0.9.71+）
• プラグインの健全性：設定済みの各プラグインがエラーなく読み込まれることを検証します（v0.9.71+）
• 署名鍵の検証：--verify は Play の署名証明書を取得し、ローカルのキーストアと比較します（v0.9.75+）
• レポートバケット（reports-bucket）：Play の一括レポート用バケットを検査し、サービスアカウントに「一括レポートのダウンロード（読み取り専用）」権限がない場合、またはバケット名が正しくない場合に警告します（v0.9.93+）

修正可能な問題（バージョン、認証、設定キー）を自動修正するには、gpc doctor --fix を使用します。

JSON 出力に対応しています：gpc doctor --json または gpc doctor --output json。

署名鍵の検証（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

環境変数による代替指定：GPC_KEYSTORE_PATH および GPC_STORE_PASSWORD。

5a) デベロッパー確認をチェックする

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

Google による Android デベロッパー確認の適用は、2026年9月に BR、ID、SG、TH で開始されます。gpc doctor では、これをチェック項目 #20 として確認します。

gpc verify checklist は、準備状況に関する11項目を評価します（v0.9.96+）。4項目はアカウントとアプリから自動検出されます（Play Console アカウントが有効、API 経由でアプリにアクセス可能、少なくとも1つのバンドルがアップロード済み、Play App Signing に登録済み）。残りの7項目は GPC では検出できません。v0.9.96 では、この7項目すべてについてプロンプトで回答できます：

• Play Console での本人確認が完了している
• 2026年9月30日の適用スケジュールを確認済み（ブラジル、インドネシア、シンガポール、タイ）
• 自動登録の結果を確認済み
• アカウント上のすべてのアプリを Play Console に登録済み（2026年7月15日の義務化）
• 2027年2月のメモリおよび DEX 最適化の品質要件を確認済み（v0.9.96 で追加）
• Android Restore Credentials API を使用した Zero-Tap Sign-In を実装済み。2027年4月に必須となります。現在、ゲームは対象外です（v0.9.96 で追加）
• Play 以外で使用する追加の署名鍵を登録済み

各項目には、✓（完了）、✗（対応が必要）、または ?（自動検出できず、未回答）が表示されます。手動確認項目は、プロンプトに回答して初めて ✓ または ✗ になります。そのため、--no-interactive、--json、または CI では、7項目すべてが ? のままです。正確な評価を確認するには、対話モードで実行してください。

5b) CLI からドキュメントを閲覧する（v0.9.64+ 組み込みドキュメント）

v0.9.64 以降、GPC には108ページのドキュメントがバイナリに組み込まれています。ネットワークは不要です。

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 は、長いページを $PAGER に渡して表示します。機械可読な出力には、gpc docs list --json および gpc docs search --json を使用します。

5) ネットワーク設定（必要な場合）

企業プロキシやカスタム CA 証明書を使用する場合：

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,.internal.example.com   # optional: hosts to reach directly
export GPC_CA_CERT=/path/to/ca-bundle.crt

プロキシはこれらの環境変数（大文字・小文字のどちらでも可）を通じてのみ設定できます。設定ファイルにプロキシキーはありません。v0.9.98 以降、設定済みのプロキシを適用できない場合（URL の形式が不正など）は、プロキシを迂回して直接接続するのではなく、リクエストを送信する前に NETWORK_ERROR（終了コード5）でコマンドを停止します。https_proxy= のような空の小文字の環境変数によって、設定済みの HTTPS_PROXY が無効になることもありません。

再試行の設定：

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

シェル補完（v0.9.58+ ウォーカー、v0.9.60+ 動的値）

GPC は bash、zsh、fish、PowerShell のシェル補完を提供します。補完ツリーはイントロスペクションに基づいているため（v0.9.58+）、新しいコマンドやプラグインによって登録されたコマンドも、ジェネレーターを編集せずに自動補完されます。.choices() で宣言されたフラグは、TAB キーを押したときに候補リストを表示します。

# 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

動的な値（v0.9.60以降）

補完スクリプトは、非表示の gpc __complete <ctx> サブコマンドを使用して、TAB キーを押したときに複数のフラグの値を動的に補完します。API 呼び出しは行わず、設定と ~/.cache/gpc/status-*.json キャッシュを読み取るだけなので、キャッシュが空の状態でも150ミリ秒未満で返ります。

フラグ	取得元
--profile	~/.config/gpc/config.json にあるプロファイル名
--app / --apps	設定とステータスキャッシュにあるパッケージ名
--track	現在のアプリのトラック名（ステータスキャッシュから取得）

パッケージ名やトラック名の補完情報が古い場合は、gpc status にアクセスするコマンドを実行するか、gpc status を直接実行してキャッシュを更新してください。

検証

• gpc doctor ですべてのチェックに合格する
• gpc auth status で認証済みの ID が表示される
• gpc apps list で実際のアプリデータが返される
• gpc config show で解決済みの設定が表示される

エラー発生時の動作／デバッグ

症状	考えられる原因	対処方法
AUTH_EXPIRED	アクセストークンの有効期限切れ	gpc auth login を実行して再認証する
AUTH_INVALID	サービスアカウントが誤っているか、権限が不足している	Google Play Console → 設定 → API アクセスを確認する
NETWORK_ERROR	プロキシまたはファイアウォールによるブロック	HTTPS_PROXY および／または GPC_CA_CERT を設定する
CONFIG_NOT_FOUND	設定ファイルがない	gpc config init を実行するか、GPC_APP 環境変数を設定する
「API connectivity」で Doctor が失敗する	サービスアカウントに Play Console へのアクセス権が付与されていない	Play Console の API アクセス設定でサービスアカウントを追加する

以下を参照してください：

• references/troubleshooting.md

エスカレーション

• Google Play Console API アクセスの設定については、https://developers.google.com/android-publisher/getting_started を参照してください
• サービスアカウントの作成については、https://cloud.google.com/iam/docs/service-accounts-create を参照してください