SurrealDB CLI | Database

surreal is the SurrealDB command line. You install it once, and it installs, updates and runs the rest: the database, SurrealDB Cloud management, and module tooling. Each of these is a component with its own commands and its own version, so a new surreal cloud release does not wait for a database release, and the reverse.

This page covers what the command does and gets you through a first session. For the full option lists, see the CLI reference.

Components

A component is a separate program that the surreal launcher finds, fetches when needed, and starts for you. You type surreal <component> <command>, and everything after the component name goes to that component unchanged.

Component	Command	What it does	Guide
Database	`surreal db`	Start a server, open a SurrealQL shell, import and export data, validate query files	Using the database
Cloud	`surreal cloud`	Organisations, instances, backups, members and tokens on SurrealDB Cloud	Managing SurrealDB Cloud
Modules	`surreal mod`	Build and run WebAssembly modules	Working with modules

The launcher itself has five commands of its own, and they are the only commands that install or change versions: surreal install, surreal upgrade, surreal use, surreal uninstall and surreal version. Managing components explains each of them, how to pin a version, and how to run another version once with +VERSION.

Install

The install script installs surreal and, by default, the database as a pinned component.

macOS and Linux

curl -sSf https://install.surrealdb.com | sh

Windows (PowerShell)

irm https://windows.surrealdb.com | iex

Add the Cloud component at the same time with --with cloud (-With cloud on Windows), or install it later with surreal install cloud. Install the SurrealDB CLI covers the options, Homebrew and other package managers, and installing without the database.

First session

Run the database locally, then talk to it.

Run a local database

surreal db start --user root --pass secret

In a second terminal, open a SurrealQL shell against it.

Open a shell

surreal db sql --username root --password secret --pretty

To work with SurrealDB Cloud, install the Cloud component, sign in, and create an instance.

Manage SurrealDB Cloud

surreal install cloud
surreal cloud auth login
surreal cloud org use acme
surreal cloud instance create api --type shared-1 --region aws-euw1
surreal cloud instance sql api -- --ns app --db main

surreal cloud instance sql resolves the instance and credentials, then hands off to surreal db sql through the launcher, so one command covers both planes. If a command needs a component that is not installed, surreal names the download host and asks before it fetches anything.

Control plane and data plane

The components divide along a clear line.

Component	Plane	Answers
`surreal cloud`	Control plane	Which instances exist, what they run, what they cost, who may reach them
`surreal db`	Data plane	Queries, imports, exports, and running a server yourself

A component never installs or upgrades another one. When surreal cloud needs the database, it runs surreal db through the launcher, which offers to install it if it is missing.

Output that scripts can read

Every launcher command and every surreal cloud command takes --json, and sends its data to stdout and everything else, including progress, prompts and warnings, to stderr. A failed command leaves stdout empty.

Machine-readable output

surreal cloud instance list --json | jq -r '.[] | select(.state == "ready") | .name'

Scripting and CI covers exit codes, non-interactive credentials and long-running operations.

Where to go next

Install

The install script, package managers, and installing without the database.

Managing components

Install, upgrade, pin, switch and remove components.

Using the database

Start a server, query it, and move data in and out.

Managing SurrealDB Cloud

CLI reference

Every command and flag of the launcher and each component.