---
title: "Managing components"
description: "How surreal installs, upgrades, pins, switches and removes components, how version names work (3.3.2, 2, beta, nightly), running another version once with +VERSION, and offline or unattended use."
canonical_url: "https://surrealdb.com/docs/reference/cli/guides/components"
section: "CLI guides"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Managing components

How surreal installs, upgrades, pins, switches and removes components, how version names work (3.3.2, 2, beta, nightly), running another version once with +VERSION, and offline or unattended use.

`surreal` runs components, and it is the only thing that installs, upgrades or removes them. Five launcher commands cover the whole life of a component: `surreal install`, `surreal upgrade`, `surreal use`, `surreal uninstall` and `surreal list`. A component never installs or upgrades another one, and `surreal <component> ...` always belongs to the component itself.

This page explains how components are stored, how to name a version, and how to install, upgrade, pin, switch and remove them. The reference for each command is [Launcher commands](/docs/reference/cli/launcher.md).

## How components are stored

Every component version is a separate executable under the SurrealDB home, `~/.surrealdb` unless `SURREAL_CLI_HOME` says otherwise.

```text
~/.surrealdb/components/<name>/<version>/surreal-<name>   the executable
~/.surrealdb/components/<name>/pin                        the version that runs by default
```

Several versions of one component can sit side by side. The **pin** names the one that runs when you type `surreal db ...`, and nothing else decides it. The first install of a component pins it, a later install leaves the pin alone, and only `surreal use`, `surreal upgrade` and `surreal uninstall` move it. That is why installing a second database version cannot quietly change which database `surreal db start` runs.

When you run a component, `surreal` looks for its executable in this order:

1. The version named with `+VERSION`, from the store.
2. A `surreal-<name>` beside the `surreal` executable, which is how a package that ships several binaries together provides them. It runs ahead of the store, and the launcher does not upgrade or remove it.
3. The pinned version, from the store.
4. A `surreal-<name>` on your `PATH`.

A name that is not a component, such as `surreal foo`, runs a `surreal-foo` from your `PATH` if one exists, and reports an unknown component otherwise.

## Naming a version

Commands that take `COMPONENT[@VERSION]` accept these forms.

| Form | Meaning |
| --- | --- |
| `db` | The newest stable release. While a component has no stable release, its newest beta, then its newest alpha |
| `db@3.3.2` | That exact release (`db@v3.3.2` also works) |
| `db@2` | The newest stable release on major line 2 |
| `db@latest` | The newest stable release |
| `db@beta`, `db@alpha` | The newest release on that prerelease channel |
| `db@nightly` | The latest nightly build. Only the database publishes nightlies |

## See what is installed

```bash
surreal list
```

The table shows each component, the version that runs, where that version comes from, every installed version, and the path it runs from. In the `SOURCE` column, `pinned` is a version the launcher installed and pinned, `external` is a copy beside `surreal`, and `path` is a copy found on `PATH`. `surreal list --json` prints the same information as one JSON document. `surreal --version` prints only the launcher's own version.

## Install a component

```bash
surreal install cloud
surreal install db@3.3.2 cloud@0.1.0
```

`surreal install` downloads each release, checks it against its published SHA-256, runs it once to confirm it starts, and only then puts it in place. The first install of a component becomes its default. Installing another version of a component you already have installs it beside the pinned one and leaves the pin where it was.

To make what you install the default, add `--pin`. A version you name exactly becomes the default whatever it was before. A channel's release, such as `db@2` or `db@beta`, becomes the default unless the current default is a later release.

```bash
surreal install db@2 --pin
```

## Upgrade

```bash
surreal upgrade
```

With no arguments, `surreal upgrade` upgrades the launcher and every installed component that has a default version. Each follows the channel its default is on: a stable release stays on its major line, so a database on 2.x upgrades to the newest 2.x, and a prerelease follows its own channel. The `--dry-run` flag says what would change without changing it.

```bash
surreal upgrade --dry-run
```

