Quickstart¶
Five commands to feel out the surface.
1. Sync a fast view of your dialogs¶
Pulls every chat you have access to (DMs, groups, channels) into the local SQLite cache. Just metadata — names, types, ids — not messages. Fast.
2. Populate the entity cache¶
This stores Telegram access hashes in accounts/default/telegram.sqlite
so chat-id-keyed writes work without resolving a username first.
3. Pull recent messages¶
Pulls recent messages from your own chat into local SQLite. Use your
own user_id for Saved Messages, or replace it with another
<your-chat-id>.
For media:
Adds photos / voice notes / video / document files into
accounts/default/media/<chat_id>/.
4. Search what you've cached¶
Substring search across cached message text. Returns a JSON envelope with hits, chat ids, dates, and message ids.
5. Send a message¶
The --allow-write flag is required for any message that hits
Telegram. Without it the command exits with a clear error — this is
the write gate.
For multi-line text:
What now?¶
- Browse the full command reference
- Pipe JSON envelopes from Library use
- Read the safety model before sending or deleting at scale
- Set up multi-account if you have a personal + business split
Agent-ready first run¶
Use an isolated account name while testing agents. accounts-add is a
command; --account test is the global flag that selects that account.
tg accounts-add test
tg --account test login
tg --account test me
tg --account test backfill-entities
tg --account test discover --allow-write
tg --account test stats
tg --account test send 1240314255 "hello from test account" --allow-write --json
If login fails with TG_API_ID and TG_API_HASH must be set, run the
command from the directory containing .env, or export the variables.
See Install.
For agents, keep --account test explicit instead of switching the
default account. That makes every subprocess call self-contained.