# Telegram Brief CLI
`telegram-brief` is a local executable for authenticating with Telegram and searching messages across your groups/channels.
It is built to pair with an OpenCode skill: the CLI returns structured JSON, and the skill handles summarization.
## Install
```bash
npm install
npm run build
npm install -g .
```
After install, the `telegram-brief` command is available globally.
## Authentication
Run first-time login:
```bash
telegram-brief auth login
```
Check status:
```bash
telegram-brief auth status --json
```
Reauthenticate when needed:
```bash
telegram-brief auth reauth
```
Credentials and session are stored at:
`~/.config/telegram-brief/config.json`
## Search
Basic search:
```bash
telegram-brief search --query "deployment" --json
```
Date filtering:
```bash
telegram-brief search --query "incident" --date-range last7days --json
telegram-brief search --query "meeting" --start-date "2026-02-01" --end-date "2026-02-07" --json
```
Targeted groups:
```bash
telegram-brief search --query "vendor" --group-ids "@group1,-1001234567890" --json
```
Performance tuning:
```bash
telegram-brief search --query "release" --concurrency-limit 5 --rate-limit-delay 500 --json
```
## Message Context
Fetch replies to a specific matched message:
```bash
telegram-brief thread --group-id "-1001234567890" --message-id 42 --mode replies --limit 50 --json
```
Fetch parent-chain context for a reply (message -> parent -> root):
```bash
telegram-brief thread --group-id "-1001234567890" --message-id 314 --mode ancestors --max-depth 20 --json
```
## List Chats
```bash
telegram-brief chats list --max-groups 100 --json
```
## CLI Reference
```bash
telegram-brief help
```
Key search flags:
- `--query` required
- `--limit`, `--offset`
- `--sort-by relevance|date_desc|date_asc`
- `--start-date`, `--end-date`, `--date-range`
- `--group-ids` comma-separated
- `--max-groups`
- `--include-channels true|false`
- `--include-archived-chats true|false`
- `--group-types channel,supergroup,gigagroup,basicgroup`
- `--concurrency-limit`, `--rate-limit-delay`
- `--include-extended-metadata true|false`
- `thread --group-id --message-id --mode replies|ancestors`
- `thread --offset-id --offset-date --add-offset --max-id --min-id`
- `thread --max-depth`
## JSON Error Contract
Commands run with `--json` return:
```json
{
"success": false,
"error": {
"code": "AUTH_REQUIRED",
"message": "Telegram is not configured...",
"retryable": true
}
}
```
Common codes:
- `AUTH_REQUIRED`
- `SESSION_REVOKED`
- `INVALID_INPUT`
- `SEARCH_FAILED`
- `RATE_LIMITED`
- `INTERNAL_ERROR`
## OpenCode Skill Integration
A starter skill spec is included at `docs/skills/telegram-digest-skill.md`.
It defines a workflow where OpenCode:
1. Runs `telegram-brief search --json`
2. Handles auth errors by guiding reauth
3. Summarizes results into organized sections
## License
MIT
