Introduction on tgs

Installation

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

Installation#

tgs ships as a single static binary with no runtime dependencies. Pick whichever method fits your platform — the installed command is always tgs.

Homebrew (macOS & Linux)#

The quickest way on macOS and Linux:

brew install garenal1v3/tap/tgs-cli

This installs the tgs binary and keeps it up to date via brew upgrade.

Prebuilt binaries#

Grab a release archive for your platform from the releases page. Archives are named tgs-cli_<os>_<arch>:

Platform	OS	Arch
macOS (Apple Silicon)	`darwin`	`arm64`
macOS (Intel)	`darwin`	`amd64`
Linux	`linux`	`amd64` / `arm64`
Windows	`windows`	`amd64` / `arm64`

macOS & Linux#

# Choose your platform: OS = darwin (macOS) or linux; ARCH = arm64 or amd64
OS=darwin
ARCH=arm64

curl -L -o tgs.tar.gz \
 "https://github.com/garenal1v3/tgs-cli/releases/latest/download/tgs-cli_${OS}_${ARCH}.tar.gz"
tar -xzf tgs.tar.gz tgs
sudo mv tgs /usr/local/bin/
tgs version

Windows#

# PowerShell — ARCH = amd64 or arm64
$Arch = "amd64"
Invoke-WebRequest `
 -Uri "https://github.com/garenal1v3/tgs-cli/releases/latest/download/tgs-cli_windows_$Arch.zip" `
 -OutFile tgs.zip
Expand-Archive tgs.zip -DestinationPath .
# Move tgs.exe into a directory on your PATH, then:
.\tgs.exe version

Build from source#

Requires Go 1.26 or newer:

Quick Start

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

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.

2. Confirm who you are#

tgs whoami

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

Authentication

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

Authentication#

tgs connects to Telegram through your real user account via MTProto. You need to authenticate once per profile — the session is saved locally and reused on subsequent commands.

Quick Start#

The default method imports your existing session from Telegram Desktop:

tgs login

Or choose a different method:

tgs login --type code # Phone number + SMS/Telegram code
tgs login --type qr # Scan QR code from another device

Desktop Import (default)#

Imports your existing session from Telegram Desktop. tgs auto-detects the tdata directory on macOS, Linux, and Windows.

tgs login

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

Authenticate with Telegram. The session is saved locally and reused by all subsequent commands.

Synopsis#

tgs login [flags]

Flags#

Flag	Short	Default	Description
`--type`	`-T`	`desktop`	Auth method: `desktop`, `code`, or `qr`
`--desktop-dir`	`-d`	(auto-detect)	Path to Telegram Desktop tdata directory
`--passcode`			Telegram Desktop local passcode
`--phone`			Phone number for `code` method
`--code`			Verification code (for non-interactive login)
`--password`			2FA cloud password
`--profile`	`-p`	(resolved)	Profile name to authenticate into

Profile resolution order when --profile is not set: TGS_PROFILE env → .tgs.yaml file → "default".

tgs profile

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

tgs profile#

Manage account profiles.

Synopsis#

tgs profile <subcommand> [flags]

Subcommands#

tgs profile list#

List all profiles with their associated account information.

tgs profile list [flags]

Flag	Short	Default	Description
`--output`	`-o`	`json`	Output format: `json`, `text`

tgs profile list
tgs profile list --output text

* default (@myuser)
 work (@workuser)

JSON (default):

[
 {"name":"default","phone":"+79001234567","username":"alice","id":261054642,"active":true},
 {"name":"work","phone":"+79001230000","username":"alice_work","id":342178890,"active":false}
]

Text (--output text):

* default (@alice)
 work (@alice_work)

The active profile is marked with * in text mode, and "active": true in JSON. If neither username nor phone is cached, the profile name alone is shown.

tgs search messages

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

tgs search messages#

Search messages within one or more chats, channels, or groups.

Usage#

tgs search messages [query] [flags]

The query argument is required and specifies the text to search for.

Flags#

Flag	Short	Type	Default	Description
`--chat`	`-c`	string[]		Chat to search (username, phone, ID; repeatable, comma-separated). Required unless `--folder` is set.
`--folder`		string	`""`	Search all chats inside this folder (id or name); peers are additive to any `--chat` values
`--from`	`-f`	string		Filter by sender (username, phone, or ID)
`--filter`		string		Message type filter (see filter values)
`--after`		string		Only messages after date (YYYY-MM-DD or unix timestamp)
`--before`		string		Only messages before date (YYYY-MM-DD or unix timestamp)
`--topic`		int	`0`	Forum topic ID
`--limit`	`-l`	int	`50`	Max messages to return (1-100)
`--cursor`		string		Pagination cursor from previous response
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer resolution cache
`--include-comments`		bool	`false`	Also search the linked discussion group of each channel
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

