> ## 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](/docs/cli/contract/global-flags). 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](/docs/cli/contract/error-envelope).

## `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 title="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"
  }
  ```
</Accordion>

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

## `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 title="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"
  }
  ```
</Accordion>

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

## `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 title="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
    }
  }
  ```
</Accordion>

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

## `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](/docs/cli/contract/exit-codes).

## `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`.                                                            |

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

Example output:

```json theme={null}
{
  "notificationId": 19,
  "results": [
    {
      "type": "SLACK",
      "target": "C0123ABC",
      "ok": true,
      "status": null,
      "error": null
    }
  ]
}
```

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

## `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 title="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"
  }
  ```
</Accordion>

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

## `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](/docs/cli/contract/exit-codes).

## `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)                                                                                                                                                                                                                                          |
| `--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. The full map is on [Exit codes](/docs/cli/contract/exit-codes).

## `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](/docs/cli/contract/exit-codes).