> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install & authenticate the Google Play CLI

> Install gps, create a Google Play service account, and configure credentials, environment variables, and multiple accounts.

## Install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install -g @appeeky/google-play-store-cli
```

This installs both binaries:

| Binary | Role |
| - | - |
| `gps` | CLI |
| `gps-mcp` | MCP server (stdio) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gps --help
gps-mcp --help
```

Also available with `pnpm add -g`, `yarn global add`, or `bun add -g`.

## Create a service account

`gps` uses a Google Cloud **service account JSON key**, not a Google API key.

**1. Create the service account**

In Google Cloud, create a service account and enable the **Google Play Android Developer API** on its project.

**2. Download a JSON key**

Store it outside your repository. Never commit it.

**3. Invite it in Play Console**

In Play Console → **Users and permissions**, invite the service-account email and grant app or account permissions for the work you want to automate (releases, listings, reviews, monetization, financial data).

**4. Verify**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
gps whoami
```

> [!NOTE]
>
> Many Play reads (tracks, listings, APK lists) run inside a temporary edit that `gps` opens and deletes without committing. The service account still needs edit permission for those reads.

> [!WARNING]
>
> Treat the key as a secret. If it leaks, rotate it in Google Cloud and revoke the old key.

## Credentials

Resolved in this order:

| # | Source |
| - | - |
| 1 | `--credentials <path\|json>` (CLI and `gps-mcp` flag) |
| 2 | `GPS_CREDENTIALS` or `GOOGLE_PLAY_CREDENTIALS` (path or inline JSON) |
| 3 | `GOOGLE_APPLICATION_CREDENTIALS` (path) |
| 4 | `~/.config/gps/config.json` → `credentialsPath` |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gps --credentials ./sa.json whoami
GPS_CREDENTIALS="$PLAY_SA_JSON" gps whoami   # inline JSON from a CI secret
```

## Multiple accounts and apps

One service account can reach every app you grant it in Play Console. The Android Publisher API has no endpoint that lists a developer's apps, so `gps` keeps a local registry of package names under named accounts.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gps accounts add my-co --credentials /secrets/my-co-sa.json --default-package com.example.app --default
gps accounts add client --credentials /secrets/client-sa.json
gps accounts list
gps accounts use my-co

gps apps add com.example.app --account my-co --name "My App" --default
gps apps list
gps apps check          # probes listings access for each registered package
gps apps remove com.example.app --account my-co
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gps --account client --package com.client.app tracks list
gps --package com.example.app tracks list   # account picked automatically when the package is registered once
```

The config lives in `~/.config/gps/config.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "defaultAccount": "my-co",
  "accounts": {
    "my-co": {
      "credentialsPath": "/secrets/my-co-sa.json",
      "defaultPackage": "com.example.app",
      "apps": [{ "packageName": "com.example.app", "displayName": "My App" }]
    }
  }
}
```

## Local MCP server

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "google-play": {
      "command": "gps-mcp",
      "args": ["--credentials", "/path/to/service-account.json"]
    }
  }
}
```

| `gps-mcp` flag | Description |
| - | - |
| `-c, --credentials <path\|json>` | Service-account key |
| `-a, --account <id>` | Default named account from the config |
| `--read-only` | Refuse writes |

`gps-mcp` reads the same environment variables as `gps`. Tools take an optional `account` argument for multi-key setups.

## Write safety

| Mechanism | Behavior |
| - | - |
| `--confirm` | Required for every write command and for `gps call` on write operations |
| `--read-only` | Blocks writes; temporary read edits are still allowed |
| `gps-mcp --read-only` | Same, for agent sessions |

> [!TIP]
>
> No key on this machine? Use the [hosted MCP](/docs/store-cli-google-play-hosted-mcp.md) on your Appeeky connection instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.