CLI Reference - Run Cloud

This is the reference for the latest runcloud command-line interface. Install it from npm:

npm install -g runcloud

Use runcloud --version to print the installed version and runcloud <command> --help to inspect the exact options supported by that version.

Authentication

Command	Description
`runcloud login`	Sign in through the browser and save the CLI credential.
`runcloud whoami`	Show the saved credential: account, API, expiry, and file.
`runcloud logout`	Delete the saved CLI credential.
`runcloud account`	Show account access, organizations, balance, and metering status.

Use runcloud login --manual when the browser cannot return to the local callback automatically. runcloud account --json returns machine-readable output. runcloud whoami reads the stored credential without calling the API, so it answers which credential will be sent — including one supplied through RUN_CLOUD_API_KEY, which takes precedence over the saved file. It exits non-zero when there is no credential or the saved one has expired. Signing in again is runcloud login; it now offers to keep the existing session rather than replacing it silently.

Mobile sessions

The iOS and Android command groups share the same lifecycle:

Command	Description
`runcloud ios create`	Create an iOS simulator session.
`runcloud ios list`	List active iOS sessions. Pass `--all` to include released sessions.
`runcloud ios get <id>`	Get one iOS session.
`runcloud ios open-url <url> --id <id>`	Open an HTTP(S) URL or application deep link.
`runcloud ios accessibility-tree <id> [--json]`	Read the current typed accessibility hierarchy. `accessibility` is an alias.
`runcloud ios camera inject <id> <video>`	Upload MP4 or MOV and loop it through the app camera.
`runcloud ios microphone inject <id> <audio>`	Deliver supported audio through the app microphone. `mic` is an alias.
`runcloud ios screenshot <id> --output <path>`	Save the current display as a validated PNG.
`runcloud ios recording start\|list\|status\|stop\|download …`	Capture and retrieve MP4 screen recordings.
`runcloud ios logs <id> [--tail N\|--follow]`	Read retained logs or follow new entries.
`runcloud ios delete <id>`	Release an iOS session.
`runcloud android create`	Create an Android emulator session.
`runcloud android list`	List active Android sessions. Pass `--all` to include released sessions.
`runcloud android get <id>`	Get one Android session.
`runcloud android open-url <url> --id <id>`	Open an HTTP(S) URL or application deep link.
`runcloud android accessibility-tree <id> [--json]`	Read the current typed accessibility hierarchy. `accessibility` is an alias.
`runcloud android camera inject <id> <video>`	Upload MP4 or MOV and loop it through the app camera.
`runcloud android microphone inject <id> <audio>`	Deliver supported audio through the app microphone. `mic` is an alias.
`runcloud android screenshot <id> --output <path>`	Save the current display as a validated PNG.
`runcloud android recording start\|list\|status\|stop\|download …`	Capture and retrieve MP4 screen recordings.
`runcloud android logs <id> [--tail N\|--follow]`	Read retained `logcat` or follow new entries.
`runcloud android delete <id>`	Release an Android session.

open-url also accepts --json. Its successful JSON contains ok, platform, sessionId, device, leaseId, and the exact, unnormalized url argument. Percent-encode spaces, and quote a URL that contains &, #, or other shell syntax:

runcloud ios open-url \
  'runcloudproof://open/items%2F42?message=hello%20world#proof' \
  --id "$SESSION_ID" \
  --json

See Open URLs and Deep Links for the Android equivalent, authentication, encoding rules, the direct REST request, expected platform behavior, and stable error codes. Media injection accepts --bundle-id, --name, and --json on both platforms:

runcloud ios camera inject "$SESSION_ID" ./quadrants.mp4 \
  --bundle-id com.example.CameraRecorder --json
runcloud android microphone inject "$SESSION_ID" ./tone.wav \
  --bundle-id com.example.AudioRecorder --json

Camera files must be MP4 or MOV. Microphone files may be AAC, M4A, MP3, MP4-audio, or WAV. Each success response includes the retained media asset; use runcloud asset delete <asset-id> after the source is no longer needed.

Xcode builds

