telegram
Upload files and folders to a Telegram channel, or download a file from it by name
- Command:
/go/telegram - Category: Storage
- Required option: None (a path, a file name, or
login) - Output: Progress output from
tdl - Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/telegram uses a Telegram channel as remote storage. You can send a file, or a whole folder, from the server to the channel and fetch a file back later by its name. It is handy for off-server copies of backups.
It relies on tdl, a Telegram command-line tool. If tdl isn't installed, the command downloads and installs it the first time you run it.
You need:
- a Telegram account, which the server logs in to
- a Telegram channel (a private one is best) that the account can post to
The command works in four ways, chosen by its first argument:
| Argument | What it does |
|---|---|
login |
Logs in to Telegram and saves the channel to use. |
| a file | Uploads the file to the channel. |
| a directory | Uploads every file in it, including subfolders, one by one. |
| anything else | Downloads the file with that name from the channel. |
Quick start
# 1. Log in and choose the channel (only needed once)
/go/telegram login
# 2. Upload a file
/go/telegram /home/example.com/backup.zip
Syntax
/go/telegram login
/go/telegram <file>
/go/telegram <directory>
/go/telegram <file-name>
The first argument is checked in this order: login, then an existing file, then an existing directory. If it is none of those, it is taken as the name of a file to download.
Options
| Argument | Required | Notes |
|---|---|---|
login |
No | Asks for your phone number and the login code, then asks which channel to use. |
<file> |
No | Path of a file on the server. It is uploaded under its own file name. |
<directory> |
No | Path of a folder on the server. Every file inside is uploaded. |
<file-name> |
No | The name of a file in the channel, for example backup.zip. It is saved in the current directory. |
If you haven't run login yet, any other command runs login first and then stops. Run your command again afterwards.
Output
The output comes from tdl: upload and download progress, and any error it reports.
During login, the command prints the channels it found, one per line with the channel ID and the first word of its name, and then asks you to confirm:
ChannelID: <the first channel's ID, ready to edit>
Press Enter to accept the suggested ID, or type another one.
The command has no message of its own for success. Every run is logged to /var/log/go/telegram.log with a timestamp and the arguments used.
| Outcome | Exit status |
|---|---|
login finished |
1 |
| Anything else | The status of the last tdl command |
Examples
# Log in and pick the channel
/go/telegram login
# Upload one file
/go/telegram /home/example.com/backup.zip
# Upload every file in a folder
/go/telegram /root/backups
# Download backup.zip into /root/restore
mkdir -p /root/restore
cd /root/restore
/go/telegram backup.zip
[!TIP] Run downloads from a folder that doesn't already contain a file with that name. If the file exists in the current folder, the command uploads it instead.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
tdl: command not found |
The automatic install failed, for example because the server has no internet access. | Install tdl by hand and put it in /usr/local/bin. |
| The command starts a login every time | /var/go/etc/telegram.conf doesn't exist. |
Run /go/telegram login and finish it, then run your command again. |
| The channel list is empty or your channel is missing | The list only shows lines with a hyphen (-). |
Type the channel ID yourself. List your chats with tdl chat ls. |
| Upload fails with a chat or channel error | The saved channel ID is wrong, or the account can't post there. | Run login again and choose the right channel. |
| Telegram asks for a password during login | The account has two-step verification. | Enter that password. |
| A download uploads the file instead | A file with that name exists in the current folder. | Change to another folder first. |
| A download fails or finds nothing | The name doesn't match the uploaded name (case, extension), or the file was never uploaded with this command. | Use the exact file name, without a path. |
| Downloads are slow to start | The command exports the channel's whole message list before every download. | Wait, or keep the channel small. |
| Upload of a large file fails | Telegram limits the size of a file (currently 2 GB, or 4 GB for Premium accounts). | Split the file before uploading. |
| Uploading a folder fails or skips files | The folder path contains spaces. | Use a path without spaces. |
tdl_Linux_64bit.tar.gz is left in the folder |
The installer doesn't clean up after itself. | Delete it. |
tdl doesn't run on your server |
The command installs the 64-bit Intel/AMD build. | On other processors (for example ARM), install the matching tdl build by hand. |
Details
How it works
flowchart TD
A["/go/telegram arg"] --> B{"tdl installed?"}
B -- "No" --> C["Download tdl v0.20.3 and install it"]
B -- "Yes" --> D
C --> D{"arg = login?"}
D -- "Yes" --> E["tdl login, pick the channel, save telegram.conf"]
D -- "No" --> F{"telegram.conf exists?"}
F -- "No" --> E
F -- "Yes" --> G{"arg is a file, a directory, or a name?"}
G -- "file" --> H["tdl up"]
G -- "directory" --> I["tdl up for each file"]
G -- "name" --> J["Export messages, find the file, tdl dl"]
Login
- Runs
tdl login --type code, which asks for your phone number and the code Telegram sends you. - Lists your channels and asks you to confirm the channel ID.
- Saves it as
ChannelID="<id>"in/var/go/etc/telegram.conf.
Upload
Each file is uploaded under its file name only, without its folder. In a folder upload, two files with the same name in different subfolders end up with the same name in the channel.
Download
- Exports the channel's messages to
/usr/local/goadmio/tmp/export.json. - Finds the first message whose file name matches the name you gave.
- Downloads it with
tdlinto the current directory and renames it to the original name.
Files and requirements
| Item | Used for |
|---|---|
/usr/local/bin/tdl |
The Telegram tool. |
/var/go/etc/telegram.conf |
The saved channel ID. |
/usr/local/goadmio/tmp/export.json |
The channel's message list, replaced on every download. |
/var/log/go/telegram.log |
The command log. |
wget, tar, jq |
Installing tdl and finding files to download. |
| Internet access | Installing tdl and talking to Telegram. |
Security notes
tdllogs in as your Telegram account, not a bot. Anyone with root access to the server can use that session. Use a separate account for the server.- Files are stored on Telegram's servers without extra encryption. Encrypt sensitive backups before uploading, and keep the channel private.
- The
telegram.conffile is run as a shell script by the command, so only root should be able to change it.
See also
| Command | Description |
|---|---|
backup |
Create a backup for all GoAdmio accounts (local and remote) |
cb |
Copy GoAdmio backups from the local server to a remote server |
fsync |
Copy a directory from your local server to a remote server |
s3 |
Mount an S3 bucket on a GoAdmio server |
storage |
Auto-mount the /storage folder on boot using rclone |
gdown |
Download files from Google Drive |