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

# surreal cloud context

Reference for surreal cloud context - showing what an invocation resolved, switching between profiles, and listing the profiles that are configured.

`surreal cloud 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.

<Synopsis>
surreal cloud context <COMMAND> [OPTIONS]
surreal cloud contexts <COMMAND> [OPTIONS]
</Synopsis>

| Verb | Purpose | Alias |
| --- | --- | --- |
| [`show`](#context-show) | Show the context this invocation resolved | |
| [`use`](#context-use) | Switch to a different profile | |
| [`list`](#context-list) | List the configured profiles | `ls` |

`context use` switches *profile*. [`org use`](/docs/reference/cli/cloud/commands/org.md#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.

## surreal cloud context show {#context-show}

Show the context this invocation resolved.

<Synopsis>
surreal cloud context show [OPTIONS]
</Synopsis>

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

```bash
surreal cloud context show
```

```text title="Output"
Profile         work
Organization    acme
Id              67upif0m8sh1cn1p2c8t
Source          persisted context (`org use`)
API             https://api.surrealdb.com
Config          /Users/ana/.surrealdb/cloud/config.toml
Store           /Users/ana/.surrealdb/cloud/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 exactly what the next command will do.

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 `surreal cloud org use <name>`.

```bash title="Which organisation would this command hit?"
surreal cloud context show --json | jq -r '.organization.name + " via " + .source'
```

## surreal cloud context use {#context-use}

Switch to a different profile.

<Synopsis>
surreal cloud context use [OPTIONS] <PROFILE>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<PROFILE>",
            "required": true,
            "description": "The profile to make active."
        }
    ]}
/>

This command has no options of its own.

```bash title="Switch"
surreal cloud context use staging
```

```bash title="Create a profile and sign into it"
surreal cloud context use staging
surreal cloud 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`:

```text
Ensure the profile name is not empty.
```

**Warnings.** The command warns when `SURREAL_CLOUD_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:

```bash
surreal cloud --profile staging instance list
```

## surreal cloud context list {#context-list}

List the configured profiles.

<Synopsis>
surreal cloud context list [OPTIONS]
</Synopsis>

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

Accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `profile`, `active`, `org` and `api`, with `source` under `--wide`.

```bash
surreal cloud context list
```

```text title="Output"
PROFILE   ACTIVE  ORGANIZATION  API
default   no      contoso       https://api.surrealdb.com
work      yes     acme          https://api.surrealdb.com
```

```bash title="See where each organisation came from"
surreal cloud 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](/docs/reference/cli/cloud/global-flags.md#the-precedence-chain) - the chain `context show` reports on
- [`config` commands](/docs/reference/cli/cloud/commands/config.md) - the values a profile holds
- [`org use`](/docs/reference/cli/cloud/commands/org.md#org-use) - remembering an organisation within a profile
- [`auth` commands](/docs/reference/cli/cloud/commands/auth.md) - signing a profile in
- [surreal cloud reference](/docs/reference/cli/cloud.md) - the rest of the reference