Skip to main content
The Plainrouter CLI exposes the Signals Conversion API as the plainrouter command. Install the command from PyPI, npm, or the official Homebrew tap. The current PyPI release is 0.5.2 and includes both the Python SDK and CLI. The current npm release is 0.5.1 and uses @plainrouter/sdk 0.5.1. Both distributions expose the same command tree and target signed API contract 0.5.0.
The PyPI and npm CLI distributions can create events with the current consent contract. They do not expose an ingestion-verification command; use the TypeScript, Python, Ruby, or Go SDK, direct REST, or MCP for that operation.

​
Requirements

  • Python 3.11 or newer for the PyPI package, or Node.js 22.22.2 or newer for npm.
  • A Signals workspace secret.

​
Install with PyPI

Use pipx to install the CLI in an isolated Python environment:
The same package also exposes the Python SDK. From an active environment, you can run python -m plainrouter instead of the console command.

​
Install with Homebrew

Install from the official plainrouter/homebrew-tap:
The formula supports Homebrew on macOS and Linux and installs the required Node.js runtime.

​
Install with npm

Install the CLI from its official npm package page:
Confirm the command is available:
Keep only one global Plainrouter CLI installation on your PATH. If you install from more than one package manager, your shell may select a different distribution than the one you intended.

​
Sign in with a Signals workspace secret

Run the interactive login command:
Paste the Signals workspace secret at the hidden prompt. Current 0.5.x builds label this credential a tracker token for compatibility. The CLI stores it in $XDG_CONFIG_HOME/plainrouter/config.json. When XDG_CONFIG_HOME is unset, it uses ~/.config/plainrouter/config.json. The CLI creates the directory with mode 0700 and the configuration file with mode 0600. Check the active credential without printing it:
The status output shows only the token’s final four characters and its source.

​
Run your first command

List recent events and delivery metrics:
Request machine-readable output for scripts:
Without --json, the CLI prints a human-readable summary or table. A successful command exits with status 0. In JSON output, events.data is the returned event list; an empty array is a valid response and does not prove collection is configured. To inspect one event, use its returned ID:
Read deliveries[].status: accepted confirms destination acceptance, while queued or retrying delivery remains pending. Do not treat a successful list request as evidence of Meta delivery. See delivery status meanings.

​
What if the first command fails?

For a request that writes data, follow the event example and destination test sequence.

​
Use an environment variable

For CI, inject PLAINROUTER_TOKEN through your secret manager. In an interactive Bash shell, read it at a hidden prompt:
PLAINROUTER_TOKEN takes precedence over a stored token. The CLI intentionally has no --token option, which helps keep credentials out of shell history and process listings.

​
Sign out

Remove the stored configuration:
This command does not revoke or rotate the Signals workspace secret. It only removes the local file. See the CLI command reference for every supported operation.