CLI tools | Database

SurrealDB has one command line, surreal. The surreal launcher installs once, then installs, versions and runs components, each with its own commands: the database (surreal db), SurrealDB Cloud (surreal cloud) and Surrealism extensions (surreal ext). This section is the reference for all of them. For how they fit together, start with the SurrealDB CLI guide.

surreal install cloud
surreal db start --user root --pass secret
surreal cloud instance list

Reference	Covers
Launcher commands	Installing, upgrading, pinning and removing components, version names, `+VERSION`, and the launcher's environment variables
`surreal db`	The database: run a server, query it, and move data in and out
`surreal cloud`	SurrealDB Cloud: organisations, instances, backups, members and tokens
`surreal ext`	Surrealism extensions
`surqlfmt`	Formatting `.surql` files, distributed separately as an npm package

Launcher commands

These commands belong to the launcher, and nothing else installs or changes component versions. See Launcher commands for options and examples.

Command	Purpose
`surreal install <COMPONENT[@VERSION]>...`	Install components, or another version of one beside those installed
`surreal upgrade [<COMPONENT[@VERSION]> \| cli]...`	Upgrade the launcher and every installed component, or those named
`surreal use <COMPONENT@VERSION>`	Make an installed version the default
`surreal uninstall <COMPONENT[@VERSION]>...`	Remove a version, or a component entirely
`surreal list`	Show each component, the version that runs, and where it runs from
`surreal --version`	Print the launcher's own version
`surreal +VERSION <COMPONENT> ...`	Run another version for one command
`surreal help`	Print the launcher's help

surreal db

The database component. Everything after db goes to the database, so the same flags and SURREAL_* variables apply. Each command has its own page under database commands.

Command	Purpose
`surreal db start`	Run a SurrealDB server
`surreal db sql`	Open an interactive SurrealQL shell
`surreal db import`	Load a SurrealQL file into a database
`surreal db export`	Dump a database to SurrealQL
`surreal db is-ready`	Check that a server accepts connections
`surreal db validate`	Validate SurrealQL files
`surreal db fix`	Repair storage issues
`surreal db mcp`	Run the Model Context Protocol server over stdio
`surreal ext`	Build, sign, install and run Surrealism extensions
`surreal db version`	Print the database or server version

The old top-level forms, such as surreal start, still run and print a deprecation warning. Upgrading the database is surreal upgrade db, a launcher command.

surreal cloud

The SurrealDB Cloud component. Every command takes --json, and sends its data to stdout and everything else to stderr. See global flags and output and exit codes.

Command	Purpose
`surreal cloud auth`	Sign in, sign out, and inspect credentials
`surreal cloud org`	Manage organisations, usage, spend and plans
`surreal cloud instance`	Create, scale, pause, back up, connect to and delete instances
`surreal cloud team`	Manage organisation members
`surreal cloud invite`	Manage organisation invitations
`surreal cloud token`	Manage personal access tokens
`surreal cloud catalog`	Browse regions, instance types and versions
`surreal cloud config`	Read and write configuration
`surreal cloud context`	Inspect and switch profiles
`surreal cloud whoami`, `api`, `open`, `status`, `version`, `completion`	Identity, raw API calls, dashboard links, diagnostics and shell completions

surreal ext

The Surrealism extension component, which builds, signs and installs extensions. Its first release is not published yet. Before SurrealDB 4.0, the same commands were surreal db module. See surreal ext.

SurrealQL formatter

surqlfmt reformats .surql files to a consistent style. It is distributed as an npm package rather than as a component of surreal, which makes it easy to pin in a project and run in CI.

npm install -g @surrealdb/surql-fmt
surqlfmt --check ./src/**/*.surql

See the SurrealQL formatter reference for its options and usage patterns.