> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# SurrealDB CLI

The surreal command installs once, then installs, versions and runs components: the database (surreal db), SurrealDB Cloud (surreal cloud) and WebAssembly modules (surreal mod). A first session, how components work, and where each workflow is documented.

`surreal` is the SurrealDB command line. You install it once, and it installs, updates and runs the rest: the database, SurrealDB Cloud management, and module tooling. Each of these is a **component** with its own commands and its own version, so a new `surreal cloud` release does not wait for a database release, and the reverse.

This page covers what the command does and gets you through a first session. For the full option lists, see the [CLI reference](/docs/reference/cli.md).

## Components

A component is a separate program that the `surreal` launcher finds, fetches when needed, and starts for you. You type `surreal <component> <command>`, and everything after the component name goes to that component unchanged.

| Component | Command | What it does | Guide |
| --- | --- | --- | --- |
| Database | `surreal db` | Start a server, open a SurrealQL shell, import and export data, validate query files | [Using the database](/docs/explore/cli/database.md) |
| Cloud | `surreal cloud` | Organisations, instances, backups, members and tokens on SurrealDB Cloud | [Managing SurrealDB Cloud](/docs/explore/cli/cloud.md) |
| Modules | `surreal mod` | Build and run WebAssembly modules | [Working with modules](/docs/explore/cli/modules.md) |

The launcher itself has five commands of its own, and they are the only commands that install or change versions: `surreal install`, `surreal upgrade`, `surreal use`, `surreal uninstall` and `surreal version`. [Managing components](/docs/explore/cli/components.md) explains each of them, how to pin a version, and how to run another version once with `+VERSION`.

## Install

The install script installs `surreal` and, by default, the database as a pinned component.

```bash title="macOS and Linux"
curl -sSf https://install.surrealdb.com | sh
```

```powershell title="Windows (PowerShell)"
irm https://windows.surrealdb.com | iex
```

Add the Cloud component at the same time with `--with cloud` (`-With cloud` on Windows), or install it later with `surreal install cloud`. [Install the SurrealDB CLI](/docs/explore/cli/install.md) covers the options, Homebrew and other package managers, and installing without the database.

## First session

Run the database locally, then talk to it.

```bash title="Run a local database"
surreal db start --user root --pass secret
```

In a second terminal, open a SurrealQL shell against it.

```bash title="Open a shell"
surreal db sql --username root --password secret --pretty
```

To work with SurrealDB Cloud, install the Cloud component, sign in, and create an instance.

```bash title="Manage SurrealDB Cloud"
surreal install cloud
surreal cloud auth login
surreal cloud org use acme
surreal cloud instance create api --type shared-1 --region aws-euw1
surreal cloud instance sql api -- --ns app --db main
```

`surreal cloud instance sql` resolves the instance and credentials, then hands off to `surreal db sql` through the launcher, so one command covers both planes. If a command needs a component that is not installed, `surreal` names the download host and asks before it fetches anything.

## Control plane and data plane

The components divide along a clear line.

| Component | Plane | Answers |
| --- | --- | --- |
| `surreal cloud` | Control plane | Which instances exist, what they run, what they cost, who may reach them |
| `surreal db` | Data plane | Queries, imports, exports, and running a server yourself |

A component never installs or upgrades another one. When `surreal cloud` needs the database, it runs `surreal db` through the launcher, which offers to install it if it is missing.

## Output that scripts can read

Every launcher command and every `surreal cloud` command takes `--json`, and sends its data to stdout and everything else, including progress, prompts and warnings, to stderr. A failed command leaves stdout empty.

```bash title="Machine-readable output"
surreal cloud instance list --json | jq -r '.[] | select(.state == "ready") | .name'
```

[Scripting and CI](/docs/explore/cli/cloud/scripting.md) covers exit codes, non-interactive credentials and long-running operations.

## Where to go next

- [Install](/docs/explore/cli/install.md) - The install script, package managers, and installing without the database.

- [Managing components](/docs/explore/cli/components.md) - Install, upgrade, pin, switch and remove components.

- [Using the database](/docs/explore/cli/database.md) - Start a server, query it, and move data in and out.

- [Managing SurrealDB Cloud](/docs/explore/cli/cloud.md) - Sign in, create and scale instances, and manage members.

- [CLI reference](/docs/reference/cli.md) - Every command and flag of the launcher and each component.