org

surrealctl org manages organisations. An organisation owns instances, members and billing, and almost every other command needs to know which one you mean — so this group is usually the second one you reach for after auth.

surrealctl org <COMMAND> [OPTIONS]surrealctl orgs <COMMAND> [OPTIONS]

Personal access tokens are read-only here: the mutating verbs answer 403, exit 4. See Authentication.

surrealctl org list

List the organisations you belong to.

surrealctl org list [OPTIONS]

This command takes no positional arguments — it lists everything you can see.

Also accepts the list presentation flags. Column ids are name, id, plan, state, role and members, with billing_provider, max_free, max_paid, privatelink, locked and archived_at shown only under --wide.

surrealctl org list

NAME      ID                    PLAN    STATE   YOUR ROLE  MEMBERS
acme      67upif0m8sh1cn1p2c8t  scale   active  owner            7
contoso   6a2k9lqzt4v8bn3m1x5c  free    active  member           2

surrealctl org list --columns name --no-header

An empty list is a success: exit 0 and an empty array under --json.

surrealctl org get

Show one organisation.

surrealctl org get [OPTIONS] [ORG]

This command has no options of its own.

surrealctl org get acme

surrealctl org get

The detail view reports the id, plan, state, your role, the member count, free and paid instance allowances, the billing provider and details, the payment method and PrivateLink availability. Two further fields appear only when they apply: Resources Locked when true, and Archived when the organisation has been archived. Backup retention bounds are shown when the plan defines them.

surrealctl org create

Create an organisation.

surrealctl org create [OPTIONS] <NAME>

surrealctl org create acme --use

Refusals. A name outside 1 to 30 characters is a usage error, exit 2, raised before any request.

surrealctl org update

Rename an organisation.

surrealctl org update [OPTIONS] --name <NAME> [ORG]

surrealctl org update acme --name "Acme Corporation"

Renaming does not change the organisation's id, so scripts that address it by id are unaffected.

surrealctl org archive

Archive an organisation.

surrealctl org archive [OPTIONS] [ORG]

surrealctl org archive contoso

Refusals. The command confirms first unless --force or the global --yes is given. In a non-interactive session with neither, it exits 2 having sent nothing. Declining the prompt prints Nothing was archived. and exits 0.

An organisation that is already archived is a no-op that exits 0. It says so and stops before the archive request:

`contoso` is already archived.

The document is still emitted, so org archive <name> --json answers with the organisation in both cases rather than changing shape with remote state the caller has not seen.

Archived organisations are hidden from org list unless you pass --all.

surrealctl org use

Remember an organisation as the default for this profile.

surrealctl org use [OPTIONS] [ORG]

surrealctl org use acme

surrealctl org use

surrealctl org use --clear

The choice is written to the [profile.<name>.context] table of config.toml, which sits below a hand-written org key in the precedence chain — so setting org yourself is never overwritten by this command.

Refusals. Omitting [ORG] in a non-interactive session exits 2 and names the flags that would have settled it. The command warns when SURREALCTL_ORG is set, because the variable outranks what it just wrote.

org use remembers an organisation within a profile. context use switches the whole profile.

surrealctl org roles

List the roles an organisation can assign.

surrealctl org roles [OPTIONS] [ORG]

Also accepts the list presentation flags. Column ids are name and permissions.

surrealctl org roles

The role vocabulary is per organisation, which is why team invite and team update point here rather than validating a --role value locally.

surrealctl org permissions

Show what you are permitted to do in an organisation.

surrealctl org permissions [OPTIONS] [ORG]

Also accepts the list presentation flags. Column ids are resource and action.

surrealctl org permissions --org acme

This is the authorisation model to consult when a command answers 403. auth scopes reports the credential's own scopes, which are a different thing.

surrealctl org usage

Show resource usage across an organisation's instances.

surrealctl org usage [OPTIONS] [ORG]

Also accepts the list presentation flags. Column ids are instance_id, metric_type, compute_hours, disk_used_bytes, period_start and period_end, with instance_type and source under --wide.

surrealctl org usage --sort compute_hours --reverse

For one instance rather than all of them, use instance usage.

surrealctl org spend

Show an organisation's billed spend.

surrealctl org spend [OPTIONS] [ORG]

Also accepts the list presentation flags. Column ids are description, resource, amount, units and effective_at, with instance_id, instance_type and cloud_usage_units under --wide.

surrealctl org spend --period 07-2026

surrealctl org spend --sort amount --reverse --limit 10

A total is printed on stderr in text modes, computed before --limit is applied, so the total is always the whole bill even when the table is truncated.

Refusals. The period is validated locally, exit 2, and an ISO-ordered value gets a correction rather than a bare rejection:

`2026-03` looks like YYYY-MM. This API wants the month first: use 03-2026.

Under --json, amounts stay in integer minor units. Formatting is a view concern.

surrealctl org plans

List the plans available to an organisation.

surrealctl org plans [OPTIONS] [ORG]

Also accepts the list presentation flags. Column ids are name, id, regions and instance_types, with description under --wide.

surrealctl org plans

This is the organisation-scoped answer, and the one to trust before an instance create. The catalog commands list what the platform offers globally, which is always the wider set.

Related pages

• •

  instance commands — the instances an organisation owns

• •

  team commands — its members

• •

  catalog commands — platform-wide regions, types and versions

• •

  Global flags — --org and the precedence chain

• •

  Overview — the rest of the reference

• •

  SurrealDB CLI — for working with the data inside an instance