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

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

Authentication

Run first-time login:

Check status:

Reauthenticate when needed:

Credentials and session are stored at:

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

Search

Basic search:

Date filtering:

Targeted groups:

Performance tuning:

Message Context

Fetch replies to a specific matched message:

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

List Chats

CLI Reference

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:

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