Bitrise RDE CLI
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. This page is the broader reference for what the CLI can do.
Installing the CLIClick to copy link
Install the latest version with the install script:
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 or install from source with go install github.com/bitrise-io/bitrise-cli@latest.
Signing inClick to copy link
Sign in to your Bitrise account. This opens your browser to authenticate:
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 workspaceClick to copy link
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:
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 sessionsClick to copy link
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 --wait to block until the session is running. |
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. |
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 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 sessionClick to copy link
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:
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:
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:
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 agentsClick to copy link
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. Some behaviors worth knowing:
- The CLI asks you to pick a stack and a machine type, and remembers your choice for the repository. Pass
--stackand--machine-typeto 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.
- 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.
Templates, saved inputs, and machine optionsClick to copy link
The CLI also manages the configuration objects behind your sessions:
bitrise-cli rde template: list, create, view, update, and delete templates.bitrise-cli rde saved-input: list, create, view, update, and delete 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.
Full command referenceClick to copy link
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:
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.