token

surrealctl token manages personal access tokens: the sdbp_… credentials that authenticate CI jobs and automation against the control plane.

surrealctl token <COMMAND> [OPTIONS]surrealctl tokens <COMMAND> [OPTIONS]

Managing personal access tokens needs an interactive login session, so nothing was sent.

Sign in with:  surrealctl auth login

Being signed out is a different answer with a different code: 3, not 4. Sign in with auth login.

These tokens are not database credentials. For a token a SurrealDB client can authenticate with, use instance token.

surrealctl token list

List your personal access tokens.

surrealctl token list [OPTIONS]

This command takes no positional arguments.

Accepts the list presentation flags and nothing else. Column ids are label, id, scopes, created_at and expires_at, with user_id under --wide.

surrealctl token list

LABEL              ID                    SCOPES                  CREATED       EXPIRES
build runner       67upif0m8sh1cn1p2c8t  read:cloud              2 months ago  in 4 days
nightly export     6a2k9lqzt4v8bn3m1x5c  read:cloud              3 days ago    never

surrealctl token list --json | jq -r '.[] | .label + " " + .expires_at'

Only the label, the id, the scopes and the timestamps are stored — the secret itself exists once, at creation. A token with no expiry carries the 9999-12-31T23:59:59Z sentinel under --json.

surrealctl token create

Create a personal access token.

surrealctl token create [OPTIONS] <LABEL>

The secret is returned exactly once. Capture it on creation or create another one.

TOKEN=$(surrealctl token create "build runner" --scope read:cloud | tail -1)

surrealctl token create "nightly export" \
    --scope read:cloud \
    --scope write:cloud-instances \
    --expires-in 90 \
    | tail -1 > /run/secrets/surrealctl

Output is a detail view with the secret stripped, then a success line, then the bare secret as the last line on stdout — so | tail -1 is the whole capture recipe. The footer names the token's id rather than its label, because a label may contain spaces.

`token create` has no --json form. The secret is returned exactly once, and it can neither go inside
the document nor share stdout with it.
Run it without --json and take the last line:
  surrealctl token create <label> | tail -1

Refusals, all exit 2 and all before the request:

• •

  stdout is a terminal and --reveal was not passed:

Refusing to print a secret to a terminal, where it would stay in your scrollback.
Pipe it:  surrealctl token create <label> | tail -1
Or pass --reveal if you meant to see it.

• •

  A label outside 1 to 120 characters.

• •

  More than 32 scopes: A token carries at most 32 scopes; 40 were given.

• •

  An --expires-in outside 1 to 365 days, unless it is the literal never.

Warnings before the request:

• •

  --expires-in never warns, because the API's own schema calls a non-expiring token discouraged.

• •

  No --scope at all notes that the token will be permitted nothing, and points at token scopes.

Scopes are not pre-checked against the catalogue. An ungrantable scope answers 403 naming the problem, which is more useful than the bare 400 the API gives for everything else.

surrealctl token delete

Revoke a personal access token.

surrealctl token delete [OPTIONS] <TOKEN>

surrealctl token delete "build runner"

surrealctl token delete 67upif0m8sh1cn1p2c8t --force --json

Refusals. The confirmation names the token. Declining exits 0. In a non-interactive session without --force or --yes, it exits 2 having sent nothing.

surrealctl token scopes

List the scopes a token can be granted.

surrealctl token scopes [OPTIONS]

This command takes no positional arguments.

Accepts the list presentation flags and nothing else. Column ids are id, category and label, with description under --wide.

surrealctl token scopes

surrealctl token scopes --columns id --no-header

This is the menu. auth scopes is the receipt: what the credential in hand actually carries.

Related pages

• •

  Authentication — how a token is supplied, and what it cannot do

• •

  auth commands — signing in with a login session

• •

  instance token — database tokens, which are a different credential

• •

  Output and exit codes — the secret guard

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — for working with the data inside an instance