Notifications

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

`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

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.

Example output

{
  "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.

`octolens notifications get`

Get a single notification by id Arguments

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

Examples

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.

Example output

{
  "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.

`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

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.

Example output

{
  "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.

`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

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:

{
  "ok": true,
  "id": 19
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on 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

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:

{
  "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.

`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

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.

Example output

{
  "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.

`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

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:

{
  "data": [
    {
      "id": "C0123ABC",
      "name": "releases"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on 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

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:

{
  "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.

`octolens slack status`

Show the workspace’s Slack connection status Examples

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:

{
  "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.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

`octolens notifications create`

`octolens notifications get`

`octolens notifications list`

`octolens notifications rm`

`octolens notifications test`

`octolens notifications update`

`octolens slack channels`

`octolens slack connect`

`octolens slack status`

​octolens notifications create

​octolens notifications get

​octolens notifications list

​octolens notifications rm

​octolens notifications test

​octolens notifications update

​octolens slack channels

​octolens slack connect

​octolens slack status

`octolens notifications create`

`octolens notifications get`

`octolens notifications list`

`octolens notifications rm`

`octolens notifications test`

`octolens notifications update`

`octolens slack channels`

`octolens slack connect`

`octolens slack status`