CLI tool

The SurrealDB command-line tool can be used to start a single SurrealDB instance, export a dataset as a .surql file, import SurrealQL into a local or remote database, or upgrade to a new version of SurrealDB.

Important

Before using the CLI, you will need to install SurrealDB.

Getting Started

The CLI, allowing 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 --endpoint http://localhost:8000 --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. This will start a database in memory with 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 --auth-level root --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!