CLI
Every roomi command and flag.
On this page
- How roomi works
- Rehearse, then commit
- What acts at once
- Which project a command acts on
- Flags
- Output
- Commands
- roomi login
- roomi logout
- roomi whoami
- roomi config
- roomi auth header
- roomi init
- roomi validate
- roomi dev
- roomi deploy
- roomi promote
- roomi pages list
- roomi pages add
- roomi pages remove
- roomi pages push
- roomi link
- roomi links
- roomi link copy
- roomi open
- roomi community status
- roomi community card
- roomi community list
- roomi community withdraw
- roomi logs
- roomi rollback
- roomi --help
- Environment
- API tokens
- What roomi needs
- Exit status
roomi is the command line for Roomi. It writes and checks
pitch.json, rehearses a deploy on your own machine, publishes exactly what
the rehearsal checked, and makes a private link for each viewer. This page
lists every command and every flag it takes.
The CLI is published on npm as roomi, and needs Node 24 or
later. Run it with npx @getroomi/cli <command>, or install it with
npm install -g @getroomi/cli and run roomi <command> (the install also gives you
pitch, the command's name before Roomi, which still works the same). It talks to
Roomi, https://api.getroomi.com, unless you point it elsewhere
(roomi config). Install the CLI covers
setting it up.
Most people start with the connector, from a chat with Claude,
and come to roomi for a container demo, a build bigger than a chat carries,
work in a repository with Claude Code, or a script. Install the
CLI says when, and the connector says so too.
How roomi works
Rehearse, then commit
roomi deploy on its own is a rehearsal. It checks pitch.json, asks the
platform whether it would take the project (when you are signed in), scans the
project for secrets, builds the demo, runs it and requires it to answer, runs
every step of the story on that running copy, and prints what would go live.
Nothing of the demo leaves your machine. roomi deploy --commit does the same and then
publishes exactly the artefact the rehearsal just checked. roomi deploy --commit --preview sends it as a preview instead, which only you and your
team see; roomi promote rehearses making it live, and roomi promote --commit does it.
roomi validate is the quick half of the rehearsal: it checks pitch.json
and what it names without building or running anything.
Every roomi community command that changes something rehearses the same
way: it reads, runs the pre-flight check (and, for a listing, the listing
checks, writing nothing), and prints what would change.
--commit makes the change.
What acts at once
roomi link, roomi pages add, roomi pages remove and roomi pages push
are not rehearsed. Each is one small change, and each prints what it did and,
where there is one, the id that undoes it. The one change that would lose
something, replacing a page's content with a file of the same title, is
refused unless you pass --replace.
Which project a command acts on
A project is named by its slug, the part of the room's address before the
domain. Without --project, roomi makes the slug from the name in the
pitch.json in the current folder: lower-case, every run of other characters
turned into one hyphen, anything before the first letter dropped, at most 40
characters. "Corner for Bullring" is corner-for-bullring.
--project <slug> names the project instead. roomi deploy, roomi link,
roomi open, every roomi pages command and every roomi community command
take it.
Flags
Every flag is read by one parser before any command runs, so:
- a flag roomi does not know stops it with an error before anything happens;
- a flag that takes a value and is given none stops it the same way;
- a flag a command does not use is ignored.
roomi validate --commitvalidates.
-y is short for --yes, and -h for --help.
Output
What roomi reports goes to standard output; a refusal or a failure goes to
standard error. A rehearsal prints one line per check, starting ok, FAIL
or note:
ok manifest: pitch.json validates (container, 4 apps, a 5-step story)
ok secrets: gitleaks scanned the project and found nothing
ok build: docker build --platform linux/amd64 -t pp-build/corner-for-bullring:latestA note never stops anything. A FAIL stops the command and says why. A
problem in pitch.json names where it is and prints the address of the docs
that explain it.
Errors lists every one.
Commands
roomi login
roomi loginSigns roomi in to the platform as you. It asks the platform for a code, prints
an address and the code, opens that address in your browser, and waits while
you sign in to the app and confirm the code. If the browser cannot be opened,
open the printed address yourself. When you do, the platform issues a token and
roomi stores it, one per platform address, and never prints it. On a Mac it
goes in the macOS Keychain. On Linux, Windows or anywhere else it goes in
credentials.json beside your settings (~/.config/pitch/credentials.json),
a file only you can read and write, in a folder only you can open. roomi
refuses to use that file if anyone else can read it, and says how to fix it.
This is the device sign-in of OAuth (RFC 8628). When the platform gives one, roomi also prints an address with the code already filled in. roomi polls at the interval the platform asks for, slows down when told to, and gives up when the code expires.
Takes no flags.
Open https://app.getroomi.com/device and enter the code <code>
Opened it in your browser.
Waiting for you to confirm…
Signed in. The token is in the macOS Keychain.Off a Mac, the last line names the file instead.
Exit status: 0 once signed in. 1 when sign-in could not start, was denied in the browser, failed, or the code expired before it was confirmed.
roomi logout
roomi logoutEnds the session on the platform, so the token stops working, and removes it from the Keychain (or the credentials file). If the platform does not confirm the sign-out, roomi says so and removes the token from this machine anyway.
An API token is not a session, so signing out cannot end it: roomi removes it from this machine and says to revoke it in the app's Settings to stop it working anywhere else.
Takes no flags. Prints Signed out., or Not signed in. when there was no
token. Exit status: 0.
With ROOMI_TOKEN or PP_TOKEN set, roomi logout ends that token's session
on the platform, then stops with an error, because there is no stored token to
remove, and exits 1.
roomi whoami
roomi whoamiSays which platform roomi is talking to and where that came from, then asks it who the token belongs to, and prints their name, email and workspace, and whether it is a sign-in or an API token:
API https://api.getroomi.com (the default)
Priya Shah <priya@example.com> in Priya's workspace on https://api.getroomi.com
Signed in with roomi login; the token is in the macOS Keychain.Takes no flags. Exit status: 0 when the token is valid; 1 when there is no
token, or the platform no longer accepts it (run roomi login again, or make
another API token).
roomi config
roomi config
roomi config get api
roomi config set api <url>
roomi config unset apiWhich platform roomi talks to, kept for you in ~/.config/pitch/config.json
(under XDG_CONFIG_HOME when that is set), readable by you alone. roomi talks
to https://api.getroomi.com unless this says otherwise, or PP_API
does, which wins. You need it only to work on Roomi itself, against a
platform running on your own machine. set api takes an origin only, such as
http://127.0.0.1:8200 for a platform on your own machine; plain http is
refused anywhere else. Your sign-in is kept per platform, so after switching,
roomi whoami says whether you are signed in there. A settings file roomi
cannot read stops every command, rather than being ignored.
Acts at once and says what it did. Exit status: 0; 1 for an address roomi refuses.
roomi auth header
roomi auth header [--print]Prints the stored token as the one JSON object an HTTP client reads as a header, and nothing else on standard output:
{"Authorization":"Bearer <token>"}The Claude Code plugin reads it this way to call the connector as you, and a script can use it to call the HTTP API.
| Flag | What it does |
|---|---|
--print |
Prints the header even when standard output is a terminal. Without it, roomi refuses to print a token to a screen a person is looking at, and prints it only into a pipe or a file. |
Exit status: 0 when the header was printed. 1 when standard output is a
terminal and --print was not given, or when roomi is not signed in.
roomi init
roomi init [--print] [--force] [--yes] [--kind container|static] [--output <dir>]
[--health <path>] [--device <app>=<device>]…
roomi init --update [--print]Reads the repository in the current folder and writes a first pitch.json,
and beside it pitch.README.md, which says what roomi found and shows the
shape of a story on your own apps, and PITCH.md, the guide for a coding
agent working in the repository. It adds one line pointing at PITCH.md to
the end of AGENTS.md and CLAUDE.md (making an AGENTS.md if there is
neither), unless the file already mentions it. It never changes your code
(Build with your AI agent).
It reads the name from package.json; whether the build is a server (a
Dockerfile at the root) or a folder of files, and for a folder, where the
build writes it (a Next export's distDir, read from next.config with the
variables the build script sets: Static demos);
the apps and the path each is
served under; the device each is for, from its name or its layout; a health
route, a reset route and demo routes it can call; and the Markdown and HTML
files in docs/ and documentation/, which it lists as pages. It does not
write a story: that is how you tell the demo, and it cannot know it.
It finds a server's routes in its src/ and server/ folders and in the
files at its root (an index.js or a server.js), as calls such as
app.get('/healthz', …); in a Next app's route handlers
(app/healthz/route.ts, or under src/app/); and in a TanStack Start server
route (createFileRoute('/healthz') with server.handlers in src/routes/).
Two things it says before anything it asks, and changes nothing for:
- A
Dockerfilewhose last stage is not built on Node (FROM python:3.12-slim, say). Container demos run on Node 24, and only/appcomes from your image, so a server that needs another runtime cannot start (Container demos). - A Next export without
trailingSlash: true. Next then writes each page as a.htmlfile (patients.html), and a tour step opens a page as a folder (patients/index.html), so no step could open anything but the home page. Add it besideoutput: 'export'innext.config(Static demos).
What it cannot tell, it asks, after printing any note that explains why.
With nobody at the terminal to ask (Claude Code, a script), it stops, names
the flag that answers each question, and writes nothing. A repository whose apps each run on their own port is not one origin
yet; roomi init then prints the change that would make it one, and writes
nothing.
| Flag | What it does |
|---|---|
--print |
Prints pitch.json, pitch.README.md and PITCH.md, and the line it would add to AGENTS.md or CLAUDE.md, instead of writing them. Writes nothing, and runs even when the files exist. |
--force |
Replaces pitch.json, pitch.README.md and PITCH.md if they exist. Without it, roomi stops rather than overwrite any of them. |
--update |
Rewrites PITCH.md from the docs as they are now, and touches nothing else. Says so and writes nothing when it is already current. |
--yes, -y |
Takes the suggested answer to every question that has one (the output folder dist, the health path /healthz). A question with no suggested answer is still asked, or named: a Next export's folder, when roomi cannot read its distDir, is one. |
--kind <kind> |
container (a server built from the Dockerfile) or static (a built folder of files). Anything else is refused. |
--room <type> |
standard or immersive: the type of room. immersive writes "room": "immersive" into pitch.json; standard writes no room, which is a standard room. Without it roomi asks (--yes takes standard), and with nobody at the terminal it writes no room. Anything else is refused. An immersive room needs Team. |
--output <dir> |
The folder a static build writes, relative to the project. |
--health <path> |
The path a container build answers on once it is up. |
--device <app>=<device> |
The device the room frames an app in: phone, tablet, laptop, screen or none. Give it once per app. An app id roomi did not find, or a device that is not one of these, is refused. A flag overrides what roomi read. |
roomi init --print
roomi init --kind static --output build --yes
roomi init --device client=phone --device hq=laptop --forceExit status: 0 when the files were written (or printed). 1 when either file
exists without --force, the repository is not one origin, a flag was
malformed, a question went unanswered, or the draft did not validate.
The fields it writes are in pitch.json.
roomi validate
roomi validateChecks everything that can be known without building: pitch.json against
the schema, fields roomi does not know, the story, the pages on disk, the
static output folder, and the container Dockerfile as far as it can be read.
It builds, runs and sends nothing.
Each problem names where it is (story[1].app) and the docs page that
explains it. A problem is something roomi deploy would refuse; a note is
advice and stops nothing.
pitch.json does not validate: 1 problem
story[1].app: step "moment" happens in app "coach", which apps does not declare
https://getroomi.com/docs/pitch-json#field-story-appTakes no flags. Exit status: 0 when nothing would stop a deploy, notes or not; 1 when there is at least one problem. Every check is in Errors.
roomi dev
roomi dev [--port <n>] [--target <url>] [--static] [--no-open] [--pull]Serves the real pitch room on your machine, around the demo as you build it:
the same page, script and stylesheet the platform serves a viewer, with your
own dev server on the stage. Run it beside npm run dev (or next dev,
vite, your server), and it opens the room in your browser.
Preview locally walks through it.
- The room is at
http://<slug>.localhost:8300and the demo inside it athttp://<slug>--demo.localhost:8300: two addresses, as a room and its demo are. Both are this machine only; roomi dev listens on 127.0.0.1. - Everything in the room works: the tour, with each step's page, frame and ring; Read more; the next steps; comment mode, with its screenshots. None of it is recorded or sent. The room says Local preview — not saved, and comments are listed in roomi dev's panel on the room, and printed here.
- A container build's calls (a step's
run, the scenarios, the reset) are made on your dev server, as the room makes them on a viewer's copy. pitch.json, its pages andpitch.brand.jsonare watched. When they change, the room redraws. Your dev server's own hot reload shows through the stage as it always does.- What is wrong is counted on the room and listed in its panel, and printed
here, in
roomi validate's words and the rehearsal's: a problem inpitch.json, a page file missing, a step's page your dev server answers with a 404, a call the demo refused.
| Flag | What it does |
|---|---|
--port <n> |
The port the room and the demo are served on. The default is 8300. |
--target <url> |
Your dev server, such as http://127.0.0.1:3000. Without it, roomi dev reads the port from package.json's dev, start, serve and preview scripts (the port a script names, or its tool's default: 3000 for next dev, 5173 for Vite), then tries the common dev ports. Only an address on this machine is accepted. |
--static |
Serves a static build's output folder (output) instead of a dev server, as the platform serves a static build: each path, or the index.html inside it. Build it first. |
--no-open |
Leaves the browser alone. --open, opening it, is the default. |
--pull |
Draws the brand name, colour and room theme saved in your account instead of pitch.brand.json and pitch.theme.json. Read only, and only when signed in. Local preview |
ok roomi dev: no problems
room http://columbus.localhost:8300
demo your dev server at http://127.0.0.1:3000 (`dev` in package.json runs next dev), framed at http://columbus--demo.localhost:8300
Local preview: nothing is recorded or sent, and comments stay on this machine.
pitch.json, its pages, pitch.brand.json and pitch.theme.json are watched; the room redraws when they change.
Opened it in your browser.
Ctrl-C stops it.roomi dev needs a pitch.json that validates to start; once it is running, a
pitch.json that stops validating leaves the last room on screen and says
why. It never signs in and never talks to the platform. Exit status: 0 when
stopped with Ctrl-C; 1 when it could not start (no pitch.json, the port in
use, --static on a container build, a --target that is not on this
machine).
roomi deploy
roomi deploy [--commit] [--project <slug>] [--note <text>]Rehearses the deploy and, with --commit, publishes it. In order:
- Validates
pitch.jsonasroomi validatedoes. A problem stops here. - Checks you are signed in, with
--commitonly, before anything slow. - Asks the platform whether it would take the project, before anything
slow, when you are signed in: two reads, and nothing of the demo is sent.
A project you have is deployed over. A new address the plan has no room
for stops here, with the platform's own refusal (the plan that allows
more), the projects you could delete in the app, and
--project <slug>to deploy over one of them instead. Signed out, nothing is asked and the rehearsal says so;--commitasks. - Scans the project for secrets with gitleaks. Your own
.gitleaksignoreis not read, so a finding cannot be waved through from inside the build. - Builds.
- A static build runs the
buildscript inpackage.json(with pnpm, yarn, bun or npm, by the lockfile), requiresindex.htmlin the output folder, scans the output for secrets, and packs it. - A container build needs Docker running. It builds your
Dockerfileforlinux/amd64, reads how the image starts from itsCMDandENV(unlesspitch.jsonsetsrun), copies/appout of the image as the bundle, and scans the bundle for secrets.
- A static build runs the
- Runs it, for a container build: starts the platform's own runner on
loopback, hands it the bundle as the platform will, and requires the
healthpath to answer. roomi's own calls to the demo during the rehearsal go to that copy on loopback, and nowhere else. - Runs the story: every step's calls, in order, on that copy, then the page the step opens. A step whose call the demo refuses, or whose page does not answer, fails the deploy. On a static build, every page a step opens must be a file in what was built.
- Prints what would go live: the project, the artefact's size, the apps, how it starts, the controls, the story and the pages.
Without --commit it stops there, and nothing of the demo has left the machine. With
--commit it goes on:
- Creates the project if its slug is new.
- Uploads the artefact, registers the build, uploads every page
pitch.jsonlists, and makes the build live. A page that will not upload leaves the previous build live. - Prints the room's address where it opens (a listed room), or else the
next steps the plan allows: on Free, which has no viewer links,
roomi opento see it and listing it from the app to show anyone; on a paid plan,roomi link <name>for each viewer's own link.
With --commit --preview, step 10 is different: the build is uploaded and
registered as the project's preview, and it does not go live. No viewer
link, public address or Community card shows it; you and your team see it with
roomi open --preview, or Preview on the project in the app, until it is
made live. A newer preview replaces the last one. The room's pages are shared
with the live room, so a preview sends none of the pages pitch.json lists:
roomi pages push sends them when you want viewers to have them. The listing
checks of a listed project run when the preview goes live, not before.
| Flag | What it does |
|---|---|
--commit |
Publishes what the rehearsal checked. Without it, nothing is sent. |
--preview |
With --commit, sends the build as a preview only you and your team see, instead of making it live. Viewers keep the live build until roomi promote makes this one live. |
--project <slug> |
Deploys to this project instead of the one named by pitch.json. Needed when the name makes no usable slug (fewer than three characters). |
--note <text> |
A note kept with the build, up to 200 characters. |
roomi deploy
roomi deploy --commit --note "New onboarding flow"
roomi deploy --commit --preview --note "New pricing, for the team first"
roomi deploy --commit --project corner-demo ok project: "corner-for-bullring" is new, and the plan has room for it (2 of 5 projects)
…
What would go live: project "corner-for-bullring" at https://api.getroomi.com
Corner for Bullring — container, health /healthz
artefact 41.2 MB (43198464 bytes)
apps:
client /app phone Bullring (opens first)
hq /hq/ laptop Corner HQ
starts with: node server.js
story:
1 arrive in client "Where it starts"
Rehearsal only: nothing has left this machine. `roomi deploy --commit` publishes exactly this.Exit status: 0 when the rehearsal passed (and, with --commit, the build is
live, or with --preview it is the preview). 1 at the first thing that stops
it. Every stop is in Errors.
roomi promote
roomi promote [--commit] [--project <slug>]Makes the project's preview the live build. Without --commit it is a
rehearsal: it names the build being previewed and the one live now, and
changes nothing. With --commit the preview goes live, as a deploy does:
everyone opening a link gets it from their next page load, a listed project's
checks run first, and it stops being the preview. Rolling back afterwards is
the same as for any build: an earlier one, made live again from the app's
Builds tab.
preview 9c41… (Corner for Bullring, "New pricing, for the team first")
live 77b0… (Corner for Bullring)
Rehearsal only: nothing changed. `roomi promote --commit` makes the preview live for every viewer.| Flag | What it does |
|---|---|
--commit |
Makes the preview live. Without it, nothing changes. |
--project <slug> |
The project whose preview it is, instead of the one named by pitch.json. |
Exit status: 0 when the rehearsal passed or the preview is live. 1 when nothing is being previewed, roomi is not signed in, or the project does not exist.
roomi pages list
roomi pages list [--project <slug>]Lists the room's pages in the order the room shows them, with each one's
position, id, kind (markdown or html) and title. Exit status: 0; 1 when
roomi is not signed in or the project does not exist.
roomi pages add
roomi pages add <file.md|file.html> [--title <title>] [--replace] [--project <slug>]Adds one page to the room. Viewers see it at once. The file is a Markdown
(.md) or HTML (.html) file of up to 2,000,000 characters. Its title is
--title, else its first # heading (Markdown) or its <title> (HTML), else
its file name; a title is 1 to 80 characters.
If the room already has a page with that title, roomi changes nothing and
says so, unless you pass --replace.
| Flag | What it does |
|---|---|
--title <title> |
The page's title, instead of the one in the file. |
--replace |
Replaces the content of the page that already has this title. |
--project <slug> |
The project to add it to. |
Added "Why Corner" (markdown) to corner-for-bullring as page 7c5e0a9b-41d2-4f86-b3e7-2a9d6c1f8e04.
Viewers of https://corner-for-bullring.getroomi.app see it now. `roomi pages remove 7c5e0a9b-41d2-4f86-b3e7-2a9d6c1f8e04` takes it out.Exit status: 0 when the page was added or replaced; 1 otherwise.
roomi pages remove
roomi pages remove <id> [--project <slug>]Takes a page out of the room by its id, which roomi pages list shows. If
pitch.json here lists the same page, roomi says so: the next deploy uploads
it again unless you take it out of pages. Exit status: 0 when the page was
removed; 1 when there is no page with that id.
roomi pages push
roomi pages push [--project <slug>]Uploads every page pitch.json lists, as roomi deploy --commit does,
without deploying a build. A page with the same title as one the room has
replaces it. Exit status: 0; 1 when pitch.json does not validate or lists no
pages.
roomi pages with no subcommand prints the four commands and exits 0; an
unknown subcommand prints them and exits 1. More on pages in
Pages.
roomi link
roomi link <name> [--email <address> [--send]] [--expires <days>] [--project <slug>]Makes a private link to the room for one viewer, named by <name> (every
word after link, so roomi link Priya Shah names Priya Shah). The link is
printed for you to send; if it is lost, roomi link copy
shows it again. (roomi link copy … is that command, never a link for
someone called Copy.)
| Flag | What it does |
|---|---|
--email <address> |
The viewer's email, kept with the link. Nothing is sent to it unless you say so. |
--send |
Roomi emails the link to --email for you, once, from its own address, naming you by the name you chose to be shown by. Without --send or --no-send, at a terminal, roomi link asks; without a terminal it does not ask and does not send. Refused, with nothing made, when a safeguard says no (no chosen name, an address that bounced or asked not to get links, or past 10 an hour or 50 a day). |
--expires <days> |
The link stops opening the room after this many days: a whole number from 1 to 365. Without it, the link does not expire. |
--project <slug> |
The project the link opens. |
A link for Priya Shah, until 2026-10-29:
https://corner-for-bullring.getroomi.app/l/…
Send it to them.
If it is lost, `roomi link copy "Priya Shah"` shows it again.With --send, the last lines say it is on its way instead:
Roomi is emailing it to priya@example.com for you, from its own address, saying it is from you. It goes once.
If it is lost, `roomi link copy "Priya Shah"` shows it again.Exit status: 0 when the link was made. 1 with no name, a malformed
--expires, --send without --email, no project, or a refusal from the platform. On the Free plan the
platform refuses every private link: see Plans and limits.
roomi links
roomi links [--show] [--project <slug>]Lists the project's viewer links, one line each: the viewer, their email,
the link's stage (or revoked, expired), when it expires, and its id. No
address is printed unless you ask.
| Flag | What it does |
|---|---|
--show |
Prints each live link's address under it. Each one is asked for separately and recorded in the project's history. A link made before 1 October 2026 says to reissue it in the app instead. |
--project <slug> |
The project whose links to list. |
Exit status: 0 when the links were listed. 1 with no project, or a refusal from the platform.
roomi link copy
roomi link copy <name or id> [--project <slug>]One live link's address again, when the viewer has lost it: by the viewer's
name (any case) or the link's id from roomi links. It is printed, and at a
terminal on a Mac copied to the clipboard too; piped, it is only printed.
Recorded in the project's history.
Priya Shah's link:
https://corner-for-bullring.getroomi.app/l/…
Recorded in the project's history.Exit status: 0 when the address was shown. 1 with no name, no live link of that name, two live links of that name (it lists their ids: give one), or a link made before 1 October 2026, which cannot be shown again and is reissued in the app.
roomi open
roomi open [--preview] [--project <slug>]Opens the room with macOS's open. A project listed on the community opens
at its own address, which roomi prints. A private room's address admits
nobody, so roomi opens it as a viewer sees it, on a one-time pass (the app's
Preview as viewer), and prints the pass only when open could not use it.
While a build is being previewed, that pass shows the preview, and the room
says so; --preview asks for it even on a listed project, whose own address
only ever shows the live build.
Exit status: 0 when it opened; 1 when open failed, nothing is live yet (or,
with --preview, nothing is being previewed), roomi is not signed in, or the
project does not exist.
roomi community status
roomi community status [--project <slug>]The project's Community card and where its listing stands: an unlisted
draft, listed (with its public address), blocked by a check (with what it
found), taken off by Roomi (with its comment, as the app shows it), or
waiting for review. Also what the pre-flight check found when listing was
last asked for. Changes nothing. To ask for a review of a block, or of a
listing taken off, use Ask for a review in the app, or appeal_listing
from Claude: roomi has no command for it.
Listing on the Community walks through it.
roomi community card
roomi community card [--title <title>] [--line <line>] [--cover <image>] [--commit] [--project <slug>]The card strangers see on the Community. --title is up to 60 characters
and --line up to 140; a first card needs both, and a saved one keeps
whichever you leave out. --cover is a PNG, JPEG or WebP image on this
machine, at most 1 MB, its type read from its bytes: a file that is not one,
or is bigger, stops roomi before the platform hears anything.
Without --commit it rehearses: it prints the card as it would be, and runs
the pre-flight check on the project
with those words, which names anything that might identify a real business.
With --commit it saves the words, then the cover, through the same routes
as the app. A listed card is checked again as it now reads: it stays listed
if the checks pass, and is blocked, off the Community, if one fails; the
rehearsal says so first. A new cover shows on the Community once its own
check has passed.
roomi community list
roomi community list [--commit] [--project <slug>]Lists the project on the Community, once its checks pass. Without
--commit it runs the checks without writing anything and says what
committing would do: "Would be listed now", "Would be blocked" with what a
check found, or "Would wait for review" (after Roomi took the project
off before). Then it prints what listing means (public at one address, five
people at once, on Free total views as the only analytics, checked again on
every change) and what the pre-flight check finds. With --commit the checks
run for real: it prints "Listed: the checks passed, and it is public at …",
"Not listed: a check blocked it.", or that it was sent for review. It needs a
saved card and a live build, and says which is missing.
roomi community withdraw
roomi community withdraw [--commit] [--project <slug>]Takes a listed project off the Community at once, or a waiting one out of
review. Without --commit it says what would stop; with it, the card is kept
as an unlisted draft. A project that is neither has nothing to withdraw.
roomi logs
roomi logs [--build <id>] [--follow] [--project <slug>]Prints what the live build is writing: each line its server wrote to standard
output or standard error, oldest first, with the time and the viewer whose copy
wrote it. --build reads another build, by its id or its first eight
characters. --follow (or -f) keeps reading every two seconds and prints new
lines as they are written, until you press Ctrl-C.
Build 3f2a9c1e (live) of corner: 1 copy running.
10:01:02 Ana | listening on 8080
10:01:03 Ana (stderr) | DATABASE_URL=[redacted]A container demo runs one copy per viewer link, while that viewer has the room
open. Each copy keeps its newest 2,000 lines while it runs, and none once it
stops, so a build nobody has open has nothing to show, and roomi says so. A
static build has no server and writes no logs. Before any line leaves the
platform, anything that looks like a secret is replaced with [redacted]:
passwords, keys and tokens by their names or their shapes, a password in a
URL, an Authorization header, a private key, and any long random-looking run
of letters and digits. Reading logs changes nothing and does not keep a copy
awake.
Only your own workspace's builds can be read. Exit status: 0 when it read the logs, 1 when there is no such project or build.
roomi rollback
roomi rollback [--commit] [--build <id>] [--project <slug>]Makes an earlier build live again: by default the newest build older than the
live one, or the one --build names, by its id or its first eight characters.
Without --commit it changes nothing: it says which build is live now and
which would go live, and stops.
Project: corner (https://corner.getroomi.app/)
Live now: build 3f2a9c1e · container · 2026-10-12 14:02 UTC · "new pricing page"
Would go live: build 9b41d07a · container · 2026-10-11 09:30 UTC · "last week"
Rehearsal only: nothing was changed. `roomi rollback --commit` makes it live.With --commit it makes that build live at once, and prints the command that
goes forward again. Every viewer link keeps working and opens that build from
then on. It is not a deploy: nothing is uploaded, and it does not count against
the day's deploys. The project's Builds tab in the app does the same with
Roll back to this.
Exit status: 0 when it rehearsed, made the build live, or the build was already live; 1 when there is no earlier build, or no such build.
roomi --help
roomi
roomi --help
roomi deploy --helpPrints a summary of every command. --help (or -h) after any command prints
the same summary and does nothing else: roomi deploy --help never deploys.
Exit status: 0. An unknown command, roomi help included, prints the same
summary and exits 1.
Environment
roomi reads these variables. None of them is required.
| Variable | What it does |
|---|---|
PP_API |
The platform roomi talks to, ahead of roomi config. The default is https://api.getroomi.com. A trailing slash is ignored. The Keychain keeps one token per platform address, so a local token and another platform's never stand in for each other. |
PP_CONFIG |
A settings file to read and write instead of ~/.config/pitch/config.json. |
ROOMI_TOKEN |
A token to use instead of the stored one, for scripts and CI: an API token, or the token roomi login keeps. roomi reads it and never stores it. While it is set, roomi login and roomi logout are refused. |
PP_TOKEN |
The older name for ROOMI_TOKEN, still read. ROOMI_TOKEN wins when both are set. |
PP_KEYCHAIN |
A Keychain file to keep the token in, instead of your default Keychain (macOS only). |
PP_GITLEAKS |
The gitleaks program the secret scan runs. The default is gitleaks on your PATH. |
PP_HEALTH_TIMEOUT_MS |
How long a container rehearsal waits for the platform's runner to open its control port, in milliseconds. The default is 60000. |
API tokens
An API token is a key for scripts and CI, made in the app under Settings → Claude & CLI → API tokens. Name it for where it will live, choose whether it expires (never, or after 30, 90 or 365 days), and copy it: it is shown once, when it is made, and never again. Roomi keeps only a hash of it.
ROOMI_TOKEN=roomi_... roomi deploy --commitA token acts as you, in the workspace you made it in, and reaches what roomi
does: projects, builds and their logs, rollbacks, links, pages, what the room
collected, and the Community listing. It cannot change billing, your account
or the team, make or revoke tokens, or delete a project, and it never reaches
anything else. Any program can use it as Authorization: Bearer roomi_....
It stops working when you revoke it in Settings, when it expires, and when you leave that workspace; being asked back does not bring an old token back. Signing out everywhere ends your sessions but does not revoke tokens: revoke each one in Settings. You can hold 20 live tokens per workspace.
What roomi needs
- Node 24 or later.
- gitleaks for
roomi deploy, on yourPATHor atPP_GITLEAKS. A scan that could not run is not a clean scan, so the deploy stops. - Docker, running, for a container build.
- A browser for
roomi loginandroomi open, on any system. On a Mac the token goes in the Keychain; elsewhere in a file only you can read. In CI, pass an API token inROOMI_TOKENinstead.
Exit status
Every command exits 0 when it did what it says and 1 when it did not; a rehearsal that passed is a 0. A flag roomi does not know, or one missing its value, stops it with a non-zero status before the command runs. A script can rely on these:
roomi validate && roomi deploy && roomi deploy --commit