Command	Description
`runcloud xcode build [path]`	Package source, submit a remote Xcode build, stream logs, and optionally download the artifact.
`runcloud xcode rebundle [path] --basis-build <id>`	Reuse a compatible Expo or React Native native shell and replace only its JavaScript bundle.
`runcloud xcode get <id>`	Read durable build state, artifact metadata, and an actionable failure.
`runcloud xcode list`	List builds visible to an organization member.
`runcloud xcode events`	Replay ordered build events after a durable cursor.
`runcloud xcode logs <id> [--follow]`	Read the sanitized live or retained log.
`runcloud xcode artifact <id>`	Download retained output through authenticated access.
`runcloud xcode cancel <id>`	Cancel queued or running work.

xcode build supports project/workspace and shared-scheme selection, iOS and watchOS device and simulator SDKs, Debug or Release, XcodeGen, React Native and Expo preparation, optional Git initialization, safe build settings, manual or cloud signing, App Store upload and automatic build numbering, custom output upload, source include/exclude rules, additional files, and independent remote and client wait timeouts. Pass --no-wait or --detach to return the durable build ID without losing access to later status, logs, or output. See Build with Xcode for executable unsigned and signed examples, source packaging behavior, and intentional compatibility differences. ios create and android create accept:

Option	Description
`--model <model>`	Select a device model.
`--region <region>`	Request a fleet region.
`--display-name <name>`	Add a human-readable session name.
`--org-id <id>`	Select the organization that owns the session.
`--label <key=value>`	Attach a label. Repeat the option for multiple labels.
`--install <file>`	Upload and install a local app artifact. Repeat for multiple artifacts.
`--install-asset <name-or-id>`	Install a previously uploaded asset.
`--inactivity-timeout <duration>`	Release an idle session after a duration such as `60s` or `3m`; use `none` to disable.
`--hard-timeout <duration>`	Set the maximum session lifetime, such as `10m` or `1h`.
`--codec <auto\|mjpeg\|webrtc>`	Select the viewer stream codec.
`--rm`	Release the session when the command exits.
`--json`	Return JSON instead of formatted terminal output.

iOS sessions also support runcloud ios tunnel <id> and runcloud ios tunnel-status for connecting a local development service to the remote simulator. See Run an iOS Simulator for the full workflow. ios logs and android logs return the last 200 current-lease entries by default. Set --tail from 1 to 1,000, use --follow for new entries, and add --json for structured output. --tail and --follow are mutually exclusive.

Simulator controls

Every control command is available under both runcloud ios and runcloud android unless the capability table says otherwise:

Command	Description
`tap <id> <x> <y>`	Tap normalized display coordinates.
`swipe <id> <from-x> <from-y> <to-x> <to-y>`	Swipe between two display points; accepts `--duration`.
`gesture <id> --steps <json>`	Run an ordered one- or two-finger gesture.
`type-text <id> <text>`	Enter US ASCII text.
`press-key <id> <key>`	Press a semantic key; accepts `--shift`, `--control`, `--alt`, `--meta`, and `--duration`.
`press-button <id> <button>`	Press a hardware or system button; accepts `--duration`.
`rotate <id> <orientation>`	Set an absolute display orientation.
`reload <id>`	Reload the foreground app.
`scroll <id> <delta-x> <delta-y>`	Send normalized scroll deltas; accepts a paired `--x` and `--y` anchor.
`toggle-software-keyboard <id>`	Toggle the on-screen keyboard.
`simulate-memory-warning <id>`	Send a memory-warning event.
`rotate-digital-crown <id> <delta>`	Request Digital Crown input. Current iOS Simulator and Android Emulator sessions return an unsupported-action error.
`set-render-debug <id> <option> <enabled>`	Change an iOS rendering diagnostic. Android returns an unsupported-action error.

rotate accepts portrait, portrait_upside_down, landscape_left, and landscape_right. Current iPhone Simulator sessions support portrait and the two landscape values; requesting portrait_upside_down returns a structured, non-retryable unsupported_action error. Android Emulator sessions support all four values. Coordinates are inclusive from 0 to 1, with {0, 0} at the top-left of the current display. Every control accepts --timeout <milliseconds> (100 to 60,000, default 15,000), --request-id <id>, and --json. Successful JSON contains ok, requestId, sessionId, platform, action, status, timestamps, duration, and action-specific result data. Error JSON contains the same correlation fields when available and an error object with code, message, retryable, and optional details. Ctrl-C while a request is pending exits with code 130 and an interaction_cancelled JSON error. A timeout has status timed_out and code interaction_timeout; neither case releases the session. Screenshot capture uses the parallel screenshot_cancelled, screenshot_timeout, screenshot_transport_error, and screenshot_invalid_response codes. accessibility-tree accepts --timeout (20,000 milliseconds by default) and --json. Without --json, it prints an indented tree. Its JSON is the stable cross-platform schema documented in Read the Accessibility Tree. Ctrl-C returns accessibility_cancelled; transport, timeout, and invalid-schema failures use the corresponding accessibility_* code and never release the session. See Control a Simulator for all keys, buttons, gestures, platform differences, and copy-pasteable examples.

