TeleGram-Scraper

Русская версия документации: README.ru.md

Public binary distribution repository for the tgs.py project.

This repository contains release artifacts only:

tgs.exe: Windows one-file executable
tgs: Linux one-file executable
tgs_automation.exe: Windows automation helper
tgs_automation: Linux automation helper
tgs_gui.exe: Windows desktop GUI frontend
tgs.zip: bundled release archive

Source code lives in the main repository:

https://github.com/Antiokh/tgs.py

What The Tool Does

tgs is a command-line utility for working with Telegram through a user account.

Main workflows:

create and store Telegram API configuration
authorize a Telegram account through Telethon
export members from groups and channels
export messages to txt, json, csv, and sqlite
create richer SQLite dumps with users, metadata, and optional media
send direct messages in bulk from a template
post one formatted message to a target group or channel
check the local license state or generate a license request

Included Binaries

Main CLI:

tgs.exe
tgs

Automation helper:

tgs_automation.exe
tgs_automation

Desktop GUI:

tgs_gui.exe

The GUI binary is a frontend over the main CLI runtime. Place tgs_gui.exe next to tgs.exe in the same folder so the GUI can invoke the compiled CLI binary directly. The GUI supports English and Russian UI text and writes editable locale files into tgs_config/gui_locales/. The repository tgs.zip bundle remains focused on the CLI pair and automation helper; the GUI is distributed as a separate standalone binary because adding tgs_gui.exe pushes the archive above GitHub's 100 MB hard limit.

Included Commands

tgs.exe -h
tgs.exe <command> -h
./tgs -h
./tgs <command> -h

Available commands:

bootstrap
setup
users
add
dump
posts
send
post
license

Quick Start

1. Configure Telegram API credentials

Create your Telegram application credentials at:

https://my.telegram.org/apps

Then run:

tgs.exe setup

or:

./tgs setup

You can also pass values directly:

tgs.exe setup -p +15551234567 -i YOUR_API_ID -k YOUR_API_HASH -o tgs_config\config.data

2. Verify the environment

tgs.exe bootstrap --check

If dependencies are missing in a Python environment, use:

python tgs.py bootstrap

For the standalone binaries, dependency management is already baked into the build environment used to produce the release artifacts.

3. Explore available command help

tgs.exe users -h
tgs.exe posts -h
tgs.exe dump -h
tgs.exe send -h
tgs.exe post -h
tgs_automation.exe -h

Configuration

Current releases use two default working folders:

tgs_config/: configs, sessions, license files, and license requests
tgs_data/: exported CSV, JSON, SQLite, archives, and media

GUI-specific runtime files:

tgs_config/gui_state.json: remembered GUI state such as the selected language
tgs_config/gui_locales/: editable GUI locale JSON files

The main config file usually lives at:

tgs_config/config.data

Most commands accept:

-c, --config: config file path

Default:

tgs_config/config.data

License Notes

The binary checks for a local license and may apply reduced limits when no valid license is installed.

User-facing behavior:

license checks the currently available license
if validation fails, the tool can generate a local license request file
some high-impact workflows may run with reduced limits until a valid license is installed
automation run-due requires a valid license before it executes due jobs

For normal usage, you only need:

tgs.exe license

Command Reference

`bootstrap`

Installs or verifies required third-party packages in a Python environment.

Useful commands:

python tgs.py bootstrap
python tgs.py bootstrap --check

For packaged binaries, this is mostly relevant when you also work with the source checkout.

`setup`

Creates the local Telegram config file.

Arguments:

-o, --output: output config file, default tgs_config\config.data
-p, --phone: phone number in international format
-i, --api_id: Telegram API ID
-k, --api_hash: Telegram API hash

Examples:

tgs.exe setup
tgs.exe setup -o tgs_config\config-anna.data
tgs.exe setup -p +15551234567 -i 123456 -k abcdef123456

`users`

Exports members from a source group or channel into CSV.

Arguments:

-s, --source: source group/channel username or numeric ID
-o, --output: output CSV file
-c, --config: config file

Behavior:

if --source is omitted, an interactive selector is shown
default output is a timestamped CSV in tgs_data/users/
CSV columns include username, user ID, access hash, display name, group title, and group ID

Examples:

tgs.exe users -s my_group
tgs.exe users -s 123456789 -o tgs_data\users\members.csv

`add`

Adds users to a target group either from CSV or from another source group.

Arguments:

-i, --input: CSV file with members
-s, --source: source group/channel
-t, --target: target group/channel
-m, --mode: user_id or username, default user_id
-d, --delay: delay before starting, in seconds or HH:MM:SS
-c, --config: config file

Behavior:

if source or target is omitted, the tool can prompt interactively
existing members are skipped
randomized waits are used between invite attempts

Examples:

tgs.exe add -i tgs_data\users\members.csv -t my_target_group
tgs.exe add -s source_group -t target_group
tgs.exe add -i tgs_data\users\members.csv -t target_group -m username -d 01:30:00

`posts`

Exports messages from a source group or channel.

Arguments:

