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 agentsIt 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
--yesfor a delete.
export PM_AGENT=1The 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 --jsonWhen 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> --jsonThen 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-keysends 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> \
--jsonA 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 completeVersioned 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-matchout only whensettings_versionis null (nothing saved yet). - A
409 settings_conflictmeans someone saved in between: read again, reapply the change and retry. feed-source-settings updateworks 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 innext_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-secretsprints it for them) beforenext_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 "…" \
--jsonNot for your own mistakes, the local environment, or an error you recovered from. One report per issue; never include personal data, tokens or secrets.