Integrate

The troupe CLI

Every command of the troupe command-line tool, with its options and exit codes.

Running it

The CLI comes with @alivelabs/troupe. Run it with bunx from a project that has the package installed:

Shell

bunx troupe <command> [options]

Bun runs the command; npx cannot. bunx troupe --help lists the commands, and --version prints the version. init, test, mcp install, login, logout and whoami print their own options with --help.

Results go to stdout. Progress, warnings and errors go to stderr. So a printed URL or --json output is safe to capture.

Command	What it does
`init`	Writes a config, an example test and the project's script
`test`	Runs tests
`install`	Prepares platforms once
`doctor`	Checks the environment
`runtime`	Starts, stops and inspects the runtime daemon, and cleans up
`studio`	Opens Troupe Studio
`mcp`	Serves MCP over stdio, and writes an MCP client's config
`login`, `logout`, `whoami`	Signs in to Troupe Cloud
`merge-reports`, `show-report`, `show-trace`	Merges and serves reports and traces

Commands

`init`

Shell

bunx troupe init [--app <build>]...

Writes a project into the current directory and never replaces a file that exists: troupe.config.ts, e2e/example.e2e.ts, the "e2e": "troupe test" script and the @alivelabs/troupe dev dependency in package.json, and the report directories in .gitignore. See the Quick start.

Option	What it does
`--app <build>`	The app to test. Repeat it to name an iOS build (a `.app`, or a `.tar.gz`, `.tgz`, `.zip` or `.ipa` that holds one) and an Android `.apk`

Without --app, init looks for the newest build of an Expo, React Native, Xcode or Gradle project where those tools leave one.

`test`

Shell

bunx troupe test [files...] [options]

Runs the tests of troupe.config.ts, or only the files you name. It starts the runtime daemon when none runs, and checks the environment for the config's platforms before it acquires a device: a failed check ends the run with exit code 3 and prints each fix. See Testing.

Option	What it does
`-c`, `--config <file>`	The config file. Default: `troupe.config.ts` in this directory
`--project <name>`	Only this project. Repeatable
`-g`, `--grep <regex>`	Only tests whose title matches
`--grep-invert <regex>`	Skip tests whose title matches
`-j`, `--workers <n>`	At most `n` workers. The runtime's device capacity also bounds it
`--shard <i/n>`	Run shard `i` of `n`
`--retries <n>`	Retries per failed test
`--timeout <ms>`	The timeout of each test
`--repeat-each <n>`	Run each test `n` times
`-x`, `--max-failures <n>`	Stop after `n` failures
`--forbid-only`	Fail when a `test.only` is present
`--reporter <names>`	Reporters, comma-separated: `list`, `line`, `dot`, `json`, `junit`, `blob`
`--trace <mode>`	`on`, `off`, `retain-on-failure`, `on-first-retry`, `on-all-retries` or `retain-on-first-failure`
`--output <dir>`	The directory for traces and attachments
`--no-daemon`	Run the runtime inside this command for this run. Also the case when `CI` is set
`--list`	List the tests the run would schedule. It needs no runtime and no device
`-u`, `--update-snapshots`	Rewrite screenshot snapshots that are missing or differ

`install`

Shell

bunx troupe install [platform...] [--no-device] [--no-daemon]

Prepares ios, android or catalyst once: it records the toolchain in host.json, runs the environment checks, builds what the platform builds ahead, and starts one device to prove the path. With no platform it prepares those the config uses, or without a config every platform this machine can run. See Install.

Option	What it does
`--no-device`	Skip starting a device
`--no-daemon`	Start that device from a runtime inside this command. Also the case when `CI` is set

`doctor`

Shell

bunx troupe doctor [--json] [--all]

Runs the read-only environment checks of the platforms the config uses and prints one line per check. A failed check prints its fix on the next line.

Output

pass  xcode.selected [ios-simulator]: Xcode <version> (<build>) at <path>
pass  ios.deviceHub [ios-simulator]: Neither Device Hub nor Simulator.app is running.

Option	What it does
`--all`	Check every platform. Also the case when there is no config
`--json`	Print the result of `runtime.doctor` as JSON

It exits 1 when a check fails.

`runtime`

Manages the runtime daemon. See The runtime.

