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

Login Methods#

Desktop Import (default)#

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

# Auto-detect Telegram Desktop data
tgs login

# Custom tdata path
tgs login --desktop-dir /path/to/tdata

# Passcode-protected Telegram Desktop client
tgs login --passcode SECRET

No phone number or code entry required — the session is transferred directly.

Phone + Code#

Interactive login with your phone number. Supports 2FA (cloud password).

# Interactive — prompts for phone and code
tgs login --type code

# Provide phone upfront
tgs login --type code --phone +1234567890

tgs will prompt for the verification code sent by Telegram. If 2FA is enabled, pass the cloud password via the --password flag — tgs does not prompt for it interactively.

Non-Interactive Login (for AI agents)#

The code method supports a fully non-interactive two-step flow. This is the recommended way for AI agents and automation tools.

# Step 1: request the code
tgs login --type code --phone +1234567890
# → {"status":"code_sent","profile":"default"}

# Step 2: complete login with the received code
tgs login --type code --phone +1234567890 --code 12345
# → {"status":"logged_in","user":{...}}

# With 2FA
tgs login --type code --phone +1234567890 --code 12345 --password mysecret

QR Code#

Displays a QR code in the terminal. Scan it with the Telegram app on another device.

tgs login --type qr

After scanning, tgs completes the authentication automatically. QR login does not support accounts with 2FA enabled — use the code method with --password for those.

Login to a Specific Profile#

Use --profile to authenticate into a named profile. The profile is created automatically if it does not exist.

tgs login --profile work
tgs login --type code --profile personal

See Profiles for multi-account setup.

Verifying Login#

After logging in, confirm the active account:

tgs whoami

Logout#

tgs logout                  # logout current profile
tgs logout --profile work   # logout specific profile

Logout revokes the session on Telegram servers and clears local session data.

Full Flag Reference#

See tgs login and tgs logout for all flags.