CLI command reference

Plainrouter CLI exposes nine API commands through the PyPI plainrouter package 0.5.2, npm @plainrouter/cli package 0.5.1, and the official Homebrew tap. All distributions target signed API contract 0.5.0. The contract also includes ingestion verification, which is available through the SDKs, direct REST, or MCP rather than a CLI command.

Global options

Option	Purpose
`--json`	Print the API response as formatted JSON.
`--help`	Show help for the current command.
`--version`	Print the CLI version.

You can place --json on any API command. Authentication commands also support it.

Authentication

Command	Purpose
`plainrouter auth login`	Prompt for and store the Signals workspace secret. The `0.5.x` prompt calls it a tracker token.
`plainrouter auth status`	Show the masked credential source and API base URL.
`plainrouter auth logout`	Remove the stored local configuration.

The CLI resolves configuration in this order:

PLAINROUTER_TOKEN for authentication.
PLAINROUTER_BASE_URL for the API origin.
The token and baseUrl in the local configuration file.
The production base URL, https://plainrouter.com/api/v1.

Events

This request can send a real conversion. Use it only for an actual paid order with recorded full advertising consent and a connected Meta destination. Replace the order ID and decimal amount; the example omits event_time for an immediate event. Queued events must preserve their original payment timestamp.

plainrouter events create --data '{
  "event_name": "Purchase",
  "event_id": "order-123",
  "consent_basis": "consent",
  "consent": {
    "ad_storage": "granted",
    "ad_user_data": "granted",
    "ad_personalization": "granted"
  },
  "value_data": {
    "value": "49.90",
    "currency": "EUR",
    "order_id": "order-123"
  }
}'
plainrouter events get order-123
plainrouter events list --per-page 25

Command	Options
`events create`	Required `--data <json>` request object.
`events get <id>`	Event ID as the positional argument.
`events list`	Optional `--per-page <count>`.

Use a stable event ID when creating an event so retries remain idempotent. A duplicate: true receipt means the original event exists, not that Meta accepted it. Inspect events get before considering a delivery replay. Use the sandbox for synthetic validation without production writes.

Destination test operations

Use a controlled destination and its current Meta Test Events code. Test mode changes delivery behavior for that destination: coordinate the test window, send the test purchase while mode is enabled, inspect Meta Test Events, and restore normal mode afterward even if the test fails. See destination testing.

plainrouter destinations test-mode DESTINATION_ID \
  --on --test-event-code TEST42
plainrouter destinations test-purchase DESTINATION_ID \
  --value 25.00 --currency EUR --order-id test-order-123
plainrouter destinations test-mode DESTINATION_ID --off

destinations test-mode requires exactly one of --on or --off. The test purchase accepts optional --value, --currency, and --order-id values.

Replay deliveries

plainrouter deliveries replay \
  --delivery-id 7 \
  --delivery-id 9 \
  --event-name Purchase \
  --limit 50

Repeat --delivery-id to select multiple deliveries. You can also filter by event name and cap the number of deliveries evaluated.

Reports

plainrouter reports reconciliation --date 2026-08-18
plainrouter reports emq

The reconciliation date must use YYYY-MM-DD format.

Delete user data

plainrouter user-data delete \
  --type email \
  --hash HASHED_IDENTIFIER

The identifier type is email, phone, or external_id. The command asks for confirmation before sending the deletion request. The 0.5.x CLI exposes the legacy SHA-256 form through --hash. Use direct REST or an SDK when you need to submit a verified raw identifier; both forms remain body-only and workspace-scoped. Use --yes only in an automation that has already applied an equivalent confirmation gate:

plainrouter user-data delete \
  --type email \
  --hash HASHED_IDENTIFIER \
  --yes \
  --json

Handle errors

The CLI writes errors to standard error and exits with status 1. Validation errors include field-level details when the API returns them. A 401 response means the Signals workspace secret is missing, invalid, or no longer active. Stop retrying and replace the credential.

Get started

Reference

CLI command reference

Global options

Authentication

Events

Destination test operations

Replay deliveries

Reports

Delete user data

Handle errors

​Global options

​Authentication

​Events

​Destination test operations

​Replay deliveries

​Reports

​Delete user data

​Handle errors

Global options

Authentication

Events

Destination test operations

Replay deliveries

Reports

Delete user data

Handle errors