# org

Reference for surrealctl org — listing and creating organisations, renaming and archiving them, remembering a default, and reading roles, permissions, usage, spend and plans.

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

<Synopsis>
surrealctl org <COMMAND> [OPTIONS]
surrealctl 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 | |

Personal access tokens are read-only here: the mutating verbs answer 403, exit `4`. See [Authentication](/docs/reference/cli/surrealctl/authentication.md#what-a-personal-access-token-cannot-do).

## surrealctl org list {#org-list}

List the organisations you belong to.

<Synopsis>
surrealctl 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/surrealctl/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
surrealctl 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"
surrealctl org list --columns name --no-header
```

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

## surrealctl org get {#org-get}

Show one organisation.

<Synopsis>
surrealctl 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
surrealctl org get acme
```

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

Create an organisation.

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

Rename an organisation.

<Synopsis>
surrealctl 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
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 {#org-archive}

Archive an organisation.

<Synopsis>
surrealctl 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
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:

```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`.

## surrealctl org use {#org-use}

Remember an organisation as the default for this profile.

<Synopsis>
surrealctl 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"
surrealctl org use acme
```

```bash title="Pick from a list"
surrealctl org use
```

```bash title="Forget it again"
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](/docs/reference/cli/surrealctl/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 `SURREALCTL_ORG` is set, because the variable outranks what it just wrote.

`org use` remembers an organisation *within* a profile. [`context use`](/docs/reference/cli/surrealctl/commands/context.md#context-use) switches the whole profile.

## surrealctl org roles {#org-roles}

List the roles an organisation can assign.

<Synopsis>
surrealctl 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/surrealctl/output-and-exit-codes.md#list-presentation-flags). Column ids are `name` and `permissions`.

```bash
surrealctl org roles
```

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

## surrealctl org permissions {#org-permissions}

Show what you are permitted to do in an organisation.

<Synopsis>
surrealctl 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/surrealctl/output-and-exit-codes.md#list-presentation-flags). Column ids are `resource` and `action`.

```bash
surrealctl org permissions --org acme
```

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

## surrealctl org usage {#org-usage}

Show resource usage across an organisation's instances.

<Synopsis>
surrealctl 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/surrealctl/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"
surrealctl org usage --sort compute_hours --reverse
```

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

## surrealctl org spend {#org-spend}

Show an organisation's billed spend.

<Synopsis>
surrealctl 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/surrealctl/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"
surrealctl org spend --period 07-2026
```

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

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

List the plans available to an organisation.

<Synopsis>
surrealctl 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/surrealctl/output-and-exit-codes.md#list-presentation-flags). Column ids are `name`, `id`, `regions` and `instance_types`, with `description` under `--wide`.

```bash
surrealctl org plans
```

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

## Related pages

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