> ## 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.

# Install the CLI

> Install runcloud with one command, and control what it does in CI and agent environments

```bash theme={null}
curl -fsSL https://run.cloud/install | sh
```

This installs a standalone `runcloud` binary and then starts sign-in, so one
command takes you from nothing to an authenticated CLI. Nothing needs to be
preinstalled — no Node, no package manager, no `sudo`.

If you already have Node:

```bash theme={null}
npm install -g runcloud && runcloud login
```

## What the installer does

1. Detects your platform: `darwin-arm64`, `darwin-x64`, `linux-x64`, or
   `linux-arm64`. Anything else exits with a message pointing at npm.
2. Reads the release manifest from `https://dl.run.cloud/latest.json`.
3. Downloads the binary for your platform and verifies its SHA-256. A mismatch
   aborts without touching an existing install.
4. Installs to `~/.run-cloud/bin/runcloud`, writing to a temporary file and
   renaming it into place so an interrupted download cannot leave a partial
   binary on your `PATH`.
5. Adds `~/.run-cloud/bin` to your `PATH` in `~/.zshrc`, `~/.bashrc`, or
   `~/.profile` — once, not on every run.
6. Starts `runcloud login`, unless the environment says otherwise (below).

Re-running the command upgrades in place and is safe to repeat.

## Non-interactive installs

CI runners, Dockerfiles, and agents that already hold an API key must not be
asked to pick a sign-in method. The installer skips sign-in and exits `0` when
any of the following is true:

| Condition                                           | Why                                                                 |
| --------------------------------------------------- | ------------------------------------------------------------------- |
| `RUN_CLOUD_API_KEY` or `RUN_CLOUD_API_TOKEN` is set | A caller with a key does not need an account chooser.               |
| `CI` is set                                         | The convention every CI provider sets.                              |
| `RUNCLOUD_NO_LOGIN` is set                          | Explicit opt-out.                                                   |
| Standard output is not a terminal                   | Output is being captured or redirected.                             |
| `/dev/tty` cannot be opened                         | Common in containers, where the device exists but opening it fails. |

In those cases the binary is installed and the command prints how to sign in
later. An agent with a key can use the CLI immediately:

```bash theme={null}
export RUN_CLOUD_API_KEY="rc_live_..."
curl -fsSL https://run.cloud/install | sh
runcloud ios create --json
```

<Note>
  Under `curl … | sh` the pipe is the script's standard input, so an interactive
  prompt has nothing to read there. The CLI opens the controlling terminal
  itself, which is what lets one command both install and sign in.
</Note>

## Environment variables

| Variable               | Default                | Effect                                                   |
| ---------------------- | ---------------------- | -------------------------------------------------------- |
| `RUNCLOUD_VERSION`     | latest                 | Install a specific release, for example `0.1.9-abc1234`. |
| `RUNCLOUD_INSTALL_DIR` | `~/.run-cloud/bin`     | Where the binary is written.                             |
| `RUNCLOUD_NO_LOGIN`    | unset                  | Install only; do not start sign-in.                      |
| `RUNCLOUD_DL_BASE`     | `https://dl.run.cloud` | Download origin. Mostly useful for testing.              |
| `CI`                   | unset                  | When set, sign-in is skipped.                            |
| `RUN_CLOUD_API_KEY`    | unset                  | When set, sign-in is skipped and the CLI uses the key.   |

Pin a release in CI so a new build cannot change what your pipeline runs. The
release id is the version plus the commit it was built from, and every release
gets its own permanent path:

```bash theme={null}
RUNCLOUD_VERSION=0.1.9-abc1234 RUNCLOUD_NO_LOGIN=1 \
  sh -c "curl -fsSL https://run.cloud/install | sh"
```

`https://dl.run.cloud/latest.json` names the current release id.

## Where things live

| Path                        | Contents                           |
| --------------------------- | ---------------------------------- |
| `~/.run-cloud/bin/runcloud` | The binary.                        |
| `~/.run-cloud/credentials`  | The saved credential, mode `0600`. |

`RUN_CLOUD_HOME` moves both. To uninstall, delete `~/.run-cloud` and remove the
`PATH` line the installer added to your shell config.

## Verifying a download

Every release publishes a manifest with a SHA-256 per platform, which the
installer checks before installing. To verify by hand:

```bash theme={null}
curl -fsSL https://dl.run.cloud/latest.json
```

Each entry gives the object path and its digest; artifacts live at
`https://dl.run.cloud/<release-id>/runcloud-<target>.gz` and are never
rewritten — a rebuilt binary always gets a new path.

## Next steps

<Card title="Quickstart" icon="rocket" href="/cli/quickstart">
  Authenticate and open your first sandbox or mobile session.
</Card>