# `bird invitations create`

## Usage

```bash
bird invitations create [flags]
```

## Description

Create a workspace invitation

Smart invite: if the email matches an existing org member not yet in this workspace,
adds them directly and returns a member object. Otherwise creates an invitation
and returns an invitation object. The type discriminator field indicates which action
was taken.

Build the request from flags, a JSON MemberCreate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Procedure

Step 1 of 3 of "Invite a user to a workspace and manage the invitation". Next: bird invitations get.

## Examples

```bash
# print the body shape (no credentials needed)
bird invitations create --example
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--email`           | Email address of the user to add. If the user is already an org member, they are added directly. Otherwise an invitation is sent. |
| `--role`            |                                                                                                                                   |
| `--response-schema` | Print the fields this command returns, then exit                                                                                  |

## Related

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