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

# surreal cloud other commands

Reference for the surreal cloud leaf commands - whoami, api, open, status, version and completion.

Six commands sit at the top level rather than inside a noun group. They cover identity, the raw API escape hatch, opening the dashboard, diagnostics, version information and shell completion.

| Command | Purpose | Alias |
| --- | --- | --- |
| [`whoami`](#whoami) | Show who the API thinks you are | |
| [`api`](#api) | Call the API directly | |
| [`open`](#open) | Open a dashboard page in a browser | |
| [`status`](#status) | Check that everything is configured and reachable | `doctor` |
| [`version`](#version) | Output version information | |
| [`completion`](#completion) | Generate shell completions | |

## surreal cloud whoami {#whoami}

Show who the API thinks you are.

<Synopsis>
surreal cloud whoami [OPTIONS]
</Synopsis>

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

```bash
surreal cloud whoami
```

```text title="Output"
Email           ana@acme.example
User Id         67upif0m8sh1cn1p2c8t
Name            Ana Silva
Default Org     acme
```

`whoami` spends a request on the API's own profile route, which makes it the counterpart to [`auth status`](/docs/reference/cli/cloud/commands/auth.md#auth-status): that one reports what is on this machine, without touching the network; this one reports what the API believes. When they disagree, the API is right.

In text modes the default organisation is shown by name, which costs a second request. That lookup is skipped under `--json`, where the payload is the profile exactly as the API sent it.

## surreal cloud api {#api}

Call the API directly.

<Synopsis>
surreal cloud api [OPTIONS] <METHOD> <PATH>
</Synopsis>

This is the escape hatch. It signs a request with whatever credential the profile holds, applies the same retries and the same error classification as every other command, and prints the body - so a route that has no dedicated command is still reachable without rebuilding authentication by hand.

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<METHOD>",
            "required": true,
            "description": "The HTTP method: `get`, `post`, `put`, `patch` or `delete`. Case-insensitive."
        },
        {
            "name": "<PATH>",
            "required": true,
            "description": "The path, such as `/api/cloud/v0/organizations`. A leading `/` is added when absent."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--data",
            "short": "-d",
            "value": "<BODY>",
            "description": "A JSON body, `@FILE` to read a file, or `-` to read standard input."
        },
        {
            "name": "--query",
            "value": "<KEY=VALUE>",
            "description": "A query parameter, as `key=value`. Repeatable."
        },
        {
            "name": "--header",
            "value": "<NAME:VALUE>",
            "description": "An extra request header, as `name:value`. Repeatable."
        },
        {
            "name": "--include",
            "description": "Print the response status and headers to stderr."
        },
        {
            "name": "--raw",
            "description": "Print the body exactly as it arrived, without pretty-printing."
        },
        {
            "name": "--force",
            "description": "Send a write without confirming."
        }
    ]}
/>

```bash title="A GET, pretty-printed"
surreal cloud api get /api/cloud/v0/organizations
```

```bash title="Query parameters and response headers"
surreal cloud api get /api/cloud/v0/organizations --query limit=5 --include
```

```bash title="A write, from a file"
surreal cloud api post /api/cloud/v0/organizations --data @org.json --force
```

```bash title="A write, from stdin"
echo '{"name":"acme"}' | surreal cloud api post /api/cloud/v0/organizations -d - --force
```

`-d` follows curl's spellings: `-` and `@-` mean standard input, `@path` means a file, and anything else is treated as an inline body.

**Confirmation.** Any write method - `POST`, `PUT`, `PATCH` or `DELETE` - confirms first unless `--force` or the global `--yes` is given. Declining prints `Nothing was sent.` and exits `0`. In a non-interactive session with neither, it exits `2` having sent nothing.

**Refusals**, all exit `2`:

- An unknown method:

```text
Ensure the method is one of get, post, put, patch or delete (got `HEAD`)
```

- A URL where a path was expected:

```text
Ensure the path is a path and not a URL; the host comes from --api
```

- A malformed `--query` or `--header`. Both split on their first separator only, so a value containing `=` or `:` survives intact.
- A reserved header. `Authorization`, `X-Cloud-Token` and `X-Request-Id` come from the credential in use:

```text
`authorization` is set from the credential in use and cannot be overridden here. Pass --token or --token-file to change what is sent.
```

- A body on a `GET`: `A GET takes no body. Use --query for parameters, or pick another method.`
- A body that is not valid JSON, naming where it came from.

**Notes.** A path on neither the Cloud nor the accounts surface is sent **without credentials**, and says so first. Retries follow the method: a `GET` is retried freely, a `POST` never, and `PUT`, `PATCH` and `DELETE` only when the connection failed before anything was sent.

`--raw` writes the bytes verbatim, control characters included, which is safe only because it is opt-in. `--json` is unaffected by `--raw`: it always emits one parseable document, turning a non-JSON body into a JSON string and an empty body into `null`. In text mode an empty body prints nothing, and a note on stderr reports the status that answered with none.

## surreal cloud open {#open}

Open a dashboard page in a browser.

<Synopsis>
surreal cloud open [OPTIONS] [SUBJECT] [REF]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[SUBJECT]",
            "default": "dashboard",
            "description": "What to open: `dashboard`, `org`, `instance`, `billing` or `terms`."
        },
        {
            "name": "[REF]",
            "description": "The organisation or instance, by id, slug or name."
        }
    ]}
/>

This command has no options of its own - only the [global flags](/docs/reference/cli/cloud/global-flags.md).

