surreal cloud org

surreal cloud 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 use after auth.

surreal cloud org <COMMAND> [OPTIONS]surreal cloud orgs <COMMAND> [OPTIONS]

This group declares the scopes read:cloud and write:cloud-organization, the same pair as team and invite. A personal access token is read-only here regardless: the gateway refuses every non-GET Cloud route for one, so the mutating verbs answer 403 and exit 4 even for a token carrying write:cloud-organization. See Authentication.

surreal cloud org list

List the organisations you belong to.

surreal cloud 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.

surreal cloud org list

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

surreal cloud org list --columns name --no-header

Archived organisations are left out of the table. When any were hidden, a note on stderr says how many and suggests --all. --json always carries every organisation, because the filter only affects the table. An empty list is a success: exit 0 and an empty array under --json.

surreal cloud org get

Show one organisation.

surreal cloud org get [OPTIONS] [ORG]

This command has no options of its own.

surreal cloud org get acme

surreal cloud 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.

surreal cloud org create

Create an organisation.

surreal cloud org create [OPTIONS] <NAME>

surreal cloud org create acme --use

Refusals. A name outside 1 to 30 characters, measured after trimming, is a usage error, exit 2, raised before any request. The same limit applies to org update --name.

On success the command prints the new organisation's detail view. With --use, it then records the organisation for the current profile and says so.

surreal cloud org update

Rename an organisation.

surreal cloud org update [OPTIONS] --name <NAME> [ORG]

surreal cloud org update acme --name "Acme Corporation"

The name has the same 1 to 30 character limit as org create, checked locally with exit 2 before any request. Renaming does not change the organisation's id, so scripts that address it by id are unaffected.

surreal cloud org archive

Archive an organisation.

surreal cloud org archive [OPTIONS] [ORG]

surreal cloud org archive contoso

Refusals. The command confirms first unless --force or the global --yes is given. The question names the organisation and how many instances it holds, and archiving cannot be undone from the CLI because there is no unarchive command. In a non-interactive session with neither flag, 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.

surreal cloud org use

Remember an organisation as the default for this profile.

surreal cloud org use [OPTIONS] [ORG]

surreal cloud org use acme

surreal cloud org use

surreal cloud 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 SURREAL_CLOUD_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.

surreal cloud org roles

List the roles an organisation can assign.

surreal cloud org roles [OPTIONS] [ORG]

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

surreal cloud 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.

surreal cloud org permissions

Show what you are permitted to do in an organisation.

surreal cloud org permissions [OPTIONS] [ORG]

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

surreal cloud 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.

surreal cloud org usage

Show resource usage across an organisation's instances.

surreal cloud 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.

surreal cloud org usage --sort compute_hours --reverse

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

surreal cloud org spend

Show an organisation's billed spend.

surreal cloud 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.

surreal cloud org spend --period 07-2026

surreal cloud 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 as the API's integers, in millicents, in a field the API spells amount_millcents. Formatting them as currency is left to the table view.

surreal cloud org plans

List the plans available to an organisation.

surreal cloud org plans [OPTIONS] [ORG]

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

surreal cloud 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