JSON output and exit codes
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:
{
"ok": true,
"data": { … },
"request_id": "…"
}Failure:
{
"ok": false,
"error": {
"code": "…",
"message": "…",
"details": { … },
"hint": "…"
},
"request_id": "…",
"exit_code": 1
}datais the API’s answer for an API command, and the command’s own result for a built-in such asproductmetrics status.request_idappears when the API answered. Quote it inproductmetrics feedback --request-idor to support.detailsandhintappear when there are any.hintis the command to run next, such as theproductmetrics login --scopescommand that adds a missing scope.error.codeis lower_snake and stable enough to branch on. The API’s codes are listed in 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.
{
"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-linkbilling create-checkout-linkgoogle-ads send-invitestores 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.
{
"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 |
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: valuefor 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.
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.