Skip to main content
A notification is a delivery rule attached to a feed: when new mentions match the feed’s filters, they are delivered to the destinations you configure — Slack, email, or a webhook. A feed carries at most one notification, and a notification carries at most one destination per type. The whole pipeline — feed → notification → test — works from the terminal, end to end. You need a saved feed first; octolens feeds list shows yours, and the Feeds reference covers creating one.
1

Connect Slack (once per workspace)

Slack is interactive, admin-gated OAuth, so it lives in the browser — the CLI does the hand-off and waits:
The authorize URL is always printed before the command blocks, so on a headless box you can open it anywhere; the wait is bounded and an expiry fails loudly rather than hanging. Already connected? It returns immediately. Check any time with:
Skip this step entirely for email or webhook destinations.
2

Find the channel id

Slack destinations take channel ids, not names — resolve them first:
octolens slack channelsFlagsWhen Slack is not connected this exits 2 (SLACK_NOT_CONNECTED) pointing at octolens slack connect — rather than answering an empty list — so a script piping the first id into the next step fails at the real cause.
3

Create the delivery rule

On a terminal with flags omitted, octolens notifications create runs a short wizard: name, destination (with a live Slack channel picker), feed, cadence. Headless runs spell everything out with flags:
Cadence is --frequency hourly|hourlyAtTopOfHour|daily|weekly (default daily), with --time/--timezone for daily digests and --day-of-week required for weekly ones. --delivery-mode picks one digest per period (batch) or one message per mention (individual). The schedule is deep-validated up front — a malformed --time, an unknown timezone or a weekly rule with no day exits 2 naming the flag, instead of persisting a schedule that never delivers.Two failures worth knowing by name: a feed that already has a notification exits 2 (ITEM_EXISTS, naming the conflicting notification id so you can update or remove it), and an unknown feed exits 4 (FEED_NOT_FOUND).octolens notifications createFlags
4

Prove it delivers

notifications test performs a real delivery of the latest matching mention to every destination and reports the per-destination outcome. Scheduled deliveries are untouched.
The exit code is the answer. Zero means every destination accepted the message — nothing less:On success the per-destination report is on stdout; on a failure the whole report moves into the error document on stderr (same fields, plus error), so you never lose the detail of which destination refused — read results[] from stdout on exit 0 and from stderr otherwise.octolens notifications testArguments

​
What Slack messages contain

Every card has the same structure; only the body text differs by source.
  • Long-form sources (LinkedIn, news, web pages, newsletters, podcast and YouTube descriptions, DEV and Medium articles) always show one sentence (at most about 280 characters) around the first whole monitored keyword, plus the relevance explanation — never the full source text. Markdown formatting scraped with the page (tables, headings, lists, bold) is flattened to plain text.
  • Every other source shows a post of up to about 280 characters in full, with the first whole monitored keyword in bold. A longer post becomes a bounded excerpt of about that length centered on that keyword, plus the relevance explanation.
Ellipses mark an excerpt as partial, and the matched keyword is the only emphasized text in the body. The relevance explanation appears beneath the body as smaller italic context without an extra label (it is omitted when there is none). If the keyword does not appear in the source text, the card shows its opening instead. On short cards, occurrences inside a link or URL, inline code or italic text are passed over in favour of the next one, and nothing is bolded if none is left. If the first occurrence is already bold in the post, the card keeps the author’s formatting and adds no other emphasis. Use See post to open the complete source.

​
Webhooks

A webhook destination POSTs matching mentions to a public http(s) endpoint — the escape hatch into everything Slack and email are not:
The URL is judged by what its host resolves to, not what it looks like: a host that is (or DNS-resolves to) a private, loopback or link-local address is refused with WEBHOOK_URL_INVALID (exit 2), and the same screen runs again at every delivery.

​
Living with it

  • Patch, don’t re-create. notifications update changes only what you pass — inside the destination you name, omitted fields are preserved, so fixing a webhook URL keeps its cadence:
  • Pause and resume with --disable / --enable; delete with octolens notifications rm 7 — like every deletion, headless runs require --yes or nothing is deleted.
  • Email destinations need no setup at all: --email a@acme.com,b@acme.com (the recipient list travels as one comma-separated value).
The full flag set, the multi-destination --destinations-json escape hatch and the update-preservation rules are on the Notifications reference.