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

# Use the CLI from an AI agent (/docs/cli/for-agents)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1598 · 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), [JSON output and exit codes](/docs/cli/json-and-exit-codes.md)

> How Claude Code, Codex or a script should drive productmetrics: JSON on every call, no prompts, discovery before guessing, safe retries and versioned writes.

`productmetrics` is built to be driven by an agent:

* it never prompts without a terminal;
* it prints one JSON document per call;
* it tells the agent what to run next in `error.hint`.

Start every session with:

```bash
productmetrics help agents
```

It prints the rules below, in short.

## Agent mode

Without a terminal, or with `CI`, `PM_AGENT=1` or `--no-input`, `productmetrics`:

* never prompts and never opens a browser;
* prints no colours;
* fails with exit code 2 and names the flag to pass where it would have asked, such as `--yes` for a delete.

```bash
export PM_AGENT=1
```

## The loop



**1. Pass --json to every command**

stdout then holds exactly one JSON document; progress, warnings and hints go to stderr. See [JSON and exit codes](/docs/cli/json-and-exit-codes).

**2. Check the sign-in**

```bash
productmetrics status --json
```

When `signed_in` is false, ask the person to run `productmetrics login` in their own terminal: signing in needs them in a browser. In CI, set `PM_TOKEN`.

**3. Discover, never guess**

```bash
productmetrics capabilities --json --search "merchant center"
productmetrics merchant-center create-connection --help --json
```

`--help --json` gives the exact flags, types, allowed values, the scope and an example. Ids come from earlier results (`productmetrics whoami --json`), never from guesses.

**4. Read the state before a setup step**

```bash
productmetrics onboarding get-state --json
productmetrics setup get-status --company-id <company_id> --json
```

Then any operation whose id ends in `get_setup_status` or `get_status` (`productmetrics capabilities --json --search status`).

`setup get-status` returns `journey_stage` (`onboarding`, `needs_workspace`, `needs_property`, `setup_complete`, `product_data_ready`, `feed_live`, `activated`) and the first open step in `hub.company.next_action` / `hub.property.next_action`. `unknown` means that part could not be read, not that it is missing.

**5. Write safely**

Pass `--auto-idempotency-key` where `--help` lists it, send `--if-match` where the operation has a version, and use `--dry-run` to check a request first. Details below.

## Idempotency keys

A change that may be retried takes an `Idempotency-Key` header (a UUID):

* `--auto-idempotency-key` sends a new random key. When the call fails, the hint prints the key it used.
* `--idempotency-key <uuid>` sends that key. Retry with the same key and the operation returns the first result instead of doing the work twice.

Three operations take a key: `companies create` and `tracking update-margin-policy` require one, and `stores connect` uses one so a retry does not start a second store connection. On any other command the flags are a usage error (exit 2): after a failure there, read to check whether the change happened before retrying. `productmetrics <group> <command> --help` lists `--auto-idempotency-key` where it applies.

```bash
productmetrics companies create \
  --name "My Shop" \
  --auto-idempotency-key \
  --json
# failed? retry with the key the hint names:
productmetrics companies create \
  --name "My Shop" \
  --idempotency-key <uuid-from-hint> \
  --json
```

A new account saves its account type and completes onboarding first; otherwise `companies create` fails with `onboarding_incomplete` and the hint names both commands:

```bash
productmetrics onboarding set-account-type --account-type direct_advertiser
productmetrics onboarding complete
```

## Versioned writes: --if-match

Settings carry a version. Read it, then send it with the change, so a change made in between is not overwritten:

```bash
productmetrics settings get \
  --property-id <property_id> \
  --select '.data.settings_version'
productmetrics settings update \
  --property-id <property_id> \
  --body-file new-settings.json \
  --if-match '"<settings_version>"'
```

* Leave `--if-match` out only when `settings_version` is null (nothing saved yet).
* A `409 settings_conflict` means someone saved in between: read again, reapply the change and retry.
* `feed-source-settings update` works the same way.

## Dry run

```bash
productmetrics google-ads create-property-connection \
  --company-id <company_id> \
  --connection-mode user_oauth \
  --customer-id <customer_id> \
  --dry-run
```

`--dry-run` prints the request that would be sent, and sends nothing. The `Authorization` header and secret-looking fields are redacted.

## Deletes

Operations whose access is `destructive` need `--yes`. Ask the person first; never decide it alone. Without `--yes`, `productmetrics` exits 2.

## Steps for a person

Some steps need a person, and the command exits 4 with `next_action` saying which:

* **`browser`**: the Google grant, Shopify approval, checkout, accepting a Google Ads invite. The URL is in `next_action.url`.
* **`store_plugin`**: a WooCommerce or Shopware 6 store waits for its setup token. The person installs the Product Metrics plugin in their store admin and pastes the token (`--show-secrets` prints it for them) before `next_action.expires_at`.

```json
{
  "ok": true,
  "data": {
    "url": "<app>/connect/google?scope=ads",
    "scope": "ads",
    "check_with": "setup.get_status"
  },
  "next_action": {
    "type": "browser",
    "url": "<app>/connect/google?scope=ads"
  },
  "request_id": "…"
}
```

Give the person the URL or the token, wait until they say they are done, then read the state again. See [JSON and exit codes](/docs/cli/json-and-exit-codes#next_action).

## Secrets

Secret fields, such as a store setup token, print as `"<hidden: pass --show-secrets>"`. Pass `--show-secrets` only to show the value to the person; never store or log it.

## Feedback

When the API or `productmetrics` behaved wrongly or confusingly, an operation you needed was missing, or something worked notably well:

```bash
productmetrics feedback \
  --sentiment negative \
  --message "…" \
  --context "…" \
  --json
```

Not for your own mistakes, the local environment, or an error you recovered from. One report per issue; never include personal data, tokens or secrets.

## Where next

* [JSON and exit codes](/docs/cli/json-and-exit-codes)
* [Commands](/docs/cli/commands)
* [Claude Code](/docs/integrations/claude-code): the same API as MCP tools
