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

npm install
npm run build
npm install -g .

After install, the telegram-brief command is available globally.

Authentication

Run first-time login:

telegram-brief auth login

Check status:

telegram-brief auth status --json

Reauthenticate when needed:

telegram-brief auth reauth

Credentials and session are stored at:

~/.config/telegram-brief/config.json

Search

Basic search:

telegram-brief search --query "deployment" --json

Date filtering:

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:

telegram-brief search --query "vendor" --group-ids "@group1,-1001234567890" --json

Performance tuning:

telegram-brief search --query "release" --concurrency-limit 5 --rate-limit-delay 500 --json

Message Context

Fetch replies to a specific matched message:

telegram-brief thread --group-id "-1001234567890" --message-id 42 --mode replies --limit 50 --json

Fetch parent-chain context for a reply (message -> parent -> root):

telegram-brief thread --group-id "-1001234567890" --message-id 314 --mode ancestors --max-depth 20 --json

List Chats

telegram-brief chats list --max-groups 100 --json

CLI Reference

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:

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