Skip to content
CLI

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
}
  • 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.

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

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

PathPicks
.keyA 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: 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.

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

Exit codes

CodeMeaningWhat to do
0OK
1The API answered with an error, or could not be reachedRead error.code and error.hint. Retry only when the hint says so
2Usage error: an unknown command, flag or value, a missing required value, or a delete without --yesFix the command; error.hint names the flag
3Not signed in, the token was refused, or it lacks the scopeRun the productmetrics login command the hint names; in CI, set a valid PM_TOKEN
4A 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