# context

Reference for surrealctl context — showing what an invocation resolved, switching between profiles, and listing the profiles that are configured.

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

<Synopsis>
surrealctl context <COMMAND> [OPTIONS]
surrealctl 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/surrealctl/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.

## surrealctl context show {#context-show}

Show the context this invocation resolved.

<Synopsis>
surrealctl context show [OPTIONS]
</Synopsis>

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

```bash
surrealctl context show
```

```text title="Output"
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>`.

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

## surrealctl context use {#context-use}

Switch to a different profile.

<Synopsis>
surrealctl 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"
surrealctl context use staging
```

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

```text
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:

```bash
surrealctl --profile staging instance list
```

## surrealctl context list {#context-list}

List the configured profiles.

<Synopsis>
surrealctl context list [OPTIONS]
</Synopsis>

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

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

```bash
surrealctl 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"
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](/docs/reference/cli/surrealctl/global-flags.md#the-precedence-chain) — the chain `context show` reports on
- [`config` commands](/docs/reference/cli/surrealctl/commands/config.md) — the values a profile holds
- [`org use`](/docs/reference/cli/surrealctl/commands/org.md#org-use) — remembering an organisation within a profile
- [`auth` commands](/docs/reference/cli/surrealctl/commands/auth.md) — signing a profile in
- [Overview](/docs/reference/cli/surrealctl/overview.md) — the rest of the reference
- [SurrealDB CLI](/docs/reference/cli/surrealdb-cli/overview.md) — for working with the data inside an instance