spectron

surrealctl spectron manages Spectron: contexts, the API keys and access tokens that reach them, and the principals and grants that decide what those credentials may do.

surrealctl spectron <COMMAND> [OPTIONS]

Naming a context

Every context-scoped route needs both an organisation and a context, and no route accepts a context by name — contexts have no slug, so a name costs one lookup. Commands whose noun lives inside a context take --context <REF>; the spectron context verbs take a positional instead.

The inference chain is deliberately shorter than the organisation chain: there is no spectron context use, no server default and nothing persisted.

1. 1.

   No contexts at all is an error naming --context.

2. 2.

   Exactly one context is used silently.

3. 3.

   Several, in a non-interactive session, is a usage error, exit 2:

Several Spectron contexts are available and none was chosen.
Pass --context.

Available:
  research
  production

4. 4.

   Several, on a terminal, opens a picker.

spectron context list is the one command in the group that needs no context of its own, so it is what to run when --context has just failed to resolve.

Grant syntax

Grants are written <noun>:<verb>=<pattern>[,<pattern>] and --grant is repeatable. Repeats merge rather than overwrite, so --grant memory:read=/a --grant memory:read=/b grants both patterns.

--grant memory:read=/projects/acme
--grant memory:read=/projects/acme,/projects/shared
--grant memory:write=/projects/acme --grant memory:read=/

A malformed grant is a usage error, exit 2, and the message repeats the expected shape. Run spectron verbs for the verbs a grant may name and spectron scopes for the paths a pattern may match.

surrealctl spectron context list

List the Spectron contexts in an organisation.

surrealctl spectron context list [OPTIONS]

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

Accepts the list presentation flags. Column ids are name, state, region and id, with host and organization_id under --wide.

surrealctl spectron context list

NAME        STATE   REGION    ID
research    ready   aws-euw1  67upif0m8sh1cn1p2c8t
production  ready   aws-use1  6a2k9lqzt4v8bn3m1x5c

surrealctl spectron context get

Show one Spectron context.

surrealctl spectron context get [OPTIONS] [CONTEXT]

This command has no options of its own.

surrealctl spectron context get research

surrealctl spectron context create

Create a Spectron context.

surrealctl spectron context create [OPTIONS] --region <REGION> <NAME>

surrealctl spectron context create research --region aws-euw1

Region slugs come from catalog regions.

surrealctl spectron context update

Rename a Spectron context.

surrealctl spectron context update [OPTIONS] --name <NAME> [CONTEXT]

surrealctl spectron context update research --name "Research and development"

surrealctl spectron context delete

Delete a Spectron context.

surrealctl spectron context delete [OPTIONS] [CONTEXT]

surrealctl spectron context delete research

Note that this positional does not fall back to "the only one" the way the read verbs do. A delete that infers its target is a delete in the wrong terminal tab.

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

surrealctl spectron key list

List a context's API keys.

