CLI tool

The SurrealDB command-line tool uses a single command for functionality such as starting a single SurrealDB instance, exporting a dataset as a .surql file, importing SurrealQL into a local or remote database, upgrading to a new version of SurrealDB, or opening a REPL to make queries on a running instance.

Important

Before using the CLI, you will need to install SurrealDB. To experiment with SurrealDB before installing, see the Surrealist sandbox.

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 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
	}
]

We hope that the SurrealDB CLI simplifies your interactions with SurrealDB and empowers you to efficiently manage your databases and clusters. Let’s dive into the CLI section and explore its capabilities!