Via CLI | Connect | SurrealDB

Open an interactive SurrealQL shell against an instance with surreal sql, and where to get the token.

Open an interactive SurrealQL shell against an instance with the SurrealDB CLI.

Use the shell for ad-hoc queries, for checking a schema definition, and for scripting a one-off change.

Prerequisites

Install the CLI. See the installation guide. It is a single executable and does not need a local server.

Open a shell

surreal sql connects to the endpoint and opens a prompt:

Connect to an instance

surreal sql \
  --endpoint wss://<endpoint> \
  --ns main --db main \
  --token <token>

The Connect menu of the instance in SurrealDB Studio generates this command with your endpoint and token filled in.

The Connect menu in SurrealDB Studio showing the ready-made surreal sql command for an instance, with the endpoint, namespace, database, and token already populated.

The --token value is a JSON Web Token that authenticates the session. Treat it as a credential, because it grants whatever the authenticating user or access method grants. Keep it out of shell history and out of committed scripts. Where a script needs a token, mint one at runtime with surrealctl instance token rather than store it.

You can authenticate with --user and --pass instead if the instance has a system user defined. See DEFINE USER.

Next steps

SurrealDB CLI: every command and flag.
surrealctl: the management-plane CLI. surrealctl instance sql opens the same shell against a named instance without you supplying an endpoint, and calls surreal to do it.