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

# Notifications

> Send new mentions to Slack, email or a webhook, on the schedule you choose.

Flags and arguments below are the contract as the binary states it. The global flags (`--json`, `--timeout`, …) apply here too and are documented on [Global flags](https://octolens.com/docs/cli/contract/global-flags.md). Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on [The error envelope](https://octolens.com/docs/cli/contract/error-envelope.md).

## `octolens notifications create`

Create a notification on a feed (flags for agents, a guided wizard on a TTY)

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--day-of-week` | `integer` | no | 0 (Sunday)–6 (Saturday), required for --frequency weekly |
| `--delivery-mode` | `string` | no | batch = one digest per period; individual = one message per mention |
| `--destinations-json` | `string` | one of (headless) | Full-fidelity destinations as a JSON array (for multiple destinations). Mutually exclusive with the ergonomic destination flags. |
| `--email` | `string` | one of (headless) | Recipient emails, comma-separated. Implies --type EMAIL |
| `--feed` | `integer` | yes (headless) | Feed id whose filters drive this notification |
| `--frequency` | `string` | no | Delivery cadence: hourly, hourlyAtTopOfHour, daily, weekly (create default: daily; on update, omit to keep the destination's current cadence) |
| `--name` | `string` | yes (headless) | Notification display name |
| `--slack` | `string` | one of (headless) | Slack channel ids, comma-separated (e.g. C0123ABC,C0456DEF). Implies --type SLACK |
| `--time` | `string` | no | Wall-clock time for daily/weekly delivery, 24-hour HH:mm (00:00–23:59, e.g. 09:00) |
| `--timezone` | `string` | no | IANA timezone (e.g. Europe/Madrid) or UTC offset (e.g. UTC+2:00) paired with --time |
| `--type` | `string` | no | Destination type: EMAIL, SLACK, or WEBHOOK (inferred from the target flag if omitted) |
| `--webhook` | `string` | one of (headless) | Webhook URL to POST matching mentions to. Implies --type WEBHOOK |

**Examples**

```bash theme={null}
octolens notifications create --name "Reddit → Slack" --feed 7 --slack C0123ABC --frequency hourly
octolens notifications create --name Webhook --feed 7 --webhook https://hooks.example.com/x --json
octolens notifications create   # interactive wizard on a TTY
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `POST /api/v2/notifications`.

| Field | Type | Description |
| - | - | - |
| `id` | integer | Notification id — what `notifications get/update/test/rm` accept. |
| `name` | string | Display name, shown in the app and included in deliveries. |
| `enabled` | boolean | When `false`, the notification is paused and nothing is delivered. |
| `feedId` | integer | The feed whose filters decide which mentions trigger this notification. |
| `feedName` | string \| null | Display name of the linked feed. |
| `destinations` | object\[] | Delivery destinations (at most one per type). Same shape as a feed's `destinations`. |
| `destinations[].type` | enum: `EMAIL`, `SLACK`, `WEBHOOK` | Delivery channel. The matching `emailDestination` / `slackDestination` / `webhookDestination` sub-object is populated. |
| `destinations[].frequency` | enum: `hourly`, `hourlyAtTopOfHour`, `daily`, `weekly` | Delivery cadence. `daily`/`weekly` also carry `time` + `timezone` (and `dayOfWeek` for weekly). |
| `createdAt` | string | Creation time, ISO 8601. |
| `updatedAt` | string | Last update time, ISO 8601. |

Without `--json`: A terminal prints a confirmation line and the created notification's detail panel.

> [accordion] Example output
>
> ```json theme={null}
> {
>   "id": 19,
>   "name": "Competitor mentions — Slack",
>   "enabled": true,
>   "feedId": 42,
>   "feedName": "Competitor mentions",
>   "destinations": [
>     {
>       "type": "SLACK",
>       "frequency": "hourly",
>       "deliveryMode": "individual",
>       "slackDestination": {
>         "channels": "C0123ABC"
>       }
>     }
>   ],
>   "createdAt": "2026-06-01T09:30:00.000Z",
>   "updatedAt": "2026-07-14T16:05:00.000Z"
> }
> ```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens notifications get`

Get a single notification by id

**Arguments**

| Argument | Type | Required | Description |
| - | - | - | - |
| `ID` | `integer` | required | Numeric notification id (from `notifications list`) |

**Examples**

```bash theme={null}
octolens notifications get 42
octolens notifications get 42 --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/notifications/{id}`.

| Field | Type | Description |
| - | - | - |
| `id` | integer | Notification id — what `notifications get/update/test/rm` accept. |
| `name` | string | Display name, shown in the app and included in deliveries. |
| `enabled` | boolean | When `false`, the notification is paused and nothing is delivered. |
| `feedId` | integer | The feed whose filters decide which mentions trigger this notification. |
| `feedName` | string \| null | Display name of the linked feed. |
| `destinations` | object\[] | Delivery destinations (at most one per type). Same shape as a feed's `destinations`. |
| `destinations[].type` | enum: `EMAIL`, `SLACK`, `WEBHOOK` | Delivery channel. The matching `emailDestination` / `slackDestination` / `webhookDestination` sub-object is populated. |
| `destinations[].frequency` | enum: `hourly`, `hourlyAtTopOfHour`, `daily`, `weekly` | Delivery cadence. `daily`/`weekly` also carry `time` + `timezone` (and `dayOfWeek` for weekly). |
| `createdAt` | string | Creation time, ISO 8601. |
| `updatedAt` | string | Last update time, ISO 8601. |

Without `--json`: A terminal renders the notification's detail panel: feed, destinations, cadence.

> [accordion] Example output
>
> ```json theme={null}
> {
>   "id": 19,
>   "name": "Competitor mentions — Slack",
>   "enabled": true,
>   "feedId": 42,
>   "feedName": "Competitor mentions",
>   "destinations": [
>     {
>       "type": "SLACK",
>       "frequency": "hourly",
>       "deliveryMode": "individual",
>       "slackDestination": {
>         "channels": "C0123ABC"
>       }
>     }
>   ],
>   "createdAt": "2026-06-01T09:30:00.000Z",
>   "updatedAt": "2026-07-14T16:05:00.000Z"
> }
> ```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens notifications list`

List your notifications (feed → destination delivery rules)

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--all` | `boolean` | no | Show the full collection (the default for this bounded list) |
| `--limit` | `integer` | no | Show only the first N items (mutually exclusive with --all) |

**Examples**

```bash theme={null}
octolens notifications list
octolens notifications list --json
octolens notifications list --limit 5
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/notifications`.

| Field | Type | Description |
| - | - | - |
| `data` | object\[] | Every notification of the workspace (bounded — no paging needed). |
| `data[].id` | integer | Notification id — what `notifications get/update/test/rm` accept. |
| `data[].name` | string | Display name, shown in the app and included in deliveries. |
| `data[].enabled` | boolean | When `false`, the notification is paused and nothing is delivered. |
| `data[].feedId` | integer | The feed whose filters decide which mentions trigger this notification. |
| `data[].feedName` | string \| null | Display name of the linked feed. |
| `data[].destinations` | object\[] | Delivery destinations (at most one per type). Same shape as a feed's `destinations`. |
| `data[].destinations[].type` | enum: `EMAIL`, `SLACK`, `WEBHOOK` | Delivery channel. The matching `emailDestination` / `slackDestination` / `webhookDestination` sub-object is populated. |
| `data[].destinations[].frequency` | enum: `hourly`, `hourlyAtTopOfHour`, `daily`, `weekly` | Delivery cadence. `daily`/`weekly` also carry `time` + `timezone` (and `dayOfWeek` for weekly). |
| `data[].createdAt` | string | Creation time, ISO 8601. |
| `data[].updatedAt` | string | Last update time, ISO 8601. |
| `pagination.nextCursor` | null | Always `null`: the whole notification set fits one response. |

Without `--json`: A terminal renders each notification with its destinations; piped stdout emits one tab-delimited record per notification.

> [accordion] Example output
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": 19,
>       "name": "Competitor mentions — Slack",
>       "enabled": true,
>       "feedId": 42,
>       "feedName": "Competitor mentions",
>       "destinations": [
>         {
>           "type": "SLACK",
>           "frequency": "hourly",
>           "deliveryMode": "individual",
>           "slackDestination": {
>             "channels": "C0123ABC"
>           }
>         }
>       ],
>       "createdAt": "2026-06-01T09:30:00.000Z",
>       "updatedAt": "2026-07-14T16:05:00.000Z"
>     }
>   ],
>   "pagination": {
>     "nextCursor": null
>   }
> }
> ```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens notifications rm`

Delete a notification by id (the feed is not affected)

**Arguments**

| Argument | Type | Required | Description |
| - | - | - | - |
| `ID` | `integer` | required | Numeric notification id (from `notifications list`) |

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--yes` | `boolean` | yes (headless) | Skip the confirmation prompt |

**Examples**

```bash theme={null}
octolens notifications rm 42 --yes
octolens notifications rm 42 --yes --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `DELETE /api/v2/notifications/{id}`.

| Field | Type | Description |
| - | - | - |
| `ok` | boolean | Always `true` — a failed deletion answers the error envelope instead. |
| `id` | integer | Id of the deleted notification. The linked feed is not affected. |

Without `--json`: A terminal prints one confirmation line.

Example output:

```json theme={null}
{
  "ok": true,
  "id": 19
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens notifications test`

Send a real test delivery to every destination and report the outcome

**Arguments**

| Argument | Type | Required | Description |
| - | - | - | - |
| `ID` | `integer` | required | Numeric notification id (from `notifications list`) |

**Examples**

```bash theme={null}
octolens notifications test 42
octolens notifications test 42 --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `POST /api/v2/notifications/{id}/test`.

| Field | Type | Description |
| - | - | - |
| `notificationId` | integer | The notification that was tested. |
| `results` | object\[] | One entry per configured destination, in stored order — a REAL delivery was attempted for each. |
| `results[].type` | enum: `EMAIL`, `SLACK`, `WEBHOOK` | Destination channel this result is for. |
| `results[].target` | string | The delivery target: email list, Slack channel ids, or webhook URL. |
| `results[].ok` | boolean | Whether the test delivery succeeded. |
| `results[].status` | integer \| null | HTTP status returned by the target (webhook deliveries only; `null` otherwise). |
| `results[].error` | string \| null | Failure detail when `ok` is `false`. |
| `mentions` | object\[] | The mentions that were delivered, newest first — the same set for every destination. |
| `mentions[].id` | integer | Numeric mention id. |
| `mentions[].source` | string | Platform the mention came from. |
| `mentions[].title` | string \| null | Mention title, when the source has one. |
| `mentions[].body` | string \| null | Mention text, truncated to 280 characters. |
| `mentions[].url` | string | Link to the original post. |
| `mentions[].author` | string \| null | Author handle. |
| `mentions[].timestamp` | string | When the mention was posted (UTC). |

Without `--json`: A terminal renders one line per destination with its outcome.

> [accordion] Example output
>
> ```json theme={null}
> {
>   "notificationId": 19,
>   "results": [
>     {
>       "type": "SLACK",
>       "target": "C0123ABC",
>       "ok": true,
>       "status": null,
>       "error": null
>     }
>   ],
>   "mentions": [
>     {
>       "id": 481516,
>       "source": "reddit",
>       "title": "Anyone using Acme for monitoring?",
>       "body": "We switched to Acme last month and…",
>       "url": "https://reddit.com/r/devops/comments/abc123",
>       "author": "devops_dana",
>       "timestamp": "2026-09-20 14:03:11"
>     }
>   ]
> }
> ```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens notifications update`

Update a notification (name, feed, enable/disable, destinations)

**Arguments**

| Argument | Type | Required | Description |
| - | - | - | - |
| `ID` | `integer` | required | Numeric notification id (from `notifications list`) |

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--day-of-week` | `integer` | no | 0 (Sunday)–6 (Saturday), required for --frequency weekly |
| `--delivery-mode` | `string` | no | batch = one digest per period; individual = one message per mention |
| `--destinations-json` | `string` | no | Full-fidelity destinations as a JSON array (for multiple destinations). Mutually exclusive with the ergonomic destination flags. |
| `--disable` | `boolean` | no | Pause delivery |
| `--email` | `string` | no | Recipient emails, comma-separated. Implies --type EMAIL |
| `--enable` | `boolean` | no | Resume delivery |
| `--feed` | `integer` | no | Re-point the notification at a different feed id |
| `--frequency` | `string` | no | Delivery cadence: hourly, hourlyAtTopOfHour, daily, weekly (create default: daily; on update, omit to keep the destination's current cadence) |
| `--name` | `string` | no | Replace the display name |
| `--slack` | `string` | no | Slack channel ids, comma-separated (e.g. C0123ABC,C0456DEF). Implies --type SLACK |
| `--time` | `string` | no | Wall-clock time for daily/weekly delivery, 24-hour HH:mm (00:00–23:59, e.g. 09:00) |
| `--timezone` | `string` | no | IANA timezone (e.g. Europe/Madrid) or UTC offset (e.g. UTC+2:00) paired with --time |
| `--type` | `string` | no | Destination type: EMAIL, SLACK, or WEBHOOK (inferred from the target flag if omitted) |
| `--webhook` | `string` | no | Webhook URL to POST matching mentions to. Implies --type WEBHOOK |

**Examples**

```bash theme={null}
octolens notifications update 42 --name "Renamed"
octolens notifications update 42 --disable
octolens notifications update 42 --webhook https://new.example.com/hook  # keeps the cadence
octolens notifications update 42 --type SLACK --frequency daily  # cadence only, keeps the channels
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `PATCH /api/v2/notifications/{id}`.

| Field | Type | Description |
| - | - | - |
| `id` | integer | Notification id — what `notifications get/update/test/rm` accept. |
| `name` | string | Display name, shown in the app and included in deliveries. |
| `enabled` | boolean | When `false`, the notification is paused and nothing is delivered. |
| `feedId` | integer | The feed whose filters decide which mentions trigger this notification. |
| `feedName` | string \| null | Display name of the linked feed. |
| `destinations` | object\[] | Delivery destinations (at most one per type). Same shape as a feed's `destinations`. |
| `destinations[].type` | enum: `EMAIL`, `SLACK`, `WEBHOOK` | Delivery channel. The matching `emailDestination` / `slackDestination` / `webhookDestination` sub-object is populated. |
| `destinations[].frequency` | enum: `hourly`, `hourlyAtTopOfHour`, `daily`, `weekly` | Delivery cadence. `daily`/`weekly` also carry `time` + `timezone` (and `dayOfWeek` for weekly). |
| `createdAt` | string | Creation time, ISO 8601. |
| `updatedAt` | string | Last update time, ISO 8601. |

Without `--json`: A terminal prints a confirmation line and the notification's detail panel after the update.

> [accordion] Example output
>
> ```json theme={null}
> {
>   "id": 19,
>   "name": "Competitor mentions — Slack",
>   "enabled": true,
>   "feedId": 42,
>   "feedName": "Competitor mentions",
>   "destinations": [
>     {
>       "type": "SLACK",
>       "frequency": "hourly",
>       "deliveryMode": "individual",
>       "slackDestination": {
>         "channels": "C0123ABC"
>       }
>     }
>   ],
>   "createdAt": "2026-06-01T09:30:00.000Z",
>   "updatedAt": "2026-07-14T16:05:00.000Z"
> }
> ```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens slack channels`

Search the workspace's Slack channels (feeds a notification's --slack)

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--all` | `boolean` | no | Drain every page (mutually exclusive with --limit) |
| `--limit` | `integer` | no | Return the first N channels (across pages) |
| `--search` (`-q`) | `string` | no | Case-insensitive substring match against channel name |

**Examples**

```bash theme={null}
octolens slack channels
octolens slack channels --search releases
octolens slack channels --all --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/integrations/slack/channels`.

| Field | Type | Description |
| - | - | - |
| `data` | object\[] | Channels matching the query. |
| `data[].id` | string | Slack channel id (e.g. `C0123ABC`) — what `--slack` flags accept. |
| `data[].name` | string | Channel name without the leading `#`. |
| `pagination.nextCursor` | string \| null | Opaque resume cursor. `null` when the listing is complete. |

Not connected is an ERROR (`SLACK_NOT_CONNECTED`, exit 2), never an empty list — an empty `data` unambiguously means connected-but-nothing-matched.

Without `--json`: A terminal renders the channel list; piped stdout emits one tab-delimited record per channel.

Example output:

```json theme={null}
{
  "data": [
    {
      "id": "C0123ABC",
      "name": "releases"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens slack connect`

Connect Slack via the browser OAuth flow, then wait for it to go live

**Flags**

| Flag | Type | Required (headless) | Description |
| - | - | - | - |
| `--no-browser` | `boolean` | no | Print the authorize URL instead of opening a browser (headless boxes) |
| `--onboarding` | `boolean` | no | Connect through a one-time link bound to this workspace (the `octolens onboard slack` hand-off): no browser sign-in needed, works over SSH. Under --json it answers at once with the link when none is live. |
| `--timeout` | `integer` | no | Seconds to wait for the browser OAuth flow to complete (default 120) — this command's own meaning for --timeout, not the global per-request budget. Expiry while unconnected exits 1 (SLACK\_CONNECT\_TIMEOUT). 0 = just open the URL and return without waiting (check with `slack status`). (default: `120`) |

**Examples**

```bash theme={null}
octolens slack connect
octolens slack connect --no-browser --timeout 0
octolens slack connect --timeout 300 --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/integrations/slack`.

| Field | Type | Description |
| - | - | - |
| `connected` | boolean | `true` only when the workspace has a Slack link AND the app is still installed. |
| `hasSlackIntegration` | boolean | Whether the workspace has ever linked a Slack account. |
| `isInstalled` | boolean | Whether the Slack app is currently installed in the linked workspace. |
| `teamName` | string \| null | The linked Slack workspace name, or `null` when not connected. |
| `hasNotificationSettings` | boolean | Whether any Slack notification channel configuration is saved. |
| `authorizeUrl` | string | The OAuth URL to open to (re)connect Slack. Absent when Slack was already connected at start. |

When Slack is already connected, the command answers the bare status (no `authorizeUrl`), identical to `slack status`. Otherwise it reports the OAuth URL plus the status after waiting up to `--timeout` seconds for the browser flow to complete (`--timeout 0` skips the wait).

Without `--json`: A terminal prints the OAuth URL, polls until connected or timed out, then renders the status.

Example output:

```json theme={null}
{
  "connected": false,
  "hasSlackIntegration": true,
  "isInstalled": false,
  "teamName": null,
  "hasNotificationSettings": true,
  "authorizeUrl": "https://app.octolens.com/api/slack/oauth/start"
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).

## `octolens slack status`

Show the workspace's Slack connection status

**Examples**

```bash theme={null}
octolens slack status
octolens slack status --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/integrations/slack`.

| Field | Type | Description |
| - | - | - |
| `connected` | boolean | `true` only when the workspace has a Slack link AND the app is still installed. |
| `hasSlackIntegration` | boolean | Whether the workspace has ever linked a Slack account. |
| `isInstalled` | boolean | Whether the Slack app is currently installed in the linked workspace. |
| `teamName` | string \| null | The linked Slack workspace name, or `null` when not connected. |
| `hasNotificationSettings` | boolean | Whether any Slack notification channel configuration is saved. |

Without `--json`: A terminal renders the connection status and linked workspace name.

Example output:

```json theme={null}
{
  "connected": true,
  "hasSlackIntegration": true,
  "isInstalled": true,
  "teamName": "Acme",
  "hasNotificationSettings": true
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.