-s, --source: source group/channel username or ID
-o, --output: output path
-t, --type: text, json, csv, sqlite, or all
-l, --limit: maximum number of messages
-p, --pinned: only pinned messages
-m, --media: include media handling
-a, --archive: archive the result
--date-from: only include messages on or after a date/datetime
--date-to: only include messages on or before a date/datetime
--from-user: only include messages from a given sender
--contains: only include messages containing text
--with-media: only include messages with media
--retries: retries per message on transient export errors
--resume-from-id: continue from older history before this message ID
-f, --formats: extra SQLite text representations such as html, md, json
-c, --config: config file

Notes:

text creates plain readable message blocks
json stores structured message objects
csv stores spreadsheet-friendly rows with proper multiline escaping
sqlite stores a richer queryable dataset
all creates text, json, and sqlite
default output goes to tgs_data/posts/ unless you pass --output

Examples:

tgs.exe posts -s my_channel
tgs.exe posts -s my_channel -t csv
tgs.exe posts -s my_channel -t sqlite -f "html,md,json"
tgs.exe posts -s my_channel -t json --contains "launch"
tgs.exe posts -s my_channel -t csv --with-media --date-from 2026-01-01
tgs.exe posts -s my_channel -t json --resume-from-id 5000 --retries 5

`dump`

Creates a fuller SQLite dump than posts.

Arguments:

-s, --source: source group/channel username or ID
-o, --output: output SQLite path
-m, --media: include media downloads and media metadata
-a, --archive: archive the resulting SQLite file
--date-from: only include messages on or after a date/datetime
--date-to: only include messages on or before a date/datetime
--from-user: only include messages from a given sender
--contains: only include messages containing text
--with-media: only include messages with media
--retries: retries per message on transient export errors
--resume-from-id: continue from older history before this message ID
-f, --formats: extra formatted message columns such as html, md, json
-c, --config: config file

Typical stored data includes:

chat/channel metadata
participant information
messages
optional media records
default output goes to tgs_data/dump/ unless you pass --output

Examples:

tgs.exe dump -s my_channel
tgs.exe dump -s my_channel -m -a -f "html,md,json"
tgs.exe dump -s my_channel --contains "announcement" --date-from 2026-01-01
tgs.exe dump -s my_channel --resume-from-id 5000 --retries 5

`send`

Sends direct messages to users loaded from CSV and/or a source group.

Arguments:

-i, --input: CSV file with recipients
-s, --source: source group to collect recipients from
-t, --text: message file
-f, --format: text, html, or markdown
-j, --message-json: legacy structured message file
--preview: render the first resolved message without sending
--dry-run: validate recipients and rendering without sending
--whitelist: CSV file with recipients to explicitly allow
--blacklist: CSV file with recipients to exclude
--limit-users: limit recipients after filters are applied
--report-json: write a JSON results report
--report-csv: write a CSV results report
--verbose-log: write an extended structured JSON log
-d, --delay: delay before starting the send task
--delay-min: minimum delay between sends in seconds
--delay-max: maximum delay between sends in seconds
-m, --mode: user_id or username, default user_id
-c, --config: config file

Template placeholders supported in message files:

%%username%%
%%first_name%%
%%last_name%%

Formatting behavior:

text: safely escaped and sent through the HTML pipeline
html: validated and sent as HTML
markdown: converted to Telegram-compatible HTML before sending

Operational notes:

--preview and --dry-run do not send anything
--delay postpones the whole send task
--delay-min/--delay-max control per-recipient pacing
recipients are deduplicated by user ID
buttons are not used in the user-account send workflow

Examples:

tgs.exe send -i tgs_data\users\members.csv -t message.txt -f text
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html
tgs.exe send -i tgs_data\users\members.csv -t message.md -f markdown --preview
tgs.exe send -i tgs_data\users\members.csv -t message.md -f markdown --dry-run
tgs.exe send -s source_group -t message.html -f html
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html --whitelist tgs_data\users\testers.csv --limit-users 10
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html --blacklist tgs_data\users\do_not_contact.csv
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html --report-csv tgs_data\reports\send_results.csv
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html --verbose-log tgs_data\logs\send_verbose.json
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html --delay 21:30 --delay-min 8 --delay-max 15

`post`

Posts one formatted message into a target group or channel.

Arguments:

-g, --group: target group/channel ID, username, or title
-t, --text: message file
-f, --format: text, html, or markdown
-j, --message-json: legacy structured message file
--preview: render the final message without posting
--dry-run: validate target resolution and rendering without posting
-d, --delay: delay before starting the post task
--delay-min: randomized minimum delay before posting
--delay-max: randomized maximum delay before posting
--verbose-log: write an extended structured JSON log
-c, --config: config file

Behavior:

if --group is omitted, the tool opens the selector
if a title matches multiple local chats, it shows a choice list
text, html, and markdown use the same rendering pipeline as send

Examples:

tgs.exe post -t announcement.html -f html
tgs.exe post -g test_vscode -t announcement.md -f markdown
tgs.exe post -g "OpenAir Belgrade" -t announcement.txt -f text --preview
tgs.exe post -g my_channel -t announcement.html -f html --dry-run
tgs.exe post -g my_channel -t announcement.html -f html --delay 21:30
tgs.exe post -g my_channel -t announcement.html -f html --verbose-log tgs_data\logs\post_verbose.json

