SurrealDB CLI | Database

The SurrealDB command-line tool can be used to export a dataset as SurrealQL from a local or remote SurrealDB database, import SurrealQL data into a local or remote database, and start a single SurrealDB instance or distributed cluster.

The surreal binary is the data-plane command-line tool for SurrealDB. It starts a server, opens an interactive SurrealQL shell, moves data in and out of a database, and reports on the version and readiness of an instance.

Usage

surreal [OPTIONS] <COMMAND>

Important

Before using the CLI, you will need to install SurrealDB. To experiment with SurrealDB before installing, see the SurrealDB Studio sandbox online. To persist your Sandbox data while still experimenting, click on Deploy to Cloud in SurrealDB Studio to create a free SurrealDB Cloud instance.

surreal and surrealctl

surreal and surrealctl are separate binaries that co-exist, and they serve different purposes.

surreal owns the data plane: running a server, querying it, and importing or exporting data.
surrealctl owns the control plane: organisations, instances, members, tokens, and billing on SurrealDB Cloud.

Neither replaces the other. surrealctl instance sql, surrealctl instance import, and surrealctl instance export resolve the endpoint and credentials of a Cloud instance and then hand off to the surreal binary, so the flags documented here still apply once the handoff happens. Environment variables are kept apart as well: surreal reads SURREAL_*, and surrealctl reads SURREALCTL_* only.

Getting started

The CLI allows you to use the surreal command from your terminal or command prompt. This documentation provides detailed information on each command, including usage examples and options. For a concise map of every subcommand, see CLI commands.

For a quickstart, surreal start and surreal sql will be enough to get you started.

surreal start --user root --pass secret

Unless you specify otherwise, the CLI will start a database in memory that serves at 127.0.0.1:8000 (or http://localhost:8000). This database has a single root user named root and a password secret.

In another window, you can then open up an interactive shell to make queries using the surreal sql command. As of SurrealDB 3.0, the sql command will connect to the default 'main' name for both namespace and database.

# Connect to namespace 'main' and database 'main'
surreal sql --username root --password secret --pretty

# Connect to a different namespace and database
surreal sql --namespace ns --database db --username root --password secret --pretty

Warning

Using generic usernames and passwords is not recommended for production use. Please replace the authentication credentials with your own.

This will start an interactive shell to make queries. The output below shows what you will see when logged in as the root user inside a namespace called main and a database called main, with pretty (easily readable) output per query.

You can then try out a few queries and see the output.

main/main> CREATE person SET age = 20;
main/main> CREATE person SET age = 30;
main/main> SELECT * FROM person WHERE age > 25;

Output

[
	{
		age: 20,
		id: person:6jodx8xv39jsxdgykt0t
	}
]

[
	{
		age: 30,
		id: person:10bcq2owseyqqoinjgxl
	}
]

[
	{
		age: 30,
		id: person:10bcq2owseyqqoinjgxl
	}
]

Next steps

CLI commands - every subcommand, with its arguments and options.
Environment variables - the SURREAL_* variables that mirror the flags on this page.
surrealctl - managing organisations and Cloud instances from the command line.