# Bitrise RDE CLI

> Install and use the Bitrise RDE CLI to create and connect to Remote Dev Environment sessions, run commands, transfer files, and run AI coding agents from your terminal.

The Bitrise RDE CLI lets you manage Remote Dev Environments from your terminal: create and connect to sessions, run commands in them, transfer files, and start AI coding agents. The CLI is open source, and all RDE commands live under `bitrise-cli rde`.

If you just want to get started fast, follow the [Quickstart](/bitrise-rde/getting-started/quickstart). This page is the broader reference for what the CLI can do.

## Installing the CLI

Install the latest version with the install script:

```bash
curl -fsSL https://app.bitrise.io/cli/install.sh | bash
```

This installs the `bitrise-cli` binary to `~/.local/bin`. Make sure that directory is on your `PATH`. You can also download a build from the [GitHub releases](https://github.com/bitrise-io/bitrise-cli/releases) or install from source with `go install github.com/bitrise-io/bitrise-cli@latest`.

## Signing in

Sign in to your Bitrise account. This opens your browser to authenticate:

```bash
bitrise-cli auth login
```

Check your status with `bitrise-cli auth status`, and sign out with `bitrise-cli auth logout`. For non-interactive use, such as CI, set the `BITRISE_TOKEN` environment variable to a personal access token, or pipe a token into `bitrise-cli auth login --with-token`.

### Choosing a workspace

RDE commands run against a workspace. If you belong to exactly one, the CLI selects it automatically. If you belong to more than one, the CLI asks you to pick one. To skip the prompt, save a default:

```bash
bitrise-cli config set default_workspace_id WORKSPACE_ID
```

For a single command, the `--workspace` flag takes precedence, followed by the `BITRISE_WORKSPACE_ID` environment variable, then the saved default.

## Managing sessions

The `bitrise-cli rde session` commands cover the full session lifecycle. Commands that take a `SESSION_ID` also accept the session's name, as long as the name is unique.

| Command | What it does |
| --- | --- |
| `bitrise-cli rde session create NAME` | Create a session from a `--template`, or without one by passing `--stack` and `--machine-type`. Add `--device-platform ios` or `android` to boot a virtual device with it. Add `--wait` to block until the session, and its device, are ready. |
| `bitrise-cli rde session list` | List your sessions and their status. |
| `bitrise-cli rde session view SESSION_ID` | Show a session's details, including connection credentials. |
| `bitrise-cli rde session update SESSION_ID` | Rename a session, change its description, or adjust its auto-terminate timer. |
| `bitrise-cli rde session exec SESSION_ID -- COMMAND` | Run a command in the session over SSH. See [Running commands in a session](#running-commands-in-a-session). |
| `bitrise-cli rde session upload SESSION_ID LOCAL_PATH REMOTE_FOLDER` | Upload a file or folder into the session. |
| `bitrise-cli rde session download SESSION_ID REMOTE_PATH LOCAL_PATH` | Download a file or folder from the session. |
| `bitrise-cli rde session ssh SESSION_ID` | Print the session's SSH command and password, for `scp` or for tunneling a device session's ports. |
| `bitrise-cli rde session vnc SESSION_ID` | Print the session's VNC connection details, or tunnel them to a local port with `--forward` (macOS only). |
| `bitrise-cli rde session open-vnc SESSION_ID` | Open the session's desktop in your default VNC viewer (macOS only). |
| `bitrise-cli rde session logs SESSION_ID --stage startup` | Print the session's warmup or startup script logs. Add `--follow` to stream them live. |
| `bitrise-cli rde session notifications SESSION_ID` | List events the session emitted, such as agent stops and permission prompts. |
| `bitrise-cli rde session diff SESSION_ID` | Show how the session's template changed since the session was created. |
| `bitrise-cli rde session terminate SESSION_ID` | Stop the machine but keep the session for later. |
| `bitrise-cli rde session restore SESSION_ID` | Restart a terminated session from its persistent disk. Add `--wait` to block until it's running. |
| `bitrise-cli rde session delete SESSION_ID` | Permanently delete a terminated session. |
| `bitrise-cli rde session delete-terminated` | Permanently delete all terminated sessions in the workspace. |

## Running commands in a session

`bitrise-cli rde session exec` runs a single command in a session and streams its output back, without opening an interactive shell. It's the main building block for scripting sessions and for letting AI agents drive them:

```bash
bitrise-cli rde session exec SESSION_ID -- npm test
```

The command runs in a login shell, so the session's `PATH`, Homebrew packages, and language version managers are all available. If a local SSH agent is running, the CLI forwards it into the session, so Git over SSH inside the session uses your local keys.

Everything after `--` is passed as a program with literal arguments. To use pipes, `&&`, or redirection, add `--shell` and quote the command:

```bash
bitrise-cli rde session exec SESSION_ID --shell -- 'cd my-app && xcodebuild | xcpretty'
```

The most useful flags:

- `--timeout`: the remote command is stopped after 10 minutes by default. Raise the cap for long builds (`--timeout 30m`) or disable it with `--timeout 0`.
- `--env`: forward a local environment variable to the remote command (`--env NPM_TOKEN`), or set a literal value (`--env CI=1`). Forwarded values are never printed locally, but they are visible in the session's process list while the command runs.
- `--output json`: emit a single JSON object with the exit code, stdout, and stderr — easy to parse from a script or an agent.

To share a list of forwarded environment variables with your team, add them to `.bitrise/rde.yml` in your repository:

```yaml
exec:
  env:
    - API_BASE_URL
    - NPM_TOKEN=abc123
```

The `exec` command reads the file from the working directory or any parent folder and forwards the listed variables on every run. `--env` overrides a same-named entry, and `--no-env-file` skips the file entirely.

## Running AI coding agents

The `bitrise-cli rde claude` command creates a session, clones your current repository branch into it, and drops you into Claude Code running on the cloud machine. While the agent works, the CLI keeps a secure connection open so it can open a VNC viewer or transfer files to and from your local machine.

This is the recommended way to start. For the full walkthrough, see the [Quickstart](/bitrise-rde/getting-started/quickstart). Some behaviors worth knowing:

- The CLI asks you to pick a stack and a machine type, and remembers your choice for the repository. Pass `--stack` and `--machine-type` to skip the prompts, for example in scripts.
- If no Claude Code credential is saved for your workspace yet, the CLI picks up your local one, or opens the browser so you can create one, and saves it for future sessions. You can also manage the credential in the [Bitrise RDE UI](/bitrise-rde/rde-options/bitrise-rde-ui#authentication).
- If the connection drops, the CLI reconnects automatically while Claude Code keeps running in the session. Press Ctrl-C during a reconnect to detach and leave the machine running.
- When you exit Claude Code, the session is terminated automatically, but preserved so you can restore it later.

To return to a session, use `bitrise-cli rde claude --continue` for the most recent one, or `bitrise-cli rde claude --resume` to pick from a list. Resuming reconnects to a running session, or restores a terminated one and continues the same Claude Code conversation.

## Virtual devices

The CLI covers both ways to use [virtual devices](/bitrise-rde/devices/virtual-devices):

- `bitrise-cli rde session create NAME --device-platform ios|android`: create a [device session](/bitrise-rde/devices/device-sessions). The `--device-model`, `--device-os-version`, `--device-system-image`, and `--artifact-url-stdin` flags set the device and the app to install.
- `bitrise-cli rde device-guide [ios|android]`: print the guide for waiting for, connecting to, and driving a device.
- `bitrise-cli rde preview-link create --device-platform ios|android --artifact-url URL`: mint a [device preview link](/bitrise-rde/devices/device-preview-links).

## Warm pools

`bitrise-cli rde warm-pool` manages [warm pools](/bitrise-rde/configuration/warm-pools), and the session and preview link commands claim from them. Commands that take a `WARM_POOL_ID` also accept the pool's name.

| Command | What it does |
| --- | --- |
| `bitrise-cli rde warm-pool create NAME --template TEMPLATE --size N` | Create a pool. Add `--input` and `--secret-input` for the template's inputs, and the `--stack`, `--machine-type`, and `--device-*` flags to override the template. |
| `bitrise-cli rde warm-pool list` | List the workspace's pools, with their size and how many sessions are ready. `--all` is the read-only cost view of the same pools, for workspace owners and members who manage billing. |
| `bitrise-cli rde warm-pool view WARM_POOL_ID` | Show a pool's status, configuration, and warm sessions. |
| `bitrise-cli rde warm-pool set-size WARM_POOL_ID N` | Change how many sessions the pool keeps booted. `0` drains it but keeps the configuration. |
| `bitrise-cli rde warm-pool update WARM_POOL_ID` | Rename a pool or change its configuration. A configuration change replaces the warm sessions. |
| `bitrise-cli rde warm-pool delete WARM_POOL_ID` | Delete a pool and its warm sessions. |
| `bitrise-cli rde session create NAME --warm-pool WARM_POOL_ID` | Claim a session from a pool. |
| `bitrise-cli rde preview-link create --warm-pool WARM_POOL_ID --artifact-url URL` | Mint a device preview link whose opens are served from a warm pool. |

## Templates, saved inputs, and machine options

The CLI also manages the configuration objects behind your sessions:

- `bitrise-cli rde template`: list, create, view, update, and delete [templates](/bitrise-rde/configuration/templates).
- `bitrise-cli rde saved-input`: list, create, view, update, and delete [saved inputs](/bitrise-rde/configuration/saved-inputs).
- `bitrise-cli rde stack list`: list the stacks available in your workspace.
- `bitrise-cli rde machine-type list --stack STACK_ID`: list the machine types compatible with a given stack.

## Workspace usage

Workspace owners and members who manage billing can check what the workspace's active sessions consume:

```bash
bitrise-cli rde usage
```

The report is a point-in-time snapshot: active session counts and vCPU and memory totals split by OS, plus a per-user breakdown. Add `--output json` for a machine-readable version to use in scripts and automations.

## Full command reference

Every command has detailed built-in help, written so that both people and AI agents can discover features from it. The help is updated together with the features themselves, so it's the most current reference:

```bash
bitrise-cli rde --help
bitrise-cli rde session exec --help
```

The generated reference for every command, flag, and argument lives in the open-source repository: [bitrise-io/bitrise-cli](https://github.com/bitrise-io/bitrise-cli/tree/main/docs/cli).