context

surrealctl context inspects and switches profiles. A profile bundles a credential, an API base URL and a set of configuration values, so switching profile changes all three in one move.

surrealctl context <COMMAND> [OPTIONS]surrealctl contexts <COMMAND> [OPTIONS]

context use switches profile. org use remembers an organisation within a profile. Neither is expressible as the other, and you will usually want both: one profile per account or tenant, one remembered organisation inside each.

surrealctl context show

Show the context this invocation resolved.

surrealctl context show [OPTIONS]

This command takes no positional arguments and no options of its own.

surrealctl context show

Profile         work
Organization    acme
Id              67upif0m8sh1cn1p2c8t
Source          persisted context (`org use`)
API             https://api.surrealdb.com
Config          /Users/ana/.config/surrealctl/config.toml
Store           /Users/ana/.config/surrealctl/credentials.json

The command resolves through the same chain every other command uses, including the interactive picker when several organisations are available and nothing has chosen — so what it reports is genuinely what the next command will do, not an approximation of it.

A failure to resolve an organisation is reported as part of the answer rather than as an error: the profile, the API base and both file paths are still printed, followed by a note and the hint surrealctl org use <name>.

surrealctl context show --json | jq -r '.organization.name + " via " + .source'

surrealctl context use

Switch to a different profile.

surrealctl context use [OPTIONS] <PROFILE>

This command has no options of its own.

surrealctl context use staging

surrealctl context use staging
surrealctl auth login

The profile is created if it does not exist. A new profile gets a note that it has no stored credentials, plus the hint naming the login command for it.

Refusals. An empty or whitespace-only name is a usage error, exit 2:

Ensure the profile name is not empty.

Warnings. The command warns when SURREALCTL_PROFILE is set, because the variable outranks the file it just wrote.

For a single command against a different profile, pass --profile rather than switching:

surrealctl --profile staging instance list

surrealctl context list

List the configured profiles.

surrealctl context list [OPTIONS]

This command takes no positional arguments and no options of its own.

Accepts the list presentation flags. Column ids are profile, active, org and api, with source under --wide.

surrealctl context list

PROFILE   ACTIVE  ORGANIZATION  API
default   no      contoso       https://api.surrealdb.com
work      yes     acme          https://api.surrealdb.com

surrealctl context list --wide

The profile in force is always listed, even when the file has no entry for it — so --profile scratch context list shows scratch. The order is stable between runs.

Related pages

• •

  Global flags — the chain context show reports on

• •

  config commands — the values a profile holds

• •

  org use — remembering an organisation within a profile

• •

  auth commands — signing a profile in

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — for working with the data inside an instance