> ## Documentation Index
> Fetch the complete documentation index at: https://developers.reintersect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Every reintersect command, its flags, its JSON output and the checks it runs.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

The `reintersect` CLI ships with `@reintersect/sdk`. Run it with `npx reintersect`, `pnpm reintersect`
or `bunx reintersect`, or through the scripts the templates add (`dev`, `check`, `deploy`).

`reintersect build` and `reintersect dev` need `esbuild` in your project, and hosted apps also need
`miniflare` to run locally. The templates add both as dev dependencies; when one is missing, the CLI
says which package to install. The CLI runs on Node.js 22 or later.

## Help

```bash theme={null}
reintersect --help
reintersect deploy --help
reintersect help env set
```

`reintersect --help` lists the commands by what they're for: Develop (`dev`, `check`, `build`),
Ship (`deploy`, `logs`), Configure (`env`) and Account (`login`, `logout`, `whoami`). Each
command's `--help` shows its flags, their values and a few examples. Running `reintersect` or
`reintersect env` on its own prints the same help.

When a command name, flag or value is wrong, the CLI says which one and exits `1`. It suggests the
closest name when there is one, such as `Did you mean reintersect deploy?` for `reintersect deplyo`.
With `--json`, that message comes back as an error with the tag `CliUsageError`. Flags that switch
something on, such as `--preview`, take a value only after `=`: `--preview=false`.

## Finding your app

Commands that read your code load the module that exports `app`:

1. The `--entry` flag, if given.
2. `"reintersect": { "entry": "…" }` in `package.json`.
3. The first of `src/app.ts`, `src/app.tsx`, `src/app.js`, `app.ts`, `app.tsx`, `app.js`.

Commands that act on a deployed app take `--app <id>`, or read `REINTERSECT_APP_ID`. The id is in
**Settings → Developer → Apps**.

## Output

In a terminal, commands draw progress and results interactively. In CI, when output is piped, or with
`--json`, they print plain lines with no color codes. Set `NO_COLOR` to keep the terminal view
without colors. With `--json`, the result is one JSON value on stdout and every
other message goes to stderr, including anything your app prints while the CLI loads it. A failure
prints `{ "error": { "tag": "…", "message": "…" } }`.

Every command exits `0` on success and `1` on failure, including when `check` finds errors.

## login

```bash theme={null}
reintersect login
```

Signs in with a device code. The CLI prints a code and opens Reintersect, where you confirm the code
and pick the workspace. It stores a CLI key for that workspace in
`$XDG_CONFIG_HOME/reintersect/credentials.json` (default `~/.config/reintersect/credentials.json`),
readable only by you. Sign-in also works over SSH and in containers, because you can open the printed
link on any device.

## logout and whoami

```bash theme={null}
reintersect logout
reintersect whoami [--json]
```

`logout` deletes the stored credentials. `whoami` shows the workspace and member you're signed in as,
or the app, repository and ref of a deploy token. With `--json` it prints that session plus `baseUrl`
and `source` (`credentials` or `environment`).

## dev

```bash theme={null}
reintersect dev [--entry <file>] [--port <port>]
```

Runs your app locally with live deliveries from Reintersect:

1. Builds your app and watches for changes.
2. Creates or updates your personal development app and its development install, and syncs the
   manifest on every rebuild.
3. Runs the app locally: hosted apps in Miniflare (the Workers runtime), self-hosted apps in a local
   Node server (`--port`, default any free port).
4. Connects to Reintersect over a WebSocket relay. Each delivery for your development install is
   replayed to the local app as the exact signed request, and the response goes back.
5. Prints the playground link and a live list of deliveries with their status and duration.

Hosted apps under `reintersect dev` follow the hosted egress rules: outbound requests must be
`https` and match `egress`, or they fail with `egress_denied`. Once the first delivery arrives, calls
your app makes to the Reintersect API carry that delivery's install token, the same way the hosted
gateway adds it. Local environment values come from `.dev.vars`. The CLI keeps the development app's
signing secret in `.reintersect/dev/session.json` (readable only by you). If the connection drops, the CLI reconnects;
if another `reintersect dev` takes over the same development app, this one stops.

## build

```bash theme={null}
reintersect build [--entry <file>] [--target workerd|node] [--json]
```

Bundles your app into `.reintersect/build`: `app.mjs` for `--target workerd` (the default, used by
hosted deploys) or `server.mjs` for `--target node`. Start a node build with
`node .reintersect/build/server.mjs`; it listens on `PORT` (default `8787`) and prints its URL.
`--json` prints `{ "file", "target", "kilobytes", "app" }`.

## check

```bash theme={null}
reintersect check [--entry <file>] [--app <id>] [--json]
```

