CLI

Every roomi command and flag.

On this page

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 --commit validates.

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

A 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 login

Signs 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 logout

Ends 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 whoami

Says 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 api

Which 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 Dockerfile whose last stage is not built on Node (FROM python:3.12-slim, say). Container demos run on Node 24, and only /app comes 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 .html file (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 beside output: 'export' in next.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 --force

Exit 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 validate

Checks 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-app

Takes 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:8300 and the demo inside it at http://<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 and pitch.brand.json are 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 in pitch.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:

  1. Validates pitch.json as roomi validate does. A problem stops here.
  2. Checks you are signed in, with --commit only, before anything slow.
  3. 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; --commit asks.
  4. Scans the project for secrets with gitleaks. Your own .gitleaksignore is not read, so a finding cannot be waved through from inside the build.
  5. Builds.
    • A static build runs the build script in package.json (with pnpm, yarn, bun or npm, by the lockfile), requires index.html in the output folder, scans the output for secrets, and packs it.
    • A container build needs Docker running. It builds your Dockerfile for linux/amd64, reads how the image starts from its CMD and ENV (unless pitch.json sets run), copies /app out of the image as the bundle, and scans the bundle for secrets.
  6. 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 health path to answer. roomi's own calls to the demo during the rehearsal go to that copy on loopback, and nowhere else.
  7. 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.
  8. 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:

  1. Creates the project if its slug is new.
  2. Uploads the artefact, registers the build, uploads every page pitch.json lists, and makes the build live. A page that will not upload leaves the previous build live.
  3. 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 open to 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 <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 [--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 <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 --help

Prints 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 --commit

A 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 your PATH or at PP_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 login and roomi 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 in ROOMI_TOKEN instead.

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