telefire

name	telefire
description	Use when the user asks to interact with Telegram or Matrix through the TeleFire CLI — listing chats or rooms, resolving account info, searching messages, fetching history, deleting messages, monitoring keywords, or running Matrix room commands

Telefire

TeleFire is a CLI for Telegram and Matrix automation.

Current baseline:

• Python 3.14+
• Telegram on Telethon
• Matrix on mautrix
• default-first config in ~/.telefire/config.toml

Install options:

• repo-local: uv run telefire ...
• one-shot: uvx telefire ...
• global install: uv tool install telefire or pipx install telefire

Run pattern:

• telefire telegram <command> [args...]
• telefire matrix <command> [args...]
• telefire init

Current CLI Rules

• Protocol commands are grouped:
  • telefire telegram ...
  • telefire matrix ...
• init stays top-level.
• Required args can be positional or flags. Always trust the relevant --help output.
• The old "all arguments must use named flags" rule is no longer valid.
• Prefer --account for Telegram and Matrix.
• Telegram also accepts --session as an explicit session-file override.
• Default Telegram session name is telefire.
• telefire init updates the default accounts only. Optional named accounts are manual config.

Setup Checklist

Before running TeleFire commands, verify the runtime state:

1. Check config:

cat ~/.telefire/config.toml

Minimum Telegram config:

• [telegram] with api_id and api_hash
• optional session_name

Minimum Matrix config:

• [matrix] with base_url and user_id
• optional device_name
• and either a password for first-run bootstrap, or an existing session file under ~/.telefire/matrix/default/session.json

2. Check the selected Telegram session file:

ls ~/.telefire/telegram/telefire.session

For other accounts, pass --account=<name> — it resolves the session name automatically.

3. Validate the selected Telegram session:

uv run telefire telegram get_entity me
uv run telefire telegram get_entity me --session=work

4. Validate a Matrix account:

uv run telefire matrix whoami

If the Matrix account only has a password configured, the first successful run will bootstrap and persist a session token under ~/.telefire/matrix/<account>/.

5. If needed, inspect the Matrix account store directly:

find ~/.telefire/matrix -maxdepth 2 -type f | sort

6. If a Telegram session is invalid, remove the selected session files and re-authenticate:

rm ~/.telefire/telegram/<session>.session*

Then rerun a Telegram command and complete the login flow.

Cache Account and Room Data

On first use (or when stale), snapshot account details and room/chat lists so later requests can skip the API call:

# Telegram — cache identity and chat list
uv run telefire telegram get_entity me
uv run telefire telegram get_all_chats

# Matrix — cache identity and room list
uv run telefire matrix whoami
uv run telefire matrix list_rooms

Save the output to a scratch file or memory so you can resolve chat/room names to IDs without re-running these commands each time the user asks about a specific chat.

Config Model

Focus on the default account first. Default fields live directly under [telegram] / [matrix].

[telegram]
api_id = 1094995
api_hash = "..."
session_name = "telefire"
store_dir = "/home/you/.telefire/telegram"

[matrix]
base_url = "https://matrix.example.com"
user_id = "@you:example.com"
device_name = "telefire"
store_dir = "/home/you/.telefire/matrix/default"
password = "..."

Optional extra accounts can be added manually:

[telegram.work]
session_name = "work"

[matrix.work]
base_url = "https://matrix.work.example"
user_id = "@you:work.example"
store_dir = "/home/you/.telefire/matrix/work"
password = "..."

Telegram storage:

• ~/.telefire/telegram/telefire.session
• ~/.telefire/telegram/work.session

Matrix storage:

• ~/.telefire/matrix/default/session.json
• ~/.telefire/matrix/default/sync_store.json
• ~/.telefire/matrix/default/state_store.bin

Matrix accounts are account-scoped by directory, unlike Telegram where multiple accounts usually share one store dir and differ by session filename.

Discovery

Run --help at any level:

uv run telefire --help
uv run telefire telegram --help
uv run telefire matrix --help
uv run telefire telegram COMMAND --help

Quick Reference

Telegram One-Shot Commands

Command	Key Args	Purpose
get_all_chats		List all chats with IDs
get_entity	ENTITY	Resolve user/chat info (me, username, or chat)
find_user	CHAT NAME [--limit=500]	Find username/ID from display name
search_messages	CHAT QUERY [--user=X] [--slow=True] [--limit=100] [--before=DATE] [--after=DATE]	Search messages. --slow=True for Chinese text
list_messages	CHAT [--user=X] [--print_stat=True] [--before=DATE] [--after=DATE]	List messages. --print_stat for hourly distribution
get_messages_by_ids	CHAT --ids=ID1,ID2	Fetch specific messages by ID
summary_messages	CHAT [--user=X] [--limit=10]	Recent messages from user
list_deleted_user_messages	CHAT	Messages from deleted accounts
delete_all	CHAT [--before=DATE] [--after=DATE] [--query=X]	Delete own messages (irreversible, no dry-run)
chat_count	CHAT [--user=X]	Message count statistics
regex_messages	CHAT REGEX	Filter messages by regex

Matrix Commands

Command	Key Args	Purpose
whoami		Show current Matrix identity
list_rooms		List joined rooms

All Telegram commands accept --account=X and --session=X. All Matrix commands accept --account=X.

Useful Telegram Workflows

List chats:

uv run telefire telegram get_all_chats

Resolve an entity:

uv run telefire telegram get_entity me
uv run telefire telegram get_entity username_or_chat

Search messages:

uv run telefire telegram search_messages --chat=coder_ot --query='keyword'
uv run telefire telegram search_messages --chat=coder_ot --query='中文' --slow=True

List messages from a specific user:

uv run telefire telegram list_messages --chat=coder_ot --user=Fangliding --print_stat=True

Delete your own messages:

uv run telefire telegram list_messages --chat=chat-name --user=your-username
uv run telefire telegram delete_all --chat=chat-name --before='2024-01-01'

Useful Matrix Workflows

List rooms:

uv run telefire matrix list_rooms

Notes

• --user requires username or numeric ID — display names fail with ValueError. Use find_user to resolve.
• search_messages --slow=True is the safer choice for Chinese text (server-side search performs poorly with CJK).
• delete_all is irreversible with no dry-run. Always preview with list_messages first.
• --before and --after accept flexible date strings parsed by dateutil (e.g. 2024-01-01, last week).
• Use the default account as the normal path. Reach for --account only when you actually need another account.
• Use --session only for raw Telegram session-file overrides.
• Plugins that need storage accept --db=PATH for custom SQLite path (defaults to ~/.telefire/data.db).