> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Commands available in the latest runcloud CLI.

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

```bash theme={null}
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 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.

## 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 URL or deep link.                                           |
| `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 URL or deep link.                                           |
| `runcloud android delete <id>`              | Release an Android session.                                              |

`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.                                                     |
| `--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](/ios/run-simulator) for the full
workflow.

## Assets and samples

| Command                            | Description                                            |
| ---------------------------------- | ------------------------------------------------------ |
| `runcloud asset push <file>`       | Upload an app artifact for later installation.         |
| `runcloud asset list`              | List uploaded 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`.

## 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.                                          |
| `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 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`, or `runcloud/box` 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](/compute/boxes) 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](/compute/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:

```bash theme={null}
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](/cli/quickstart) for complete runnable examples.