> ## Documentation Index
> Fetch the complete documentation index at: https://e328d4e-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://e328d4e-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://e328d4e-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://e328d4e-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# JSON output and exit codes (/docs/cli/json-and-exit-codes)

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

> The --json envelope productmetrics prints, how --select picks part of it, next_action for the steps a person finishes (a browser or a store plugin), and what exit codes 0 to 4 mean.

With `--json`, stdout holds exactly one JSON document and everything else (progress, warnings, hints) goes to stderr. Scripts and agents can parse stdout and branch on the exit code.

## The envelope

**Success:**

```json
{
  "ok": true,
  "data": { … },
  "request_id": "…"
}
```

**Failure:**

```json
{
  "ok": false,
  "error": {
    "code": "…",
    "message": "…",
    "details": { … },
    "hint": "…"
  },
  "request_id": "…",
  "exit_code": 1
}
```

* `data` is the API's answer for an API command, and the command's own result for a built-in such as `productmetrics status`.
* `request_id` appears when the API answered. Quote it in `productmetrics feedback --request-id` or to support.
* `details` and `hint` appear when there are any. `hint` is the command to run next, such as the `productmetrics login --scopes` command that adds a missing scope.
* `error.code` is lower_snake and stable enough to branch on. The API's codes are listed in [Errors](/docs/api/overview#errors).

## next_action

A result that leaves a step for a person adds `next_action` and exits 4. `next_action.type` says which step.

**`browser`**: a person opens a URL.

```json
{
  "ok": true,
  "data": {
    "url": "…",
    "scope": "ads",
    "check_with": "setup.get_status"
  },
  "next_action": {
    "type": "browser",
    "url": "…"
  },
  "request_id": "…"
}
```

`productmetrics` sets it when a result says `action_required` or `mode: redirect`, or when a browser-step operation answers with a URL:

* `google get-connect-link`
* `billing create-checkout-link`
* `google-ads send-invite`
* `stores connect` (Shopify)

Give the person `next_action.url`, wait, then read the state again.

**`store_plugin`**: a WooCommerce or Shopware 6 store waits for its setup token. `stores connect` answers `mode: plugin_claim`; the person installs the Product Metrics plugin in their store admin and pastes the token there before `expires_at`.

```json
{
  "ok": true,
  "data": {
    "mode": "plugin_claim",
    "claim": {
      "setupToken": "<hidden: pass --show-secrets>",
      "expiresAt": "…"
    }
  },
  "next_action": {
    "type": "store_plugin",
    "expires_at": "…"
  },
  "request_id": "…"
}
```

Pass `--show-secrets` to print the token for the person, wait until they have pasted it, then read the state again (`tracking get-commerce-configuration`).

## --select

`--select <path>` prints part of a success document. It implies `--json`; a failure prints whole.

| Path   | Picks                                      |
| ------ | ------------------------------------------ |
| `.key` | A field (missing: `null`)                  |
| `[n]`  | The n-th element                           |
| `[]`   | Every element, or every value of an object |

```bash
productmetrics whoami --select '.data.properties[].property_id'
```

Strings and numbers print raw, one per line; objects and arrays print as one-line JSON.

## Other output modes

* **Default (no `--json`):** `key: value` for objects and a table for lists, for a person to read.
* `-q`, `--quiet`: only the primary id of the result, or nothing.
* `--verbose`: requests, timings and request ids on stderr; never tokens or bodies.

## Help as JSON

`productmetrics help --json` and `productmetrics <command> --help --json` print the usual envelope; its `data` describes the command: usage, flags with type, required, choices and defaults, the global flags, the operation (`capability`: its id, scope and access) for an API command, examples and the exit codes.

```bash
productmetrics settings update --help --json --select '.data.capability'
```

## Exit codes

| Code | Meaning                                                                                                                                 | What to do                                                                             |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `0`  | OK                                                                                                                                      |                                                                                        |
| `1`  | The API answered with an error, or could not be reached                                                                                 | Read `error.code` and `error.hint`. Retry only when the hint says so                   |
| `2`  | Usage error: an unknown command, flag or value, a missing required value, or a delete without --yes                                     | Fix the command; `error.hint` names the flag                                           |
| `3`  | Not signed in, the token was refused, or it lacks the scope                                                                             | Run the `productmetrics login` command the hint names; in CI, set a valid `PM_TOKEN`   |
| `4`  | A person must finish a step: next_action says which (open next_action.url in a browser, or paste the setup token into the store plugin) | Do what `next_action` says (see above), wait for the person, then read the state again |

`productmetrics help exit-codes` prints the same list.

## Where next

* [For agents](/docs/cli/for-agents)
* [API errors](/docs/api/overview#errors)
