> ## Documentation Index
> Fetch the complete documentation index at: https://plainrouter.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plainrouter CLI: install, authenticate and inspect events

> Install the Plainrouter CLI, store a Signals workspace secret securely, and run your first authenticated event or diagnostics command.

The Plainrouter CLI exposes the Signals Conversion API as the `plainrouter` command. Install the command from [PyPI](https://pypi.org/project/plainrouter/), [npm](https://www.npmjs.com/package/@plainrouter/cli), or the [official Homebrew tap](https://github.com/plainrouter/homebrew-tap).

The current [PyPI release](https://pypi.org/project/plainrouter/) is `0.5.2` and includes both the Python SDK and CLI. The current [npm release](https://www.npmjs.com/package/@plainrouter/cli) 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`.

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

## 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](https://pypi.org/project/plainrouter/)

Use [`pipx`](https://pipx.pypa.io/) to install the CLI in an isolated Python environment:

```bash theme={null}
pipx install plainrouter==0.5.2
```

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](https://brew.sh/)

Install from the official [`plainrouter/homebrew-tap`](https://github.com/plainrouter/homebrew-tap):

```bash theme={null}
brew install plainrouter/tap/plainrouter
```

The formula supports [Homebrew](https://brew.sh/) on macOS and Linux and installs the required Node.js runtime.

## Install with [npm](https://www.npmjs.com/package/@plainrouter/cli)

Install the CLI from its [official npm package page](https://www.npmjs.com/package/@plainrouter/cli):

```bash theme={null}
npm install --global @plainrouter/cli@0.5.1
```

Confirm the command is available:

```bash theme={null}
plainrouter --version
plainrouter --help
```

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:

```bash theme={null}
plainrouter auth login
```

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:

```bash theme={null}
plainrouter auth status
```

The status output shows only the token's final four characters and its source.

## Run your first command

List recent events and delivery metrics:

```bash theme={null}
plainrouter events list
```

Request machine-readable output for scripts:

```bash theme={null}
plainrouter events list --per-page 25 --json
```

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:

```bash theme={null}
plainrouter events get EVENT_ID --json
```

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](/docs/reference/statuses-and-terms#destination-delivery).

## What if the first command fails?

| Symptom                        | Next step                                                                                                                                  |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Command not found              | Check your package manager's binary directory is on `PATH`; rerun `plainrouter --version`.                                                 |
| Missing or rejected credential | Run `plainrouter auth status`, then check whether `PLAINROUTER_TOKEN` overrides the stored secret. Use a Signals secret, not an MCP token. |
| No returned events             | Confirm the correct workspace and retention. Arrival-only records are aggregate and are not listed as conversion events.                   |
| Event lookup returns `404`     | Copy the event ID from ingestion or the list response and check workspace scope.                                                           |
| Request validation fails       | Read standard error for field details; the CLI exits with status `1`.                                                                      |

For a request that writes data, follow the [event example and destination test sequence](/docs/cli/command-reference).

## Use an environment variable

For CI, inject `PLAINROUTER_TOKEN` through your secret manager. In an interactive Bash shell, read it at a hidden prompt:

```bash theme={null}
read -r -s -p "Signals workspace secret: " PLAINROUTER_TOKEN
export PLAINROUTER_TOKEN
plainrouter reports emq --json
unset PLAINROUTER_TOKEN
```

`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:

```bash theme={null}
plainrouter auth logout
```

This command does not revoke or rotate the Signals workspace secret. It only removes the local file.

See the [CLI command reference](/docs/cli/command-reference) for every supported operation.