surreal launcher commands | CLI tools

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. Its own commands are install, upgrade, use, uninstall and version.

Usage

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]

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 explains how components are stored and chosen.

Components

Component	Runs as	Reference
`db`	`surreal db <command>`	Database commands
`cloud`	`surreal cloud <command>`	Cloud commands
`mod`	`surreal mod <command>`	Modules

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.

Usage

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

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

Options

Name	Description
`--pin`	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.
`--json`	Print one JSON document on stdout.
`--plain`	Plain text: no tables, no colour, no animation.
`--color<WHEN>`	When to use colour: `auto` (default), `always` or `never`.
`--quiet, -q`	Print only results and errors.
`--yes, -y`	Answer yes to every question.
`--no-input`	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.

Usage

surreal upgrade [OPTIONS] [COMPONENT[@VERSION] | cli]...

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

Options

Name	Description
`--nightly`	Upgrade the database to the latest nightly build. The same as `db@nightly`.
`--alpha`	Upgrade the database to the latest alpha release. The same as `db@alpha`.
`--beta`	Upgrade the database to the latest beta release. The same as `db@beta`.
`--version<VERSION>`	Upgrade the database to this version. The same as `db@<VERSION>`.
`--dry-run`	Say what would change without changing it.
`--json`	Print one JSON document on stdout.
`--plain`	Plain text: no tables, no colour, no animation.
`--color<WHEN>`	When to use colour: `auto` (default), `always` or `never`.
`--quiet, -q`	Print only results and errors.
`--yes, -y`	Answer yes to every question.
`--no-input`	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.

Usage

surreal use [OPTIONS] <COMPONENT@VERSION>

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.

Usage

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

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.

Usage

surreal version [OPTIONS]

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.

+VERSION

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

Usage

surreal +VERSION COMPONENT [ARGS]...

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.

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.

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

The launcher reads only SURREAL_CLI_*. Variables that start with SURREAL_ and not SURREAL_CLI_ belong to the database, and SURREAL_CLOUD_* 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.