Basic Commands
Learn all the essential commands for using tgdl effectively.
Command Overview
tgdl has these main commands:
| Command | Purpose |
|---|---|
login |
Authenticate with Telegram |
logout |
Remove session and logout |
channels |
List your channels |
groups |
List your groups |
bots |
List your bot chats |
download |
Download media from entities |
download-link |
Download from message link |
status |
Check authentication status |
Authentication Commands
login
Purpose: Authenticate tgdl with your Telegram account.
When to use: - First time setup - After logout - Session expired
What you need: - API ID and Hash from my.telegram.org/apps - Your phone number - Access to Telegram app (for verification code)
logout
Purpose: Remove session and credentials.
When to use: - Switching accounts - Securing your system - Troubleshooting authentication issues
Safe Operation
Logout does NOT delete your downloaded files!
status
Purpose: Check if you're logged in and see configuration.
Shows: - Authentication status - User information - File locations - API credentials (masked)
Discovery Commands
channels
Purpose: List all channels you're a member of.
Output includes: - Channel ID (for downloads) - Channel title - Username (if public)
Example output:
📢 Found 5 channels:
ID Title Username
====================================================================
1234567890 Tech News @technews
9876543210 Daily Photos N/A
Tips: - Copy the ID for use with download command - N/A means private channel - Public channels show their @username
groups
Purpose: List all groups you're a member of.
Similar to channels command but shows groups instead.
bots
Purpose: List all bot chats.
Shows: - Bot ID - Bot name - Bot username
Download Commands
download
Purpose: Download media from channels, groups, or bot chats.
Basic Usage
# From channel
tgdl download -c 1234567890
# From group
tgdl download -g 1234567890
# From bot
tgdl download -b 1234567890
With Media Type Filters
# Only photos
tgdl download -c 1234567890 -p
# Only videos
tgdl download -c 1234567890 -v
# Photos and videos
tgdl download -c 1234567890 -p -v
# Everything except photos
tgdl download -c 1234567890 -v -a -d
Media type options:
- -p or --photos - Photos/images
- -v or --videos - Video files
- -a or --audio - Audio files
- -d or --documents - Documents/files
With Size Limits
# Max 100MB
tgdl download -c 1234567890 --max-size 100MB
# Min 1MB (skip small files)
tgdl download -c 1234567890 --min-size 1MB
# Between 1MB and 100MB
tgdl download -c 1234567890 --min-size 1MB --max-size 100MB
Size units: B, KB, MB, GB, TB
With Download Limits
# First 50 files only
tgdl download -c 1234567890 --limit 50
# Faster (10 parallel downloads)
tgdl download -c 1234567890 --concurrent 10
Concurrent downloads: - Default: 5 - Range: 1-50 - Higher = faster (but more bandwidth)
Custom Output Directory
Combined Example
# Download videos under 100MB, max 20 files, fast mode
tgdl download -c 1234567890 -v --max-size 100MB --limit 20 --concurrent 10
download-link
Purpose: Download media from a single message link.
Supported links:
- Public channels: https://t.me/username/123
- Private channels: https://t.me/c/1234567890/123
With filters:
# Only if it's a video
tgdl download-link https://t.me/channel/123 -v
# With size limit
tgdl download-link https://t.me/channel/123 --max-size 50MB
Understanding Download Behavior
Automatic Skip
Already downloaded files are automatically skipped:
Found 25 already downloaded files, will skip...
Fetching messages from entity 1234567890...
Found 10 new media files to download
How it works: 1. tgdl extracts message IDs from existing filenames 2. Compares with messages to download 3. Skips any that match
Progress Tracking
tgdl remembers what it downloaded:
First run:
Second run (later):
Stored in: ~/.tgdl/progress.json
Resume Support
Interrupted downloads can be resumed:
- Download starts
- Press Ctrl+C or connection lost
- Run same command again
- Already downloaded files are skipped
- Download continues
File Naming
Files are named with message ID:
downloads/entity_1234567890/
├── 12345.jpg # Message ID 12345
├── 12346.mp4 # Message ID 12346
└── 12347.pdf # Message ID 12347
Benefits: - Unique filenames - Reliable duplicate detection - Easy to track what's downloaded
Common Use Cases
Backup a Channel
Download Recent Videos
Download Large Files Only
Quick Preview Download
Update Collection
# Run periodically to get new content
tgdl download -c 1234567890
# Only downloads new messages since last run
Download Specific Range
Keyboard Controls
During Download
- Ctrl+C - Cancel download (gracefully)
- Current file completes
- Progress is saved
-
Can resume later
-
No other controls - Download runs automatically
Cancel vs Error
Cancelled:
Error:
Tips & Best Practices
1. Start Small
For First Time
Helps you: - See file organization - Check download speed - Verify filters work
2. Use Filters Wisely
Save Storage
Benefits: - Saves disk space - Faster downloads - Only get what you need
3. Check Storage First
Disk Space
Large channels can have gigabytes of content. Check available space:
4. Optimize Speed
Faster Downloads
5. Regular Updates
Keep Collections Current
Only downloads new content each time.
6. Use Custom Directories
Organization
Common Mistakes
❌ Wrong: Forgetting Entity Flag
Error: Missing -c, -g, or -b
✅ Correct
❌ Wrong: Multiple Entity Types
Error: Can't download from multiple entities at once
✅ Correct
❌ Wrong: Invalid Size Format
Error: Should be 100MB (not 100M)
✅ Correct
Quick Reference
Most Used Commands
# Login
tgdl login
# List what's available
tgdl channels
# Download all from channel
tgdl download -c ID
# Download videos only
tgdl download -c ID -v
# Download with size limit
tgdl download -c ID --max-size 100MB
# Fast download
tgdl download -c ID --concurrent 10
# Check status
tgdl status
Command Template
tgdl download \
-c|g|b ID \
[-p] [-v] [-a] [-d] \
[--max-size SIZE] [--min-size SIZE] \
[--min-id ID] [--max-id ID] \
[--limit N] [--concurrent N] \
[-o DIR]