GramFlow

GramFlow uses your own Telegram account to upload files up to 4 GiB (2 GiB on non-Premium accounts) straight from the terminal — no bot, no Saved Messages gymnastics, no browser upload limits.

It started as a maintenance-focused fork of the unmaintained uploadgram project, migrated to an actively maintained Telegram client library, and picked up a long list of bug fixes along the way.

• Heavily inspired by telegram-upload

Features

• Uploads any file or a whole directory tree (recursively) to a chat, group, channel, or forum topic
• Sends images as real Telegram photos, videos as videos (with an auto-generated thumbnail), audio with proper metadata — everything else as a document
• Groups consecutive photos/videos into Telegram albums (media groups) instead of one message per file
• Resumes an interrupted batch — re-running the same folder against the same destination skips files already uploaded
• Batch-wide progress in a single status message, alongside the existing per-file progress bar
• gramflow login / gramflow logout to manage the saved session explicitly
• Optional delete-on-success, custom captions, custom thumbnails, and a live console progress bar
• Skips oversized files with a clear notice instead of failing silently
• Natural file ordering (file2 before file10) and dotfiles ignored

Installation

pip install gramflow

Requirements

• Python 3.10+
• ffmpeg on your PATH (optional — only needed to auto-generate video thumbnails; uploads still work without it)
• kurigram — installed automatically as a dependency. It's an actively maintained drop-in replacement for pyrogram, and is still imported as pyrogram in code, per its own convention.

On first run, GramFlow will ask for a Telegram api_id and api_hash. Get both for free at my.telegram.org (API development tools) and they'll be saved to ~/.config/gramflow/config.env for future runs.

Usage

Authentication

gramflow login    # authenticate once and save the session
gramflow logout   # revoke the session with Telegram and remove it locally

You don't need to run login explicitly — the first upload will prompt for phone number / code / 2FA password automatically if there's no saved session. login/logout exist as explicit, discoverable commands for managing that session on demand (e.g. switching accounts, or fully logging out of a shared machine).

Uploading

gramflow <chat_id> <path> [options]

$ gramflow 7351948 /path/to/dir/or/file --delete_on_success --fd -t /path/to/custom/thumbnail --caption "A Custom Caption" --topic 1

The boolean flags (--delete_on_success, --fd, --progress, --no-resume, --fresh, --no-albums) are plain on/off switches — include the flag to enable it, omit it to disable it. --delete_on_success True does not work; just pass --delete_on_success on its own.

By default, files are sent without a caption. To get the old file-name-as-caption behaviour back, pass --caption "<filename>" yourself.

Resuming an interrupted upload

If a batch is interrupted (crash, Ctrl+C, lost connection), just run the exact same command again — files already confirmed uploaded (matched by path, size, and modified time) are skipped automatically, and the batch picks up where it left off. Pass --fresh if you want to force a full re-upload of that same folder/destination instead.

Configuration

Environment variables (all optional besides the two credentials, which will be prompted for interactively if missing):

Security note

GramFlow logs in as your own Telegram account, not a bot. The session file it creates under ~/.config/gramflow/ grants full access to that account — treat it like a password (don't commit it, don't share it, don't upload it anywhere). Automating a personal account also falls under Telegram's own Terms of Service for user accounts, so keep usage reasonable (avoid extremely high message/upload rates) to stay within normal limits.

Troubleshooting

• FLOOD_WAIT_X errors — Telegram is rate-limiting your account; wait the number of seconds it reports before retrying. Sending very large batches back-to-back makes this more likely.
• No video thumbnail generated — make sure ffmpeg is installed and on your PATH. Without it, uploads still work, just without a thumbnail.
• Asked for api_id/api_hash every run — check that ~/.config/gramflow/config.env is writable and isn't being wiped by another process (e.g. a container that resets $HOME on restart).
• Asked to log in again unexpectedly — the session file lives at ~/.config/gramflow/GramFlow.session. If it's missing or was deleted, the next upload (or gramflow login) will re-prompt for authentication.
• A file re-uploads even though it succeeded before — resume matching is based on path, size, and modified time; if any of those changed (e.g. the file was re-saved or moved), it's treated as a new file. Use --fresh to intentionally clear resume history for a folder.

Contributing

Issues and pull requests are welcome at github.com/kavidu-dilhara/gramflow.

License

MIT LICENSE. GramFlow is a fork of uploadgram; original copyright is preserved in file headers alongside the new copyright for this fork.

Author

Kavidu Dilhara GitHub: @kavidu-dilhara Repository: github.com/kavidu-dilhara/gramflow