tgs sources list

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

tgs sources list#

Enumerate all Telegram dialogs in your account — channels, supergroups, groups, users, and bots.

Usage#

tgs sources list [flags]

Flags#

Flag	Short	Type	Default	Description
`--type`		string[]	(all)	Filter by type: `channel`, `supergroup`, `group`, `user`, `bot` (repeatable, comma-separated)
`--with-stats`		bool	`false`	Fetch expensive metrics (total/24h/first messages + full info) for every returned source
`--limit`	`-l`	int	`0`	Max records to return (1-500, 0=all)
`--cursor`		string		Pagination cursor from previous response
`--folder`		string	`""`	Filter to chats inside this folder (id or name), archived chats included; incompatible with `--cursor`
`--archived`		bool	`false`	Include archived dialogs (ignored when `--folder` is set — a folder already includes its archived chats)
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer and stats caches
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

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:

tgs logout

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

tgs logout#

Revoke the current session on Telegram servers and clear local session data.

Synopsis#

tgs logout [flags]

Flags#

Flag	Short	Default	Description
`--profile`	`-p`	(resolved)	Profile to log out from

Profile resolution order when --profile is not set: TGS_PROFILE env → .tgs.yaml file → "default".

Examples#

# Logout the current profile
tgs logout

# Logout a specific profile
tgs logout --profile work

Output#

JSON (default):

{"profile":"default","status":"logged_out"}

Text (--output text):

Logged out (profile: default)

If the profile is not logged in, the command exits non-zero with an error message.

tgs search global

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

tgs search global#

Search messages globally across all chats, channels, and groups.

Usage#

tgs search global [query] [flags]

The query argument is required and specifies the text to search for.

Flags#

Flag	Short	Type	Default	Description
`--channels-only`		bool	`false`	Search only in channels; incompatible with `--folder`
`--groups-only`		bool	`false`	Search only in groups; incompatible with `--folder`
`--users-only`		bool	`false`	Search only in private chats; incompatible with `--folder`
`--archived`		bool	`false`	Search in the archive folder (folder ID 1); ignored when `--folder` is set
`--folder`		string	`""`	Search only in this folder (id or name), archived chats included; incompatible with `--channels-only`, `--groups-only`, `--users-only`
`--filter`		string		Message type filter (see filter values)
`--after`		string		Only messages after date (YYYY-MM-DD or unix timestamp)
`--before`		string		Only messages before date (YYYY-MM-DD or unix timestamp)
`--limit`	`-l`	int	`50`	Max messages to return (1-100)
`--cursor`		string		Pagination cursor from previous response
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

tgs sources inspect

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

tgs sources inspect#

Fetch detailed information for a single Telegram source. Works for sources you are subscribed to as well as public channels you are not a member of.

Usage#

tgs sources inspect <ref> [flags]

The ref argument identifies the target source. Supported formats:

Format	Example	Description
`@username`	`@durov`	Public username with `@` prefix
`username`	`durov`	Public username without prefix
`id:<n>`	`id:-1001234567890`	Telegram peer ID (recommended for negative IDs — pflag eats bare `-N` as a flag)
Numeric ID	`12345`	Positive peer ID. For negative IDs use the `id:` form above, or insert `--` (e.g. `inspect -- -1001234567890`)
Phone number	`+79001234567`	For contacts and your own account
`-` or `@me`	`-`	Saved Messages (your personal chat)

Flags#

Flag	Short	Type	Default	Description
`--no-stats`		bool	`false`	Skip expensive stats (total/24h/first messages)
`--no-cache`		bool	`false`	Disable peer and stats caches
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

tgs whoami

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

tgs whoami#

Show the current profile name and account information. Reads from local storage — no Telegram connection required.

Synopsis#

tgs whoami [flags]

Flags#

Flag	Short	Default	Description
`--profile`	`-p`	(resolved)	Profile to inspect
`--output`	`-o`	`json`	Output format: `json`, `text`

Profile resolution order when --profile is not set: TGS_PROFILE env → .tgs.yaml file → "default".

Examples#

# Show current profile (JSON output)
tgs whoami

# Human-readable output
tgs whoami --output text

# Inspect a specific profile
tgs whoami --profile work

# Inspect a profile with text output
tgs whoami --profile work --output text

