# Connect commands

> Connect a web app, a desktop app or this Mac's phones, and stop them.

Source: https://rehearsal.dev/docs/reference/cli-connect

`rehearsal connect` on its own shows what this computer can connect. At a terminal it asks which one, then starts it. Name the kind to skip the question.

Rehearsal's browsers run on its servers, so they cannot open `http://localhost:3000` on your computer. `connect web` lets them reach your app through your terminal for as long as it runs. `connect list` and `connect stop` read and close a connection you started with `--detach`. [Test an app on your computer](https://rehearsal.dev/docs/cli/connect-a-local-app.md) walks through a first connection.

`connect electron` connects a desktop app built on Electron. `connect ios` and `connect android` let your Mac open your iPhone and Android runs. Each runs only what you start. `connect remove` stops Rehearsal using one of your computers for good. [iPhone, Mac and Electron apps](https://rehearsal.dev/docs/cli/native-apps.md) walks through a desktop app.

## rehearsal connect

Show what this computer can connect, and connect the one you pick.

Each row says what was found here: the local URLs that answer now, the desktop apps, and whether this computer can open iPhone simulators or Android emulators. At a terminal it asks which to connect and starts it. Elsewhere it prints the list with the command for each.

Name the kind to skip the question: `rehearsal connect web`, electron, ios or android. A computer you connect runs only what you start.

```sh
rehearsal connect
```

Needs the list needs no sign-in. Connecting what you pick needs one.

Ctrl+C does what it does in the command you picked.

```sh
# See what this computer can connect and pick one
rehearsal connect

# Read the list in a script
rehearsal connect --json
```

## rehearsal connect web

Connect a web app that runs on this computer.

Rehearsal's browsers reach your app through this terminal for as long as the command runs. The environment stays yours between runs: connecting the same URL again comes back to it instead of adding another one.

With no URL, it asks for one and offers the local URLs that answer now.

`--detach` keeps the connection open in the background and returns once it connects, which suits a script or a coding agent. List such connections with `rehearsal connect list` and close them with `rehearsal connect stop`.

`--json` works with `--detach`.

```sh
rehearsal connect web [url] [flags]
```

| Argument | Description |
| --- | --- |
| `[url]` | The URL your app answers on, such as `http://localhost:3000`. Asked for when you leave it out. |

| Flag | Description |
| --- | --- |
| `--project <project>` | The project that holds the app: its ID, slug or name. |
| `--app <app>` | The app to connect: its ID or its name. |
| `--name <name>` | What to call this connection in Rehearsal. The default is the app's name followed by "local". |
| `--allow <url>` | Another local URL Rehearsal may reach, such as an API on another port. Repeat it for more than one. |
| `--detach` | Keep the connection in the background and return once it connects. |
| `--timeout <time>` | With `--detach`, how long to wait for the connection, such as 60s. The default is 60s, at most 10m. |

Needs a sign-in with the `tunnel` scope and permission to manage projects.

Ctrl+C closes the connection. The environment stays in Rehearsal. With `--detach`, Ctrl+C stops only the wait.

```sh
# Pick a local URL that answers now
rehearsal connect web

# Connect a local app
rehearsal connect web http://localhost:3000

# Connect and allow a second port
rehearsal connect web http://localhost:3000 --allow http://localhost:3001

# Connect in the background from a script
rehearsal connect web http://localhost:3000 --project parcel --app web --detach --json
```

## rehearsal connect electron

Connect this computer to run a desktop app built on Electron.

With a path, this computer opens a fresh copy of the app for each session and test you start, while the command runs. It runs only what you start, never a teammate's run. Give the app's folder or its `.app` file. With no path, it asks which of the Electron apps found on this computer to connect.

One desktop app connects from a computer at a time. A fresh copy works on a Mac only for now.

`--window` connects the window of an app that runs now, or that the path or start command starts, on any computer. Rehearsal works in that window while this terminal stays open. A window cannot run saved tests.

`--detach` stays connected in the background and returns once Rehearsal hears from this computer. List it with `rehearsal connect list` and stop it with `rehearsal connect stop`.

```sh
rehearsal connect electron [path] [flags]
```

| Argument | Description |
| --- | --- |
| `[path]` | The app's folder or `.app` file. With `--window`, also a command that starts the app. Asked for when you leave it out. |

| Flag | Description |
| --- | --- |
| `--project <project>` | The project that holds the app: its ID, slug or name. |
| `--app <app>` | The app in Rehearsal to connect: its ID or its name. |
| `--name <name>` | What to call this computer in Rehearsal. The default is its host name. With `--window`, what to call the connection. |
| `--detach` | Stay connected in the background and return once Rehearsal hears from this computer. |
| `--timeout <time>` | With `--detach`, how long to wait, such as 2m. The default is 2m, at most 10m. |
| `--window` | Connect the window of an app that runs now, or that the path or command starts. It cannot run saved tests. |
| `--url <url>` | With `--window`, the URL the app's window shows, such as `http://localhost:5173`. The default is the page its first window shows. |
| `--debug-port <port>` | With `--window`, connect an app you started with this debugging port open. |

Needs a sign-in with the tunnel and hosts scopes and permission to manage projects.

Ctrl+C disconnects. While a run uses the app, the first Ctrl+C says so and the second disconnects. With `--window`, Ctrl+C also quits an app the command started. With `--detach`, Ctrl+C stops only the wait.

```sh
# Pick an Electron app on this computer
rehearsal connect electron

# Connect an installed app
rehearsal connect electron /Applications/Parcel.app

# Connect in the background from a script
rehearsal connect electron /Applications/Parcel.app --project parcel --app desktop --detach --json

# Connect the window of an app you develop
rehearsal connect electron --window "npm start --" --url http://localhost:5173

# Connect the window of an app you started
rehearsal connect electron --window --debug-port 9222
```

## rehearsal connect ios

Connect this computer to open your iPhone runs on its simulators.

While it runs, the iPhone runs you start open their simulators on this computer. It runs only what you start, never a teammate's run. Signing in is enough. iPhone simulators need a Mac.

`--detach` stays connected in the background and returns once the iPhone simulators are ready. List it with `rehearsal connect list` and stop it with `rehearsal connect stop`.

```sh
rehearsal connect ios [flags]
```

| Flag | Description |
| --- | --- |
| `--phones <count>` | How many iPhone simulators can be open at once, from 1 to 3. The default is 2. |
| `--name <name>` | What to call this computer in Rehearsal. The default is its host name. |
| `--workspace <workspace-id>` | The workspace to connect this computer in, by ID. Asked for when you have more than one. |
| `--detach` | Stay connected in the background and return once the iPhone simulators are ready. |
| `--timeout <time>` | With `--detach`, how long to wait for the iPhone simulators, such as 5m. The default is 5m, at most 15m. |

Needs a sign-in with the `hosts` scope and permission to manage projects.

Ctrl+C disconnects. While a run uses an iPhone, the first Ctrl+C says so and the second disconnects. With `--detach`, Ctrl+C stops only the wait.

```sh
# Connect this computer
rehearsal connect ios

# Connect with one iPhone simulator at a time
rehearsal connect ios --phones 1

# Connect in the background from a script
rehearsal connect ios --detach --json
```

## rehearsal connect android

Connect this computer to open your Android runs on its emulators.

While it runs, the Android runs you start open their emulators on this computer. It runs only what you start, never a teammate's run. Signing in is enough. This version opens Android emulators on a Mac only.

`--detach` stays connected in the background and returns once the Android emulators are ready. List it with `rehearsal connect list` and stop it with `rehearsal connect stop`.

```sh
rehearsal connect android [flags]
```

| Flag | Description |
| --- | --- |
| `--emulators <count>` | How many Android emulators can be open at once, from 1 to 3. The default is 1, since each one uses several processor cores. |
| `--name <name>` | What to call this computer in Rehearsal. The default is its host name. |
| `--workspace <workspace-id>` | The workspace to connect this computer in, by ID. Asked for when you have more than one. |
| `--detach` | Stay connected in the background and return once the Android emulators are ready. |
| `--timeout <time>` | With `--detach`, how long to wait for the Android emulators, such as 5m. The default is 5m, at most 15m. |

Needs a sign-in with the `hosts` scope and permission to manage projects.

Ctrl+C disconnects. While a run uses an emulator, the first Ctrl+C says so and the second disconnects. With `--detach`, Ctrl+C stops only the wait.

```sh
# Connect this computer
rehearsal connect android

# Connect with two Android emulators at a time
rehearsal connect android --emulators 2

# Connect in the background from a script
rehearsal connect android --detach --json
```

## rehearsal connect list

List the connections this computer started and your connected computers.

Each connection shows whether its background process still runs here, whether Rehearsal holds it open, and whether the tunnel to Rehearsal is up. Tunnel connected means Rehearsal can reach this computer, not that your app answers.

Your computers connected with `rehearsal connect electron`, ios or android are listed too: only your own, in the workspace this computer connected in or `--workspace`.

```sh
rehearsal connect list [id-or-name] [flags]
```

| Argument | Description |
| --- | --- |
| `[id-or-name]` | One connection by its ID, or one computer by its ID or name. Leave it out to list every one. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | The workspace of a connection or computer this computer did not start, by ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `tunnel` scope and permission to manage projects.

```sh
# List every connection and computer
rehearsal connect list

# Read one in a script
rehearsal connect list <connection-id> --json

# Read a computer by its name
rehearsal connect list Studio
```

## rehearsal connect stop

Close a connection or disconnect a computer started with `--detach`.

Stops its background process, closes the connection in Rehearsal and deletes the file this computer kept for it. Stopping one that has already ended changes nothing. The local environment stays in Rehearsal for the next connection.

A computer connected in the background closes its desktop app, iPhone simulators or Android emulators and disconnects. It stays yours in Rehearsal until you remove it.

With nothing named, it asks which of the connections running in the background here to stop. With only one, it stops that one.

```sh
rehearsal connect stop [id-or-name] [flags]
```

| Argument | Description |
| --- | --- |
| `[id-or-name]` | The connection's ID, or the computer's ID or name, as `--detach` printed it. Asked for when you leave it out. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | The workspace of a connection or computer this computer did not start, by ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--dry-run` | Ask and check everything, then stop before anything starts or changes, and say what would happen. Off by default. |

Needs a sign-in with the `tunnel` scope and permission to manage projects.

```sh
# Close a background connection
rehearsal connect stop <connection-id>

# Close it from a script
rehearsal connect stop <connection-id> --json

# Disconnect a computer by its name
rehearsal connect stop Studio

# See what it would stop
rehearsal connect stop Studio --dry-run
```

## rehearsal connect remove

Remove one of your computers from Rehearsal.

Rehearsal stops opening anything on it, and a connection still running on it ends. Run on that computer, it also deletes what the computer saved. Connecting it again later works as the first time did.

With no computer named, it asks which of yours to remove. With only one, it takes that one. It always asks before removing, unless you add `--yes`.

```sh
rehearsal connect remove [computer] [flags]
```

| Argument | Description |
| --- | --- |
| `[computer]` | The computer's name or ID, as `rehearsal connect list` shows it. Asked for when you leave it out. |

| Flag | Description |
| --- | --- |
| `--yes` | Remove it without asking first. |
| `--workspace <workspace-id>` | The workspace to look in, by ID. Defaults to the one this computer connected in. |
| `--dry-run` | Ask and check everything, then stop before anything starts or changes, and say what would happen. Off by default. |

Needs a sign-in with the `hosts` scope and permission to manage projects.

```sh
# Remove a computer
rehearsal connect remove Studio

# Remove it from a script
rehearsal connect remove <computer-id> --yes --json

# See which computer it would remove
rehearsal connect remove Studio --yes --dry-run
```
