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

# surreal launcher commands

Reference for the surreal launcher: install, upgrade, use, uninstall, version, --version, +VERSION, help, version names, SURREAL_CLI_* environment variables, and exit codes.

The `surreal` launcher is the command you install once. It owns every operation that installs or changes versions, and it hands everything else to a [component](/docs/explore/cli/components.md). Its own commands are `install`, `upgrade`, `use`, `uninstall` and `version`.

<Synopsis>
surreal [+VERSION] [COMPONENT] <COMMAND> [ARGS]...
surreal install [OPTIONS] <COMPONENT[@VERSION]>...
surreal upgrade [OPTIONS] [COMPONENT[@VERSION] | cli]...
surreal use [OPTIONS] <COMPONENT@VERSION>
surreal uninstall [OPTIONS] <COMPONENT[@VERSION]>...
surreal version [OPTIONS]
</Synopsis>

A component name as the first argument runs that component with everything after it, unchanged: `surreal db ...`, `surreal cloud ...`, `surreal mod ...`. The launcher never interprets those arguments. The guide to [managing components](/docs/explore/cli/components.md) explains how components are stored and chosen.

## Components

| Component | Runs as | Reference |
| --- | --- | --- |
| `db` | `surreal db <command>` | [Database commands](/docs/reference/cli/db.md) |
| `cloud` | `surreal cloud <command>` | [Cloud commands](/docs/reference/cli/cloud.md) |
| `mod` | `surreal mod <command>` | [Modules](/docs/reference/cli/modules.md) |

## Version names

Commands that take `COMPONENT[@VERSION]`, and `+VERSION`, accept the following.

| Form | Meaning |
| --- | --- |
| `3.3.2` or `v3.3.2` | That exact release |
| `2` | The newest stable release on major line 2 |
| `latest` | The newest stable release. Without a version, a component installs this, or its newest beta then alpha while it has no stable release |
| `beta`, `alpha` | The newest release on that channel |
| `nightly` | The latest nightly build. Only the database publishes one |

## surreal install

Install components, or another version of one beside those installed. The first install of a component becomes its default; later installs leave the default alone unless `--pin` is given.

<Synopsis>
surreal install [OPTIONS] <COMPONENT[@VERSION]>...
</Synopsis>

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

<OptionsTable
	title="Options"
	options={[
		{ "name": "--pin", "description": "Make each installed version the default. A version named exactly becomes the default whatever it was; a channel's release, such as `db@2`, becomes the default unless the current default is later." },
		{ "name": "--json", "description": "Print one JSON document on stdout." },
		{ "name": "--plain", "description": "Plain text: no tables, no colour, no animation." },
		{ "name": "--color", "value": "<WHEN>", "description": "When to use colour: `auto` (default), `always` or `never`." },
		{ "name": "--quiet", "short": "-q", "description": "Print only results and errors." },
		{ "name": "--yes", "short": "-y", "description": "Answer yes to every question." },
		{ "name": "--no-input", "description": "Never prompt. Fail where a question would be asked." }
	]}
/>

Every download is checked against its published SHA-256 and run once before it is put in place.

## surreal upgrade

Upgrade the launcher and every installed component, or only the ones named. Each follows the channel its default is on: a stable release stays on its major line, and a prerelease follows its own channel. Naming a version moves the default to that version, installing it first if needed. `cli` is the launcher itself.

<Synopsis>
surreal upgrade [OPTIONS] [COMPONENT[@VERSION] | cli]...
</Synopsis>

```bash
surreal upgrade
surreal upgrade db@3.3.2
surreal upgrade cli --dry-run
```

<OptionsTable
	title="Options"
	options={[
		{ "name": "--nightly", "description": "Upgrade the database to the latest nightly build. The same as `db@nightly`." },
		{ "name": "--alpha", "description": "Upgrade the database to the latest alpha release. The same as `db@alpha`." },
		{ "name": "--beta", "description": "Upgrade the database to the latest beta release. The same as `db@beta`." },
		{ "name": "--version", "value": "<VERSION>", "description": "Upgrade the database to this version. The same as `db@<VERSION>`." },
		{ "name": "--dry-run", "description": "Say what would change without changing it." },
		{ "name": "--json", "description": "Print one JSON document on stdout." },
		{ "name": "--plain", "description": "Plain text: no tables, no colour, no animation." },
		{ "name": "--color", "value": "<WHEN>", "description": "When to use colour: `auto` (default), `always` or `never`." },
		{ "name": "--quiet", "short": "-q", "description": "Print only results and errors." },
		{ "name": "--yes", "short": "-y", "description": "Answer yes to every question." },
		{ "name": "--no-input", "description": "Never prompt. Fail where a question would be asked." }
	]}
/>

`surreal db upgrade` is not run. It reports that the launcher manages the database's versions and points to `surreal upgrade db`.

