# How to Pair the PingRoom CLI Without Copying a Token

> Install the public CLI, claim its separate robot by QR code, grant only the Rooms it needs, and verify the saved connection without pasting a bearer token.

- Published: 2026-10-18
- Author: PingRoom
- Category: Developers
- Topics: PingRoom CLI setup, pair notification CLI, developer notification app
- Canonical: https://pingroom.io/blog/pair-pingroom-cli-without-copying-a-token
- Cover image: https://pingroom.io/blog/pair-pingroom-cli-without-copying-a-token-cover.webp
- Cover description: Two PingRoom avatars review three miniature Room doors and a clay access token while Pingo watches beside the workbench.

To connect the PingRoom CLI on a local computer, install the current package and run `pingroom` with no arguments. The CLI creates a separate robot, shows a QR code, and waits while you claim that robot in the PingRoom app. You choose its home Room and the Rooms it may reach. No bearer token needs to pass through your clipboard or shell history.

This guide is for an interactive terminal on your own computer. CI, shared servers, and unattended containers need a different credential plan, covered below.

## Before you start

You need:

- Node.js 20 or later
- PingRoom installed on your phone and signed in
- authority to grant a connected robot access to the Rooms you select

Install the public CLI, then confirm the version:

```bash
npm install --global @pingroom/cli
pingroom --version
```

This walkthrough was verified against public CLI `0.13.0`. If your version is older, update before continuing.

## Pair the CLI

Run the CLI without a command:

```bash
pingroom
```

Choose QR pairing. Scan the code with PingRoom, review the separate robot identity, choose its home Room, and grant access to one Room, several Rooms, or all Rooms.

The home Room has a specific job: it is where direct Questions and Handoffs for this robot arrive. The wider Room grant controls where the robot may perform Room-scoped actions. They are related settings, not interchangeable ones.

Pairing itself sends no Ping. Installing the phone app also grants nothing on its own; the connection exists only after you claim the robot and approve its access.

## Choose the narrowest useful grant

Use the smallest grant that fits the work:

| Grant         | Good fit                                                        | Tradeoff                                                      |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
| One Room      | One project, household, or alert stream                         | You must update the grant before the CLI can work elsewhere   |
| Several Rooms | A local tool serving a known set of projects                    | Review the selected set when projects change                  |
| All Rooms     | A trusted personal tool that genuinely needs account-wide reach | New Rooms may become reachable without another selection step |

An instruction in a script does not expand this grant. A Room outside it should fail with `room_not_granted`, and the human can change access under Connected Agents in PingRoom.

In the illustration, [Pingo the Pigeon](/Pingo) watches the humans make that choice. That is the accurate division of responsibility: Pingo is a fictional editorial companion, while a person reviews and approves every connection.

![Two PingRoom avatars choose among three miniature Room doors while Pingo observes from the end of the table.](/blog/pair-pingroom-cli-without-copying-a-token-1.webp)

## Verify the connection without reading the credential

Start with a read-only command:

```bash
pingroom rooms list --json
```

A successful response proves that the CLI can use its saved credential and read the Rooms inside its grant. It does not send a Ping.

If you also want to test the phone round-trip, run:

```bash
pingroom activate
```

Activation is optional and separate from pairing. It sends one test Question to the robot's home Room and waits for the supported phone flow to finish. A successful answer confirms that this CLI observed the completed activation; it is not a general guarantee that every future notification banner will appear. Phone permissions, Focus settings, network conditions, and Room preferences still matter.

Free accounts currently include 20 successful quota-gated connected-agent operations per day. That allowance covers agent broadcasts, action triggers, Questions, Handoffs, approvals, and Inbox activation together. It is not a daily cap on Pings sent by people in the app. Pro lifts the connected-agent allowance.

## Where the local state lives

The CLI stores the connection at `~/.pingroom/credentials.json` by default. The file is created with owner-only permissions inside a private state directory. Treat it as a credential anyway:

- do not print or commit it
- do not copy it into a project `.env` file
- give each service user a separate `PINGROOM_HOME` if several system users share a host
- use `pingroom logout` when this computer should forget the connection

An explicit `PINGROOM_TOKEN` always outranks the saved credential. That precedence keeps CI configuration independent, but it can also make a local command use a different identity than you expect. Check your environment before debugging a surprising Room list.

## Use the right setup for each machine

| Environment                                         | Recommended setup                                                                                                                                  |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your interactive laptop                             | Run `pingroom` and claim the QR pairing in the app                                                                                                 |
| Headless machine with a human available to claim it | Run `pingroom pair`, keep the process open, and use its one-time claim link before it expires                                                      |
| CI runner                                           | Supply a protected `PINGROOM_TOKEN` or use a Room webhook; do not start an interactive pairing prompt                                              |
| MCP client                                          | Follow the separate [MCP connection guide](/blog/connect-mcp-client-to-pingroom), which uses browser authorization rather than this CLI credential |

For the complete scope and revocation contract, keep the [Agent Access documentation](/documents/agent-access) as the authority. The [developer directory](/developers) links the CLI, MCP, SDK, and webhook surfaces so you can choose the one that matches the job.

Once the CLI is paired, the next useful step is to [create a private Room from the command line](/blog/create-a-pingroom-room-from-the-command-line) or list the Rooms already in its grant.