Quick Start#

From zero to your first search in five commands. This assumes tgs is already installed — if not, see Installation.

1. Authenticate#

The default login imports your existing session from Telegram Desktop — no phone number or code required:

tgs login

Other methods (phone + code, QR, a non-interactive flow for AI agents) are covered in Authentication.

tgs whoami

Returns the active account as JSON — your ID, name, and username.

See every dialog in your account — channels, groups, users, bots:

tgs sources list

Add --type channel to filter by kind, or --with-stats for message counts. See Sources.

tgs search messages "release" -c @durov

-c accepts a username, t.me link, phone number, or numeric ID. Narrow results with --from, --filter, and --after / --before.

Not sure which chat? Search all of them at once:

tgs search global "meeting notes"

That’s the core loop. Every command outputs JSON — pipe it into jq or hand it to an AI agent. Go deeper in the Search guide.