# CLI

- URL: https://getroomi.com/docs/cli
- Built: 2026-10-26

`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](#roomi-config)). [Install the CLI](https://getroomi.com/docs/install) covers
setting it up.

Most people start with the [connector](https://getroomi.com/docs/claude), 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](https://getroomi.com/docs/install#when-you-need-it) 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`:

```text
  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](https://getroomi.com/docs/errors) lists every one.

## Commands

### roomi login

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

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

> [!NOTE]
> In a script or CI, pass an [API token](#api-tokens) in `ROOMI_TOKEN`
> instead of signing in. While `ROOMI_TOKEN` (or `PP_TOKEN`, its older name) is
> set, roomi will not store a token or remove one: `roomi login` stops with an
> error when it comes to store the new token, so the stored one is never
> bypassed without you knowing.

### roomi logout

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

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

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

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

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

```json http
{"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](https://getroomi.com/docs/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

```sh
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](https://getroomi.com/docs/ai-agents)).

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](https://getroomi.com/docs/static#what-roomi-init-reads));
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](https://getroomi.com/docs/containers#node-24)).
- **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](https://getroomi.com/docs/static)).

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

```sh
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](https://getroomi.com/docs/pitch-json).

### roomi validate

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

```text
  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](https://getroomi.com/docs/errors#roomi-validate).

### roomi dev

```sh
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](https://getroomi.com/docs/preview) 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](https://getroomi.com/docs/preview#your-accounts-look) |

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

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

9. Creates the project if its slug is new.
10. 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.
11. 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](#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. |

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

```text
  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](https://getroomi.com/docs/errors#roomi-deploy).

### roomi promote

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

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

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

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

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

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

```sh
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](https://getroomi.com/docs/pages).

### roomi link

```sh
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`](#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. |

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

```text
  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](https://getroomi.com/docs/plans).

### roomi links

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

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

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

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

```sh
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](https://getroomi.com/docs/listing) walks through it.

### roomi community card

```sh
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](https://getroomi.com/docs/community#the-pre-flight-scan) 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

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

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

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

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

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

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

```sh
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](#api-tokens), 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. |

> [!WARNING]
> A token in `ROOMI_TOKEN` acts as you. Keep it in your CI's secret store,
> never in a file in the repository. An API token reaches one workspace and
> only what roomi does, and you can revoke it in Settings at any time.

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

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

```sh
roomi validate && roomi deploy && roomi deploy --commit
```

> [!NOTE]
> Every workspace starts on Free, and moves to Pro or Team whenever you like, in Settings, Billing. Sign in at app.getroomi.com with GitHub or Google, then add the connector to Claude at https://mcp.getroomi.com/mcp, or run the CLI with npx @getroomi/cli. These pages describe the connector, the CLI, pitch.json, the app and the room as they are.
