rooms.sh CLI

Create, scaffold, publish, and debug rooms.sh room projects from the terminal.

Quick Start

Check your login state:

npx rooms.sh@latest whoami

If you are not logged in, connect the CLI:

npx rooms.sh@latest login

Create a room on rooms.sh and keep the returned roomId:

npx rooms.sh@latest create --name "Cozy Reading Nook" --json

Initialize a local project with that roomId and the room name:

npx rooms.sh@latest init --id <room-id> --name "Cozy Reading Nook"

The --name value is slugged and used for both the generated project directory and the package.json package name. To choose a different filesystem path, pass --directory:

npx rooms.sh@latest init --id <room-id> --name "Cozy Reading Nook" --directory ./my-room

Then build and publish from the generated project:

cd cozy-reading-nook
cat .agents/skills/room-builder/SKILL.md
npm run typecheck
npm run publish:room

Generated Project

rooms.sh init creates a TypeScript room project with:

• room.ts: the room definition built with @rooms.sh/sdk.
• package.json: scripts for npm run typecheck and npm run publish:room.
• .rooms/project.json: non-secret room metadata such as roomId and origin.
• .agents/skills/room-builder/SKILL.md: local instructions for agents building rooms.

Secrets are not written to the project. The CLI reads credentials from ~/.rooms/settings.json after login, or from ROOMS_API_KEY when that environment variable is set.

Commands

rooms.sh login [--origin <url>] [--no-browser]
rooms.sh logout [--origin <url>] [--all]
rooms.sh whoami [--origin <url>] [--json]
rooms.sh rotate [--origin <url>]
rooms.sh create [--origin <url>] [--name <room display name>] [--json]
rooms.sh init --id <room-id> [--name <room-name>] [--origin <url>] [--directory <path>] [--skip-install]
rooms.sh publish [entry-file] [--room <room-id>] [--origin <url>] [--project <tsconfig>]

Debugging

After publishing, open a debug session in a browser tab:

rooms.sh debug open --json

Keep that tab open, then inspect or capture the room:

rooms.sh debug status --session <debug-session-id>
rooms.sh debug scene --session <debug-session-id> --json
rooms.sh debug snapshot --session <debug-session-id> --camera <camera-id> --out ./snapshot.png
rooms.sh debug focus --session <debug-session-id> --item <item-id> --angle iso
rooms.sh debug item --session <debug-session-id> --item <item-id> --json
rooms.sh debug item-snapshot --session <debug-session-id> --item <item-id> --angle front --out ./item.png
rooms.sh debug unfocus --session <debug-session-id>

Debug commands should run one at a time. Wait for each command to finish before starting the next one.

Local Development

Use --origin to point the CLI at a non-production rooms.sh origin:

rooms.sh login --origin http://localhost:3000
rooms.sh create --origin http://localhost:3000 --name "Local Room" --json
rooms.sh init --origin http://localhost:3000 --id <room-id> --name "Local Room"

You can also set ROOMS_ORIGIN to avoid passing --origin repeatedly.