Screen recordings

The recording command group is identical for iOS and Android:

Command	Description
`recording start <session-id>`	Start one MP4 capture. Accepts `--idempotency-key`.
`recording list <session-id>`	List retained recordings for the session.
`recording status <session-id> <recording-id>`	Show status, lifecycle events, failures, and retrieval metadata. `get` is an alias.
`recording stop <session-id> <recording-id>`	Stop and finalize the capture. Safe to repeat.
`recording download <session-id> <recording-id> --output <path>`	Download and validate a ready MP4 through the authenticated API.

Every command accepts --json. The download result contains the local path, byte size, content type, and SHA-256 digest without printing a signed storage URL. See Record a Simulator for lifecycle, retention, retry, release, SDK, and REST examples.

Assets and samples

Command	Description
`runcloud asset push <file>`	Upload an app artifact for later installation.
`runcloud asset list [--org-id <id>]`	List organization Assets.
`runcloud asset pull <id>`	Download an uploaded asset.
`runcloud asset delete <id>`	Delete an uploaded asset.
`runcloud sample download ios`	Download the checksum-verified iOS onboarding app.
`runcloud sample download android`	Download the checksum-verified Android onboarding app.

asset also accepts the plural alias assets; sample accepts samples. Xcode outputs appear as immutable Assets and can be installed on any authorized simulator host without exposing build-host credentials.

Capabilities and mobile launches

Command	Description
`runcloud capability create`	Mint a 60–3,600 second bearer token restricted to selected Assets, builds, or idempotency keys.
`runcloud capability list`	List capability metadata without returning secret token values.
`runcloud capability revoke <id>`	Revoke a capability immediately.
`runcloud mobile launch --asset <id> --idempotency-key <key>`	Create one retry-safe mobile session and install an existing Asset.
`runcloud mobile launch --build <id> --idempotency-key <key>`	Create one retry-safe iOS session from a successful simulator build.
`runcloud mobile get <id>`	Inspect the stable launch operation, session, or actionable failure.

Use the same launch idempotency key after a timeout or lost response. A retry returns the original operation and never consumes a second simulator. See Build with Xcode for complete capability, event, Asset, rebundle, and launch examples.

Sandboxes

Sandboxes are the single compute noun. Persistence and a stable public hostname are capabilities you turn on, not a separate product:

Command	Description
`runcloud sandbox create`	Create a microVM sandbox.
`runcloud sandbox list`	List sandboxes; exposed ones show their hostname. `--state` and `--name` filter.
`runcloud sandbox get <id>`	Inspect a sandbox, including its public hostname when exposed.
`runcloud sandbox expose <id>`	Publish a guest port at a stable hostname, or change the published port.
`runcloud sandbox exec <id> <command...>`	Run a command through `/bin/sh -c`.
`runcloud sandbox shell <id>`	Open an interactive shell; paused sandboxes resume automatically.
`runcloud sandbox pause <id>`	Pause a sandbox so it can be resumed later. `stop` is an alias.
`runcloud sandbox resume <id>`	Resume a paused sandbox. `start` is an alias.
`runcloud sandbox rename <id> <name>`	Change a sandbox’s label; pass `""` to clear it.
`runcloud sandbox logs <id>`	Show recent sandbox logs.
`runcloud sandbox rm <id>`	Permanently destroy a sandbox and its public hostname. `kill` and `terminate` are aliases.
`runcloud sandbox snapshot create <id>`	Capture a restorable snapshot.
`runcloud sandbox snapshot list`	List snapshots.
`runcloud sandbox snapshot rm <id>`	Delete a snapshot.
`runcloud sandbox restore <snapshot-id>`	Create a sandbox from a snapshot.
`runcloud sandbox setup-ssh <sandbox>`	Install a dedicated key and add the exposed sandbox to SSH config.
`runcloud sandbox ssh <sandbox> [command...]`	Open a shell or run a command over SSH.
`runcloud sandbox cp <sandbox> <source> <destination>`	Copy files with SCP; prefix the remote path with `:`.
`runcloud sandbox code <sandbox> [path]`	Open the exposed sandbox with VS Code Remote SSH.
`runcloud sandbox domain add\|list\|status\|rm`	Manage custom domains on an exposed sandbox.

