tgs login#
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".
Examples#
# Import session from Telegram Desktop (default)
tgs login
# Custom tdata path
tgs login --desktop-dir ~/AppData/Roaming/Telegram\ Desktop/tdata
# Passcode-protected Telegram Desktop
tgs login --passcode mysecret
# Phone + verification code (interactive)
tgs login --type code
# Phone + code with phone pre-filled
tgs login --type code --phone +1234567890
# Non-interactive two-step login (for AI agents / automation)
# Step 1: send the verification code
tgs login --type code --phone +1234567890
# Step 2: complete login with the code
tgs login --type code --phone +1234567890 --code 12345
# Non-interactive login with 2FA
tgs login --type code --phone +1234567890 --code 12345 --password mysecret
# QR code login
tgs login --type qr
# Login to a specific profile
tgs login --profile work
# Login to a profile with a specific method
tgs login --type code --profile work --phone +0987654321Auth Methods#
| Method | Description |
|---|---|
desktop | Import session from Telegram Desktop. No phone or code needed. |
code | Phone number + SMS/Telegram verification code. Supports 2FA. Can be fully non-interactive with --phone, --code, and --password flags. |
qr | Display QR code in terminal. Scan with Telegram on another device. Accounts with 2FA enabled cannot use QR login — use code with --password instead. |
Output#
On successful login:
JSON (default):
{"profile":"default","status":"logged_in","user":{"id":261054642,"phone":"+79001234567","username":"alice","first_name":"Alice","last_name":"Doe"}}Text (--output text):
Logged in as Alice Doe (id: 261054642, profile: default)In the two-step code flow, the first call (without --code) sends the verification code:
{"profile":"default","status":"code_sent"}Verification code sent (profile: default). Re-run with --code to complete login.On failure, the command exits non-zero and prints an error to stderr. Common reasons: invalid code, expired QR token, incorrect 2FA password, or session already present (use tgs logout first).