# 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