---
title: "Via CLI"
description: "Open an interactive SurrealQL shell against an instance with surreal db sql, and where to get the token."
canonical_url: "https://surrealdb.com/docs/operate/instances/connect/via-cli"
section: "Connect"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Via CLI

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

Open an interactive SurrealQL shell against an instance with the [SurrealDB CLI](/docs/reference/cli/db.md).

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](/docs/running/installation.md). It is a single executable and does not need a local server.

## Open a shell

[`surreal db sql`](/docs/reference/cli/db/commands/sql.md) connects to the endpoint and opens a prompt:

```bash title="Connect to an instance"
surreal db sql \
  --endpoint wss://<endpoint> \
  --ns main --db main \
  --token <token>
```

The **Connect** menu of the instance in [SurrealDB Studio](https://studio.surrealdb.com) 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.](~/assets/img/image/cloud/open-in-cli.png)

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 `surreal cloud 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](/docs/reference/query-language/statements/define/user.md).

## Next steps

- **[SurrealDB CLI](/docs/reference/cli/db.md):** every command and flag.
- **[surreal cloud](/docs/reference/cli/guides/cloud/instances.md):** the management-plane CLI. `surreal cloud instance sql` opens the same shell against a named instance without you supplying an endpoint, and runs `surreal db sql` to do it.