`license`

Checks the current local license state or creates a local license request when needed.

Arguments:

-c, --config: config file

Usage:

tgs.exe license

`tgs_automation`

tgs_automation is a companion binary for automation-oriented workflows.

Current scope:

validate an automation plan JSON
print a normalized plan view
show which main runner will be used
show the concrete tgs commands implied by the plan
execute jobs that are due right now through run-due
record automation state in SQLite for later inspection

Runner resolution behavior:

it prefers the compiled tgs.exe or tgs binary when present
it falls back to python tgs.py only when the main binary is not available
run-due expects an external scheduler heartbeat such as Windows Task Scheduler or cron
nothing runs just because a job exists in a plan file; a scheduler still has to call run-due
run-due validates the configured license before execution and skips due jobs until the license passes

Examples:

tgs_automation.exe -h
tgs_automation.exe validate-plan plan.json
tgs_automation.exe show-plan plan.json
tgs_automation.exe show-runner
tgs_automation.exe show-commands plan.json
tgs_automation.exe run-due plan.json

Message Formats

For send and post, the preferred workflow is:

message file plus --format

Supported values:

text
html
markdown

Typical examples:

tgs.exe send -i tgs_data\users\members.csv -t message.txt -f text
tgs.exe send -i tgs_data\users\members.csv -t message.html -f html
tgs.exe send -i tgs_data\users\members.csv -t message.md -f markdown

Export Outputs

Common export targets:

users: CSV
posts: text, json, csv, sqlite
dump: SQLite

Typical output folders created by the tool:

tgs_data/users/
tgs_data/posts/
tgs_data/dump/
tgs_config/licenses/
tgs_config/license_requests/

Practical Workflows

Export members from a group

tgs.exe users -s source_group -o tgs_data\users\members.csv

Export posts to CSV for spreadsheet work

tgs.exe posts -s my_channel -t csv -o tgs_data\posts\messages.csv

Create a richer SQLite dump with media

tgs.exe dump -s my_channel -m -a -f "html,md,json"

Preview a bulk message before sending

tgs.exe send -i tgs_data\users\members.csv -t message.md -f markdown --preview

Post one announcement to a target channel

tgs.exe post -g my_channel -t announcement.html -f html

Validate an automation plan

tgs_automation.exe validate-plan plan.json
tgs_automation.exe show-commands plan.json

Execute automation jobs that are due right now

tgs_automation.exe run-due plan.json

Operational model:

save the plan file from the GUI or prepare it manually
let Task Scheduler, cron, or another wrapper call run-due repeatedly
if the current local date/time is earlier than a job slot, the job is skipped for now
if the current local date/time is later than the slot, the job runs once and is recorded in SQLite
the default automation state DB lives next to the plan as <plan_name>_automation.sqlite
accepted schedule styles include Daily HH:MM, Mon-Fri HH:MM, Mon-Thu HH:MM, Mon-Wed|Fri HH:MM, and Day <N> HH:MM

Platform Notes

tgs.exe is the Windows main CLI
tgs is the Linux main CLI
tgs_automation.exe is the Windows automation helper
tgs_automation is the Linux automation helper
all included artifacts are one-file executables
behavior may still depend on Telegram account state, session files, and target chat access

Operational Notes

The tool works with real Telegram accounts and real chats
some commands intentionally wait between actions to reduce rate-limit issues
generated exports may contain personal data and message history
use the tool only where you have permission and understand platform restrictions

Release Notes

This repository is intended for binary distribution.

It does not ship source snapshots and does not document internal implementation details. For development history and source-level changes, see:

https://github.com/Antiokh/tgs.py

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
CHANGELOG.md		CHANGELOG.md
README.md		README.md
README.ru.md		README.ru.md
tgs		tgs
tgs add.lnk		tgs add.lnk
tgs dump.lnk		tgs dump.lnk
tgs license.lnk		tgs license.lnk
tgs posts.lnk		tgs posts.lnk
tgs setup.lnk		tgs setup.lnk
tgs.exe		tgs.exe
tgs.zip		tgs.zip
tgs_automation		tgs_automation
tgs_automation.exe		tgs_automation.exe
tgs_gui.exe		tgs_gui.exe

Folders and files

Latest commit

History

Repository files navigation

TeleGram-Scraper

What The Tool Does

Included Binaries

Included Commands

Quick Start

1. Configure Telegram API credentials

2. Verify the environment

3. Explore available command help

Configuration

License Notes

Command Reference

bootstrap

setup

users

add

posts

dump

send

post

license

tgs_automation

Message Formats

Export Outputs

Practical Workflows

Export members from a group

Export posts to CSV for spreadsheet work

Create a richer SQLite dump with media

Preview a bulk message before sending

Post one announcement to a target channel

Validate an automation plan

Execute automation jobs that are due right now

Platform Notes

Operational Notes

Release Notes

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 6

Contributors

Uh oh!

`bootstrap`

`setup`

`users`

`add`

`posts`

`dump`

`send`

`post`

`license`

`tgs_automation`