Getting Started 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.

Getting Started 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)#