## surreal use

Make an installed version of a component the default. It never downloads.

<Synopsis>
surreal use [OPTIONS] <COMPONENT@VERSION>
</Synopsis>

```bash
surreal use db@2.7.0
surreal use db@2
```

A major line or channel selects the newest installed release on it. The output options are the same as for `surreal install`.

## surreal uninstall

Remove installed versions of components.

<Synopsis>
surreal uninstall [OPTIONS] <COMPONENT[@VERSION]>...
</Synopsis>

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

`db@2.7.0` removes that version, and `db` alone removes every version of the component and its default. A channel such as `db@2` is refused, because it does not name a release. The default is removed by name only once nothing else is installed, so choose another with `surreal use` first. The output options are the same as for `surreal install`.

## surreal version

Show each component, the version that runs, and where it runs from.

<Synopsis>
surreal version [OPTIONS]
</Synopsis>

```text title="Sample output"
COMPONENT  VERSION  SOURCE  INSTALLED  PATH
cli        0.1.0    cli                /usr/local/bin/surreal
db         3.3.4    pinned  3.3.4      /home/you/.surrealdb/components/db/3.3.4/surreal-db
mod
cloud      0.1.0    pinned  0.1.0      /home/you/.surrealdb/components/cloud/0.1.0/surreal-cloud
```

The `SOURCE` column is `pinned` for a version in the launcher's store, `path` for an executable found beside `surreal` or on `PATH`, and `missing` or `unpinned` where nothing is selected. With `--json`, the command prints one document with the launcher, the home folder, whether offline mode is on, and each component's `name`, `version`, `source`, `installed` versions and `path`. The output options are the same as for `surreal install`.

`surreal --version` (`-V`) prints the same information on a few lines. To print a database server's version, use [`surreal db version`](/docs/reference/cli/db/commands/version.md).

## +VERSION

Run one version of a component for a single command, without changing the default.

<Synopsis>
surreal +VERSION COMPONENT [ARGS]...
</Synopsis>

```bash
surreal +2.6.5 db start --user root --pass secret
```

If the version is not installed, the launcher offers to install it, under the rules in [Offline and unattended use](/docs/explore/cli/components.md#offline-and-unattended-use).

## surreal help

`surreal help` and `surreal --help` print the launcher's help, with the banner. `--no-banner` or `SURREAL_CLI_NO_BANNER` prints it without. `surreal <COMPONENT> help` prints a component's own help.

## Deprecated forms

The database's commands still run without `db`, and print a deprecation warning that names the replacement: `surreal start` is `surreal db start`. The set is closed: `start`, `sql`, `import`, `export`, `isready`, `is-ready`, `validate`, `fix`, `ml`, `module` and `mcp`, and database options placed before a command. `surreal module` points to `surreal mod`. See [Using the database](/docs/explore/cli/database.md#the-deprecated-top-level-commands).

## Environment variables

| Variable | Effect |
| --- | --- |
| `SURREAL_CLI_HOME` | The SurrealDB home, where components are stored. Defaults to `~/.surrealdb` |
| `SURREAL_CLI_OFFLINE` | `1` forbids every network request. A missing component fails at once with exit code 12 |
| `SURREAL_CLI_DOWNLOAD_ROOT` | Replaces the download host, for a mirror. An `http` or `https` address with no credentials, query or fragment |
| `SURREAL_CLI_NO_BANNER` | Hides the banner above `surreal help` |
| `SURREAL_CLI_JSON` | The same as `--json` |
| `SURREAL_CLI_PLAIN` | The same as `--plain` |
| `SURREAL_CLI_INSTALL_DB` | Read by the install script: `1` installs the database, `0` does not. See [Install the SurrealDB CLI](/docs/explore/cli/install.md) |

The launcher reads only `SURREAL_CLI_*`. Variables that start with `SURREAL_` and not `SURREAL_CLI_` belong to the database, and [`SURREAL_CLOUD_*`](/docs/reference/cli/cloud/global-flags.md) belong to Cloud. Every component the launcher runs receives `SURREAL_INVOKED_AS`, the way it was typed, so its help reads `surreal cloud instance list`, and `SURREAL_CLI_LAUNCHER`, the launcher's absolute path, which a component uses to run another one.

## Exit codes

A component's exit code is the launcher's. The launcher's own commands use the same codes as `surreal cloud`.

| Code | Meaning |
| --- | --- |
| `0` | The command did what was asked |
| `1` | A failure that fits no other code |
| `2` | A bad invocation, such as an unknown component or an invalid version name |
| `12` | A component the command needs is not installed and was not fetched: offline, nobody there to agree, or the offer declined. The message names the command that installs it |

The full list is in [output and exit codes](/docs/reference/cli/cloud/output-and-exit-codes.md).