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.

When starting with the CLI, the most commonly used commands are surreal start to start the server, along with surreal sql to open up an interactive shell to make queries. Other common commands are surreal upgrade to switch between versions of SurrealDB, and surreal import and surreal export to import and export your data.

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

surreal start --user root --pass root

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 root.

In another window, you can then open up an interactive shell to make queries using the surreal sql command.

surreal sql --namespace ns --database db --username root --password root --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. Since you are logged in as the root user inside a namespace called ns and a database called db, with pretty (easily readable) output per query.

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

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

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

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

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

Alternatively, you can start a local database in memory with the command below. The --endpoint memory flag will start a database in memory, while the other arguments will connect to a single namespace called test and a database called test. Please replace the username and password with your own.

surreal sql --endpoint memory --namespace test --database test --username username --password password

Warning

The above command will start a database in memory with a single namespace called test and a database called test and allow root access to the database. Using generic usernames and passwords is not recommended for production use.

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!