Install the CLI
For a container demo, a bigger build, a terminal or Claude Code: roomi on your machine.
On this page
roomi is the command-line tool that checks, rehearses and publishes a demo from the folder it lives in. This page covers when you need it, what it needs on your machine, how to run it, how it signs in as you, and where it keeps the credential it signs in with.
When you need it
You may not. The connector deploys a static demo from a chat with Claude, with nothing to install, and most people start there. Install roomi when:
- the demo has a server. A container demo deploys only from your machine.
- the build is bigger than a chat carries, more than 200 files or 3 MB.
roomitakes a static build of at most 5,000 files, 32 MB per file and 256 MiB unpacked. - you work on the demo in its repository with Claude Code, through the plugin.
- you want links and pages from a terminal, or a deploy from a script.
When one of those applies, the connector says so. In Claude Code, Claude offers to run the install for you, and runs it only on your yes; in a chat, it gives you the commands. Either way, roomi login is yours to approve in your browser.
Run it
The CLI is published on npm as @getroomi/cli, and installs the roomi command. Run it without installing anything:
npx @getroomi/cli --helpor install it once, which gives you the command roomi:
npm install -g @getroomi/cli
roomi --helpThese docs write the command as roomi throughout, so roomi login means npx @getroomi/cli login if you did not install it. The install also gives you pitch, the command's name before Roomi: pitch deploy still works, and does exactly what roomi deploy does. It talks to Roomi, https://api.getroomi.com, with nothing to configure.
Requirements
| What | Why |
|---|---|
| Node 24 | roomi requires Node 24 or later (node --version); npm warns if yours is older. It is also the Node every container demo runs on. |
| gitleaks | Every rehearsal scans the project, and the build it makes, for secrets. If gitleaks cannot run, the deploy stops rather than calling an unscanned build clean. On a Mac: brew install gitleaks. |
| Docker, running | Only for a container demo. roomi deploy builds your Dockerfile and runs the result on the platform's own runner, locally. A static demo does not need Docker. |
| A browser | roomi login, roomi open and roomi dev open your browser with the Mac's open command (xdg-open on Linux, start on Windows). On a Mac the token goes in the Keychain; elsewhere in a file only you can read. See Other systems. |
| Your package manager | For a static demo with a build script, roomi deploy runs it with the package manager your lockfile names: pnpm, yarn, bun, or npm if there is no lockfile. |
If gitleaks is installed somewhere that is not on your PATH, set PP_GITLEAKS to its full path.
Create an account
Sign in at app.getroomi.com with Continue with GitHub or Continue with Google. There is no separate sign-up: the first time you sign in, your account is made, with a workspace of your own on the Free plan. Once you are in, you can add a passkey in Settings and sign in with it from then on.
Sign in
roomi loginroomi asks the platform for a one-time code, prints where to enter it, and opens that page in your browser:
Open https://app.getroomi.com/device and enter the code K7QXDRPM
(or go straight to https://app.getroomi.com/device?user_code=K7QXDRPM)
Opened it in your browser.
Waiting for you to confirm…If the browser did not open, open the address yourself. If you are not signed in to the app there, it asks you to sign in first and brings you back. Enter the code, or check the one already filled in against your terminal, and choose Yes, connect roomi. Only approve a code your own roomi login printed, moments ago: approving someone else's code signs their machine in as you.
The terminal then says:
Signed in. The token is in the macOS Keychain.A code lasts 30 minutes. If it runs out before you approve it, roomi says the code expired and stores nothing; run roomi login again for a new one. If you choose No, deny it in the browser, it says Sign-in was denied in the browser. and stores nothing.
This is the OAuth device authorization flow (RFC 8628): the terminal never sees your password or your GitHub or Google sign-in, only the session token the platform grants once you approve.
Check who you are
roomi whoami Priya Shah <priya@example.com> on https://api.getroomi.comIt names the account and the platform the token is for. If there is no token it says you are not signed in, and if the stored token has expired, or its session was ended, it says the stored token is no longer valid. Either way, roomi login signs you in again.
Sign out
roomi logoutThis ends the session on the platform, so the token stops working wherever a copy of it is, and then deletes it from the Keychain (or the credentials file). If the platform cannot be reached, roomi says so and removes the token from your machine anyway.
Where the token lives
On a Mac, the token is kept in the macOS Keychain under the service name pitch-product-cli, and nowhere else: never in a file, never in your project, never printed. It reaches the Keychain on standard input rather than as a command-line argument, so no other process can read it from the process list.
On Linux, Windows and anywhere else, it is kept in credentials.json beside your settings (~/.config/pitch/credentials.json, under XDG_CONFIG_HOME when that is set): a file only you can read and write (0600), in a folder only you can open (0700). If anyone else can read the file, roomi refuses to use it and says how to fix it. Windows has no such permissions on a file: there it is as private as your user folder.
There is one entry per platform address. A token for one platform never stands in for another, so signing in to a local platform while developing does not touch the token for the hosted one.
Scripts and CI
For a script or CI, make an API token in the app (Settings → Claude & CLI → API tokens) and set ROOMI_TOKEN:
ROOMI_TOKEN=roomi_... roomi deploy --commitroomi uses ROOMI_TOKEN instead of the stored token for that one run, and never writes it anywhere. While it is set, roomi login and roomi logout refuse, with ROOMI_TOKEN is set, so roomi is not keeping a token of its own. Unset it to sign in or out., so the stored token is never bypassed without you knowing. PP_TOKEN, its older name, still works.
An API token acts as you in one workspace, and reaches only what roomi does: it cannot change billing, your account or the team. It is shown once when it is made; revoke it in Settings when it is no longer needed, or the moment it might have leaked. CLI has the details. Keep it in your CI system's secret store, never in a repository.
The header for other programs
roomi auth headerThis prints the one line a program needs to call the platform as you, and nothing else:
{"Authorization":"Bearer ..."}It is how the Claude Code plugin signs its connection in to a platform running on your own machine (Deploying from Claude). Because it prints your token, it refuses when its output is a terminal a person is looking at, with This prints your token. It is meant to be read by a program; pass --print to see it here. Pass --print only if you mean to see it.
Choosing the platform
roomi talks to https://api.getroomi.com. roomi whoami says which platform it is using, and where that came from:
API https://api.getroomi.com (the default)You only change it to work on Roomi itself, against a platform running on your own machine. roomi config set api <url> keeps the address for you, and roomi config unset api goes back to production; PP_API overrides both for one shell or script. CLI has the details.
roomi config set api http://127.0.0.1:8200Environment variables
| Variable | What it does |
|---|---|
PP_API |
The platform's address, for this run, ahead of roomi config. Unset, roomi uses https://api.getroomi.com. |
PP_CONFIG |
A settings file to use instead of ~/.config/pitch/config.json. |
ROOMI_TOKEN |
A token to use for this run instead of the stored one: an API token from Settings. Never stored. |
PP_TOKEN |
The older name for ROOMI_TOKEN, still read. |
PP_GITLEAKS |
The path to gitleaks, when it is not on your PATH. |
PP_KEYCHAIN |
A keychain file to keep the token in, instead of your default keychain (macOS only). |
PP_HEALTH_TIMEOUT_MS |
How long a container rehearsal waits for the platform's runner to open, in milliseconds. The default is 60000. |
Other systems
roomi login works on Linux and Windows as it does on a Mac: it opens your browser, and keeps the token in the credentials file described in Where the token lives. Where there is no browser at all, such as a server or CI, use an API token in ROOMI_TOKEN.
roomi login, roomi open and roomi dev print the address they open as well as opening it, so where the browser cannot be opened you can copy the address from the terminal.
Next
- Quickstart: a static demo in a room.
- Your first container demo: a demo with a server.
- CLI: every command and flag.