# Install the CLI

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

`roomi` is the command-line tool that checks, rehearses and publishes a demo from the folder it lives in. This page covers when you need it, what it needs on your machine, how to run it, how it signs in as you, and where it keeps the credential it signs in with.

## When you need it

You may not. The [connector](https://getroomi.com/docs/claude) deploys a static demo from a chat with Claude, with nothing to install, and most people start there. Install `roomi` when:

- **the demo has a server.** A [container demo](https://getroomi.com/docs/containers) deploys only from your machine.
- **the build is bigger than a chat carries**, more than 200 files or 3 MB. `roomi` takes a static build of at most 5,000 files, 32 MB per file and 256 MiB unpacked.
- **you work on the demo in its repository with Claude Code**, through the [plugin](https://getroomi.com/docs/claude#the-claude-code-plugin).
- **you want links and pages from a terminal**, or a deploy from a script.

When one of those applies, the connector says so. In Claude Code, Claude offers to run the install for you, and runs it only on your yes; in a chat, it gives you the commands. Either way, `roomi login` is yours to approve in your browser.

## Run it

The CLI is published on npm as `@getroomi/cli`, and installs the `roomi` command. Run it without installing anything:

```sh
npx @getroomi/cli --help
```

or install it once, which gives you the command `roomi`:

```sh
npm install -g @getroomi/cli
roomi --help
```

These docs write the command as `roomi` throughout, so `roomi login` means `npx @getroomi/cli login` if you did not install it. The install also gives you `pitch`, the command's name before Roomi: `pitch deploy` still works, and does exactly what `roomi deploy` does. It talks to Roomi, `https://api.getroomi.com`, with nothing to configure.

## Requirements

| What | Why |
|---|---|
| **Node 24** | `roomi` requires Node 24 or later (`node --version`); npm warns if yours is older. It is also the Node every container demo runs on. |
| **gitleaks** | Every rehearsal scans the project, and the build it makes, for secrets. If gitleaks cannot run, the deploy stops rather than calling an unscanned build clean. On a Mac: `brew install gitleaks`. |
| **Docker, running** | Only for a [container demo](https://getroomi.com/docs/containers). `roomi deploy` builds your Dockerfile and runs the result on the platform's own runner, locally. A [static demo](https://getroomi.com/docs/static) does not need Docker. |
| **A browser** | `roomi login`, `roomi open` and `roomi dev` open your browser with the Mac's `open` command (`xdg-open` on Linux, `start` on Windows). On a Mac the token goes in the Keychain; elsewhere in a file only you can read. See [Other systems](#other-systems). |
| **Your package manager** | For a static demo with a `build` script, `roomi deploy` runs it with the package manager your lockfile names: pnpm, yarn, bun, or npm if there is no lockfile. |

If gitleaks is installed somewhere that is not on your `PATH`, set `PP_GITLEAKS` to its full path.

## Create an account

Sign in at [app.getroomi.com](https://app.getroomi.com) with **Continue with GitHub** or **Continue with Google**. There is no separate sign-up: the first time you sign in, your account is made, with a workspace of your own on the Free plan. Once you are in, you can add a passkey in Settings and sign in with it from then on.

## Sign in

```sh
roomi login
```

`roomi` asks the platform for a one-time code, prints where to enter it, and opens that page in your browser:

```text
  Open https://app.getroomi.com/device and enter the code K7QXDRPM
  (or go straight to https://app.getroomi.com/device?user_code=K7QXDRPM)
  Opened it in your browser.
  Waiting for you to confirm…
```

If the browser did not open, open the address yourself. If you are not signed in to the app there, it asks you to sign in first and brings you back. Enter the code, or check the one already filled in against your terminal, and choose **Yes, connect roomi**. Only approve a code your own `roomi login` printed, moments ago: approving someone else's code signs their machine in as you.

The terminal then says:

```text
  Signed in. The token is in the macOS Keychain.
```

A code lasts 30 minutes. If it runs out before you approve it, `roomi` says the code expired and stores nothing; run `roomi login` again for a new one. If you choose **No, deny it** in the browser, it says `Sign-in was denied in the browser.` and stores nothing.

This is the OAuth device authorization flow (RFC 8628): the terminal never sees your password or your GitHub or Google sign-in, only the session token the platform grants once you approve.

## Check who you are

```sh
roomi whoami
```

```text
  Priya Shah <priya@example.com> on https://api.getroomi.com
```

It names the account and the platform the token is for. If there is no token it says you are not signed in, and if the stored token has expired, or its session was ended, it says the stored token is no longer valid. Either way, `roomi login` signs you in again.

## Sign out

```sh
roomi logout
```

This ends the session on the platform, so the token stops working wherever a copy of it is, and then deletes it from the Keychain (or the credentials file). If the platform cannot be reached, `roomi` says so and removes the token from your machine anyway.

## Where the token lives

On a Mac, the token is kept in the macOS Keychain under the service name `pitch-product-cli`, and nowhere else: never in a file, never in your project, never printed. It reaches the Keychain on standard input rather than as a command-line argument, so no other process can read it from the process list.

On Linux, Windows and anywhere else, it is kept in `credentials.json` beside your settings (`~/.config/pitch/credentials.json`, under `XDG_CONFIG_HOME` when that is set): a file only you can read and write (`0600`), in a folder only you can open (`0700`). If anyone else can read the file, `roomi` refuses to use it and says how to fix it. Windows has no such permissions on a file: there it is as private as your user folder.

There is one entry per platform address. A token for one platform never stands in for another, so signing in to a local platform while developing does not touch the token for the hosted one.

## Scripts and CI

For a script or CI, make an API token in the app (**Settings → Claude & CLI → API tokens**) and set `ROOMI_TOKEN`:

```sh
ROOMI_TOKEN=roomi_... roomi deploy --commit
```

`roomi` uses `ROOMI_TOKEN` instead of the stored token for that one run, and never writes it anywhere. While it is set, `roomi login` and `roomi logout` refuse, with `ROOMI_TOKEN is set, so roomi is not keeping a token of its own. Unset it to sign in or out.`, so the stored token is never bypassed without you knowing. `PP_TOKEN`, its older name, still works.

An API token acts as you in one workspace, and reaches only what `roomi` does: it cannot change billing, your account or the team. It is shown once when it is made; revoke it in Settings when it is no longer needed, or the moment it might have leaked. [CLI](https://getroomi.com/docs/cli#api-tokens) has the details. Keep it in your CI system's secret store, never in a repository.

## The header for other programs

```sh
roomi auth header
```

This prints the one line a program needs to call the platform as you, and nothing else:

```text
{"Authorization":"Bearer ..."}
```

It is how the Claude Code plugin signs its connection in to a platform running on your own machine ([Deploying from Claude](https://getroomi.com/docs/claude#how-it-signs-in)). Because it prints your token, it refuses when its output is a terminal a person is looking at, with `This prints your token. It is meant to be read by a program; pass --print to see it here.` Pass `--print` only if you mean to see it.

## Choosing the platform

`roomi` talks to `https://api.getroomi.com`. `roomi whoami` says which platform it is using, and where that came from:

```text
  API https://api.getroomi.com (the default)
```

You only change it to work on Roomi itself, against a platform running on your own machine. `roomi config set api <url>` keeps the address for you, and `roomi config unset api` goes back to production; `PP_API` overrides both for one shell or script. [CLI](https://getroomi.com/docs/cli#roomi-config) has the details.

```sh
roomi config set api http://127.0.0.1:8200
```

## Environment variables

| Variable | What it does |
|---|---|
| `PP_API` | The platform's address, for this run, ahead of `roomi config`. Unset, `roomi` uses `https://api.getroomi.com`. |
| `PP_CONFIG` | A settings file to use instead of `~/.config/pitch/config.json`. |
| `ROOMI_TOKEN` | A token to use for this run instead of the stored one: an API token from Settings. Never stored. |
| `PP_TOKEN` | The older name for `ROOMI_TOKEN`, still read. |
| `PP_GITLEAKS` | The path to gitleaks, when it is not on your `PATH`. |
| `PP_KEYCHAIN` | A keychain file to keep the token in, instead of your default keychain (macOS only). |
| `PP_HEALTH_TIMEOUT_MS` | How long a container rehearsal waits for the platform's runner to open, in milliseconds. The default is 60000. |

## Other systems

`roomi login` works on Linux and Windows as it does on a Mac: it opens your browser, and keeps the token in the credentials file described in [Where the token lives](#where-the-token-lives). Where there is no browser at all, such as a server or CI, use an API token in `ROOMI_TOKEN`.

`roomi login`, `roomi open` and `roomi dev` print the address they open as well as opening it, so where the browser cannot be opened you can copy the address from the terminal.

## Next

- [Quickstart](https://getroomi.com/docs/quickstart): a static demo in a room.
- [Your first container demo](https://getroomi.com/docs/first-container): a demo with a server.
- [CLI](https://getroomi.com/docs/cli): every command and flag.

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