Skip to content
CLI

Use the CLI from an AI agent

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.

Start every session with:

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.
export PM_AGENT=1

The loop

Pass --json to every command

stdout then holds exactly one JSON document; progress, warnings and hints go to stderr. See JSON and exit codes.

Check the sign-in

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.

Discover, never guess

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.

Read the state before a setup step

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.

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: Write safely.

Write safely

The last step of the loop, in detail.

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.

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:

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:

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

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.

Hand-offs to a person

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.
{
  "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.

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:

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