---
title: "Deploy SurrealDB Earth and run your first query with one command"
description: "Install the surreal CLI, deploy a SurrealDB Earth instance with one command, and run a first query, or use the Deploy page in Studio."
url: https://surrealdb.com/blog/deploy-surrealdb-earth-and-run-your-first-query-with-one-command
date: 2026-11-09
authors: "Tobie Morgan Hitchcock"
---

# Deploy SurrealDB Earth and run your first query with one command

![Deploy SurrealDB Earth and run your first query with one command](https://cdn.surrealdb.com/n8dp88hk6qtj7mcvn5xc9nyk.auto)

You can deploy a SurrealDB Earth instance from the Deploy page in Studio, or from your terminal with one `surreal` command that deploys an instance and runs your first query. Creating an instance takes about 500ms, and a cold start currently takes about 300ms.

Studio is the easiest way for most people to start, and the first section below covers it. If you spend most of your day in a terminal, the `surreal` CLI is the faster way, and the rest of this post shows how to use it.

## What you need

Earth is serverless SurrealDB built on Cloudflare Durable Objects and R2. Each Earth database is its own instance.

You need two things before you start:

- **A SurrealDB Cloud account.** You can sign up with Google, GitHub, or an email address and password. Earth Free needs no payment details, and it includes a monthly allowance. Earth Pro raises the allowance.
- **A browser or a terminal.** Use a browser to deploy from Studio, or a terminal on macOS, Linux or Windows to deploy with the CLI.

## Deploy from Studio

[SurrealDB Studio](https://app.surrealdb.com) offers the deploy flow as a page. Open your organisation, choose Instances, and select Deploy instance.

1. Enter a name. The name cannot change later.
2. Pick the Earth region card, which is the default.
3. Choose where your data lives and, where one is offered, a preferred location. The [section on data residency](#choose-where-your-data-lives) below explains the options.
4. Review the instance details, including cells, network policy and capabilities.
5. Choose a plan at checkout and select Deploy instance.

## How do I install the surreal CLI?

`surreal` is SurrealDB's command-line tool. It is made of components that you install as you need them: `surreal db` runs the database on your own machine, and `surreal cloud` manages your SurrealDB Cloud instances. This post uses `surreal cloud`.

The install script installs `surreal` and the database, and `--with cloud` adds the `cloud` component in the same step:

**macOS and Linux**

```bash
curl -sSf https://install.surrealdb.com | sh -s -- --with cloud
```

**Windows**

```powershell
& ([scriptblock]::Create((irm https://windows.surrealdb.com))) -With cloud
```

To add a component later, install it by name:

```bash
surreal install cloud
```

## Sign in to SurrealDB Cloud

Sign in once. The command opens a browser, or shows a device code or a URL when no browser is available.

```bash
surreal cloud auth login
surreal cloud whoami
```

If your account belongs to several organisations, choose the one to deploy into:

```bash
surreal cloud org list
surreal cloud org use acme
```

## Deploy Earth with no questions asked

`surreal cloud instance deploy` with `--yes` takes every default and asks nothing. It deploys an Earth instance under a generated name such as `brave-falcon`, and waits until the instance is ready.

```bash
surreal cloud instance deploy --yes
```

Run the command without `--yes` and it asks for whatever the flags left out, in the same order as Studio's Deploy page, then confirms before it deploys. The CLI and Studio use the same defaults, so `--yes` and an untouched Deploy page produce the same instance.

## Choose where your data lives

Every Earth instance has a data residency, which decides where its data may be stored and processed. Choose `eu` to keep the data inside the European Union, or `us` to keep it inside the United States. The default, `world`, lets Earth place the instance anywhere on Cloudflare's network.

Within a residency, a location hint says where you would prefer the instance to run, usually near most of your users. Without one, Earth places the instance automatically.

| Residency | Where the data stays | Location hints |
| :-- | :-- | :-- |
| `eu` | The European Union | `weur` (Western Europe), `eeur` (Eastern Europe) |
| `us` | The United States | `wnam` (western North America), `enam` (eastern North America) |
| `world` | Anywhere | Any of the above, and `apac` (Asia-Pacific) or `oc` (Oceania) |

The command below deploys an instance named `my-app` that keeps its data in the EU and prefers to run in Western Europe:

```bash
surreal cloud instance deploy my-app --residency eu --location-hint weur --yes
```

Choose the residency and the location hint with care, because neither can change after the instance is created. `surreal cloud catalog residencies` lists the residencies and the location hints each one accepts.

## Deploy and run a query in one command

`surreal cloud instance sql --deploy` deploys an instance, waits for it, creates a database token and opens a SurrealQL shell on it. Pipe a query into it, and the shell runs the query and exits:

```bash
echo "CREATE person:tobie SET name = 'Tobie'; SELECT * FROM person;" \
  | surreal cloud instance sql --deploy --yes --namespace app --database main
```

The namespace and database are created on first use. The token is passed to the shell in an environment variable, so it never appears on the command line.

## Query an instance you already have

Open a shell on an existing instance by name:

```bash
surreal cloud instance sql my-app --namespace app --database main
```

Then run SurrealQL at the prompt:

```surql
CREATE person:tobie CONTENT { name: 'Tobie', city: 'London' };
SELECT * FROM person;
```

`import` and `export` connect to the database the same way, so `surreal cloud instance export my-app` exports the instance you just queried.

## CLI flags for Earth

These flags apply to `surreal cloud instance deploy` when you deploy Earth:

| Flag | What it sets |
|---|---|
| `--residency` | Where data may live: `world`, `eu` or `us` |
| `--location-hint` | A preferred location inside the residency, such as `weur` for Western Europe |
| `--cells` | How many cells the instance may run across |
| `--allow-ip` and `--deny-ip` | A network policy of IP addresses or CIDR blocks |
| `--no-wait` | Return as soon as the API accepts the request |

A flag that belongs to a dedicated instance, such as `--nodes` or `--type`, is refused for Earth. Pass a cloud region to `--region` to deploy a dedicated instance instead.

## Clean up

List your instances and delete the one you created:

```bash
surreal cloud instance list --earth
surreal cloud instance delete my-app --force
```

Every command accepts `--json`, so `surreal cloud instance list --json | jq -r '.[].name'` prints the instance names for scripts.

## Next steps

An Earth instance takes one step in Studio or one command in a terminal. Sign up with an email address, deploy with `surreal cloud instance deploy --yes` or from the Deploy page, and choose a residency such as `eu` when your data needs to stay in one region. `surreal cloud instance sql --deploy` goes one step further and runs your first query on the new instance in the same command.

The [SurrealDB Earth documentation](https://surrealdb.com/docs/manage/instances/earth) covers cells, residency, network policy and usage in more depth, and the [`surreal cloud` reference](https://surrealdb.com/docs/reference/cli/cloud) lists every command.

[Start free on Earth](https://surrealdb.com/earth)