streamlens 0.1.0__tar.gz

streamlens-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+.DS_Store
+.idea/
+.vscode/
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# local runtime data: never commit
+*.db
+.env
+cookies.txt
+yt_cookies.txt
+channels.local.txt

streamlens-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First public release. A rewrite of the private Airflow + Postgres bot into a standalone library.
+
+- `Publisher` / `publish()`: one auto-updating Telegram message (new message first, then the old one is deleted)
+- Rich message with platform groups and per-stream slideshow "now / 5 / 10 / 15 / 20 min ago"; plain-text fallback
+- Local state in a single SQLite file: message ids, recent frames, viewer history (change over ~10 min)
+- CLI: `send` (JSON/CSV/stdin), `watch` (poll a channel list), `check`, `clear`, `--dry-run`
+- Sources for `watch`: YouTube and Kick via yt-dlp + ffmpeg, Twitch via public previews or the Helix API
+- Languages: `en`, `ru`

streamlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Voronko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamlens-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: streamlens
+Version: 0.1.0
+Summary: Live-stream tracker for Telegram: one auto-updating rich message with frames from YouTube, Twitch and Kick streams
+Project-URL: Homepage, https://github.com/klipbn/streamlens
+Project-URL: Issues, https://github.com/klipbn/streamlens/issues
+Project-URL: Changelog, https://github.com/klipbn/streamlens/blob/main/CHANGELOG.md
+Author: Alexey Voronko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot,kick,livestream,monitoring,telegram,twitch,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Requires-Dist: tzdata; platform_system == 'Windows'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: frames
+Requires-Dist: yt-dlp[default]>=2025.1.1; extra == 'frames'
+Description-Content-Type: text/markdown
+
+# streamlens
+
+[![PyPI](https://img.shields.io/pypi/v/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![Python](https://img.shields.io/pypi/pyversions/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![CI](https://img.shields.io/github/actions/workflow/status/klipbn/streamlens/ci.yml?style=flat-square&label=tests)](https://github.com/klipbn/streamlens/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+
+**Live streams in one Telegram message that keeps itself up to date.**
+Hand it a list of streams (or a list of channels) and a bot token; it posts who is live, how many viewers they have,
+how that changed, and a slideshow of frames from the last 20 minutes for each stream.
+
+- **No server, no database.** Pure Python; state is one small SQLite file.
+- **Bring your own data** (`Publisher.publish([...])`) **or let it watch channels** for you (`streamlens watch`).
+- **YouTube, Twitch, Kick** out of the box; any other platform if you pass the numbers yourself.
+- **Safe updates:** the new message is sent first, then the old one is deleted; a failed send never empties the chat.
+- English and Russian texts, time zone for the footer, size limits of Telegram handled for you.
+
+It grew out of a production Airflow + Postgres pipeline that tracks streams around the clock; this is the same
+message format, extracted into something you can `pip install`.
+
+## Quick start
+
+```bash
+pip install streamlens
+```
+
+You need a bot token from [@BotFather](https://t.me/BotFather) and a chat id. Add the bot to your group (or make it
+an admin of your channel) and check that it can post:
+
+```bash
+export STREAMLENS_TOKEN="123456:ABC..."
+export STREAMLENS_CHAT_ID="-1001234567890"   # group / channel id, or your own user id
+streamlens check
+```
+
+> How to find the chat id: add [@RawDataBot](https://t.me/RawDataBot) to the group, or open
+> `https://api.telegram.org/bot<TOKEN>/getUpdates` after writing anything to your bot.
+
+### 1. You have the data
+
+```python
+from streamlens import Publisher, Stream
+
+publisher = Publisher(token="123456:ABC...", chat_id="-1001234567890", lang="en", tz="Europe/Berlin")
+
+publisher.publish([
+    Stream(name="Some Twitch channel", url="https://www.twitch.tv/some_channel", online=12400),
+    Stream(name="Some YouTube channel", url="https://www.youtube.com/@some_channel/live", online=830,
+           title="Late night talk", image=open("frame.jpg", "rb").read()),
+])
+```
+
+Call `publish` every ~5 minutes (cron, Airflow, a loop). Only `name` and `url` are required; the platform is detected
+from the URL. Each call stores the frame you pass in `image`, so the slideshow *now / 5 / 10 / 15 / 20 min ago*
+builds up by itself. The change in viewers versus ~10 minutes ago is computed from the history the same way.
+
+From the shell, with a JSON or CSV file (or `-` for stdin):
+
+```bash
+streamlens send examples/streams.json
+cat streams.csv | streamlens send -          # columns: name,url,online[,title,image,started_at,...]
+streamlens send examples/streams.json --dry-run --chat-id 1   # print instead of sending
+```
+
+### 2. You only have channel links
+
+```bash
+pip install "streamlens[frames]"     # + ffmpeg on PATH, for YouTube/Kick frames
+streamlens watch examples/channels.txt --every 5
+```
+
+`channels.txt` is one URL per line (`Name | URL` to set a display name). Every 5 minutes it finds out who is live,
+grabs a frame and updates the message.
+
+| Platform | Live status | Viewers | Frame | Notes |
+|---|---|---|---|---|
+| YouTube | yt-dlp | yes | from the stream (ffmpeg) | use the channel `/live` URL |
+| Twitch | public preview | with a free [Twitch app](https://dev.twitch.tv/console): set `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET` | public preview | works without keys, just no viewer count |
+| Kick | yt-dlp | no (Kick has no public count) | from the stream (ffmpeg) | pass your own numbers via `Publisher` if you have them |
+
+Age-restricted YouTube streams need a `cookies.txt` of a YouTube account (`--cookies`); it is used only for those.
+
+## Options
+
+| Option (`Publisher(...)` / CLI flag) | Default | What it does |
+|---|---|---|
+| `lang` / `--lang` | `en` | `en` or `ru` |
+| `tz` / `--tz` | `UTC` | time zone of the "updated" footer, e.g. `Europe/Moscow` |
+| `mode` / `--mode` | `auto` | `rich` (frames), `text` (plain), `auto` = rich, falls back to text if the Bot API has no rich messages |
+| `split` / `--split` | one message | several messages, e.g. `--split twitch+kick --split youtube` |
+| `sort` / `--sort` | `asc` | `asc`: the biggest stream ends up at the bottom, next to the input field |
+| `min_online` / `--min-online` | `0` | hide small streams |
+| `exclude` / `--exclude` | none | names or URLs that are never shown |
+| `state` / `--state` | `./streamlens.db` | where message ids and frames are kept |
+
+`streamlens clear` deletes the messages the bot posted. `--dry-run` works everywhere and never touches Telegram.
+
+## Deploy
+
+Anything that runs a command every few minutes works. Pick one.
+
+**Long-running process (systemd, tmux, a VPS):** `streamlens watch channels.txt --every 5`
+
+**cron:** `*/5 * * * * streamlens watch /path/channels.txt --once` (env vars in the crontab or an env file)
+
+**Docker:**
+
+```bash
+cp examples/channels.txt channels.local.txt        # edit
+printf 'STREAMLENS_TOKEN=...\nSTREAMLENS_CHAT_ID=...\n' > .env
+docker compose up -d
+```
+
+The image contains ffmpeg and Node.js (the JS runtime that yt-dlp needs for YouTube). State lives in a volume.
+
+**Existing pipeline (Airflow, a script):** import `Publisher` and call `publish()` with your data on your schedule.
+
+## Telegram limits it handles for you
+
+- One rich message takes at most 50 pictures. With many streams the frames per stream go 5 → 4 → 3 → 2 → 1, and above
+  50 streams only the biggest ones get a frame.
+- Telegram clients fold long rich messages behind "Show more" after roughly 20 pictures in the visible part. This is a
+  client behaviour; no Bot API setting for it is documented. Measured on real messages: the fewer frames per stream, the more streams stay visible before the fold.
+- Bot tokens never appear in error messages or logs.
+
+## Development
+
+```bash
+git clone https://github.com/klipbn/streamlens && cd streamlens
+pip install -e ".[dev,frames]"
+pytest && ruff check .
+```
+
+MIT © Alexey Voronko. Russian version: [README.ru.md](README.ru.md).

streamlens-0.1.0/README.md

@@ -0,0 +1,134 @@
+# streamlens
+
+[![PyPI](https://img.shields.io/pypi/v/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![Python](https://img.shields.io/pypi/pyversions/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![CI](https://img.shields.io/github/actions/workflow/status/klipbn/streamlens/ci.yml?style=flat-square&label=tests)](https://github.com/klipbn/streamlens/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+
+**Live streams in one Telegram message that keeps itself up to date.**
+Hand it a list of streams (or a list of channels) and a bot token; it posts who is live, how many viewers they have,
+how that changed, and a slideshow of frames from the last 20 minutes for each stream.
+
+- **No server, no database.** Pure Python; state is one small SQLite file.
+- **Bring your own data** (`Publisher.publish([...])`) **or let it watch channels** for you (`streamlens watch`).
+- **YouTube, Twitch, Kick** out of the box; any other platform if you pass the numbers yourself.
+- **Safe updates:** the new message is sent first, then the old one is deleted; a failed send never empties the chat.
+- English and Russian texts, time zone for the footer, size limits of Telegram handled for you.
+
+It grew out of a production Airflow + Postgres pipeline that tracks streams around the clock; this is the same
+message format, extracted into something you can `pip install`.
+
+## Quick start
+
+```bash
+pip install streamlens
+```
+
+You need a bot token from [@BotFather](https://t.me/BotFather) and a chat id. Add the bot to your group (or make it
+an admin of your channel) and check that it can post:
+
+```bash
+export STREAMLENS_TOKEN="123456:ABC..."
+export STREAMLENS_CHAT_ID="-1001234567890"   # group / channel id, or your own user id
+streamlens check
+```
+
+> How to find the chat id: add [@RawDataBot](https://t.me/RawDataBot) to the group, or open
+> `https://api.telegram.org/bot<TOKEN>/getUpdates` after writing anything to your bot.
+
+### 1. You have the data
+
+```python
+from streamlens import Publisher, Stream
+
+publisher = Publisher(token="123456:ABC...", chat_id="-1001234567890", lang="en", tz="Europe/Berlin")
+
+publisher.publish([
+    Stream(name="Some Twitch channel", url="https://www.twitch.tv/some_channel", online=12400),
+    Stream(name="Some YouTube channel", url="https://www.youtube.com/@some_channel/live", online=830,
+           title="Late night talk", image=open("frame.jpg", "rb").read()),
+])
+```
+
+Call `publish` every ~5 minutes (cron, Airflow, a loop). Only `name` and `url` are required; the platform is detected
+from the URL. Each call stores the frame you pass in `image`, so the slideshow *now / 5 / 10 / 15 / 20 min ago*
+builds up by itself. The change in viewers versus ~10 minutes ago is computed from the history the same way.
+
+From the shell, with a JSON or CSV file (or `-` for stdin):
+
+```bash
+streamlens send examples/streams.json
+cat streams.csv | streamlens send -          # columns: name,url,online[,title,image,started_at,...]
+streamlens send examples/streams.json --dry-run --chat-id 1   # print instead of sending
+```
+
+### 2. You only have channel links
+
+```bash
+pip install "streamlens[frames]"     # + ffmpeg on PATH, for YouTube/Kick frames
+streamlens watch examples/channels.txt --every 5
+```
+
+`channels.txt` is one URL per line (`Name | URL` to set a display name). Every 5 minutes it finds out who is live,
+grabs a frame and updates the message.
+
+| Platform | Live status | Viewers | Frame | Notes |
+|---|---|---|---|---|
+| YouTube | yt-dlp | yes | from the stream (ffmpeg) | use the channel `/live` URL |
+| Twitch | public preview | with a free [Twitch app](https://dev.twitch.tv/console): set `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET` | public preview | works without keys, just no viewer count |
+| Kick | yt-dlp | no (Kick has no public count) | from the stream (ffmpeg) | pass your own numbers via `Publisher` if you have them |
+
+Age-restricted YouTube streams need a `cookies.txt` of a YouTube account (`--cookies`); it is used only for those.
+
+## Options
+
+| Option (`Publisher(...)` / CLI flag) | Default | What it does |
+|---|---|---|
+| `lang` / `--lang` | `en` | `en` or `ru` |
+| `tz` / `--tz` | `UTC` | time zone of the "updated" footer, e.g. `Europe/Moscow` |
+| `mode` / `--mode` | `auto` | `rich` (frames), `text` (plain), `auto` = rich, falls back to text if the Bot API has no rich messages |
+| `split` / `--split` | one message | several messages, e.g. `--split twitch+kick --split youtube` |
+| `sort` / `--sort` | `asc` | `asc`: the biggest stream ends up at the bottom, next to the input field |
+| `min_online` / `--min-online` | `0` | hide small streams |
+| `exclude` / `--exclude` | none | names or URLs that are never shown |
+| `state` / `--state` | `./streamlens.db` | where message ids and frames are kept |
+
+`streamlens clear` deletes the messages the bot posted. `--dry-run` works everywhere and never touches Telegram.
+
+## Deploy
+
+Anything that runs a command every few minutes works. Pick one.
+
+**Long-running process (systemd, tmux, a VPS):** `streamlens watch channels.txt --every 5`
+
+**cron:** `*/5 * * * * streamlens watch /path/channels.txt --once` (env vars in the crontab or an env file)
+
+**Docker:**
+
+```bash
+cp examples/channels.txt channels.local.txt        # edit
+printf 'STREAMLENS_TOKEN=...\nSTREAMLENS_CHAT_ID=...\n' > .env
+docker compose up -d
+```
+
+The image contains ffmpeg and Node.js (the JS runtime that yt-dlp needs for YouTube). State lives in a volume.
+
+**Existing pipeline (Airflow, a script):** import `Publisher` and call `publish()` with your data on your schedule.
+
+## Telegram limits it handles for you
+
+- One rich message takes at most 50 pictures. With many streams the frames per stream go 5 → 4 → 3 → 2 → 1, and above
+  50 streams only the biggest ones get a frame.
+- Telegram clients fold long rich messages behind "Show more" after roughly 20 pictures in the visible part. This is a
+  client behaviour; no Bot API setting for it is documented. Measured on real messages: the fewer frames per stream, the more streams stay visible before the fold.
+- Bot tokens never appear in error messages or logs.
+
+## Development
+
+```bash
+git clone https://github.com/klipbn/streamlens && cd streamlens
+pip install -e ".[dev,frames]"
+pytest && ruff check .
+```
+
+MIT © Alexey Voronko. Russian version: [README.ru.md](README.ru.md).

streamlens-0.1.0/examples/channels.txt

@@ -0,0 +1,5 @@
+# One channel per line. Optional display name before the pipe.
+# YouTube: use the channel's /live URL. Twitch and Kick: the channel URL.
+https://www.twitch.tv/twitch
+Lofi Girl | https://www.youtube.com/@LofiGirl/live
+https://kick.com/xqc

streamlens-0.1.0/examples/send_streams.py

@@ -0,0 +1,20 @@
+"""Publish your own data: the library does not care where the numbers come from (an API, a database, a CSV)."""
+import os
+
+from streamlens import Publisher, Stream
+
+publisher = Publisher(
+    token=os.environ["STREAMLENS_TOKEN"],
+    chat_id=os.environ["STREAMLENS_CHAT_ID"],
+    lang="en",
+    tz="Europe/Berlin",
+)
+
+streams = [
+    Stream(name="Some Twitch channel", url="https://www.twitch.tv/some_channel", online=12400),
+    Stream(name="Some YouTube channel", url="https://www.youtube.com/@some_channel/live", online=830,
+           title="Late night talk"),
+]
+
+# Call this every ~5 minutes (cron, Airflow, a while-loop...). The previous message is replaced each time.
+publisher.publish(streams)

streamlens-0.1.0/examples/streams.json

@@ -0,0 +1,5 @@
+[
+  {"name": "Some Twitch channel", "url": "https://www.twitch.tv/some_channel", "online": 12400, "title": "Ranked grind"},
+  {"name": "Some YouTube channel", "url": "https://www.youtube.com/@some_channel/live", "online": 830},
+  {"name": "Some Kick channel", "url": "https://kick.com/some_channel", "online": 95, "started_at": "2026-09-20T09:30:00Z"}
+]

streamlens-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "streamlens"
+version = "0.1.0"
+description = "Live-stream tracker for Telegram: one auto-updating rich message with frames from YouTube, Twitch and Kick streams"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alexey Voronko" }]
+keywords = ["telegram", "bot", "livestream", "twitch", "youtube", "kick", "monitoring"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Chat",
+  "Topic :: Multimedia :: Video",
+]
+dependencies = [
+  "requests>=2.25",
+  "tzdata; platform_system == 'Windows'",
+]
+
+[project.optional-dependencies]
+# Grab frames / viewer counts from YouTube and Kick (also needs ffmpeg on PATH)
+frames = ["yt-dlp[default]>=2025.1.1"]
+dev = ["pytest>=7", "ruff>=0.5", "build", "twine"]
+
+[project.scripts]
+streamlens = "streamlens.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/klipbn/streamlens"
+Issues = "https://github.com/klipbn/streamlens/issues"
+Changelog = "https://github.com/klipbn/streamlens/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/streamlens"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["UP006", "UP007", "UP035", "UP045"]  # keep typing compatible with 3.9 style

streamlens-0.1.0/src/streamlens/__init__.py

@@ -0,0 +1,12 @@
+"""streamlens: live streams in one auto-updating Telegram message."""
+from .message import build_rich_message, build_text_message
+from .models import Stream, detect_platform
+from .publisher import Publisher, publish
+from .telegram import TelegramClient, TelegramError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Stream", "Publisher", "publish", "detect_platform", "build_rich_message", "build_text_message",
+    "TelegramClient", "TelegramError", "__version__",
+]

streamlens-0.1.0/src/streamlens/cli.py

@@ -0,0 +1,193 @@
+"""Command line: ``streamlens send | watch | check | clear``."""
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime as dt
+import io
+import json
+import os
+import sys
+import time
+from typing import List, Optional
+from urllib.request import urlopen
+
+from . import __version__
+from .models import Stream
+from .publisher import Publisher
+from .sources import MissingDependency, TwitchApi, parse_channels, probe_channels
+from .telegram import TelegramClient, TelegramError
+
+ENV_TOKEN = ("STREAMLENS_TOKEN", "TELEGRAM_BOT_TOKEN")
+ENV_CHAT = ("STREAMLENS_CHAT_ID", "TELEGRAM_CHAT_ID")
+
+
+def _env(names) -> Optional[str]:
+    return next((os.environ[n] for n in names if os.environ.get(n)), None)
+
+
+def _load_image(value: Optional[str], base_dir: str) -> Optional[bytes]:
+    if not value:
+        return None
+    if value.startswith(("http://", "https://")):
+        with urlopen(value, timeout=20) as r:  # noqa: S310 (a URL that the user gave)
+            return r.read()
+    path = value if os.path.isabs(value) else os.path.join(base_dir, value)
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def _num(value) -> Optional[int]:
+    return None if value in (None, "") else int(float(value))
+
+
+def load_streams(path: str) -> List[Stream]:
+    """Reads a JSON list or a CSV (header: name,url,online,...) from a file or stdin (``-``).
+
+    Columns / keys: name, url, online, platform, title, started_at (ISO 8601), watch_url, online_diff,
+    image (a file path or an http(s) URL)."""
+    text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
+    base_dir = "." if path == "-" else os.path.dirname(os.path.abspath(path))
+    if text.lstrip().startswith(("[", "{")):
+        data = json.loads(text)
+        rows = data["streams"] if isinstance(data, dict) else data
+    else:
+        rows = list(csv.DictReader(io.StringIO(text)))
+
+    streams = []
+    for row in rows:
+        started = row.get("started_at")
+        streams.append(Stream(
+            name=row["name"], url=row["url"], online=_num(row.get("online")), platform=row.get("platform") or None,
+            online_diff=_num(row.get("online_diff")), title=row.get("title") or None,
+            watch_url=row.get("watch_url") or None,
+            started_at=dt.datetime.fromisoformat(started.replace("Z", "+00:00")) if started else None,
+            image=_load_image(row.get("image"), base_dir)))
+    return streams
+
+
+def _publisher(args) -> Publisher:
+    token, chat_id = args.token or _env(ENV_TOKEN), args.chat_id or _env(ENV_CHAT)
+    if not args.dry_run and not token:
+        sys.exit("Bot token is missing: --token or STREAMLENS_TOKEN (get one from @BotFather)")
+    if not chat_id:
+        sys.exit("Chat is missing: --chat-id or STREAMLENS_CHAT_ID")
+    split = [g.split("+") for g in args.split] if args.split else None
+    return Publisher(token, chat_id, state=args.state, lang=args.lang, tz=args.tz, mode=args.mode, split=split,
+                     sort=args.sort, min_online=args.min_online, exclude=args.exclude or (),
+                     empty_message=not args.no_empty_message, dry_run=args.dry_run)
+
+
+def cmd_send(args) -> None:
+    pub = _publisher(args)
+    streams = load_streams(args.file)
+    ids = pub.publish(streams)
+    print(f"streams: {len(streams)}, messages sent: {len(ids)}")
+
+
+def cmd_watch(args) -> None:
+    pub = _publisher(args)
+    with open(args.channels, encoding="utf-8") as f:
+        channels = parse_channels(f.read())
+    if not channels:
+        sys.exit(f"{args.channels}: no channels found")
+    twitch_id, twitch_secret = os.environ.get("TWITCH_CLIENT_ID"), os.environ.get("TWITCH_CLIENT_SECRET")
+    twitch = TwitchApi(twitch_id, twitch_secret) if twitch_id and twitch_secret else None
+    if not twitch and any("twitch.tv" in c["url"] for c in channels):
+        print("note: no TWITCH_CLIENT_ID / TWITCH_CLIENT_SECRET, so Twitch viewers are unknown (frames still work)")
+
+    while True:
+        started = time.monotonic()
+        try:
+            streams = probe_channels(channels, twitch=twitch, cookies_file=args.cookies)
+            ids = pub.publish(streams)
+            print(f"{dt.datetime.now():%Y-%m-%d %H:%M:%S} live: {len(streams)} of {len(channels)}, "
+                  f"messages sent: {len(ids)}", flush=True)
+        except (MissingDependency, ValueError):
+            raise
+        except TelegramError as e:
+            print(f"telegram error: {e}", file=sys.stderr, flush=True)
+        if args.once:
+            return
+        time.sleep(max(1, args.every * 60 - (time.monotonic() - started)))
+
+
+def cmd_check(args) -> None:
+    token, chat_id = args.token or _env(ENV_TOKEN), args.chat_id or _env(ENV_CHAT)
+    if not token or not chat_id:
+        sys.exit("Need --token and --chat-id (or STREAMLENS_TOKEN / STREAMLENS_CHAT_ID)")
+    client = TelegramClient(token)
+    try:
+        me = client.get_me()
+        print(f"token ok: @{me.get('username')}")
+        msg = client.send_text(chat_id, "✅ streamlens: the bot can post here")
+        client.delete(chat_id, msg["message_id"])
+        print(f"chat {chat_id} ok: test message sent and removed")
+    except TelegramError as e:
+        sys.exit(f"failed: {e}")
+
+
+def cmd_clear(args) -> None:
+    pub = _publisher(args)
+    print(f"deleted messages: {pub.clear()}")
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--token", help="bot token (or env STREAMLENS_TOKEN)")
+    p.add_argument("--chat-id", help="chat / channel / user id (or env STREAMLENS_CHAT_ID)")
+    p.add_argument("--state", default=os.environ.get("STREAMLENS_STATE", "streamlens.db"),
+                   help="SQLite file with message ids and frames (default: ./streamlens.db)")
+    p.add_argument("--lang", default="en", choices=("en", "ru"))
+    p.add_argument("--tz", default="UTC", help="time zone of the footer, e.g. Europe/Moscow")
+    p.add_argument("--mode", default="auto", choices=("auto", "rich", "text"),
+                   help="rich = message with frames, text = plain text, auto = rich with a text fallback")
+    p.add_argument("--split", action="append", metavar="PLATFORMS",
+                   help="separate message for these platforms, e.g. --split twitch+kick --split youtube")
+    p.add_argument("--sort", default="asc", choices=("asc", "desc"), help="asc: the biggest stream is at the bottom")
+    p.add_argument("--min-online", type=int, default=0, help="hide streams with fewer viewers")
+    p.add_argument("--exclude", action="append", metavar="NAME_OR_URL", help="never show this stream (repeatable)")
+    p.add_argument("--no-empty-message", action="store_true", help="do not post 'nobody is live'")
+    p.add_argument("--dry-run", action="store_true", help="print the message instead of sending it")
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(prog="streamlens", description="Live streams in one Telegram message.")
+    parser.add_argument("--version", action="version", version=f"streamlens {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("send", help="publish streams from a JSON/CSV file (or - for stdin)")
+    p.add_argument("file")
+    _add_common(p)
+    p.set_defaults(func=cmd_send)
+
+    p = sub.add_parser("watch", help="check a list of channels every N minutes and publish who is live")
+    p.add_argument("channels", help="text file: one channel URL per line, optionally 'Name | URL'")
+    p.add_argument("--every", type=float, default=5, help="minutes between updates (default 5)")
+    p.add_argument("--once", action="store_true", help="run one update and exit (for cron)")
+    p.add_argument("--cookies", default=os.environ.get("STREAMLENS_YT_COOKIES"),
+                   help="YouTube cookies.txt, used only for age-restricted streams")
+    _add_common(p)
+    p.set_defaults(func=cmd_watch)
+
+    p = sub.add_parser("check", help="verify the token and that the bot can post to the chat")
+    p.add_argument("--token")
+    p.add_argument("--chat-id")
+    p.set_defaults(func=cmd_check)
+
+    p = sub.add_parser("clear", help="delete the messages posted by the bot (from the local state)")
+    _add_common(p)
+    p.set_defaults(func=cmd_clear)
+
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except MissingDependency as e:
+        sys.exit(str(e))
+    except TelegramError as e:
+        sys.exit(f"telegram error: {e}")
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()