Checks your app before you deploy it. It builds and loads the app, renders every block with a minimal
and a full sample of props generated from its schemas, and runs the rules below. Each rendered
tree goes through the same validator Reintersect runs when blocks are stored, so `check` doesn't
need you to be signed in. It also warns about likely mistakes the validator accepts, such as a
percent written as `8` instead of `0.08`. With `--app`, it compares the app's access with the
published version and warns when installs will need review, including a message action that asks for
a wider `context`.

`--json` prints `{ "findings": [{ "severity", "code", "message", "file?", "line?", "column?", "endLine?", "endColumn?", "hint?" }] }`.
`severity` is `error`, `warning` or `info`; any error fails the command.

| Area | Codes |
| - | - |
| Loading | `build-failed`, `app-load-failed`, `app-export-missing`, `default-export`, `manifest-invalid` |
| Rendering | `block-render-failed`, `block-render-slow`, `block-render-skipped`, `block-props-unsampled`, `block-tree-invalid`, `block-tree-warning`, `icon-unknown`, `icon-list-outdated`, `icon-list-behind` |
| Composition | `block-not-added`, `jsx-block-unregistered`, `block-type-duplicate`, `reference-kind-duplicate`, `message-action-duplicate`, `command-duplicate`, `action-name-duplicate`, `section-duplicate`, `section-handle-foreign`, `choice-value-duplicate` |
| State and schemas | `state-transform`, `state-initial-invalid`, `state-union`, `state-cross-field`, `schema-json-failed`, `default-drift` |
| Forms | `form-field-missing`, `form-field-format`, `form-field-option` |
| References and hosts | `pattern-invalid`, `pattern-overlap`, `pattern-host-unclaimed`, `pattern-host-placeholder`, `reference-search-unmatched`, `domain-public-suffix`, `egress-public-suffix` |
| Access | `access-widened`, `access-not-compared` |
| Effect apps | `effect-fn-handler` |

Each finding's message says what to change.

## deploy

```bash theme={null}
reintersect deploy [--app <id>] [--preview] [--entry <file>] [--json]
```

Publishes your app's manifest and, for hosted apps, its bundle:

| Flags | Target |
| - | - |
| `--app <id>` or `REINTERSECT_APP_ID` | Production version of that app. |
| `--app <id> --preview` | Preview version of that app. |
| `--preview` alone | Preview version of your personal development app, created if needed. Not available with a deploy token. |
| neither | Fails: say which app. |

A hosted app is bundled for Workers and uploaded, and a self-hosted app syncs its manifest and
endpoint. Deploying the same build twice is safe. The result shows the version number, its id, the playground
link, and a note when some installs wait for an admin to approve new access.

`--json` prints:

```json theme={null}
{
  "version": {
    "id": "ver_123",
    "appId": "app_123",
    "number": 7,
    "status": "preview",
    "target": "preview",
    "manifestHash": "…",
    "bundleSha": "…",
    "reconsentRequired": false,
    "playgroundUrl": "https://app.reintersect.com/dev/app_123?version=ver_123",
    "createdAt": "2026-10-05T09:00:00.000Z"
  }
}
```

## env

```bash theme={null}
reintersect env ls [--app <id>] [--target preview|production] [--json]
reintersect env set KEY [--app <id>] [--preview] [--plain]
reintersect env rm KEY [--app <id>] [--preview]
```

Manages environment variables. `set` reads the value from a prompt, or from stdin when piped
(`printf %s "$TOKEN" | reintersect env set API_TOKEN --app app_123`). Values are secrets unless you pass
`--plain`, and go to production unless you pass `--preview`. `ls` shows each variable's name,
environment, kind and last update, but never its value; `--json` prints the rows. Changing production values of a hosted app
redeploys it.

## logs

```bash theme={null}
reintersect logs [--app <id>] [--follow] [--limit <n>] [--json]
```

Shows runtime logs of a hosted app: each request's outcome, delivery id, CPU time, log lines and
exceptions. `--follow` (`-f`) keeps polling for new entries. `--json` prints one JSON object per
entry, one per line.

## Environment variables

| Variable | Effect |
| - | - |
| `REINTERSECT_API_KEY` | Authenticates instead of the stored credentials: a member API key, or a deploy token (`reidep_…`) in CI. |
| `REINTERSECT_APP_ID` | Default for `--app`. |
| `REINTERSECT_BASE_URL` | The API origin. Default `https://api.reintersect.com`. Stored credentials only apply to the origin they were created for. |
| `REINTERSECT_RUNTIME_ROOT` | The hosted apps domain used to compute MCP URLs. Default `reintersect.app` (`staging.reintersect.app` for other API origins). |
| `XDG_CONFIG_HOME` | Where credentials are stored. |
| `CI` | Forces plain output. |
| `NO_COLOR` | Turns off colors. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.