How to Create a PingRoom Room From the Command Line

Use pingroom rooms create to create a minimal private Room from the command line. Pick an icon from the live catalog, provide a name and hex color, inspect the returned Room, save its invite code as your local default, and send one harmless test Ping.

This is a builder workflow for the public PingRoom CLI. If you have not connected it yet, start with the token-free pairing guide.

Check the prerequisites

You need public CLI 0.13.0 or later and a connected agent credential with:

• pingroom:rooms:read to browse and inspect Rooms
• pingroom:rooms:write to create a private Room
• pingroom:broadcast:send for the final test Ping

New full-access CLI pairings include the ordinary management scopes. A legacy partial credential may return insufficient_scope; reconnect once to review and replace that grant instead of working around it with a human app session.

Private Room creation does not require Pro. A free account can create up to five Rooms. Creating a Room does not invite anyone or send a notification.

1. Choose a current icon id

Room icons use catalog ids, not emoji. Browse the current catalog before you create the Room:

pingroom rooms icons

For this example, use the documented bell id. If the catalog on your account differs, choose an id from the command output rather than guessing.

2. Create the private Room

Run:

pingroom rooms create \
  --name "Build Alerts" \
  --icon bell \
  --color "#e33122" \
  --json

The private create contract is deliberately small: name, icon id, and color. Options such as public handle, description, and discovery location belong to the separate public-Room path and its additional consent scope.

Copy the invite_code from the JSON response into a shell variable for the remaining checks:

ROOM_CODE="replace-with-the-returned-code"
pingroom rooms get "$ROOM_CODE" --json

The second command should return the same Room identity. Stop if the name, icon, or code is not the one you just created.

3. Save the Room as your local default

If this terminal should use the new Room when a command omits --room, save it locally:

pingroom config set default_room "$ROOM_CODE"
pingroom config get default_room

The command-line precedence is explicit:

--room > PINGROOM_ROOM > default_room > paired home Room

That makes default_room a convenience, not an access grant. The robot still cannot reach a Room outside the grant approved by its human owner.

4. Send one harmless test Ping

Use a message that is clearly a setup check:

pingroom ping -m "Build alert Room connected"

A successful command means the server accepted the Ping. It does not prove that every eligible phone displayed a banner. Verify the Ping in Room history and, when phone display matters, check notification permission, Focus settings, Room mute state, device connectivity, and the recipient app.

The first Ping uses one connected-agent operation. Free accounts currently include 20 successful quota-gated agent operations per day; Pro lifts that agent allowance. This limit is separate from ordinary human Pings in the app.

Read common failures as policy, not syntax

At the workbench in these illustrations, Pingo only inspects the finished clay pieces. He does not create Rooms, hold credentials, invite people, or send Pings. Those actions stay with the human-authorized CLI and the people responsible for the Room.

Bring people in deliberately

An invite code is access to a private Room. Share it only through a channel you trust, and review membership as the group changes. The CLI creation step does not authorize an agent to add people on your behalf.

For the people-side membership and signal design, use the private alert group guide. For the stable builder contract, scopes, and limits, use the Agent Access documentation.