Terminal
Terminal/Skill
Runs the surreal command-line tool to start a SurrealDB server, open a SQL shell, import or export data, and upgrade.
By SurrealDB
Works with
npx skills add surrealdb/agent-skills --skill surrealdb-cliA 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.
Reference these guidelines when:
surreal start)surreal sql)surreal import / surreal export)surreal is-ready)surreal upgrade / surreal fix)surreal ml)| Method | Command |
|---|---|
| curl (macOS / Linux) | curl -sSf https://install.surrealdb.com | sh |
| Windows (PowerShell) | iwr https://windows.surrealdb.com -useb | iex |
| Homebrew | brew install surrealdb/tap/surreal |
| Docker | docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start |
Verify with surreal version. Pin a specific image tag (not latest) for production. See the install docs for the current set of methods.
| Command | Purpose | Reference |
|---|---|---|
surreal start [PATH] | Run the database server with a chosen storage backend | start.md |
surreal sql | Interactive REPL or piped, non-interactive querying | sql.md |
surreal import <FILE> | Load a SurrealQL script into a database | import-export.md |
surreal export [FILE] | Dump a database to SurrealQL (file or stdout) | import-export.md |
surreal is-ready | Exit 0 when the server is accepting connections (alias isready) | maintenance.md |
surreal version | Print local tool and remote server versions | maintenance.md |
surreal upgrade | Replace the binary with a newer release | maintenance.md |
surreal fix [PATH] | Migrate on-disk storage to the current format | maintenance.md |
surreal ml <sub> | Import / export SurrealML models | maintenance.md |
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.
sql, import, export, and ml share the same connection flags. Each flag has a SURREAL_* environment variable fallback; an explicit flag wins.
| Flag (aliases) | Env var | Notes |
|---|---|---|
-e, --endpoint | — | ws://localhost:8000 for sql; http://localhost:8000 for import/export |
--namespace (--ns) | SURREAL_NAMESPACE | Required for import/export/ml |
--database (--db) | SURREAL_DATABASE | Required for import/export/ml |
-u, --username (--user) | SURREAL_USER | |
-p, --password (--pass) | SURREAL_PASS | |
-t, --token | SURREAL_TOKEN | JWT; use instead of username/password |
--auth-level | SURREAL_AUTH_LEVEL | root (default), namespace/ns, or database/db |
Pass secrets via env vars rather than flags so they do not leak into shell history or process listings.
# 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
surreal start needs --user/--pass; only use --unauthenticated for throwaway local instances.memory (the default) is ephemeral — data vanishes on exit. Use rocksdb:/surrealkv:// for persistence and tikv:// for distributed clusters. See start.md.surreal export writes to - (stdout) unless you give a file path; redirect or pipe accordingly.is-ready. It returns a non-zero exit code until the server accepts connections — ideal in healthchecks and scripts.fix after a major upgrade if the server reports an incompatible storage version, pointing it at the same PATH used by start.surreal <command> --help for the installed version; this skill reflects v3.x.