auth

surrealctl auth signs in, signs out, and inspects credentials. Four of its five verbs work entirely from the local credential store; only login, refresh and auth status --verify touch the network.

surrealctl auth <COMMAND> [OPTIONS]

Behaviour when nothing is signed in is deliberate and differs by verb: status and logout succeed with exit 0, while scopes and refresh exit 3. See Authentication for why.

surrealctl auth login

Sign in to SurrealDB Cloud, storing a credential for the active profile.

surrealctl auth login [OPTIONS]

This command takes no positional arguments.

Left to itself the command tries browser, then device, then paste, and stops at the first one that can run. A flow named explicitly is used or it fails; there is no silent substitution.

surrealctl auth login

surrealctl auth login --flow device

echo "$CI_TOKEN" | surrealctl --profile ci auth login --with-token --label "build runner"

Refusals and short-circuits. A profile that already holds a credential is a no-op that exits 0 and names the remedy:

Profile `default` is already signed in as ana@acme.example.
Replace it with:
  surrealctl auth login --force

An interactive flow that does not complete exits 30. A session with nobody present and no way to prompt cannot start a flow at all, and says so rather than printing a device code nobody will read.

Only --with-token stores a credential. --token, --token-file and SURREALCTL_TOKEN are request-scoped and never written to disk.

surrealctl auth logout

Remove the stored credentials for a profile.

surrealctl auth logout [OPTIONS]

This command takes no positional arguments.

surrealctl auth logout

surrealctl --profile ci auth logout --force --json

Logging out revokes the refresh token at the identity provider on a best-effort basis and removes only this profile's entry. A failed revocation warns but never blocks the local wipe.

Signing out when nothing is signed in still succeeds and still emits a document, so auth logout --json in a teardown script has the same shape on its second run as on its first:

{
  "profile": "ci",
  "removed": false,
  "revoked": false
}

Declining the confirmation prints Nothing was changed. and exits 0.

surrealctl auth status

Show which credentials are in use, without touching the network.

surrealctl auth status [OPTIONS]

This command takes no positional arguments.

surrealctl auth status

surrealctl auth status --verify

The document has the same shape signed in and signed out, so a script can read one field without branching first. status warns when the machine's clock is more than five minutes out, and when SURREALCTL_CLOUD_TOKEN is supplying a session token.

For the API's own view of your identity, use whoami, which spends a request.

surrealctl auth refresh

Renew the stored credentials now, rather than waiting for them to expire.

surrealctl auth refresh [OPTIONS]

This command takes no positional arguments.

surrealctl auth refresh

The command forces both the access token and the Cloud session. --all additionally renews the token used for the account-management routes, which is the one the token commands need.

Refusals. With nothing signed in, this exits 3. On a personal access token it reports that a token does not expire on a schedule and cannot be refreshed, then exits 0 without sending anything.

surrealctl auth scopes

Show what the current credential is permitted to do.

surrealctl auth scopes [OPTIONS]

This command takes no positional arguments.

surrealctl auth scopes

SCOPE
read:cloud
write:cloud-instances

The single column is scope.

Refusals. With nothing signed in, this exits 3 — a script asking "what may this credential do" and getting an empty list would read it as "nothing is permitted" rather than "nothing is signed in".

On a login session the list is empty, and a sentence on stderr points at org permissions: identity scopes are not an authorisation model, and your role in the organisation is what decides what you may do.

For the catalogue of scopes a token can be granted, use token scopes.

Related pages

• •

  Authentication — the credential model, login flows and credential storage

• •

  token commands — creating and revoking personal access tokens

• •

  context commands — switching between profiles

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — database-level authentication, which these credentials do not cover