> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification Channels

> Create, test, and manage outbound notification delivery channels.

# crewship notifychannel

Manage outbound notification channels for email, signed webhooks, and chat or
push providers.

```bash theme={null}
crewship notifychannel <subcommand> [flags]
```

The command also accepts the alias `notify-channel`. All commands require an
authenticated CLI session and a selected workspace. Workspace-channel writes
require `ADMIN` or `OWNER`; `--personal` makes an added channel personal and
available to its owner in that user's preference matrix.

## Subcommands

| Command      | Description                                            |
| ------------ | ------------------------------------------------------ |
| `list`       | List notification channels in the workspace.           |
| `add`        | Create an email, webhook, or chat/push channel.        |
| `test <id>`  | Send a synthetic notification to a saved channel.      |
| `test-draft` | Test channel settings without saving a channel.        |
| `rm <id>`    | Delete a channel; aliases: `delete`, `remove`.         |
| `providers`  | List providers and inspect their required form fields. |
| `deliveries` | Show the outbound delivery log (admin only).           |
| `agents`     | Allow or revoke agent access to a channel.             |

## `crewship notifychannel add`

```bash theme={null}
# Webhook channels are signed with X-Crewship-Signature.
crewship notifychannel add --type webhook --url https://hooks.example.com/crewship

crewship notifychannel add --type email --to ops@example.com

# Provider fields are repeatable key=value arguments.
crewship notifychannel add --type chat --provider slack \
  --field webhook_url=https://hooks.slack.com/services/T0/B0/XXX

# Any member can create a personal channel for their own preference matrix.
crewship notifychannel add --type chat --provider ntfy \
  --field topic=my-alerts --personal
```

| Flag             | Type                   | Description                                                                            |
| ---------------- | ---------------------- | -------------------------------------------------------------------------------------- |
| `--type`         | string                 | Required: `email`, `webhook`, or `chat`.                                               |
| `--url`          | string                 | Webhook URL, or an advanced pre-composed chat delivery URL.                            |
| `--to`           | string                 | Destination address for an email channel.                                              |
| `--provider`     | string                 | Provider name for a chat channel; see `providers`.                                     |
| `--field`        | repeatable `key=value` | Provider form input. Use the field keys printed by `providers --provider <name>`.      |
| `--secret`       | string                 | Optional webhook signing secret; generated when omitted.                               |
| `--events`       | string list            | Legacy run outcomes: `failed`, `completed`, or `all`.                                  |
| `--personal`     | bool                   | Create a personal channel instead of a workspace channel.                              |
| `--categories`   | string list            | Restrict a workspace channel to notification categories; omitted means every category. |
| `--min-priority` | string                 | Priority floor: `low`, `medium`, `high`, or `urgent`.                                  |

For chat channels, `--provider` and either one or more `--field` arguments or
an advanced pre-composed `--url` are required. A created webhook secret or
chat service URL is shown once, so save it when the command prints it.

## `crewship notifychannel providers`

List the providers enabled or disabled on the instance:

```bash theme={null}
crewship notifychannel providers
crewship notifychannel providers --provider discord
```

`--provider <name>` prints that provider's category and form fields. Pass those
field keys to `add` or `test-draft` as repeated `--field key=value` arguments.

Administrators can change the instance allowlist:

```bash theme={null}
crewship notifychannel providers disable <provider>
crewship notifychannel providers enable <provider>
```

Disabling a provider stops delivery through it, including existing channels,
and refuses new channels using it. Both provider changes require `ADMIN` or
`OWNER`.

## Testing and diagnostics

Send a test through an existing channel, or verify settings before saving:

```bash theme={null}
crewship notifychannel test <channel-id>
crewship notifychannel test-draft --type webhook \
  --url https://hooks.example.com/crewship
crewship notifychannel test-draft --type chat --provider slack \
  --field webhook_url=https://hooks.slack.com/services/T0/B0/XXX
```

`test-draft` accepts `--type`, `--url`, `--to`, `--provider`, repeated
`--field`, and optional `--secret`. It sends one test and stores nothing.

Inspect delivery outcomes with optional filters:

```bash theme={null}
crewship notifychannel deliveries
crewship notifychannel deliveries --status failed --limit 50
crewship notifychannel deliveries --channel <channel-id> --category agents.error
```

| Flag         | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `--status`   | `pending`, `sent`, `failed`, `dropped_pref`, or `dropped_rate`. |
| `--channel`  | Filter by channel ID.                                           |
| `--category` | Filter by notification category.                                |
| `--limit`    | Maximum rows; the server default is 100.                        |

## Agent access

Agents have no channel access by default. Pair an agent with a channel before
allowing it to send notifications itself:

```bash theme={null}
crewship notifychannel agents list <channel-id>
crewship notifychannel agents allow <channel-id> --agent <agent-id>
crewship notifychannel agents deny <channel-id> --agent <agent-id>
```

`allow` and `deny` require the `--agent` flag. Pairing follows the channel's
authority: `ADMIN` or `OWNER` for workspace channels, and the channel owner for
a personal channel.

## Delete a channel

Deletion prompts for confirmation unless `--yes` is supplied. This is useful
for scripts and non-interactive jobs:

```bash theme={null}
crewship notifychannel rm <channel-id>
crewship notifychannel rm <channel-id> --yes
```

## Related commands

* [`crewship notify prefs`](/cli/notify) — choose which categories reach which channels.
* [Outbound notifications](/guides/notifications) — delivery categories and preference behavior.