surreal cloud other commands

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.

surreal cloud whoami

Show who the API thinks you are.

surreal cloud whoami [OPTIONS]

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

surreal cloud whoami

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

Call the API directly.

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

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.

surreal cloud api get /api/cloud/v0/organizations

surreal cloud api get /api/cloud/v0/organizations --query limit=5 --include

surreal cloud api post /api/cloud/v0/organizations --data @org.json --force

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:

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

• •

  A URL where a path was expected:

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:

`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 a dashboard page in a browser.

surreal cloud open [OPTIONS] [SUBJECT] [REF]

This command has no options of its own - only the global flags.

surreal cloud open

surreal cloud open instance production

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:

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

• •

  instance with no reference:

`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

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

surreal cloud status [OPTIONS]surreal cloud doctor [OPTIONS]

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

Accepts the 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:

surreal cloud status

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.

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

Output version information.

surreal cloud version [OPTIONS]

This command takes no positional arguments.

surreal cloud version

surreal cloud  0.1.0
Commit         9f3c1ab
Built          2026-08-11
Target         aarch64-apple-darwin

{
  "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.

surreal cloud completion

Generate shell completions.

surreal cloud completion [OPTIONS] <SHELL>

This command has no options of its own.

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

surreal cloud completion bash > /etc/bash_completion.d/surreal-cloud

surreal cloud completion fish > ~/.config/fish/completions/surreal-cloud.fish

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 - the --json contract and the full exit-code table

• •

  Authentication - what whoami and status are reporting on

• •

  Install - installing the launcher and its components

• •

  surreal cloud reference - the rest of the reference

• •

  Database commands - for queries, imports, exports and running a server