# invite

Reference for surrealctl invite — listing an organisation's pending invitations, sending one, and withdrawing one.

`surrealctl 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/surrealctl/commands/team.md).

<Synopsis>
surrealctl invite <COMMAND> [OPTIONS]
surrealctl 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/surrealctl/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.

## surrealctl invite list {#invite-list}

List an organisation's pending invitations.

<Synopsis>
surrealctl invite list [OPTIONS]
</Synopsis>

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

Accepts the [list presentation flags](/docs/reference/cli/surrealctl/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
surrealctl 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"
surrealctl invite list --wide
```

An organisation with no pending invitations is a success: exit `0`, and an empty array under `--json`.

## surrealctl invite create {#invite-create}

Invite someone to an organisation.

<Synopsis>
surrealctl 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 `surrealctl org roles` for the ones this organisation defines."
        }
    ]}
/>

```bash
surrealctl 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
    surrealctl 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 `surrealctl 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/surrealctl/commands/org.md#org-roles).

## surrealctl invite delete {#invite-delete}

Withdraw an invitation.

<Synopsis>
surrealctl 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"
surrealctl invite delete dee@acme.example
```

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

**Refusals.** The confirmation names the address the invitation was sent to. Declining 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/surrealctl/commands/team.md#team-remove) for that.

## Related pages

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