To upgrade only some things, or to move to a particular version, name them.

```bash
surreal upgrade cloud
surreal upgrade db@3.3.2
surreal upgrade db@3
surreal upgrade cli
```

`cli` is the launcher itself. Naming a version moves the default to it, installing it first if needed.

The database also takes its familiar release flags, which are shorthand for naming the channel or version.

| Flag | Same as |
| --- | --- |
| `surreal upgrade --nightly` | `surreal upgrade db@nightly` |
| `surreal upgrade --beta` | `surreal upgrade db@beta` |
| `surreal upgrade --alpha` | `surreal upgrade db@alpha` |
| `surreal upgrade --version <VERSION>` | `surreal upgrade db@<VERSION>` |

> [!NOTE]
> The database no longer upgrades itself. `surreal db upgrade` is not run and points you to `surreal upgrade db`.

## Pin or switch a version

`surreal use` makes an installed version the default. It never downloads.

```bash
surreal use db@3.3.2
surreal use db@2
```

A major line or channel, such as `db@2`, selects the newest installed release on it. To pin a version that is not installed yet, use `surreal install db@<VERSION> --pin` or `surreal upgrade db@<VERSION>`.

## Run another version once

`+VERSION` as the first argument runs one version of whatever follows, for that command only. The pin does not change. If that version is not installed, `surreal` offers to install it first, under the rules in [Offline and unattended use](#offline-and-unattended-use).

```bash
surreal +2.6.5 db start --user root --pass secret
surreal +2 db export --endpoint http://localhost:8000 backup.surql
```

The version takes the same forms as in `COMPONENT@VERSION`: a release, a major line, or `latest`, `beta`, `alpha` or `nightly`. This is how you run an older database against data that has not been migrated yet, or compare two releases.

## Remove a component

```bash
surreal uninstall db@2.7.0
surreal uninstall cloud
```

`surreal uninstall <component>@<version>` removes that version. Naming a component alone removes every version of it and its default. The default version is removed by name only when nothing else is installed, so move the pin with `surreal use` first.

## Offline and unattended use

A component is never fetched behind your back.

- **At a terminal**, `surreal` names the download host and asks before it installs a missing component. `surreal db start` on a machine without the database offers to install it.
- **Unattended** (a CI runner, an agent, `--no-input`, a pipe on standard input, or a dumb terminal), `surreal` makes no request, and exits with code 12 and the command that would install the component. The `SURREAL_CLI_YES` variable does not count as consent to a download in the middle of another command; to install without a prompt, run `surreal install` explicitly, with `--yes` if you wish.
- **With `SURREAL_CLI_OFFLINE=1`**, the network is never touched, and a missing component fails at once.

In a pipeline, install what you need in an early step.

```bash title="CI step"
surreal install db cloud --no-input
```

## Environment variables

| Variable | Effect |
| --- | --- |
| `SURREAL_CLI_HOME` | Where the SurrealDB home is. Defaults to `~/.surrealdb` |
| `SURREAL_CLI_OFFLINE` | `1` forbids every network request |
| `SURREAL_CLI_DOWNLOAD_ROOT` | Replaces the download host, for a mirror |
| `SURREAL_CLI_NO_BANNER` | Hides the banner above `surreal help` |
| `SURREAL_CLI_JSON`, `SURREAL_CLI_PLAIN` | Same as `--json` and `--plain` on the launcher's commands |

These are the launcher's variables. Variables that start with `SURREAL_` and not `SURREAL_CLI_` belong to the database, and the launcher never reads them. Cloud's variables start with `SURREAL_CLOUD_`. See [Launcher commands](/docs/reference/cli/launcher.md) for exit codes and the full list.

## Package managers and shared machines

Where a package manager such as Homebrew or Nix owns `surreal`, the launcher refuses to install or replace anything in its place, and the package manager upgrades it. Components that the package provides beside `surreal` run before any pinned copy in the store, so a package upgrade is not shadowed by an older pinned version.
