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

# surreal cloud invite

Reference for surreal cloud invite - list pending organisation invitations, send one with a role, and withdraw one by email address or code. Same command as team invite; email is checked locally and roles come from org roles.

`surreal cloud invite` manages organisation invitations: the ones that have been sent and not yet accepted. Once someone accepts, they become a member and move into [`team`](/docs/reference/cli/cloud/commands/team.md).

<Synopsis>
surreal cloud invite <COMMAND> [OPTIONS]
surreal cloud invites <COMMAND> [OPTIONS]
</Synopsis>

| Verb | Purpose | Alias |
| --- | --- | --- |
| [`list`](#invite-list) | List an organisation's pending invitations | `ls` |
| [`create`](#invite-create) | Invite someone to an organisation | |
| [`delete`](#invite-delete) | Withdraw an invitation | `rm` |

[`team invite`](/docs/reference/cli/cloud/commands/team.md#team-invite) and [`invite create`](#invite-create) are the same command reached two ways - the same arguments, the same validators and the same messages - because sending an invitation is both how a team gains a member and how an invitation comes to exist. Use whichever reads better in the script you are writing.

This group declares the scopes `read:cloud` and `write:cloud-organization`, the same pair as [`org`](/docs/reference/cli/cloud/commands/org.md) and [`team`](/docs/reference/cli/cloud/commands/team.md). A personal access token cannot use the mutating verbs: see [Authentication](/docs/reference/cli/cloud/authentication.md#what-a-personal-access-token-cannot-do). There is no `update`: to change an invitation, withdraw it and send another.

## surreal cloud invite list {#invite-list}

List an organisation's pending invitations.

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

This command takes no positional argument. The organisation comes from `--org` and the [precedence chain](/docs/reference/cli/cloud/global-flags.md#the-precedence-chain).

Accepts the [list presentation flags](/docs/reference/cli/cloud/output-and-exit-codes.md#list-presentation-flags) and nothing else. Column ids are `email`, `role` and `status`, with `code` and `organization_id` under `--wide`.

```bash
surreal cloud invite list
```

```text title="Output"
EMAIL                ROLE    STATUS
dee@acme.example     member  pending
eli@acme.example     admin   pending
```

```bash title="Include the codes, which withdrawals also accept"
surreal cloud invite list --wide
```

The list is not filtered by status, so it shows every status the API reports. An organisation with no invitations is a success: exit `0`, and an empty array under `--json`.

## surreal cloud invite create {#invite-create}

Invite someone to an organisation.

<Synopsis>
surreal cloud invite create [OPTIONS] --role <ROLE> <EMAIL>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<EMAIL>",
            "required": true,
            "description": "The email address to invite."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--role",
            "value": "<ROLE>",
            "required": true,
            "description": "The role to grant. Run `surreal cloud org roles` for the ones this organisation defines."
        }
    ]}
/>

```bash
surreal cloud invite create dee@acme.example --role member
```

```bash title="Invite a whole list, reading roles from a file"
while IFS=, read -r email role; do
    surreal cloud invite create "$email" --role "$role"
done < new-joiners.csv
```

**Refusals**, exit `2`, before any request. The address validator asks only for an `@` with something either side and no internal whitespace; the API is the authority on deliverability:

```text
`dee.acme.example` is not an email address: it has no `@`.
```

Only an empty `--role` is refused locally, because the role vocabulary is per organisation:

```text
A role cannot be empty. Run `surreal cloud org roles` to see the ones this organization defines.
```

A role the API rejects as invalid is annotated with a pointer to [`org roles`](/docs/reference/cli/cloud/commands/org.md#org-roles).

The command is never retried after the request has been written, because a repeat would send a second email carrying a second working code. On success it prints the invitation, including its code.

## surreal cloud invite delete {#invite-delete}

Withdraw an invitation.

<Synopsis>
surreal cloud invite delete [OPTIONS] <INVITE>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<INVITE>",
            "required": true,
            "description": "The invitation, by email address or code."
        }
    ]}
/>

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

```bash title="By address"
surreal cloud invite delete dee@acme.example
```

```bash title="By code, without a prompt"
surreal cloud invite delete 7f3a91c4 --force
```

The invitation has no id of its own. The API identifies it by its code, which the recipient also redeems, so `<INVITE>` accepts either. An email address is resolved to its code by listing the invitations first, and the listing also happens when you pass a code, so the confirmation can name the address.

**Refusals.** The confirmation names the address the invitation was sent to. Declining prints `Nothing was withdrawn.` and exits `0`. In a non-interactive session without `--force` or `--yes`, it exits `2` having sent nothing.

Withdrawing an invitation someone has already accepted is not how you remove them - use [`team remove`](/docs/reference/cli/cloud/commands/team.md#team-remove) for that.

## Related pages

- [`team` commands](/docs/reference/cli/cloud/commands/team.md) - members who have already joined
- [`org roles`](/docs/reference/cli/cloud/commands/org.md#org-roles) - the roles an invitation can grant
- [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