Guide on tgs

Profiles

Mon, 01 Jan 0001 00:00:00 +0000

Profiles#

tgs supports multiple Telegram accounts through profiles — similar to how AWS CLI handles credentials. Each profile has its own independent session stored in a separate database file.

How Profile Resolution Works#

When you run any tgs command, the active profile is determined by this priority chain (highest wins):

--profile flag passed to the command
TGS_PROFILE environment variable
.tgs.yaml file in the current directory or any parent directory
"default" (fallback)

Per-Directory Profiles#

You can bind a profile to a directory by creating a .tgs.yaml file. Use tgs profile switch to do this automatically:

Search

Mon, 01 Jan 0001 00:00:00 +0000

Search#

tgs provides four search subcommands that map directly to Telegram’s MTProto search methods. All output is JSON, making it straightforward to pipe into jq, feed to an AI agent, or process programmatically.

Searching in a Chat#

The most common operation: search for messages within a specific chat.

tgs search messages "docker compose" -c @devops_notes

The query argument is required. The -c / --chat flag specifies which chat to search. See Chat Resolution below for all supported formats.

Sources

Mon, 01 Jan 0001 00:00:00 +0000

Sources#

tgs sources lets you enumerate and inspect the Telegram dialogs in your account — channels, supergroups, groups, users, and bots. All output is JSON, ready to pipe into jq or feed to an AI agent.

Piping to jq: tgs writes diagnostic logs ([tgs] retry: …, [tgs] FLOOD_WAIT: …) to stderr and JSON to stdout. When piping into jq, drop stderr to keep the parser happy:
tgs sources list --with-stats 2>/dev/null | jq '.sources[].title'
Avoid 2>&1 | jq … — that mixes log lines into stdout and breaks JSON parsing.