# How to Create a PingRoom Room From the Command Line

> Choose a current icon, create a private Room with the public CLI, save its invite code as your local default, and send one harmless test Ping.

- Published: 2026-10-18
- Author: PingRoom
- Category: Developers
- Topics: PingRoom CLI rooms, create notification room, AI agent notification API
- Canonical: https://pingroom.io/blog/create-a-pingroom-room-from-the-command-line
- Cover image: https://pingroom.io/blog/create-a-pingroom-room-from-the-command-line-cover.webp
- Cover description: Two PingRoom avatars assemble a miniature private Room doorway from wood and clay while Pingo inspects the result.

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](/blog/pair-pingroom-cli-without-copying-a-token).

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

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

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

```bash
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.

![Two PingRoom avatars inspect one miniature Room doorway and a single clay Ping token while Pingo stands beside the result dish.](/blog/create-a-pingroom-room-from-the-command-line-1.webp)

## 3. Save the Room as your local default

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

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

The command-line precedence is explicit:

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

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

| Error                                        | What to check                                                                                                    |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `insufficient_scope`                         | Reconnect the legacy partial credential and review the requested scopes                                          |
| `room_not_granted`                           | Add the Room under Connected Agents in the app; changing `default_room` cannot expand access                     |
| Room quota error                             | Review the five-Room free limit or the account plan before creating another Room                                 |
| `recipient_not_ready` on a later direct test | Install or update PingRoom, sign in, enable notifications, then use `pingroom activate` to retest the phone flow |

At the workbench in these illustrations, [Pingo](/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](/blog/create-private-alert-group). For the stable builder contract, scopes, and limits, use the [Agent Access documentation](/documents/agent-access).