# `bird invitations`

## Usage

```bash
bird invitations
```

## Description

Invite people to the current workspace and manage pending invitations: list
them, read one, create an invitation for an email address, or revoke it.

Reads return JSON; list is paginated. Mutations take flags and/or a --body-file JSON body (flags overriding); run --example to print the body shape or --dry-run to preview the request.

## Procedure

**Invite a user to a workspace and manage the invitation**

Invite an email address to the workspace, which emails the recipient a link to accept. Acceptance happens out of band (the recipient follows the link); there is no API call to accept on their behalf. Track status with a get, and revoke a still-pending invitation to cancel it.

Requires: The invitation must still be pending; an accepted or already-revoked invitation cannot be revoked.

1. `bird invitations create` — Invites an email to the workspace. If the address already belongs to an org member, they are added directly and a member is returned; otherwise a pending invitation is created and the recipient is emailed a link. The type discriminator on the response says which happened. When a member was returned, the user was already in the org and is now in the workspace; there is nothing to accept. When an invitation was returned, the recipient opens the emailed link to accept and the invitation moves from `pending` to `accepted`; no API call accepts on their behalf. Next: bird invitations get or bird invitations revoke
2. `bird invitations get` — Returns the invitation with its current status (pending, accepted, revoked, expired) and expiry time.
3. `bird invitations revoke` — Cancels the pending invitation so its link no longer works.

## Commands

| Name                                               | Description                   |
| -------------------------------------------------- | ----------------------------- |
| [`create`](/docs/cli/reference/invitations-create) | Create a workspace invitation |
| [`get`](/docs/cli/reference/invitations-get)       | Get a workspace invitation    |
| [`list`](/docs/cli/reference/invitations-list)     | List workspace invitations    |
| [`revoke`](/docs/cli/reference/invitations-revoke) | Revoke a workspace invitation |