Surrealdb Cli

SurrealDB CLI

A skill for driving the `surreal` command-line binary — SurrealDB's all-in-one tool for running a server, querying it, and moving data in and out.

This skill covers operating the surreal binary itself. To write the SurrealQL that you run with it, use the surrealql skill; for declarative schema migrations and type generation, use the surrealkit skill.

When to use this skill

Reference these guidelines when:

• Starting a SurrealDB server, locally or in a container (surreal start)
• Opening the SQL shell or piping queries from a file (surreal sql)
• Importing or exporting a database for backups, seeding, or migration (surreal import / surreal export)
• Gating scripts or CI on server availability (surreal is-ready)
• Upgrading the binary or repairing on-disk storage after an upgrade (surreal upgrade / surreal fix)
• Importing or exporting SurrealML models (surreal ml)

Installation

Verify with surreal version. Pin a specific image tag (not latest) for production. See the install docs for the current set of methods.

Command map

surreal validate (SurrealQL file checking) and formatting are covered by the surrealql skill. Newer subcommands (mcp, module) also exist — run surreal help and surreal <command> --help to confirm the surface of an installed version.

Connection flags & env vars

sql, import, export, and ml share the same connection flags. Each flag has a SURREAL_* environment variable fallback; an explicit flag wins.

Pass secrets via env vars rather than flags so they do not leak into shell history or process listings.

Quick start

# 1. Start an authenticated in-memory server (foreground)
surreal start --user root --pass root memory

# 2. In another shell, open the SQL REPL on namespace/database "main"
surreal sql --endpoint ws://localhost:8000 \
  --user root --pass root --ns main --db main --pretty

# 3. Load a dump into that database
surreal import --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main backup.surql

Rules & conventions

• Authentication is on by default. surreal start needs --user/--pass; only use --unauthenticated for throwaway local instances.
• Choose a storage backend deliberately. memory (the default) is ephemeral — data vanishes on exit. Use rocksdb:/surrealkv:// for persistence and tikv:// for distributed clusters. See start.md.
• Export defaults to stdout. surreal export writes to - (stdout) unless you give a file path; redirect or pipe accordingly.
• Gate CI with `is-ready`. It returns a non-zero exit code until the server accepts connections — ideal in healthchecks and scripts.
• Run `fix` after a major upgrade if the server reports an incompatible storage version, pointing it at the same PATH used by start.
• The CLI evolves. Confirm flags and subcommands against surreal <command> --help for the installed version; this skill reflects v3.x.

References

• Running a server and storage backends — references/start.md
• Interactive and piped querying — references/sql.md
• Importing and exporting data — references/import-export.md
• Versioning, upgrades, readiness, repair, and ML models — references/maintenance.md

Import & Export

surreal import loads a SurrealQL script into a database; surreal export dumps a database back out as SurrealQL. Together they cover backups, restores, seeding, and moving data between instances.

Both share the standard connection flags (-e/--endpoint, --ns, --db, -u/--user, -p/--pass, -t/--token, --auth-level) with SURREAL_* env fallbacks. The endpoint defaults to http://localhost:8000, and --namespace and --database are required.

Import

surreal import [OPTIONS] --namespace <NS> --database <DB> <FILE>

<FILE> is a path to a .surql script and is required.

# Restore a dump with root credentials
surreal import --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main backup.surql

# With token auth
surreal import --token "$SURREAL_JWT" --ns main --db main seed.surql

Export

surreal export [OPTIONS] --namespace <NS> --database <DB> [FILE]

[FILE] is optional and defaults to - (stdout), so the export can be redirected or piped.

# Full database dump to a file
surreal export --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main backup.surql

# Stream to stdout (e.g. pipe straight into another instance)
surreal export --user root --pass root --ns main --db main | \
  surreal import --endpoint http://other:8000 \
    --user root --pass root --ns main --db main /dev/stdin

Filtering what gets exported

By default everything is exported. Use these flags to scope the dump (most take an optional true/false, e.g. --records false):

(--apis, --buckets, --modules, and --configs are also available on recent versions.)

# Schema-only backup: definitions but no row data
surreal export --user root --pass root --ns main --db main \
  --records false schema.surql

# Export just two tables
surreal export --user root --pass root --ns main --db main \
  --only --tables user,order subset.surql

Backup / restore pattern

# Back up nightly
surreal export --user root --pass root --ns main --db main \
  "backup-$(date +%F).surql"

# Restore into a fresh database
surreal import --user root --pass root --ns main --db restored \
  backup-2026-06-15.surql

Keep credentials in SURREAL_USER/SURREAL_PASS/SURREAL_TOKEN for unattended/cron use rather than passing them as flags.

Maintenance & Operations