Output#

Text output (--output text):

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.

tgs search counters

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

tgs search counters#

Get message counts grouped by filter type (photo, video, document, etc.) for one or more chats.

Usage#

tgs search counters [flags]

This command takes no positional arguments.

Flags#

Flag	Short	Type	Default	Description
`--chat`	`-c`	string		Chat to query (username, phone, or ID). Required unless `--folder` is set.
`--folder`		string	`""`	Query all chats inside this folder (id or name); results include per-chat breakdowns plus aggregated totals
`--topic`		int	`0`	Forum topic ID
`--filters`		string[]		Filter types to count (comma-separated; default: all). See filter values
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer resolution cache
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

tgs sources folders

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

tgs sources folders#

Enumerates the user’s Telegram folders (dialog filters from the UI) and resolves each one’s contents the way the Telegram client does — applying pinned/include/exclude peers and auto-flags (contacts, groups, etc.) to the full dialog list.

The default “All chats” folder is excluded; only user-defined folders and shared chatlists appear in the output.

Usage#

tgs sources folders [flags]

Flags#

Flag	Short	Type	Default	Description
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer cache
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

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.

tgs search calendar

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

tgs search calendar#

Get message search results grouped by date for one or more chats and a filter type.

Usage#

tgs search calendar [flags]

This command takes no positional arguments.

Flags#

Flag	Short	Type	Default	Description
`--chat`	`-c`	string		Chat to query (username, phone, or ID). Required unless `--folder` is set.
`--folder`		string	`""`	Query all chats inside this folder (id or name); results include per-chat arrays plus aggregated totals
`--filter`		string		Message type filter (see filter values). Required.
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer resolution cache
`--profile`	`-p`	string		Account profile name

Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".

Environment Variables

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

Environment Variables#

All tgs environment variables are optional. They override compiled-in defaults or configuration file values.

Variables#

Variable	Description
`TGS_PROFILE`	Active profile name. Overrides `.tgs.yaml` but is overridden by `--profile` flag.
`TGS_API_ID`	Telegram API ID. Overrides the value compiled into the binary.
`TGS_API_HASH`	Telegram API Hash. Overrides the value compiled into the binary.
`TGS_CONFIG_DIR`	Config directory. Takes precedence over `XDG_CONFIG_HOME`. Default: `$XDG_CONFIG_HOME/tgs`, falling back to `~/.config/tgs`.
`TGS_DATA_DIR`	Data directory for session databases. Takes precedence over `XDG_DATA_HOME`. Default: `$XDG_DATA_HOME/tgs`, falling back to `~/.local/share/tgs`.
`XDG_CONFIG_HOME`	Base config directory (XDG spec). Used as `$XDG_CONFIG_HOME/tgs` when `TGS_CONFIG_DIR` is unset.
`XDG_DATA_HOME`	Base data directory (XDG spec). Used as `$XDG_DATA_HOME/tgs` when `TGS_DATA_DIR` is unset.

Profile Selection#

# Use the "work" profile for one command
TGS_PROFILE=work tgs whoami

# Use the "work" profile for the whole shell session
export TGS_PROFILE=work

See Profile resolution order for the full priority chain.

Introduction on tgs

Installation

Installation#

Homebrew (macOS & Linux)#

Prebuilt binaries#

macOS & Linux#

Windows#

Build from source#

Quick Start

Quick Start#

1. Authenticate#

2. Confirm who you are#

Authentication

Authentication#

Quick Start#

Login Methods#

Desktop Import (default)#

tgs login

tgs login#

Synopsis#

Flags#

tgs profile

tgs profile#

Synopsis#

Subcommands#

tgs profile list#

tgs search messages

tgs search messages#

Usage#

Flags#

tgs sources list

tgs sources list#

Usage#

Flags#

Profiles

Profiles#

How Profile Resolution Works#

Per-Directory Profiles#

tgs logout

tgs logout#

Synopsis#

Flags#

Examples#

Output#

tgs search global

tgs search global#

Usage#

Flags#

tgs sources inspect

tgs sources inspect#

Usage#

Flags#

tgs whoami

tgs whoami#

Synopsis#

Flags#

Examples#

Output#

Search

Search#

Searching in a Chat#

tgs search counters

tgs search counters#

Usage#

Flags#

tgs sources folders

tgs sources folders#

Usage#

Flags#

Sources

Sources#

tgs search calendar

tgs search calendar#

Usage#

Flags#

Environment Variables

Environment Variables#

Variables#

Profile Selection#