tg-push

Python CLI for sending text plus an optional file to Telegram.

There is no bot polling loop, no MCP bridge, and no long-running server, just simple one-way messages.

Install

pip install tg-push

Or with pipx for an isolated install:

pipx install tg-push

Environment

Variable	Required	Description
TG_BOT_TOKEN	yes	Telegram bot token from @BotFather
TG_CHAT_ID	yes	Target chat ID or @channelusername

For a 1:1 bot chat, TG_CHAT_ID is your Telegram user id. For groups and channels, use the actual chat id instead.

Usage

tg-push --text "build finished"
tg-push --file ./render.png
tg-push --text "latest render" --file ./render.png
tg-push --text "report" --file ./report.pdf

Behavior

• At least one of --text or --file is required.
• If --file is present, recognized images and videos are sent as Telegram media.
• Other files are sent as documents, so PDFs, archives, and extensionless files work.
• Supported image extensions: .jpg, .jpeg, .png, .webp
• Supported video extensions: .mp4, .mov, .m4v, .webm, .mkv, .avi
• If --text is longer than Telegram's media caption limit, the file is sent first and the text is sent as follow-up messages.
• On success a one-line confirmation is printed to stdout, for example Sent report.pdf (document) to @mychannel. Errors go to stderr with exit code 1.
• The project has no runtime dependencies outside the Python standard library.