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

# CLI quickstart

> Install the PlainRouter CLI, store a Signal tracker token, and run your first command.

The PlainRouter CLI exposes the Signals Conversion API as the `plainrouter` command. Every API command delegates to the matching operation in `@plainrouter/sdk`.

The current [npm release](https://www.npmjs.com/package/@plainrouter/cli) is `0.5.0` and uses `@plainrouter/sdk` `0.5.0`. Review release notes before upgrading while the CLI remains in the `0.x` series.

<Note>
  CLI `0.5.0` can create events with the current consent contract. It does not expose an ingestion-verification command; use the TypeScript, Python, or Go SDK, direct REST, or MCP for that operation.
</Note>

## Requirements

* Node.js `22.22.2` or later in the Node 22 release line.
* A per-Signal tracker secret.

## Install with Homebrew

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 on macOS and Linux and installs the required Node.js runtime.

## Install with npm

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

Confirm the command is available:

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

## Sign in with a tracker token

Run the interactive login command:

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

Paste the tracker token at the hidden prompt. 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.

## Use an environment variable

For CI or an ephemeral shell, inject the token through your secret manager:

```bash theme={null}
export PLAINROUTER_TOKEN="YOUR_SIGNAL_TRACKER_SECRET"
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 Signal tracker secret. It only removes the local file.

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