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.
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:
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:
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 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.
Verify the connection without reading the credential
Start with a read-only command:
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:
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
.envfile - give each service user a separate
PINGROOM_HOMEif several system users share a host - use
pingroom logoutwhen 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, which uses browser authorization rather than this CLI credential |
For the complete scope and revocation contract, keep the Agent Access documentation as the authority. The developer directory 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 or list the Rooms already in its grant.
PingRoom
Short-form communication.