sandbox create accepts:

Option	Description
`--image <ref>`	Select the base image. Defaults to `runcloud/agent-base`, including with `--expose`.
`--region <region>`	Request a placement region.
`--name <name>`	Add a human-readable name. With `--expose`, it is the hostname prefix `<name>-box.run.cloud`.
`--org <id>`	Select the owning and billing organization.
`--cpu <cores>`	Set the vCPU allocation; fractional values such as `0.5` are supported.
`--memory <mb>`	Set the memory allocation in MiB.
`--disk <gb>`	Set root disk capacity in GiB.
`--idle-pause <seconds>`	Pause after inactivity; use `0` to keep the sandbox running.
`--timeout <seconds>`	Set the maximum sandbox lifetime. Defaults to `300`; use `0` to disable.
`--persistent`	Never pause when idle. Same as `--idle-pause 0`; also disables the default lifetime unless `--timeout` is explicit.
`--expose <port>`	Publish a guest port at `<name>-box.run.cloud`. Implies `--persistent` and requires `--name`.
`--no-wait`	Return after scheduling instead of waiting for the sandbox to finish building and starting.
`--json`	Return JSON instead of formatted terminal output.

sandbox expose accepts --port <port> (default 3000), --name <name> for a first exposure (defaults to the sandbox name), and --reconcile to retry hostname routing. See Persistent Sandboxes for creation and routing examples.

Images

Command	Description
`runcloud image create --ref <ref>`	Register (build-once) an OCI image ref, wait until ready, and exit non-zero if the build fails or times out.
`runcloud image create --ref <ref> --no-wait`	Schedule the build and return immediately with the registration row.
`runcloud image list`	List images your organization has registered, with state and digest.
`runcloud image refresh <ref>`	Move a tag’s pin to its current upstream digest; prints `old_digest`/`new_digest`.

See Custom Images for the full workflow, including CI pre-baking.

Deprecated: `runcloud box`

Earlier releases modeled an exposed persistent sandbox as a separate box noun. Every runcloud box … command still works as a deprecated alias and prints a pointer to its sandbox equivalent:

Deprecated	Use instead
`runcloud box create <name>`	`runcloud sandbox create --expose <port> --name <name>`
`runcloud box create <name> --sandbox <id>`	`runcloud sandbox expose <id> --name <name>`
`runcloud box list`	`runcloud sandbox list`
`runcloud box get <id>`	`runcloud sandbox get <sandbox-id>`
`runcloud box port <id> <port>`	`runcloud sandbox expose <sandbox-id> --port <port>`
`runcloud box route <id>`	`runcloud sandbox expose <sandbox-id> --reconcile`
`runcloud box rm <id>`	`runcloud sandbox rm <sandbox-id>`
`runcloud box setup-ssh\|ssh\|cp\|code\|domain …`	The same verb under `runcloud sandbox …`

SSH config blocks written by older releases keep connecting: the box proxy transport remains supported, and re-running setup-ssh rewrites the block to the current form.

Demos and agent skills

Command	Description
`runcloud demo run [name]`	Run a bundled demo. The default is `eight-device-mosaic`.
`runcloud demo init [name] [directory]`	Scaffold a standalone demo project.
`runcloud skills install`	Install the run.cloud skill for supported coding agents.

Available demos are eight-device-mosaic and live-camera-relay. Pass --open to open the viewer automatically.

Automation

Commands that return structured data accept --json. A typical shell workflow captures IDs rather than copying placeholders:

SANDBOX_ID=$(runcloud sandbox create --json | jq -r '.id')
trap 'runcloud sandbox rm "$SANDBOX_ID"' EXIT

runcloud sandbox exec "$SANDBOX_ID" "echo hello"

See the CLI quickstart for complete runnable examples.

​Authentication

​Mobile sessions

​Xcode builds

​Simulator controls

​Screen recordings

​Assets and samples

​Capabilities and mobile launches

​Sandboxes

​Images

​Deprecated: runcloud box

​Demos and agent skills

​Automation