Operational commands for versioning, upgrades, readiness checks, storage repair, and SurrealML models. These commands are version-sensitive — confirm flags with surreal <command> --help for your installed binary.

version

surreal version

Prints the local CLI version. Combined with an endpoint it also reports the remote server version:

surreal version --endpoint http://localhost:8000

is-ready

Returns exit code 0 once the server accepts connections and non-zero otherwise — ideal for CI gates, container healthchecks, and startup scripts. The alias surreal isready also works.

surreal is-ready --endpoint http://localhost:8000

# Wait for the server in a script
until surreal is-ready -e http://localhost:8000 2>/dev/null; do
  sleep 1
done
echo "SurrealDB is up"

upgrade

Replaces the running binary with another release.

surreal upgrade                      # latest stable
surreal upgrade --version 3.1.3      # pin a version
surreal upgrade --dry-run            # preview only

If SurrealDB was installed via a package manager (Homebrew) or runs in Docker, upgrade through that tool instead of surreal upgrade.

fix

After a major upgrade, an on-disk store may use an older storage format. fix migrates it in place. Point it at the same PATH used by surreal start, and run it while the server is stopped.

surreal fix rocksdb:mydata.db

ml — SurrealML models

surreal ml imports and exports SurrealML models. Both subcommands take the standard connection flags plus --namespace and --database; export also requires --name and --version.

# Import a model file
surreal ml import --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main model.surml

# Export a specific model + version
surreal ml export --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main \
  --name my_model --version 0.1.0 model.surml

Models are scoped to a namespace and database, so target the same --ns/--db on import and export.

Querying with surreal sql

surreal sql opens a SurrealQL REPL against a running server, and also accepts piped input for non-interactive use in scripts and CI.

For the SurrealQL statements themselves (SELECT, CREATE, RELATE, DEFINE, …) use the surrealql skill — this page covers driving the shell.

Connection flags

Output & input flags

Interactive REPL

surreal sql --endpoint ws://localhost:8000 \
  --username root --password root \
  --namespace main --database main --pretty

Inside the REPL you can switch context without reconnecting:

USE NS app DB production;
SELECT * FROM user LIMIT 5;

Token authentication

--token replaces --username/--password:

surreal sql --endpoint http://localhost:8000 \
  --namespace main --database main --token "$SURREAL_JWT"

Non-interactive (piped) use

Pipe a .surql file or a here-string in for scripting. The REPL reads from stdin and exits when input ends:

# Run a file of statements
cat queries.surql | surreal sql \
  --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main

# One-off query, JSON output for downstream tooling
echo 'SELECT count() FROM user GROUP ALL;' | surreal sql \
  --user root --pass root --ns main --db main --json --hide-welcome

For bulk data loads prefer surreal import over piping into sql; see import-export.md.

Tips

• Put credentials in SURREAL_USER / SURREAL_PASS (or SURREAL_TOKEN) so

they stay out of shell history and ps output.

• --endpoint accepts ws:///wss:// and http:///https://. Use the wss/

https variants for TLS-terminated remote servers.

Running a Server

surreal start [OPTIONS] [PATH] launches a SurrealDB server. The optional PATH selects the storage backend; when omitted it defaults to memory.

surreal start [OPTIONS] [PATH]

Storage backends

memory is ideal for tests and demos; rocksdb/surrealkv for local persistence; tikv for horizontally scaled deployments.

Key flags

PATH also reads from the SURREAL_PATH environment variable.

Examples

# In-memory dev server with root credentials
surreal start --user root --pass root memory

# Persistent RocksDB store with debug logging
surreal start --log debug --user root --pass root rocksdb:mydata.db

# Persistent SurrealKV store
surreal start --user root --pass root surrealkv://mydata

# Expose on all interfaces, custom port (see caveat below)
surreal start --bind 0.0.0.0:8000 --user root --pass root rocksdb:mydata.db

# Unauthenticated throwaway instance — never expose this
surreal start --unauthenticated memory

Docker

# In-memory
docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest \
  start --user root --pass root memory

# Persistent: mount a volume and store under /data
docker run --rm --pull always -p 8000:8000 -v surreal-data:/data \
  surrealdb/surrealdb:latest start --user root --pass root rocksdb:/data/mydata.db

Pin an explicit image tag (e.g. surrealdb/surrealdb:v3.1.3) in production rather than latest.

Caveats

• --bind 0.0.0.0:... exposes the server on every network interface. Only do

this behind a firewall or trusted network, and never together with --unauthenticated.

• A memory server loses all data when the process stops — do not use it for

anything you need to keep.

• After a major version upgrade, an on-disk store may need

surreal fix <PATH> before it will start. See maintenance.md.