| `[SUBJECT]` | Opens |
| --- | --- |
| `dashboard` | The account's overview page |
| `org` | An organisation's overview |
| `instance` | One instance, by id, slug or name |
| `billing` | An organisation's billing and invoices |
| `terms` | The terms and privacy policy, which this CLI links to and never accepts |

```bash title="The account overview"
surreal cloud open
```

```bash title="One instance"
surreal cloud open instance production
```

```bash title="Billing for the resolved organisation"
surreal cloud open billing
```

**The URL is always printed; it is only sometimes opened.** A browser is attempted when a person is present - which includes a `--json` invocation, since a human may well want machine output and a browser window at the same time - and a failure to open is a warning rather than an error. So the command is still useful over SSH: you get the link, and you paste it yourself.

**Refusals**, exit `2`:

- A `[REF]` alongside `dashboard` or `terms`, which take none:

```text
That subject takes no reference. Try `surreal cloud open org <name>` or `surreal cloud open instance <name>`.
```

- `instance` with no reference:

```text
`open instance` needs to know which one.

Try:  surreal cloud open instance <name>
```

`open terms` links to the legal documents and lists the others as notes. This CLI never accepts terms on your behalf.

## surreal cloud status {#status}

Check that everything is configured and reachable. Also spelled `surreal cloud doctor`.

<Synopsis>
surreal cloud status [OPTIONS]
surreal cloud doctor [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 `check`, `ok` and `detail`.

Six checks run in dependency order, one row each. No check can abort the command, so you always get the whole picture:

| Check | What it covers |
| --- | --- |
| `credential` | Which credential this profile holds, and when it expires. Local only. A failure here is fatal |
| `api` | A version request against the API. An authentication error skips this rather than failing it |
| `version` | The client version the API expects. Reported, never enforced |
| `cloud session` | The Cloud session token. A personal access token is reported as skipped, not passed or failed |
| `organization` | The full precedence chain, picker included. Never fatal |
| `system message` | A platform banner, when a session is available and the API has one. No verdict |

```bash
surreal cloud status
```

```bash title="Just the failures"
surreal cloud status --json | jq -r '.[] | select(.ok == false) | .check + ": " + .detail'
```

The `ok` column is a tri-state. A check either passed, failed, or never ran because something it depended on had already failed - the third case renders as a dash, and under `--json` the `ok` field is `null` rather than `false`.

> [!IMPORTANT]
> This is the one command that prints its table even when it exits non-zero, because the table *is* the diagnosis and a doctor command that goes silent when things break is useless in the one situation it exists for. The exit code comes from the first fatal check - `3` for a credential problem, `9` for an unreachable API - rather than a flat `1`.

`status` checks the control plane only. It does not look for the database, because that is the launcher's concern: `surreal version` lists every installed component. A `version` check that fails names `surreal upgrade cloud` as the remedy.

## surreal cloud version {#version}

Output version information.

<Synopsis>
surreal cloud version [OPTIONS]
</Synopsis>

This command takes no positional arguments.

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--local",
            "description": "Report this build without asking the API for its version."
        }
    ]}
/>

```bash
surreal cloud version
```

```text title="Output"
surreal cloud  0.1.0
Commit         9f3c1ab
Built          2026-08-11
Target         aarch64-apple-darwin
```

```json title="Under --json"
{
  "version": "0.1.0",
  "commit": "9f3c1ab",
  "build_date": "2026-08-11",
  "target": "aarch64-apple-darwin"
}
```

`version` reports the build in front of you. It needs no credential and no organisation, so it works before you have signed in and inside a container with no egress. The flag forms `surreal cloud -V` and `surreal cloud --version` print the version string alone, with the commit, build date and target in parentheses.

To see every component the launcher manages, with the version of each, use `surreal version`. For the API's own version and the client version floor it expects, use [`status`](#status).

## surreal cloud completion {#completion}

Generate shell completions.

<Synopsis>
surreal cloud completion [OPTIONS] <SHELL>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<SHELL>",
            "required": true,
            "description": "The shell to generate completions for: `bash`, `elvish`, `fish`, `powershell` or `zsh`."
        }
    ]}
/>

This command has no options of its own.

```bash title="zsh"
surreal cloud completion zsh > "${fpath[1]}/_surreal-cloud"
```

```bash title="bash"
surreal cloud completion bash > /etc/bash_completion.d/surreal-cloud
```

```bash title="fish"
surreal cloud completion fish > ~/.config/fish/completions/surreal-cloud.fish
```

```powershell title="PowerShell"
surreal cloud completion powershell | Out-String | Invoke-Expression
```

This is the one command whose payload is not a view: it emits a shell script, so `--json` does not wrap it. The script is buffered before it is written, so `surreal cloud completion bash | head -1` exits `0` rather than failing on the closed pipe.

The generated script registers completions for the component's own command name, `surreal-cloud`, which is why the file names above use it.

## Related pages

- [Output and exit codes](/docs/reference/cli/cloud/output-and-exit-codes.md) - the `--json` contract and the full exit-code table
- [Authentication](/docs/reference/cli/cloud/authentication.md) - what `whoami` and `status` are reporting on
- [Install](/docs/explore/cli/install.md) - installing the launcher and its components
- [surreal cloud reference](/docs/reference/cli/cloud.md) - the rest of the reference
- [Database commands](/docs/reference/cli/db.md) - for queries, imports, exports and running a server