# SurrealDB CLI

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.

<Synopsis>
surreal [OPTIONS] <COMMAND>
</Synopsis>

> [!IMPORTANT]
> Before using the CLI, you will need to [install SurrealDB](/docs/running/installation.md). To experiment with SurrealDB before installing, see the [SurrealDB Studio sandbox](https://app.surrealdb.com/) 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`](/docs/reference/cli/surrealctl/overview.md) 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](/docs/reference/cli/surrealdb-cli/commands.md).

For a quickstart, [`surreal start`](/docs/reference/cli/surrealdb-cli/commands/start.md) and [`surreal sql`](/docs/reference/cli/surrealdb-cli/commands/sql.md) will be enough to get you started.

```bash
surreal start --user root --pass secret
```

Unless you specify otherwise, the CLI will start a database [in memory](/docs/running/in-memory.md) 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.

```bash
# 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.

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

```surql title="Output"
[
	{
		age: 20,
		id: person:6jodx8xv39jsxdgykt0t
	}
]

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

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

## Next steps

- [CLI commands](/docs/reference/cli/surrealdb-cli/commands.md) - every subcommand, with its arguments and options.
- [Environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md) - the `SURREAL_*` variables that mirror the flags on this page.
- [surrealctl](/docs/reference/cli/surrealctl/overview.md) - managing organisations and Cloud instances from the command line.