> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# surreal cloud org

Reference for surreal cloud org - list, get, create, rename, archive and remember a default organisation, and read its roles, permissions, usage, spend and plans. Includes the --period format, archive confirmation and the scopes this group needs.

`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`](/docs/reference/cli/cloud/commands/auth.md).

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

| Verb | Purpose | Alias |
| --- | --- | --- |
| [`list`](#org-list) | List the organisations you belong to | `ls` |
| [`get`](#org-get) | Show one organisation | |
| [`create`](#org-create) | Create an organisation | |
| [`update`](#org-update) | Rename an organisation | |
| [`archive`](#org-archive) | Archive an organisation | |
| [`use`](#org-use) | Remember an organisation as the default for this profile | |
| [`roles`](#org-roles) | List the roles an organisation can assign | |
| [`permissions`](#org-permissions) | Show what you are permitted to do in an organisation | |
| [`usage`](#org-usage) | Show resource usage across an organisation's instances | |
| [`spend`](#org-spend) | Show an organisation's billed spend | |
| [`plans`](#org-plans) | List the plans available to an organisation | |

This group declares the scopes `read:cloud` and `write:cloud-organization`, the same pair as [`team`](/docs/reference/cli/cloud/commands/team.md) and [`invite`](/docs/reference/cli/cloud/commands/invite.md). 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](/docs/reference/cli/cloud/authentication.md#what-a-personal-access-token-cannot-do).

## surreal cloud org list {#org-list}

List the organisations you belong to.

<Synopsis>
surreal cloud org list [OPTIONS]
</Synopsis>

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

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--all",
            "description": "Include archived organisations."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#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`.

```bash
surreal cloud org list
```

```text title="Output"
NAME      ID                    PLAN    STATE   YOUR ROLE  MEMBERS
acme      67upif0m8sh1cn1p2c8t  scale   active  owner            7
contoso   6a2k9lqzt4v8bn3m1x5c  free    active  member           2
```

```bash title="Just the names, for a loop"
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 {#org-get}

Show one organisation.

<Synopsis>
surreal cloud org get [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

This command has no options of its own.

```bash
surreal cloud org get acme
```

```bash title="Whichever organisation is in force"
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 {#org-create}

Create an organisation.

<Synopsis>
surreal cloud org create [OPTIONS] <NAME>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<NAME>",
            "required": true,
            "description": "A name for the organisation. Between 1 and 30 characters."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--use",
            "description": "Remember this organisation as the default for this profile, as if `org use` had been run afterwards."
        }
    ]}
/>

```bash
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`](#org-update).

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 {#org-update}

Rename an organisation.

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

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--name",
            "value": "<NAME>",
            "required": true,
            "description": "The new name."
        }
    ]}
/>

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

The name has the same 1 to 30 character limit as [`org create`](#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 {#org-archive}

Archive an organisation.

<Synopsis>
surreal cloud org archive [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--force",
            "description": "Archive without confirming."
        }
    ]}
/>

```bash
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:

```text
`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`](#org-list) unless you pass `--all`.

## surreal cloud org use {#org-use}

Remember an organisation as the default for this profile.

<Synopsis>
surreal cloud org use [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Omit to choose interactively."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--clear",
            "description": "Forget the remembered organisation instead. Conflicts with `[ORG]`."
        }
    ]}
/>

```bash title="Remember one"
surreal cloud org use acme
```

```bash title="Pick from a list"
surreal cloud org use
```

```bash title="Forget it again"
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](/docs/reference/cli/cloud/global-flags.md#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`](/docs/reference/cli/cloud/commands/context.md#context-use) switches the whole profile.

## surreal cloud org roles {#org-roles}

List the roles an organisation can assign.

<Synopsis>
surreal cloud org roles [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `name` and `permissions`.

```bash
surreal cloud org roles
```

The role vocabulary is per organisation, which is why [`team invite`](/docs/reference/cli/cloud/commands/team.md#team-invite) and [`team update`](/docs/reference/cli/cloud/commands/team.md#team-update) point here rather than validating a `--role` value locally.

## surreal cloud org permissions {#org-permissions}

Show what you are permitted to do in an organisation.

<Synopsis>
surreal cloud org permissions [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `resource` and `action`.

```bash
surreal cloud org permissions --org acme
```

This is the authorisation model to consult when a command answers 403. [`auth scopes`](/docs/reference/cli/cloud/commands/auth.md#auth-scopes) reports the credential's own scopes, which are a different thing.

## surreal cloud org usage {#org-usage}

Show resource usage across an organisation's instances.

<Synopsis>
surreal cloud org usage [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#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`.

```bash title="Compute hours per instance, largest first"
surreal cloud org usage --sort compute_hours --reverse
```

For one instance rather than all of them, use [`instance usage`](/docs/reference/cli/cloud/commands/instance.md#instance-usage).

## surreal cloud org spend {#org-spend}

Show an organisation's billed spend.

<Synopsis>
surreal cloud org spend [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--period",
            "value": "<MM-YYYY>",
            "description": "The billing period, as MM-YYYY. Defaults to the current month."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `description`, `resource`, `amount`, `units` and `effective_at`, with `instance_id`, `instance_type` and `cloud_usage_units` under `--wide`.

```bash title="Last month's ledger"
surreal cloud org spend --period 07-2026
```

```bash title="The ten largest lines"
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:

```text
`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 {#org-plans}

List the plans available to an organisation.

<Synopsis>
surreal cloud org plans [OPTIONS] [ORG]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[ORG]",
            "description": "The organisation, by id or name. Defaults to the resolved one."
        }
    ]}
/>

Also accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags). Column ids are `name`, `id`, `regions` and `instance_types`, with `description` under `--wide`.

```bash
surreal cloud org plans
```

This is the organisation-scoped answer, and the one to trust before an [`instance create`](/docs/reference/cli/cloud/commands/instance.md#instance-create). The [`catalog`](/docs/reference/cli/cloud/commands/catalog.md) commands list what the platform offers globally, which is always the wider set.

## Related pages

- [`instance` commands](/docs/reference/cli/cloud/commands/instance.md) - the instances an organisation owns
- [`team` commands](/docs/reference/cli/cloud/commands/team.md) - its members
- [`catalog` commands](/docs/reference/cli/cloud/commands/catalog.md) - platform-wide regions, types and versions
- [Global flags](/docs/reference/cli/cloud/global-flags.md) - `--org` and the precedence chain
- [Overview](/docs/reference/cli/cloud.md) - the rest of the reference
- [SurrealDB CLI](/docs/reference/cli/db.md) - for working with the data inside an instance