Command	What it does	Exits non-zero
`runtime start [--detach]`	Runs the daemon in the foreground, or with `--detach` in the background
`runtime stop [--force]`	Stops the daemon. `--force` ends live sessions	1 when sessions are live and `--force` is absent
`runtime status [--json]`	Prints the daemon's sessions, devices and memory governor	1 when no daemon runs
`runtime sweep [--apply] [--no-daemon] [--json]`	Lists leaked devices and process groups Troupe owns. `--apply` removes them. `--no-daemon` sweeps from this command instead of through the daemon	1 when something it set out to remove is still there
`runtime kill-all [--disable] [--json]`	Stops every runtime of yours and sweeps every home they used. `--disable` also switches every platform off in `host.json`	1 when something Troupe owns is still there

`studio`

Shell

bunx troupe studio

Starts the daemon when none runs and prints the URL of Troupe Studio with a one-time pairing code. It takes no options and does not launch a browser.

`mcp`

Shell

bunx troupe mcp [--toolset all]

Serves MCP over stdio, bridged to the local daemon. An MCP client starts it; you rarely run it by hand. --toolset takes curated (the default) or all. See MCP.

Shell

bunx troupe mcp install --client <client> [options]

Prints the config entry for an MCP client, or merges it into the client's project file.

Option	What it does
`--client <client>`	`claude-code`, `cursor`, `vscode` or `codex`. Required
`--write`	Write the client's file instead of printing the entry
`--name <name>`	The server's name in the file. Default: `troupe`
`--toolset all`	Every tool instead of the curated set
`--cloud <url>`	Troupe Cloud's `/mcp` instead of the local runtime
`--api-key-env <name>`	With `--cloud`: send an API key from this environment variable. The file holds only the variable's name

It exits 2 when --write would have to replace a different entry or cannot merge the file safely.

`login`, `logout` and `whoami`

Shell

bunx troupe login --cloud https://api.troupe.ali.ve
bunx troupe whoami
bunx troupe logout

login prints a page to open and a code to check there, waits for your approval, and keeps the sign-in in the login keychain. whoami checks the sign-in with the cloud and prints the cloud, user, organization, project, scopes and platforms. logout revokes the sign-in and forgets it. See Signing in.

Command	Option	What it does
`login`	`--cloud <url>`	The cloud's API address. Default: the cloud you are signed in to
`whoami`	`--json`	Print the sign-in as JSON

login exits 1 when the sign-in is denied or expires, and 3 when the cloud cannot be reached or the sign-in cannot be kept. whoami exits 1 when you are not signed in. logout exits 0 either way.

Reports and traces

Shell

bunx troupe merge-reports <dir> [--reporter <names>]
bunx troupe show-report [dir]
bunx troupe show-trace <trace.zip>

Command	What it does
`merge-reports`	Replays the blob reports in `<dir>` as one run, through the reporters you name. Default: `list`
`show-report`	Serves an HTML report. Default directory: `troupe-report`
`show-trace`	Serves one trace in the trace viewer

show-report and show-trace print a URL on a loopback port and serve until Ctrl+C. See Reporters and Traces.

Exit codes

Code	Meaning
0	Success. For `test`: every test had its expected outcome
1	A test failed or timed out. For other commands: the command's own check failed, as its section says
2	Usage or configuration: an unknown option, a missing or invalid config, an invalid `host.json`
3	The environment or infrastructure: a failed environment check before `test`, a device that did not start, an unreachable server
130	Canceled with Ctrl+C

Environment variables

Variable	What it does
`TROUPE_HOME`	Where the runtime keeps its state. Default: `~/.troupe`
`TROUPE_HOST_HOME`	Where the ledger of ports shared by your runtimes is. Default: `~/.troupe-host`
`CI`	When set to anything but an empty value, `0` or `false`, `test` and `install` run the runtime inside the command
`DEVELOPER_DIR`	The Xcode that `install` records the first time it writes `host.json`
`ANDROID_HOME`, `ANDROID_SDK_ROOT`	Where `install android` looks for the SDK to record
`TROUPE_UPDATE_SNAPSHOTS`	The snapshot update mode: `all`, `changed`, `missing` or `none`
`TROUPE_STUDIO_CLOUDS`	The Troupe Clouds that Troupe Studio may sign in to

Quick start: the commands in order, from nothing to a report
Running in CI: shards, retries, reports and exit codes in a pipeline
The runtime: what the runtime commands manage

The troupe CLI

Running it

Commands

init

test

install

doctor

runtime

studio

mcp

login, logout and whoami

Reports and traces

Exit codes

Environment variables

Next

`init`

`test`

`install`

`doctor`

`runtime`

`studio`

`mcp`

`login`, `logout` and `whoami`