> ## Documentation Index
> Fetch the complete documentation index at: https://f82cc46-productmetrics.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://f82cc46-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://f82cc46-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://f82cc46-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# CLI authentication (/docs/cli/authentication)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1563 · updated: 2026-11-16 -->
Related: [Product Metrics CLI](/docs/cli/overview.md), [Quickstart for developers and agents](/docs/cli/quickstart.md), [CLI commands](/docs/cli/commands.md), [Use the CLI from an AI agent](/docs/cli/for-agents.md), [JSON output and exit codes](/docs/cli/json-and-exit-codes.md)

> Sign in to productmetrics in a browser, choose the scopes it may use, check the sign-in, and use PM_TOKEN in CI.

`productmetrics` signs in with your Product Metrics account through the same OAuth server MCP clients use.

There is no API key: you approve the CLI once in a browser, and it stores and renews the tokens itself.



* **You need:** a Product Metrics account and a browser, on this machine or another.
* **Run:** `productmetrics login`, then **Connect Product Metrics CLI**.
* **Result:** tokens stored for this API origin; sign in again after 30 days.

## Sign in

### 1. Run productmetrics login

```bash
# prints the URL, opens the browser, waits up to 5 minutes
productmetrics login
# prints the URL; open it on this machine
productmetrics login --no-browser
# browser on another machine: paste the address it lands on
productmetrics login --paste
# ask for less (default: read,setup,write)
productmetrics login --scopes read
```

**You should see:** the URL in the terminal and the Product Metrics consent page in your browser. Every flag is under [Login flags](#login-flags).

### 2. Approve on the consent page

The page names the app (**Product Metrics CLI**), lists what it **Can read** and **Can change**, and you click **Connect Product Metrics CLI**. Signed out, the button is **Continue with Google** first. The CLI then stores the tokens for this API origin.



> **Note:** With `--paste`, the browser lands on a `127.0.0.1` address after you connect. It may not load: copy the full address (or just the code) and paste it into the terminal.

**You should see:** instead of a website, the page says the answer **Returns to an app on this computer**.

### 3. Check the sign-in

```bash
# which API, signed in or not, scopes, expiry; never calls the API
productmetrics status
# calls the API: your account (email) and properties
productmetrics whoami
```

**You should see:** `"signed_in": true` and your scopes in `productmetrics status --json`:

```json
{
  "ok": true,
  "data": {
    "origin": "https://prod-backend.productmetrics.io",
    "environment": "production",
    "signed_in": true,
    "token_source": "stored",
    "scope": ["read", "setup", "write"],
    "access_token_expires_in_minutes": 42,
    "refresh_token": true,
    "credentials_file": "/home/you/.config/product-metrics/credentials.json",
    "other_signed_in_origins": []
  }
}
```

`productmetrics whoami --select '.data.properties[].property_id'` prints only your property ids, one per line.

## Login flags

| Flag              | What it does                                                                      |
| ----------------- | --------------------------------------------------------------------------------- |
| `--scopes <list>` | What to allow: `read`, `setup`, `write` (default all three)                       |
| `--no-browser`    | Print the URL without opening a browser                                           |
| `--paste`         | Read the redirected address (or the code) from stdin                              |
| `--api <origin>`  | Sign in to another environment, such as `https://stage-backend.productmetrics.io` |

## Scopes

Each API operation needs exactly one scope. The command's `--help` names it, and so does `productmetrics capabilities`.

| Scope   | Allows                                                                                    | Examples                                                                                                                                   |
| ------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `read`  | Reading your setup and data, and sending feedback                                         | `productmetrics whoami`, `productmetrics settings get`, `productmetrics orders list`, `productmetrics data query`                          |
| `setup` | Connecting accounts and stores and completing setup steps, including removing connections | `productmetrics companies create`, `productmetrics google-ads create-property-connection`, `productmetrics stores connect`                 |
| `write` | Changing settings, product rules and feeds, and inviting people                           | `productmetrics settings update`, `productmetrics product-rules create`, `productmetrics feed generate`, `productmetrics invitations send` |

A command whose scope your sign-in lacks fails with exit code 3 and a hint with the `productmetrics login --scopes` command that adds it.

Scopes never widen your role. `productmetrics` acts as you, with your role in each workspace: an operation that needs a workspace admin still fails for an editor.

## Token lifetimes

* **Access token:** one hour. `productmetrics` renews it with the refresh token when less than a minute is left.
* **Refresh token:** 30 days from `productmetrics login`, however often you use it. Then run `productmetrics login` again.

Your access is checked on every request, so if you lose access to a workspace, `productmetrics` loses it at once.

## CI and scripts: PM_TOKEN

Set `PM_TOKEN` to an access token and `productmetrics` uses it instead of the stored sign-in:

```bash
PM_TOKEN=<access token> productmetrics whoami --json
```

`productmetrics` cannot renew a `PM_TOKEN`: when it expires (after one hour), the API refuses it and `productmetrics` exits 3 with "PM_TOKEN was refused".

## Where credentials live

`${XDG_CONFIG_HOME:-~/.config}/product-metrics/credentials.json`, one entry per API origin, file mode 0600 in a 0700 directory. Signing in to stage never replaces your production sign-in.

## Sign out

```bash
# production
productmetrics logout
# stage
productmetrics logout --api https://stage-backend.productmetrics.io
```

`productmetrics logout` revokes the stored tokens and removes this origin's entry. It warns when `PM_TOKEN` is still set in the shell.

## Where next



* [Commands](/docs/cli/commands): which scope each command needs
* [For agents](/docs/cli/for-agents): signing in when an agent drives `productmetrics`
* [API overview](/docs/api/overview#authentication): the same tokens over HTTP