surrealctl spectron key list [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are name and id, with spectron_context_id and organization_id under --wide.

surrealctl spectron key list --context research

Only the name and the id are stored. The secret exists once, at creation.

surrealctl spectron key create

Create an API key.

surrealctl spectron key create [OPTIONS] <NAME>

surrealctl spectron key create "agent runtime" --context research > /run/secrets/spectron-key

surrealctl spectron key create "agent runtime" --json > key.json

Output is the bare key on stdout in text modes, and the whole body under --json so the id and name survive for a later revoke. It is never a table — a secret in a table is a secret in a screenshot.

Refusals. The secret guard fires before the request, so a forgotten --reveal never costs a key nobody can recover.

surrealctl spectron key delete

Delete an API key.

surrealctl spectron key delete [OPTIONS] <KEY>

surrealctl spectron key delete "agent runtime" --context research --force

surrealctl spectron key rotate

Replace an API key's secret, keeping its id and name.

surrealctl spectron key rotate [OPTIONS] <KEY>

surrealctl spectron key rotate "agent runtime" --force > /run/secrets/spectron-key

Rotation invalidates the previous secret, so redeploy whatever holds it. Like create, the secret guard fires before the request.

surrealctl spectron scoped-key create

Mint a scoped key for a principal — a key attenuated below what that principal itself may do.

surrealctl spectron scoped-key create [OPTIONS] --principal <REF> <NAME>

surrealctl spectron scoped-key create "read-only worker" \
    --principal "research agent" \
    --grant memory:read=/projects/acme \
    --context research \
    > /run/secrets/worker-key

This group has one verb on purpose. A renamed command is a broken script, so scoped-key stays a group even with nothing to sit beside create.

surrealctl spectron access-token create

Mint a short-lived access token.

surrealctl spectron access-token create [OPTIONS]

This command takes no positional arguments.

TOKEN=$(surrealctl spectron access-token create --ttl 15m --context research)

--ttl uses the standard duration syntax. The server clamps whatever you ask for to its own maximum, so read the expiry from the answer rather than assuming your value was taken.

surrealctl spectron principal list

List a context's principals.

surrealctl spectron principal list [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are display_name, kind, id and verbs, with grants under --wide.

surrealctl spectron principal list --context research --wide

surrealctl spectron principal create

Create a principal.

surrealctl spectron principal create [OPTIONS] --kind <KIND> <NAME>

surrealctl spectron principal create "research agent" \
    --kind agent \
    --grant memory:read=/projects \
    --grant memory:write=/projects/acme \
    --context research

--kind is a free-form string rather than a closed set, because the four values above are a convention and a closed set would need a new release before anyone could use a kind Cloud added.

surrealctl spectron principal update

Rename a principal or change its kind.

surrealctl spectron principal update [OPTIONS] <PRINCIPAL>

surrealctl spectron principal update "research agent" --kind service

Grants are not changed here. Use principal grants set for those.

surrealctl spectron principal delete

Delete a principal.

surrealctl spectron principal delete [OPTIONS] <PRINCIPAL>

surrealctl spectron principal delete "research agent" --force

surrealctl spectron principal grants set

Replace a principal's grants.

surrealctl spectron principal grants set [OPTIONS] <PRINCIPAL>

The grants route is a full replacement, so this command reads the current set, applies your flags, and confirms the result before writing.

surrealctl spectron principal grants set "research agent" \
    --grant memory:read=/projects/contoso

surrealctl spectron principal grants set "research agent" --revoke memory:write

surrealctl spectron principal grants set "research agent" \
    --clear \
    --grant memory:read=/projects \
    --force

--clear is what makes this command declarative: with it, the flags describe the complete result rather than a change to what exists. Without it, --grant merges and --revoke subtracts.

surrealctl spectron package list

List every context package this deployment offers.

surrealctl spectron package list [OPTIONS]

This command takes no positional arguments and no options of its own — not even --context. The catalogue is a property of the deployment, so it answers even when nothing else is resolvable.

Accepts the list presentation flags. Column ids are name, cost, billing_period, token_limit, storage_gb, contexts_limit and trial_days, with id, public and description under --wide.

surrealctl spectron package list

surrealctl spectron package org-list

List the packages an organisation has enabled.

surrealctl spectron package org-list [OPTIONS]

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

Accepts the list presentation flags. Column ids are package_id, enabled_at, trial_ends_at and subscription_ends_at, with disabled_at and organization_id under --wide.

surrealctl spectron package org-list --org acme

surrealctl spectron package enable

Enable a package for an organisation.

surrealctl spectron package enable [OPTIONS] <PACKAGE>

surrealctl spectron package enable "scale" --coupon LAUNCH2026

Enabling a package starts a subscription and affects billing. Check package list for what each one includes first.

surrealctl spectron package cancel

Cancel an organisation's package subscription.

surrealctl spectron package cancel [OPTIONS] <PACKAGE>

surrealctl spectron package cancel "scale"

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

surrealctl spectron scopes

List a context's scope tree.

surrealctl spectron scopes [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are path, name, depth, children and value_policy, with created_at, parent and tombstoned_at under --wide.

surrealctl spectron scopes --context research --sort path

These paths are what a grant pattern matches.

surrealctl spectron verbs

List the verbs a grant can name.

surrealctl spectron verbs [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are name, noun and description.

surrealctl spectron verbs --context research

The noun and name columns are the two halves of the <noun>:<verb> prefix in a grant.

surrealctl spectron providers

List the model providers a context can use.

surrealctl spectron providers [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are provider and models, with count under --wide.

surrealctl spectron providers --context research

surrealctl spectron usage

Show a context's token usage.

surrealctl spectron usage [OPTIONS]

This command takes no positional arguments.

Also accepts the list presentation flags. Column ids are model, token_kind, origin and tokens.

surrealctl spectron usage --context research --sort tokens --reverse

A one-line total is printed on stderr in text modes, computed before --limit is applied. A context with no ceiling gets its own sentence rather than a hole where the limit would be.

surrealctl spectron config

Show a context's configuration.

surrealctl spectron config [OPTIONS]

This command takes no positional arguments.

This command carries no list presentation flags — its answer is a detail view, not a table.

surrealctl spectron config --context research

Not to be confused with surrealctl config, which reads and writes the CLI's own configuration file on this machine.

Related pages

• •

  Spectron documentation — what contexts, principals and grants are for

• •

  org commands — the organisation that owns a context

• •

  Output and exit codes — the secret guard every minting command applies

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — for working with the data inside an instance