Content/Zh/Getting Started/Installation Copy Section

---
title: "安装"
weight: 10
---

安装

一键脚本 Copy Chapter

{{< tabs "scripts" >}}

{{< tab "Windows" >}}
tdl 将被安装到 $Env:SystemDrive\tdl（将被添加到 PATH 中），该脚本还可用于升级 tdl。

#### 安装最新版本

{{< command >}}
iwr -useb https://docs.iyear.me/tdl/install.ps1 | iex
{{< /command >}}

#### 通过 ghproxy.com 镜像安装

{{< command >}}
$Script=iwr -useb https://docs.iyear.me/tdl/install.ps1;
$Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "", "$True"
{{< /command >}}

#### 安装特定版本

{{< command >}}
$Env:TDLVersion = "VERSION"
$Script=iwr -useb https://docs.iyear.me/tdl/install.ps1;
$Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "$Env:TDLVersion"
{{< /command >}}

{{< /tab >}}

{{< tab "macOS 和 Linux" >}}
tdl 将被安装到 /usr/local/bin/tdl，该脚本还可用于升级 tdl。

#### 安装最新版本

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash
{{< /command >}}

#### 通过 ghproxy.com 镜像安装

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash -s -- --proxy
{{< /command >}}

#### 安装特定版本

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash -s -- --version VERSION
{{< /command >}}

{{< /tab >}}
{{< /tabs >}}

包管理器 Copy Chapter

{{< tabs "package managers" >}}

{{<tab "Homebrew" >}}
{{< command >}}
brew install telegram-downloader
{{< /command >}}
{{< /tab >}}

{{<tab "Scoop" >}}
{{< command >}}
scoop bucket add extras
scoop install telegram-downloader
{{< /command >}}
{{< /tab >}}

{{<tab "Termux" >}}
{{< command >}}
pkg install tdl
{{< /command >}}
{{< /tab >}}

{{<tab "AUR" >}}
{{< command >}}
yay -S tdl
{{< /command >}}
{{< /tab >}}

{{<tab "Nix" >}}

#### nix-env
{{< command >}}
nix-env -iA nixos.tdl
{{< /command >}}

#### NixOS-Configuration

environment.systemPackages = [
    pkgs.tdl
];

#### nix-shell
{{< command >}}
nix-shell -p tdl
{{< /command >}}

{{< /tab >}}

{{< /tabs >}}

[](https://repology.org/project/telegram-downloader/versions)

Docker Copy Chapter

可用镜像：
- iyear/tdl
- ghcr.io/iyear/tdl

可用标签：
- latest（默认）：最新的稳定版本
- X.Y.Z：tdl的特定版本

{{< tabs "docker" >}}
{{< tab "Docker" >}}

以一次性命令运行 tdl：
{{< command >}}
docker run --rm -it iyear/tdl <ARGUMENTS>
{{< /command >}}

进一步，挂载配置目录以保持持久化：
{{< command >}}
docker run --rm -it \
-v $HOME/.tdl:/root/.tdl \
iyear/tdl <ARGUMENTS>
{{< /command >}}

为了方便获取下载的文件，可以挂载下载目录和其他需要的目录：
{{< command >}}
docker run --rm -it \
-v $HOME/.tdl:/root/.tdl \
-v $HOME/Downloads:/downloads \
iyear/tdl <ARGUMENTS>
{{< /command >}}

在容器内运行 tdl：
{{< command >}}
docker run --rm -it <FLAGS> --entrypoint sh iyear/tdl
{{< /command >}}
{{< details title="预览输出" open=false >}}

/ # tdl version
Version: 0.17.7
Commit: ace2402
Date: 2024-11-01T14:40:56+08:00
go1.21.13 linux/amd64
/ #

如果希望使用 localhost 地址的代理，使用 host 网络运行：
{{< command >}}
docker run --rm -it <FLAGS> --network host iyear/tdl <ARGUMENTS>
{{< /command >}}
{{< /tab >}}

{{< tab "Docker Compose" >}}
使用 Docker Compose 运行 tdl，避免每次输入 docker run 选项。

{{< details title="docker-compose.yml" open=false >}}
{{< hint info >}}
示例配置使用 Docker Compose v2 语法。
{{< /hint >}}

services:
  tdl:
    image: iyear/tdl # 或指定特定版本的 X.Y.Z 版本标签
    volumes:
      - $HOME/.tdl:/root/.tdl # 保持配置持久化
      - $HOME/Downloads:/downloads # 可选
      # - /path/to/your/need:/path/in/container
    stdin_open: true
    tty: true
    # 如果需要使用 localhost 地址的代理，使用 host 网络
    network_mode: host

使用 Docker Compose 运行 tdl：
{{< command >}}
docker compose run --rm tdl <ARGUMENTS>
{{< /command >}}

在容器内运行 tdl：
{{< command >}}
docker compose run --rm --entrypoint sh tdl
{{< /command >}}
{{< details title="预览输出" open=false >}}

/ # tdl version
Version: 0.17.7
Commit: ace2402
Date: 2024-11-01T14:40:56+08:00
go1.21.13 linux/amd64
/ #

{{< /tab >}}
{{< /tabs >}}

预编译二进制 Copy Chapter

1. 下载指定操作系统和架构的压缩包：

{{< tabs "prebuilt" >}}
{{< tab "Windows" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_64bit.zip" >}}x86_64/amd64{{<
/button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_32bit.zip" >}}x86{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_arm64.zip" >}}arm64{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv5.zip" >}}armv5{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv6.zip" >}}armv6{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv7.zip" >}}armv7{{< /button >}}
{{< /tab >}}

{{< tab "macOS" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_MacOS_64bit.tar.gz" >}}Intel{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_MacOS_arm64.tar.gz" >}}M1/M2{{< /button >}}
{{< /tab >}}

{{< tab "Linux" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_64bit.tar.gz" >}}x86_64/amd64{{<
/button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_32bit.tar.gz" >}}x86{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_arm64.tar.gz" >}}arm64{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv5.tar.gz" >}}armv5{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv6.tar.gz" >}}armv6{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv7.tar.gz" >}}armv7{{< /button >}}
{{< /tab >}}
{{< /tabs >}}

2. 解压缩压缩包
3. 将可执行文件移动到所需目录
4. 将此目录添加到 PATH 环境变量
5. 确保您对文件具有执行权限

源代码 Copy Chapter

要从源代码构建 tdl 的扩展版本，您必须：

1. 安装 Git
2. 安装 Go 的 1.25 版本或更高版本
3. 根据 Go 文档中的描述更新您的 PATH 环境变量

{{< hint info >}}
安装目录由 GOPATH 和 GOBIN 环境变量控制。如果设置了 GOBIN，则二进制文件将安装到该目录。如果设置了 GOPATH，则二进制文件将安装到 GOPATH 列表中第一个目录的 bin 子目录。否则，二进制文件将安装到默认的 GOPATH 的 bin 子目录（$HOME/go 或 %USERPROFILE%\go）。
{{< /hint >}}

然后构建：

{{< command >}}
go install github.com/iyear/tdl@latest
tdl version
{{< /command >}}

---

Content/Zh/Getting Started/Quick Start Copy Section

---
title: "快速开始"
weight: 20
---

快速开始

登录 Copy Chapter

我们不在这里指定命名空间，它将使用 default 命名空间。如果你想使用其他命名空间，可以使用 -n 标志指定命名空间。

使用桌面客户端登录 Copy Section

{{< hint warning >}}
请确保从官方网站下载客户端（不要从 Microsoft Store 或 App Store 下载）
{{< /hint >}}

使用默认路径：

{{< command >}}
tdl login
{{< /command >}}

如果您设置了本地密码：

{{< command >}}
tdl login -p YOUR_PASSCODE
{{< /command >}}

或者指定自定义客户端路径：

{{< command >}}
tdl login -d /path/to/TelegramDesktop
{{< /command >}}

使用二维码登录 Copy Section

{{< command >}}
tdl login -T qr
{{< /command >}}

使用手机号码和验证码登录 Copy Section

{{< command >}}
tdl login -T code
{{< /command >}}

下载 Copy Chapter

我们从 Telegram 官方频道下载文件：

{{< command >}}
tdl dl -u https://t.me/telegram/193
{{< /command >}}

---

Content/Zh/Getting Started/Shell Completion Copy Section

---
title: "自动补全"
weight: 30
---

自动补全

运行对应的命令以在所有会话中启用 Shell 自动补全：

{{< tabs "shell" >}}
{{< tab "bash" >}}

{{< command >}}
echo "source <(tdl completion bash)" >> ~/.bashrc
{{< /command >}}

{{< /tab >}}

{{< tab "zsh" >}}

{{< command >}}
echo "source <(tdl completion zsh)" >> ~/.zshrc
{{< /command >}}

{{< /tab >}}

{{< tab "fish" >}}

{{< command >}}
echo "tdl completion fish | source" >> ~/.config/fish/config.fish
{{< /command >}}

{{< /tab >}}

{{< tab "PowerShell" >}}

{{< command >}}
Add-Content -Path $PROFILE -Value "tdl completion powershell | Out-String | Invoke-Expression"
{{< /command >}}

{{< /tab >}}
{{< /tabs >}}

---

Content/Zh/Guide/Tools/Export Members Copy Section

---
title: "导出成员"
weight: 20
---

导出成员

导出聊天成员/订阅者、管理员、机器人等。

{{< hint info >}}
部分类型用户(被禁用户/被踢出用户/……)导出需要聊天管理员权限。
{{< /hint >}}

{{< include "snippets/chat.md" >}}

默认 Copy Chapter

将所有用户导出为 tdl-users.json

{{< command >}}
tdl chat users -c CHAT
{{< /command >}}

自定义路径 Copy Chapter

指定文件路径进行导出

{{< command >}}
tdl chat users -c CHAT -o /path/to/export.json
{{< /command >}}

原始数据 Copy Chapter

导出 Telegram MTProto 原始用户结构，用于调试。

{{< command >}}
tdl chat users -c CHAT --raw
{{< /command >}}

---

Content/Zh/Guide/Tools/Export Messages Copy Section

---
title: "导出消息"
weight: 30
---

导出消息

以 JSON 格式导出聊天、频道、群组等中的媒体消息。

{{< include "snippets/chat.md" >}}

{{< hint info >}}
空的 CHAT 表示“收藏夹”
{{< /hint >}}

所有消息 Copy Chapter

将包含媒体的所有消息导出到 tdl-export.json

{{< command >}}
tdl chat export -c CHAT
{{< /command >}}

从主题/回复中导出 Copy Chapter

从特定主题导出媒体消息：
{{< hint info >}}
获取主题 ID 的方式：

1. 消息链接：https://t.me/c/1492447836/251011/269724（251011 是主题 ID）
2. tdl chat ls 命令
{{< /hint >}}

{{< command >}}
tdl chat export -c CHAT --topic TOPIC_ID
{{< /command >}}

从特定频道帖子的回复中导出媒体消息：

{{< command >}}
tdl chat export -c CHAT --reply POST_ID
{{< /command >}}

自定义路径 Copy Chapter

指定输出文件路径进行导出。默认：tdl-export.json。

{{< command >}}
tdl chat export -c CHAT -o /path/to/output.json
{{< /command >}}

自定义类型 Copy Chapter

时间范围 Copy Section

根据特定的时间戳范围进行导出。默认：1970-01-01 - 当前

{{< command >}}
tdl chat export -c CHAT -T time -i 1665700000,1665761624
{{< /command >}}

time 也是 -T 选项的默认值，因此您可以省略它

{{< command >}}
tdl chat export -c CHAT -i 1665700000,1665761624
{{< /command >}}

ID 范围 Copy Section

根据特定的消息 ID 范围进行导出。默认：0 - 最新

{{< command >}}
tdl chat export -c CHAT -T id -i 100,500
{{< /command >}}

最新 Copy Section

导出最后 100 条媒体文件：

{{< command >}}
tdl chat export -c CHAT -T last -i 100
{{< /command >}}

过滤 Copy Chapter

请参考过滤器指南以获取有关过滤器的基本知识。

列出所有可用的过滤字段：

{{< command >}}
tdl chat export -c CHAT -f -
{{< /command >}}

导出最后的 10 个媒体文件，其中 大小 > 5MiB 且 查看次数 > 200：

{{< command >}}
tdl chat export -c CHAT -T last -i 10 -f "Views>200 && Media.Name endsWith '.zip' && Media.Size > 510241024"
{{< /command >}}

包含内容 Copy Chapter

附带消息内容：

{{< command >}}
tdl chat export -c CHAT --with-content
{{< /command >}}

原始数据 Copy Chapter

导出 Telegram MTProto 原始消息结构，用于调试。

{{< command >}}
tdl chat export -c CHAT --raw
{{< /command >}}

非媒体消息 Copy Chapter

导出包括非媒体消息的所有消息，用于调试/备份。

{{< command >}}
tdl chat export -c CHAT --all
{{< /command >}}

---

Content/Zh/Guide/Tools/List Chats Copy Section

---
title: "列出聊天"
weight: 10
---

列出聊天

列出所有聊天 Copy Chapter

{{< command >}}
tdl chat ls
{{< /command >}}

JSON 格式 Copy Chapter

{{< command >}}
tdl chat ls -o json
{{< /command >}}

过滤器 Copy Chapter

请参考 过滤器指南 以获取有关过滤器的基本知识。

列出所有可用的过滤字段：

{{< command >}}
tdl chat ls -f -
{{< /command >}}

列出名字包含 "Telegram" 的频道：

{{< command >}}
tdl chat ls -f "Type contains 'channel' && VisibleName contains 'Telegram'"
{{< /command >}}

列出具有主题的群组：

{{< command >}}
tdl chat ls -f "len(Topics)>0"
{{< /command >}}

---

Content/Zh/Guide/Download Copy Section

---
title: "下载"
weight: 30
---

下载

从链接下载： Copy Chapter

{{< hint info >}}
点击官方客户端的 "复制链接" 按钮获取消息链接。
{{< /hint >}}

{{< include "snippets/link.md" >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2
{{< /command >}}

从 JSON 下载： Copy Chapter

有两种导出 JSON 文件的方式：

{{< tabs "json" >}}
{{< tab "tdl" >}}
请参考 导出消息
{{< /tab >}}

{{< tab "桌面客户端" >}}

1. 选择要导出的对话，点击右上角的三个点，然后点击 导出聊天历史。
2. 取消选中所有选项（您现在不需要下载它们），将 大小限制 设置为最小值。
3. 设置格式为 JSON 并选择您需要的时间段。
4. 导出它！result.json 就是您需要的文件。
{{< /tab >}}
{{< /tabs >}}

{{< command >}}
tdl dl -f result1.json -f result2.json
{{< /command >}}

合并下载： Copy Chapter

{{< command >}}
tdl dl \
-u https://t.me/tdl/1 -u https://t.me/tdl/2 \
-f result1.json -f result2.json
{{< /command >}}

自定义目录： Copy Chapter

将文件下载到自定义目录

{{< command >}}
tdl dl -u https://t.me/tdl/1 -d /path/to/dir
{{< /command >}}

自定义参数： Copy Chapter

使用每个任务8个线程，4个并发任务下载：

{{< command >}}
tdl dl -u https://t.me/tdl/1 -t 8 -l 4
{{< /command >}}

反序下载： Copy Chapter

按反序下载文件（从最新到最旧）

{{< hint warning >}}
不同的顺序将影响“恢复下载”功能
{{< /hint >}}

{{< command >}}
tdl dl -f result.json --desc
{{< /command >}}

MIME 探测： Copy Chapter

如果文件扩展名与 MIME 类型不匹配，tdl将使用正确的扩展名重命名文件。

{{< hint warning >}}
副作用：例如 .apk 文件将被重命名为 .zip。
{{< /hint >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 --rewrite-ext
{{< /command >}}

相册/组合消息探测 Copy Chapter

自动检测消息是否为相册/组合消息，并下载相应的所有文件。

{{< command >}}
tdl dl -u https://t.me/tdl/1 --group
{{< /command >}}

自动跳过 Copy Chapter

在下载时跳过相同的文件（即名称和大小相同）。

{{< command >}}
tdl dl -u https://t.me/tdl/1 --skip-same
{{< /command >}}

"Takeout" 会话 Copy Chapter

通过 "Takeout" 会话 下载文件：

如果下载大量媒体，更倾向于使用 "Takeout" 会话，它允许您以较低的速率限制从您的帐户中导出数据。

{{< command >}}
tdl dl -u https://t.me/tdl/1 --takeout
{{< /command >}}

过滤器 Copy Chapter

使用扩展名过滤器下载文件：

{{< hint warning >}}
扩展名仅与文件名匹配，而不是 MIME 类型。因此，这可能不会按预期工作。

白名单和黑名单不能同时使用。
{{< /hint >}}

白名单：只下载扩展名为 .jpg .png 的文件

{{< command >}}
tdl dl -u https://t.me/tdl/1 -i jpg,png
{{< /command >}}

黑名单：下载除了扩展名为 .mp4 .flv 的所有文件

{{< command >}}
tdl dl -u https://t.me/tdl/1 -e mp4,flv
{{< /command >}}

文件名模板 Copy Chapter

使用自定义文件名模板下载：

请参考 模板指南 了解更多。

{{< command >}}
tdl dl -u https://t.me/tdl/1 \
--template "{{ .DialogID }}_{{ .MessageID }}_{{ .DownloadDate }}_{{ .FileName }}"
{{< /command >}}

恢复/重新开始下载 Copy Chapter

在不需要交互的情况下恢复下载：

{{< command >}}
tdl dl -u https://t.me/tdl/1 --continue
{{< /command >}}

在不需要交互的情况下重新开始下载：

{{< command >}}
tdl dl -u https://t.me/tdl/1 --restart
{{< /command >}}

HTTP 文件服务器 Copy Chapter

将文件暴露为 HTTP 服务器，而不使用内置下载它们

{{< hint info >}}
当您想要使用下载管理器（如 aria2/wget/axel/IDM）下载文件时，适合使用此选项。
{{< /hint >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 --serve
{{< /command >}}

使用自定义端口：

{{< command >}}
tdl dl -u https://t.me/tdl/1 --serve --port 8081
{{< /command >}}

---

Content/Zh/Guide/Extensions Copy Section

---
title: "扩展 🆕"
weight: 70
---

扩展

{{< hint warning >}}
扩展是 tdl 的一项新功能，仍处于实验阶段，CLI 可能会在未来版本中发生变化。

如果你遇到任何问题或有任何建议，请在 GitHub 上创建 Issue。
{{< /hint >}}

概览 Copy Chapter

tdl 扩展是与 tdl 核心无缝集成的独立工具。它们提供了一种扩展 tdl 核心的方法，但不需要将每个新功能添加到核心代码中。

tdl 扩展具有以下特点：

- 它们可以添加和删除，而不会影响 tdl 核心。
- 它们与 tdl 集成，并会显示在 tdl 命令和其他地方。

tdl 扩展位于 ~/.tdl/extensions，由 tdl extension 子命令控制。

使用以下命令快速体验 tdl 扩展：

{{< command >}}
tdl extension install iyear/tdl-whoami
{{< /command >}}

{{< command >}}
tdl whoami
{{< /command >}}

你可以看到 tdl-whoami 扩展的输出。详情请参阅 tdl-whoami。

You are XXXXX. ID: XXXXXXXX

查找扩展 Copy Chapter

你可以通过浏览带有 tdl-extension 主题的代码库来查找扩展。

安装扩展 Copy Chapter

要安装扩展，请使用 extension install 子命令。

扩展有两种类型：

- GitHub : 托管在 GitHub 代码库上的扩展。

{{< command >}}
tdl extension install <owner>/<repo>
{{< /command >}}

要从私有代码库安装扩展，必须设置 GITHUB_TOKEN 环境变量为 GitHub 个人访问令牌（具有 Contents 读取权限）。

{{< command >}}
export GITHUB_TOKEN=YOUR_TOKEN
tdl extension install <owner>/<private-repo>
{{< /command >}}

- Local : 存储在本地计算机上的扩展。

{{< command >}}
tdl extension install /path/to/extension
{{< /command >}}

强制安装已经存在的扩展，请使用 --force 选项：

{{< command >}}
tdl extension install --force EXTENSION
{{< /command >}}

一次安装多个扩展，请使用以下命令：

{{< command >}}
tdl extension install <owner>/<repo1> /path/to/extension2 ...
{{< /command >}}

仅打印信息而不实际安装扩展，请使用 --dry-run 选项：

{{< command >}}
tdl extension install --dry-run EXTENSION
{{< /command >}}

如果你已经安装了同名的扩展，安装将失败。例如，如果你已经安装了 foo/tdl-whoami，则必须在安装 bar/tdl-whoami 之前卸载它。

运行扩展 Copy Chapter

安装扩展后，可以像运行本地 tdl 命令一样运行扩展，使用 tdl EXTENSION-NAME。EXTENSION-NAME 是包含扩展的代码库的名称，去掉 tdl- 前缀。

例如，如果你从 iyear/tdl-whoami 代码库安装了扩展，可以使用以下命令运行扩展。

{{< command >}}
tdl whoami
{{< /command >}}

运行扩展时，全局配置仍然可用。例如，以下命令在运行 tdl-whoami 扩展时指定命名空间和代理。

{{< command >}}
tdl -n foo --proxy socks5://localhost:1080 whoami
{{< /command >}}

扩展自身的选项也可以使用。例如，以下命令在运行 tdl-whoami 扩展时启用详细模式。

{{< hint info >}}
请记住在扩展子命令之前写全局选项，在扩展子命令之后写扩展选项：
{{< command >}}
tdl <全局选项> <扩展名> <扩展选项>
{{< /command >}}

{{< /hint >}}

{{< command >}}
tdl -n foo whoami -v
{{< /command >}}

通常可以在包含扩展的代码库的 README 中找到有关如何使用扩展的具体信息。

查看已安装的扩展 Copy Chapter

要查看所有已安装的扩展，请使用 extension list 子命令。此命令将列出所有已安装的扩展及其作者和版本。

{{< command >}}
tdl extension list
{{< /command >}}

更新扩展 Copy Chapter

要更新扩展，请使用 extension upgrade 子命令。将 EXTENSION 参数替换为扩展的名称。

{{< command >}}
tdl extension upgrade EXTENSION1 EXTENSION2 ...
{{< /command >}}

更新所有已安装的扩展，请设置 EXTENSION 参数为空。

{{< command >}}
tdl extension upgrade
{{< /command >}}

从 GitHub 私有代码库升级扩展，必须设置 GITHUB_TOKEN 环境变量为 GitHub 个人访问令牌（具有 Contents 读取权限）。

{{< command >}}
export GITHUB_TOKEN=YOUR_TOKEN
tdl extension upgrade EXTENSION
{{< /command >}}

仅打印信息而不实际升级扩展，请使用 --dry-run 选项：

{{< command >}}
tdl extension upgrade --dry-run EXTENSION
{{< /command >}}

卸载扩展 Copy Chapter

要卸载扩展，请使用 extension remove 子命令。将 EXTENSION 参数替换为扩展的名称。

{{< command >}}
tdl extension remove EXTENSION1 EXTENSION2 ...
{{< /command >}}

仅打印信息而不实际卸载扩展，请使用 --dry-run 选项：

{{< command >}}
tdl extension remove --dry-run EXTENSION
{{< /command >}}

开发扩展 Copy Chapter

请参阅 tdl-extension-template 代码库，了解如何为 tdl 创建、构建和发布扩展。

---

Content/Zh/Guide/Forward Copy Section

---
title: "转发"
weight: 35
---

转发

具有自动回退和消息路由的转发功能

一行命令将消息从 https://t.me/telegram/193 转发到 收藏夹：

{{< command >}}
tdl forward --from https://t.me/telegram/193
{{< /command >}}

自定义来源 Copy Chapter

{{< include "snippets/link.md" >}}

您可以从链接和导出的JSON文件转发消息：

{{< command >}}
tdl forward \
--from https://t.me/telegram/193 \
--from https://t.me/telegram/195 \
--from tdl-export.json \
--from tdl-export2.json
{{< /command >}}

自定义目标 Copy Chapter

{{< include "snippets/chat.md" >}}

特定聊天 Copy Section

转发到特定的聊天：

{{< command >}}
tdl forward --from tdl-export.json --to CHAT
{{< /command >}}

消息路由 Copy Section

通过基于 expr 的路由将消息转发至不同的聊天

列出所有可用的字段：

{{< command >}}
tdl forward --from tdl-export.json --to -
{{< /command >}}

如果消息包含 foo，则转发到 CHAT1，否则转发到 收藏夹：

{{< hint info >}}
表达式必须返回一个字符串或者结构体作为目标 CHAT，空字符串表示转发到 收藏夹。
{{< /hint >}}

{{< command >}}
tdl forward --from tdl-export.json \
--to 'Message.Message contains "foo" ? "CHAT1" : ""'
{{< /command >}}

转发含有 foo 的消息到 CHAT1，否则转发到 CHAT2 中 ID 为 4 的消息/主题：

{{< command >}}
tdl forward --from tdl-export.json \
--to 'Message.Message contains "foo" ? "CHAT1" : { Peer: "CHAT2", Thread: 4 }'
{{< /command >}}

如果表达式较复杂，你可以传递文件名：

{{< details "router.txt" >}}
你可以像写 switch 一样编写表达式：

Message.Message contains "foo" ? "CHAT1" :
From.ID == 123456 ? "CHAT2" :
Message.Views > 30 ? { Peer: "CHAT3", Thread: 101 } :
""

{{< /details >}}

{{< command >}}
tdl forward --from tdl-export.json --to router.txt
{{< /command >}}

模式 Copy Chapter

消息转发采取自动降级策略

可用模式：
- direct（默认）
- clone

Direct Copy Section

优先使用官方的转发API。

如果聊天或消息不允许使用官方转发API，将自动降级为 clone 模式。

{{< command >}}
tdl forward --from tdl-export.json --mode direct
{{< /command >}}

Clone Copy Section

通过复制方式转发消息，将不包含转发来源的标头。

将自动忽略一些无法复制的消息内容，例如投票、发票等

{{< command >}}
tdl forward --from tdl-export.json --mode clone
{{< /command >}}

编辑 Copy Chapter

使用表达式引擎编辑转发前的消息。

{{< hint info >}}
- 你必须传递合并照片的第一条消息才能编辑标题。
- 你可以传递任何合并文档的消息以编辑相应的评论。
{{< /hint >}}

你可以在表达式中引用原始消息的相关字段。

列出所有可用字段：
{{< command >}}
tdl forward --from tdl-export.json --edit -
{{< /command >}}

在原始消息后附加 测试转发消息：
{{< command >}}
tdl forward --from tdl-export.json --edit 'Message.Message + " 测试转发消息"'
{{< /command >}}

以HTML格式编写带有样式的消息：
{{< command >}}
tdl forward --from tdl-export.json --edit \
'Message.Message + <b>粗体</b> <a href="https://example.com">链接</a>'
{{< /command >}}

如果表达式较复杂，可以传递文件名：

{{< details "edit.txt" >}}

repeat(Message.Message, 2) + 
<a href="https://www.google.com">谷歌</a>
<a href="https://www.bing.com">必应</a>
<b>粗体</b>
<i>斜体</i>
<code>代码</code>
<tg-spoiler>剧透</tg-spoiler>
<pre><code class="language-go">
package main
import "fmt"
func main() {
    fmt.Println("hello world")
}
</code></pre>
 + From.VisibleName

{{< command >}}
tdl forward --from tdl-export.json --edit edit.txt
{{< /command >}}

试运行 Copy Chapter

只打印进度而不实际发送消息，可以用于调试消息路由的效果。

{{< command >}}
tdl forward --from tdl-export.json --dry-run
{{< /command >}}

静默发送 Copy Chapter

发送消息而不通知其他成员。

{{< command >}}
tdl forward --from tdl-export.json --silent
{{< /command >}}

取消分组检测 Copy Chapter

默认情况下，tdl 将自动探测到分组消息并将它们转发为合并的消息。

你可以通过 --single 禁用此行为，将其作为单个消息转发。

{{< command >}}
tdl forward --from tdl-export.json --single
{{< /command >}}

反序 Copy Chapter

对每个来源的消息进行反序转发。

{{< command >}}
tdl forward --from tdl-export.json --desc
{{< /command >}}

---

Content/Zh/Guide/Global Config Copy Section

---
title: "全局设置"
weight: 10
---

全局配置

全局配置是可以在每个命令中设置的选项。

{{< hint info >}}
每次都设置全局配置！

全局配置不代表配置会被持久化或者只需要在全局设置一次，它们只会在当前命令中生效。
你需要在每一个命令中设置它们。
{{< /hint >}}

-n/--ns -n/--ns')" title="Copy chapter prompt for LLMs"> Copy Chapter

每个命名空间代表一个 Telegram 帐号。默认值：default。

例如你想新增一个其他账户，为所有命令都添加 -n YOUR_ACCOUNT_NAME 选项即可：

{{< command >}}
tdl -n iyear
{{< /command >}}

--proxy --proxy')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置代理。默认值：""。

格式：protocol://username:password@host:port

{{< command >}}
tdl --proxy socks5://localhost:1080
tdl --proxy http://localhost:8080
tdl --proxy https://localhost:8081
{{< /command >}}

--storage --storage')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置存储。默认值：type=bolt,path=~/.tdl/data

格式: type=驱动,opt1=val1,opt2=val2,...

可用的驱动：

| 驱动名 | 选项 | 描述 |
|:----------:|:------------------------------:|---------------------------------------------|
| bolt（默认） | path=/path/to/data-directory | 将数据存储在单独的数据库文件中，因此您可以在多个进程中使用（但必须是不同的命名空间）。 |
| file | path=/path/to/data.json | 将数据存储在单个 JSON 文件中，通常用于调试。 |
| legacy | path=/path/to/data.kv | 已弃用。 将数据存储在单个数据库文件中，因此你不能在多个进程中使用它。 |
| - | - | 等待更多驱动... |

{{< command >}}
tdl --storage type=bolt,path=/path/to/data-dir
{{< /command >}}

--ntp --ntp')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置 NTP 服务器。如果为空，将使用系统时间。默认值：""。

{{< command >}}
tdl --ntp pool.ntp.org
{{< /command >}}

--reconnect-timeout --reconnect-timeout')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置 Telegram 连接的重连超时。默认值：2m。

{{< hint info >}}
如果您的网络不稳定，请将超时设置为更长时间或0（无限）。
{{< /hint >}}

{{< command >}}
tdl --reconnect-timeout 1m30s
{{< /command >}}

--debug --debug')" title="Copy chapter prompt for LLMs"> Copy Chapter

启用调试级别日志。默认值：false。

{{< command >}}
tdl --debug
{{< /command >}}

--pool --pool')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置 Telegram 客户端的连接池大小。默认值：8。

{{< hint info >}}
如果你想要更快的速度，请将连接池设置的更大或者0（无限）。
{{< /hint >}}

{{< command >}}
tdl --pool 2
{{< /command >}}

--delay --delay')" title="Copy chapter prompt for LLMs"> Copy Chapter

设置每个任务之间的延迟。默认值：0s。

{{< hint info >}}
如果你想避免因为短时间内产生大量请求被限流，请设置更长的延迟时间。
{{< /hint >}}

{{< command >}}
tdl --delay 5s
{{< /command >}}

--disable-progress-ps --disable-progress-ps')" title="Copy chapter prompt for LLMs"> Copy Chapter

禁用进度条CPU/内存使用统计信息，这可能会在某些终端中导致显示问题。默认值：false。

{{< command >}}
tdl --disable-progress-ps
{{< /command >}}

---

Content/Zh/Guide/Login Copy Section

---
type: "docs"
title: "登录"
weight: 20
bookHref: "/zh/getting-started/quick-start/#login"
---

Login

---

Content/Zh/Guide/Migration Copy Section

---
title: "迁移"
weight: 50
---

迁移

备份或恢复您的数据

备份 Copy Chapter

将您的数据备份到文件中。默认值：<date>.backup.tdl。

{{< command >}}
tdl backup
{{< /command >}}

或者指定输出文件：

{{< command >}}
tdl backup -d /path/to/custom.tdl
{{< /command >}}

恢复 Copy Chapter

从备份文件中恢复您的数据。

{{< command >}}
tdl recover -f /path/to/custom.backup.tdl
{{< /command >}}

迁移 Copy Chapter

将数据迁移到另一个存储中

查看存储以获取存储选项的详细信息。

迁移当前存储到文件类型存储：
{{< command >}}
tdl migrate --to type=file,path=/path/to/data.json
{{< /command >}}

迁移自定义存储到文件类型存储：
{{< command >}}
tdl migrate --storage type=bolt,path=/path/to/data-directory --to type=file,path=/path/to/data.json
{{< /command >}}

---

Content/Zh/Guide/Template Copy Section

---
title: "模板指南"
bookHidden: true
bookToC: false
---

模板指南

本指南将介绍可用于 tdl 模板中的变量和函数。

模板语法基于Go text/template。

下载 Copy Chapter

变量 (Beta) Copy Section

| 变量 | 描述 |
|:--------------:|:---------------------:|
| DialogID | Telegram 对话ID |
| MessageID | Telegram 消息ID |
| MessageDate | Telegram 消息日期（时间戳） |
| FileName | Telegram 文件名 |
| FileCaption | Telegram 文件说明，也就是文本消息 |
| FileSize | 可读的文件大小，例如 1GB |
| DownloadDate | 下载日期（时间戳） |

函数 (Beta) Copy Section

| 函数 | 描述 | 用法 | 示例 |
|:------------:|:------------------------------------------------------------------------------------------:|:------------------------------------------------------------:|:-------------------------------------------------------------------------------------:|
| repeat | 重复 STRING N 次 | repeat STRING N | {{ repeat "test" 3 }} |
| replace | 对 STRING 执行 PAIRS 替换 | replace STRING PAIRS... | {{ replace "Test" "t" "T" "e" "E" }} |
| upper | 将 STRING 转换为大写 | upper STRING | {{ upper "Test" }} |
| lower | 将 STRING 转换为小写 | lower STRING | {{ lower "Test" }} |
| snakecase | 将 STRING 转换为 snake_case | snakecase STRING | {{ snakecase "Test" }} |
| camelcase | 将 STRING 转换为 camelCase | camelcase STRING | {{ camelcase "Test" }} |
| kebabcase | 将 STRING 转换为 kebab-case | kebabcase STRING | {{ kebabcase "Test" }} |
| rand | 在范围 MIN 到 MAX 生成随机数 | rand MIN MAX | {{ rand 1 10 }} |
| now | 获取当前时间戳 | now | {{ now }} |
| formatDate | 格式化 TIMESTAMP 时间戳<br/>(默认格式: 20060102150405) | formatDate TIMESTAMP <br/> formatDate TIMESTAMP "format" | {{ formatDate 1600000000 }}<br/> {{ formatDate 1600000000 "2006-01-02-15-04-05"}} |
| filenamify | 尽可能将 STRING 转换为合法文件名，可选 MaxLength 限制字符串长度避免文件系统限制 | filenamify STRING MaxLength | {{ filenamify .FileName 32 }} |

示例： Copy Section

{{ .DialogID }}_{{ .MessageID }}_{{ replace .FileCaption / _ \ _ : _ }}
{{ .FileName }}_{{ formatDate .DownloadDate }}_{{ .FileSize }}
{{ .FileName }}_{{ formatDate .DownloadDate "2006-01-02-15-04-05"}}_{{ .FileSize }}
{{ lower (replace .FileName   _) }}
{{ formatDate (now) }}

默认： Copy Section

{{ .DialogID }}_{{ .MessageID }}_{{ filenamify .FileName }}

---

Content/Zh/Guide/Upload Copy Section

---
title: "上传"
weight: 40
---

上传

上传文件 Copy Chapter

上传指定的文件和目录到 保存的消息：

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir
{{< /command >}}

自定义目标 Copy Chapter

上传到自定义聊天。

{{< include "snippets/chat.md" >}}

指定聊天 Copy Chapter

上传到指定的聊天：

{{< command >}}
tdl up -p /path/to/file -c CHAT
{{< /command >}}

上传到论坛型聊天的指定主题：

{{< command >}}
tdl up -p /path/to/file -c CHAT --topic TOPIC_ID
{{< /command >}}

消息路由 Copy Chapter

通过基于表达式的消息路由，将文件上传到不同的聊天：

{{< hint warning >}}
--to 标志与 -c/--chat 和 --topic 标志冲突，只能使用其中一个。
{{< /hint >}}

列出所有可用字段：

{{< command >}}
tdl up -p /path/to/file --to -
{{< /command >}}

如果 MIME 包含 video 则上传到 CHAT1，否则上传到 收藏夹：

{{< hint info >}}
必须返回一个字符串或结构体作为目标聊天，空字符串表示上传到 收藏夹。
{{< /hint >}}

{{< command >}}
tdl up -p /path/to/file \
--to 'MIME contains "video" ? "CHAT1" : ""'
{{< /command >}}

如果 MIME 包含 video 则上传到 CHAT1，否则回复 CHAT2 的消息/主题 4：

{{< command >}}
tdl up -p /path/to/file \
--to 'MIME contains "video" ? "CHAT1" : { Peer: "CHAT2", Thread: 4 }'
{{< /command >}}

如果表达式较复杂，可以传递文件名：

{{< details "router.txt" >}}
像使用 switch 一样编写表达式：

MIME contains "video" ? "CHAT1" :
FileExt contains ".mp3" ? "CHAT2" :
FileName contains "chat3" > 30 ? {Peer: "CHAT3", Thread: 101} :
""

{{< /details >}}

{{< command >}}
tdl up -p /path/to/file --to router.txt
{{< /command >}}

自定义参数 Copy Chapter

使用每个任务8个线程、4个并发任务上传：

{{< command >}}
tdl up -p /path/to/file -t 8 -l 4
{{< /command >}}

自定义标题 Copy Chapter

使用表达式引擎编写自定义标题。

列出所有可用字段：

{{< command >}}
tdl up -p /path/to/file --caption -
{{< /command >}}

自定义简单的标题：
{{< command >}}
tdl up -p ./path/to/file --caption 'FileName + " - uploaded by tdl"'
{{< /command >}}

以HTML格式编写带有样式的消息：
{{< command >}}
tdl up -p /path/to/file --caption \
'FileName + <b>Bold</b> <a href="https://example.com">Link</a>'
{{< /command >}}

如果表达式较复杂，可以传递文件名：

{{< details "caption.txt" >}}

repeat(FileName, 2) + 
<a href="https://www.google.com">Google</a>
<a href="https://www.bing.com">Bing</a>
<b>bold</b>
<i>italic</i>
<code>code</code>
<tg-spoiler>spoiler</tg-spoiler>
<pre><code class="language-go">
package main
import "fmt"
func main() {
    fmt.Println("hello world")
}
</code></pre>
 + MIME

{{< /details >}}

{{< command >}}
tdl up -p /path/to/file --caption caption.txt
{{< /command >}}

过滤器 Copy Chapter

使用扩展名过滤器上传文件：

{{< hint warning >}}
扩展名仅与文件名匹配，而不是 MIME 类型。因此，这可能不会按预期工作。

白名单和黑名单不能同时使用。
{{< /hint >}}

白名单：只上传扩展名为 .jpg .png 的文件

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir -i jpg,png
{{< /command >}}

黑名单：上传除了扩展名为 .mp4 .flv 的所有文件

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir -e mp4 -e flv
{{< /command >}}

自动删除 Copy Chapter

删除已上传成功的文件：

{{< command >}}
tdl up -p /path/to/file --rm
{{< /command >}}

照片 Copy Chapter

将图像作为照片而不是文件上传：

{{< command >}}
tdl up -p /path/to/file --photo
{{< /command >}}

---

Content/Zh/More/Env Copy Section

---
title: "环境变量"
weight: 20
---

环境变量

{{< hint info >}}
所有环境变量的值优先级低于命令行选项。
{{< /hint >}}

通过设置环境变量，避免在每次重复输入相同的命令行选项。

| 环境变量 | 对应选项 |
|:-------------------------:|:-----------------------:|
| TDL_NS | -n/--ns |
| TDL_PROXY | --proxy |
| TDL_STORAGE | --storage |
| TDL_DEBUG | --debug |
| TDL_SIZE | -s/--size |
| TDL_THREADS | -t/--threads |
| TDL_LIMIT | -l/--limit |
| TDL_POOL | --pool |
| TDL_NTP | --ntp |
| TDL_RECONNECT_TIMEOUT | --reconnect-timeout |
| TDL_DISABLE_PROGRESS_PS | --disable-progress-ps |
| TDL_TEMPLATE | dl --template |

{{< hint warning >}}
- TDL_STORAGE 环境变量的格式与命令行选项不同：{"type": "bolt", "path": "/path/to/data-dir"} (JSON 对象)。
{{< /hint >}}

---

Content/Zh/More/Troubleshooting Copy Section

---
title: "疑难解答"
weight: 40
---

疑难解答

最佳实践 Copy Chapter

如何减小封号的风险？

- 使用官方客户端会话登录。
- 尽可能使用默认的下载和上传选项。不要设置过大的 threads 和 size。
- 不要同时在多台设备上使用相同的帐户登录。
- 不要同时下载或上传太多文件。
- 成为 Telegram 大会员。😅

常见问题 Copy Chapter

#### Q: 输入命令后为什么没有响应？日志中为什么出现 msg_id too high？

A: 检查是否需要使用代理（使用 --proxy 选项）；检查您系统的本地时间是否正确（使用 --ntp 选项或校准系统时间）

如果仍然无法解决问题，请使用 --debug 标志重新运行。然后创建一个新的 ISSUE 并将日志粘贴到问题中。

#### Q: 使用 tdl 后，桌面客户端停止工作怎么办？

A: 如果您的桌面客户端无法接收消息、加载聊天或发送消息，可能遇到了会话冲突。

您可以尝试使用 tdl login 重新登录，并选择 YES 以退出桌面客户端登录，这将删除客户端会话文件以分离会话。

#### Q: 如何将会话迁移到另一台设备？

A: 您可以使用 tdl backup 和 tdl recover 命令导出和导入会话。详细信息请参见 迁移。

#### Q: 这算滥用吗？

A: 不是。下载和上传速度受服务器端限制。由于官方客户端的速度通常不会达到帐户限制，因此开发了此工具，以尽可能高的速度下载文件。

#### Q: 这会导致封禁吗？

A: 我不确定。所有操作都不涉及向其他人主动发送消息等高风险行为。

---

Content/Zh/Reference/Expr Copy Section

---
title: "表达式指南"
bookHidden: true
---

表达式指南

表达式由 expr 引擎提供支持，它是一个简单、轻量但功能强大的表达式引擎。

表达式引擎文档：https://expr.medv.io/docs/Language-Definition

它功能强大，但对于新用户来说可能有些难以理解。如果您对表达式引擎有任何疑问，请随时提出 ISSUE。

---

Content/Zh/Snippets/Chat Copy Section

---
---

{{< details title="CHAT 示例" open=false >}}

#### 可用值：

- @iyear （用户名）
- iyear （无前缀 @ 的用户名）
- 123456789（ID）
- https://t.me/iyear （公开链接）
- +1 123456789（电话号码）

#### 如何在 Telegram 桌面端获取聊天 ID：

- 设置 → 高级 → 实验性设置 → 在资料中显示对话 ID

{{< /details >}}

---

Content/Zh/Snippets/Link Copy Section

---
---

{{< details title="消息链接示例" open=false >}}

- https://t.me/telegram/193
- https://t.me/c/1697797156/151
- https://t.me/iFreeKnow/45662/55005
- https://t.me/c/1492447836/251015/251021
- https://t.me/opencfdchannel/4434?comment=360409
- https://t.me/myhostloc/1485524?thread=1485523
- ...（如果发现新的链接格式，请提交新的 Issue）

{{< /details >}}

---

Content/Zh/ Index Copy Section

---
title: 介绍
---

tdl

{{< image src="img/logo.png" align="right" height="310" width="310">}}

📥 Telegram Downloader, but more than a downloader

特性 Copy Chapter

- 单文件启动
- 低资源占用
- 吃满你的带宽
- 比官方客户端更快
- 支持从受保护的会话中下载文件
- 具有自动回退和消息路由的转发功能
- 支持上传文件至 Telegram
- 导出历史消息/成员/订阅者数据至 JSON 文件

预览 Copy Chapter

预览中的速度已经达到了代理的限制，同时速度取决于你是否是付费用户

{{< image src="img/preview.gif" >}}

赞助者 Copy Chapter

贡献者 Copy Chapter

---

Content/En/Getting Started/Installation Copy Section

---
title: "Installation"
weight: 10
---

Installation

One-Line Scripts Copy Chapter

{{< tabs "scripts" >}}

{{< tab "Windows" >}}
tdl will be installed to $Env:SystemDrive\tdl(will be added to PATH), and script also can be used to upgrade tdl
.

#### Install latest version

{{< command >}}
iwr -useb https://docs.iyear.me/tdl/install.ps1 | iex
{{< /command >}}

#### Install with ghproxy.com

{{< command >}}
$Script=iwr -useb https://docs.iyear.me/tdl/install.ps1;
$Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "", "$True"
{{< /command >}}

#### Install specific version

{{< command >}}
$Env:TDLVersion = "VERSION"
$Script=iwr -useb https://docs.iyear.me/tdl/install.ps1;
$Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "$Env:TDLVersion"
{{< /command >}}

{{< /tab >}}

{{< tab "macOS & Linux" >}}
tdl will be installed to /usr/local/bin/tdl, and script also can be used to upgrade tdl.

#### Install latest version

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash
{{< /command >}}

#### Install with ghproxy.com

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash -s -- --proxy
{{< /command >}}

#### Install specific version

{{< command >}}
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash -s -- --version VERSION
{{< /command >}}

{{< /tab >}}
{{< /tabs >}}

Package Managers Copy Chapter

{{< tabs "package managers" >}}

{{<tab "Homebrew" >}}
{{< command >}}
brew install telegram-downloader
{{< /command >}}
{{< /tab >}}

{{<tab "Scoop" >}}
{{< command >}}
scoop bucket add extras
scoop install telegram-downloader
{{< /command >}}
{{< /tab >}}

{{<tab "Termux" >}}
{{< command >}}
pkg install tdl
{{< /command >}}
{{< /tab >}}

{{<tab "AUR" >}}
{{< command >}}
yay -S tdl
{{< /command >}}
{{< /tab >}}

{{<tab "Nix" >}}

#### nix-env
{{< command >}}
nix-env -iA nixos.tdl
{{< /command >}}

#### NixOS-Configuration

environment.systemPackages = [
    pkgs.tdl
];

#### nix-shell
{{< command >}}
nix-shell -p tdl
{{< /command >}}

{{< /tab >}}

{{< /tabs >}}

[](https://repology.org/project/telegram-downloader/versions)

Docker Copy Chapter

Available images:
- iyear/tdl
- ghcr.io/iyear/tdl

Available tags:
- latest(default): The latest stable release
- X.Y.Z: A specific version of tdl

{{< tabs "docker" >}}
{{< tab "Docker" >}}

To run tdl in one-off command:
{{< command >}}
docker run --rm -it iyear/tdl <ARGUMENTS>
{{< /command >}}

Further, to keep config persistent, you can mount the config directory:
{{< command >}}
docker run --rm -it \
-v $HOME/.tdl:/root/.tdl \
iyear/tdl <ARGUMENTS>
{{< /command >}}

To get download files, you can mount the download and other directories as needed:
{{< command >}}
docker run --rm -it \
-v $HOME/.tdl:/root/.tdl \
-v $HOME/Downloads:/downloads \
iyear/tdl <ARGUMENTS>
{{< /command >}}

To run tdl inside the container shell:
{{< command >}}
docker run --rm -it <FLAGS> --entrypoint sh iyear/tdl
{{< /command >}}
{{< details title="Preview output" open=false >}}

/ # tdl version
Version: 0.17.7
Commit: ace2402
Date: 2024-11-01T14:40:56+08:00
go1.21.13 linux/amd64
/ #

To use proxy with localhost address, run it with host network:
{{< command >}}
docker run --rm -it <FLAGS> --network host iyear/tdl <ARGUMENTS>
{{< /command >}}
{{< /tab >}}

{{< tab "Docker Compose" >}}
Run tdl with Docker Compose to avoid typing docker run flags each time.

{{< details title="docker-compose.yml" open=false >}}
{{< hint info >}}
Example configuration uses Docker Compose v2 syntax.
{{< /hint >}}

services:
  tdl:
    image: iyear/tdl # or specify X.Y.Z tag for a specific version
    volumes:
      - $HOME/.tdl:/root/.tdl # keep config persistent
      - $HOME/Downloads:/downloads # optional
      # - /path/to/your/need:/path/in/container
    stdin_open: true
    tty: true
    # use host network if you need to use proxy with localhost address
    network_mode: host

Run tdl with Docker Compose:
{{< command >}}
docker compose run --rm tdl <ARGUMENTS>
{{< /command >}}

To run tdl inside the container shell:
{{< command >}}
docker compose run --rm --entrypoint sh tdl
{{< /command >}}
{{< details title="Preview output" open=false >}}

/ # tdl version
Version: 0.17.7
Commit: ace2402
Date: 2024-11-01T14:40:56+08:00
go1.21.13 linux/amd64
/ #

{{< /tab >}}
{{< /tabs >}}

Prebuilt Binaries Copy Chapter

1. Download the archive for the desired operating system, and architecture:

{{< tabs "prebuilt" >}}
{{< tab "Windows" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_64bit.zip" >}}x86_64/amd64{{<
/button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_32bit.zip" >}}x86{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_arm64.zip" >}}arm64{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv5.zip" >}}armv5{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv6.zip" >}}armv6{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Windows_armv7.zip" >}}armv7{{< /button >}}
{{< /tab >}}

{{< tab "macOS" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_MacOS_64bit.tar.gz" >}}Intel{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_MacOS_arm64.tar.gz" >}}M1/M2{{< /button >}}
{{< /tab >}}

{{< tab "Linux" >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_64bit.tar.gz" >}}x86_64/amd64{{<
/button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_32bit.tar.gz" >}}x86{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_arm64.tar.gz" >}}arm64{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv5.tar.gz" >}}armv5{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv6.tar.gz" >}}armv6{{< /button >}}
{{< button href="https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_armv7.tar.gz" >}}armv7{{< /button >}}
{{< /tab >}}
{{< /tabs >}}

2. Extract the archive
3. Move the executable to the desired directory
4. Add this directory to the PATH environment variable
5. Verify that you have execute permission on the file

Source Copy Chapter

To build the extended edition of tdl from source you must:

1. Install Git
2. Install Go version 1.25 or later
3. Update your PATH environment variable as described in the Go documentation

{{< hint info >}}
The installation directory is controlled by the GOPATH and GOBIN environment variables. If GOBIN is set, binaries
are installed to that directory. If GOPATH is set, binaries are installed to the bin subdirectory of the first
directory in the GOPATH list. Otherwise, binaries are installed to the bin subdirectory of the
default GOPATH ($HOME/go or %USERPROFILE%\go).
{{< /hint >}}

Then build:

{{< command >}}
go install github.com/iyear/tdl@latest
tdl version
{{< /command >}}

---

Content/En/Getting Started/Quick Start Copy Section

---
title: "Quick Start"
weight: 20
---

Quick Start

Login Copy Chapter

We don't specify the namespace here, so it will use the default namespace. You can specify the namespace with
-n flag if you want to use another namespace.

Login with desktop clients Copy Section

{{< hint warning >}}
Please ensure that clients are downloaded from official website (NOT from Microsoft
Store or App Store)
{{< /hint >}}

Automatically find the client path:

{{< command >}}
tdl login
{{< /command >}}

Or if you set a local passcode:

{{< command >}}
tdl login -p YOUR_PASSCODE
{{< /command >}}

Or specify custom client path:

{{< command >}}
tdl login -d /path/to/TelegramDesktop
{{< /command >}}

Login with QR code Copy Section

{{< command >}}
tdl login -T qr
{{< /command >}}

Login with phone & code Copy Section

{{< command >}}
tdl login -T code
{{< /command >}}

Download Copy Chapter

We download media from Telegram official channel:

{{< command >}}
tdl dl -u https://t.me/telegram/193
{{< /command >}}

---

Content/En/Getting Started/Shell Completion Copy Section

---
title: "Shell Completion"
weight: 30
---

Shell Completion

Run corresponding command to enable shell completion in all sessions:

{{< tabs "shell" >}}
{{< tab "bash" >}}

{{< command >}}
echo "source <(tdl completion bash)" >> ~/.bashrc
{{< /command >}}

{{< /tab >}}

{{< tab "zsh" >}}

{{< command >}}
echo "source <(tdl completion zsh)" >> ~/.zshrc
{{< /command >}}

{{< /tab >}}

{{< tab "fish" >}}

{{< command >}}
echo "tdl completion fish | source" >> ~/.config/fish/config.fish
{{< /command >}}

{{< /tab >}}

{{< tab "PowerShell" >}}

{{< command >}}
Add-Content -Path $PROFILE -Value "tdl completion powershell | Out-String | Invoke-Expression"
{{< /command >}}

{{< /tab >}}
{{< /tabs >}}

---

Content/En/Guide/Tools/Export Members Copy Section

---
title: "Export Members"
weight: 20
---

Export Members

Export chat members/subscribers, admins, bots, etc.

{{< hint info >}}
Chat administrator permission is required for some types of members(kicked, banned, etc.).
{{< /hint >}}

{{< include "snippets/chat.md" >}}

All Copy Chapter

Export all users to tdl-users.json

{{< command >}}
tdl chat users -c CHAT
{{< /command >}}

Custom Destination Copy Chapter

Export with specified file path

{{< command >}}
tdl chat users -c CHAT -o /path/to/export.json
{{< /command >}}

Raw Copy Chapter

Export Telegram MTProto raw user structure, which is useful for debugging.

{{< command >}}
tdl chat users -c CHAT --raw
{{< /command >}}

---

Content/En/Guide/Tools/Export Messages Copy Section

---
title: "Export Messages"
weight: 30
---

Export Messages

Export media messages from chats, channels, groups, etc. in JSON format.

{{< include "snippets/chat.md" >}}

{{< hint info >}}
Empty CHAT means 'Saved Messages'
{{< /hint >}}

All Copy Chapter

Export all messages containing media to tdl-export.json

{{< command >}}
tdl chat export -c CHAT
{{< /command >}}

From Topic/Replies Copy Chapter

Export media messages from specific topic:
{{< hint info >}}
Get Topic ID:

1. Message Link: https://t.me/c/1492447836/251011/269724 (251011 is topic id)
2. tdl chat ls command
{{< /hint >}}

{{< command >}}
tdl chat export -c CHAT --topic TOPIC_ID
{{< /command >}}

Export media messages from specific channel post replies:

{{< command >}}
tdl chat export -c CHAT --reply POST_ID
{{< /command >}}

Custom Destination Copy Chapter

Export with specific output file path. Default: tdl-export.json.

{{< command >}}
tdl chat export -c CHAT -o /path/to/output.json
{{< /command >}}

Custom Type Copy Chapter

Time Range Copy Section

Export with specific timestamp range. Default: 1970-01-01 - NOW

{{< command >}}
tdl chat export -c CHAT -T time -i 1665700000,1665761624
{{< /command >}}

time is also the default value of -T option, so you can omit it

{{< command >}}
tdl chat export -c CHAT -i 1665700000,1665761624
{{< /command >}}

ID Range Copy Section

Export with specific message id range. Default: 0 - latest

{{< command >}}
tdl chat export -c CHAT -T id -i 100,500
{{< /command >}}

Last Copy Section

Export last 100 media messages:

{{< command >}}
tdl chat export -c CHAT -T last -i 100
{{< /command >}}

Filter Copy Chapter

Please refer to Filter Guide for basic knowledge about filter.

List all available filter fields:

{{< command >}}
tdl chat export -c CHAT -f -
{{< /command >}}

Export last 10 zip files that size > 5MiB and views > 200:

{{< command >}}
tdl chat export -c CHAT -T last -i 10 -f "Views>200 && Media.Name endsWith '.zip' && Media.Size > 510241024"
{{< /command >}}

With Content Copy Chapter

Export with message content:

{{< command >}}
tdl chat export -c CHAT --with-content
{{< /command >}}

Raw Copy Chapter

Export Telegram MTProto raw message structure, which is useful for debugging.

{{< command >}}
tdl chat export -c CHAT --raw
{{< /command >}}

Non-Media Copy Chapter

Export all messages including non-media messages, which is useful for debugging/backup.

{{< command >}}
tdl chat export -c CHAT --all
{{< /command >}}

---

Content/En/Guide/Tools/List Chats Copy Section

---
title: "List Chats"
weight: 10
---

List Chats

List all chats Copy Chapter

{{< command >}}
tdl chat ls
{{< /command >}}

JSON Output Copy Chapter

{{< command >}}
tdl chat ls -o json
{{< /command >}}

Filter Copy Chapter

Please refer to Filter Guide for basic knowledge about filter.

List all available filter fields:

{{< command >}}
tdl chat ls -f -
{{< /command >}}

List channels that VisibleName contains "Telegram":

{{< command >}}
tdl chat ls -f "Type contains 'channel' && VisibleName contains 'Telegram'"
{{< /command >}}

List groups that have topics:

{{< command >}}
tdl chat ls -f "len(Topics)>0"
{{< /command >}}

---

Content/En/Guide/Download Copy Section

---
title: "Download"
weight: 30
---

Download

From Links: Copy Chapter

{{< hint info >}}
Get message links from "Copy Link" button in official clients.
{{< /hint >}}

{{< include "snippets/link.md" >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2
{{< /command >}}

From JSON: Copy Chapter

There are two ways to export the JSON you need:

{{< tabs "json" >}}
{{< tab "tdl" >}}
This is especially for protected chats and more powerful than the desktop client.

Please refer to Export Messages
{{< /tab >}}

{{< tab "Desktop Client" >}}

1. Choose the dialog you want to export, and click the three dots in the upper right corner, then
click Export Chat History.
2. Uncheck all boxes(you don't need to download them now) and set Size Limit to minimum
3. Set Format to JSON and select the time period you need.
4. Export it! And result.json is what you need.
{{< /tab >}}
{{< /tabs >}}

{{< command >}}
tdl dl -f result1.json -f result2.json
{{< /command >}}

Combine Sources: Copy Chapter

{{< command >}}
tdl dl \
-u https://t.me/tdl/1 -u https://t.me/tdl/2 \
-f result1.json -f result2.json
{{< /command >}}

Custom Destination: Copy Chapter

Download files to custom directory

{{< command >}}
tdl dl -u https://t.me/tdl/1 -d /path/to/dir
{{< /command >}}

Custom Parameters: Copy Chapter

Download with 8 threads per task, 4 concurrent tasks:

{{< command >}}
tdl dl -u https://t.me/tdl/1 -t 8 -l 4
{{< /command >}}

Descending Order: Copy Chapter

Download files in descending order(from newest to oldest)

{{< hint warning >}}
Different order will affect resuming download
{{< /hint >}}

{{< command >}}
tdl dl -f result.json --desc
{{< /command >}}

MIME Detection: Copy Chapter

If the file extension is not matched with the MIME type, tdl will rename the file with the correct extension.

{{< hint warning >}}
Side effect: like .apk file, it will be renamed to .zip.
{{< /hint >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 --rewrite-ext
{{< /command >}}

Album/Grouped Detection Copy Chapter

Automatically detect if the message is an album/grouped message and download all of them.

{{< command >}}
tdl dl -u https://t.me/tdl/1 --group
{{< /command >}}

Auto Skip Copy Chapter

Skip the same files(name and size) when downloading.

{{< command >}}
tdl dl -u https://t.me/tdl/1 --skip-same
{{< /command >}}

Takeout Session Copy Chapter

Download files
with takeout session:

If you plan to download a lot of media, you may prefer to do this within a takeout session. Takeout sessions let you

export data from your account with lower flood wait limits.

{{< command >}}
tdl dl -u https://t.me/tdl/1 --takeout
{{< /command >}}

Filters Copy Chapter

Download files with extension filters:

{{< hint warning >}}
The extension is only matched with the file name, not the MIME type. So it may not work as expected.

Whitelist and blacklist can not be used at the same time.
{{< /hint >}}

Whitelist: Only download files with .jpg .png extension

{{< command >}}
tdl dl -u https://t.me/tdl/1 -i jpg,png
{{< /command >}}

Blacklist: Download all files except .mp4 .flv extension

{{< command >}}
tdl dl -u https://t.me/tdl/1 -e mp4,flv
{{< /command >}}

Name Template Copy Chapter

Download with custom file name template:

Please refer to Template Guide for more details.

{{< command >}}
tdl dl -u https://t.me/tdl/1 \
--template "{{ .DialogID }}_{{ .MessageID }}_{{ .DownloadDate }}_{{ .FileName }}"
{{< /command >}}

Resume/Restart Copy Chapter

Resume without UI interaction:

{{< command >}}
tdl dl -u https://t.me/tdl/1 --continue
{{< /command >}}

Restart without UI interaction:

{{< command >}}
tdl dl -u https://t.me/tdl/1 --restart
{{< /command >}}

Serve Copy Chapter

Expose the files as an HTTP server instead of downloading them with built-in downloader

{{< hint info >}}
This is useful when you want to download files with a download manager like aria2/wget/axel/IDM...
{{< /hint >}}

{{< command >}}
tdl dl -u https://t.me/tdl/1 --serve
{{< /command >}}

With custom port:

{{< command >}}
tdl dl -u https://t.me/tdl/1 --serve --port 8081
{{< /command >}}

---

Content/En/Guide/Extensions Copy Section

---
title: "Extensions 🆕"
weight: 70
---

Extensions

{{< hint warning >}}
Extensions are a new feature in tdl. They are still in the experimental stage, and the CLI may change in future versions.

If you encounter any problems or have any suggestions, please open an issue on GitHub.
{{< /hint >}}

Overview Copy Chapter

tdl extensions are add-on tools that integrate seamlessly with tdl. They provide a way to extend the core feature set of tdl, but without requiring every new feature to be added to the core.

tdl extensions have the following features:

- They can be added and removed without impacting the core tdl tool.
- They integrate with tdl, and will show up in tdl help and other places.

tdl extensions live in ~/.tdl/extensions, which is controlled by tdl extension commands.

To get started with extensions, you can use the following commands:

{{< command >}}
tdl extension install iyear/tdl-whoami
{{< /command >}}

{{< command >}}
tdl whoami
{{< /command >}}

You can see the output of the tdl-whoami extension. Refer to the tdl-whoami for details.

You are XXXXX. ID: XXXXXXXX

Finding extensions Copy Chapter

You can find extensions by browsing repositories with the tdl-extension topic.

Installing extensions Copy Chapter

To install an extension, use the extension install subcommand.

There are two types of extensions:

- GitHub : Extensions hosted on GitHub repositories.

{{< command >}}
tdl extension install <owner>/<repo>
{{< /command >}}

To install an extension from a private repository, you must set up a GitHub personal access token(with Contents read permission) in your environment with the GITHUB_TOKEN variable.

{{< command >}}
export GITHUB_TOKEN=YOUR_TOKEN
tdl extension install <owner>/<private-repo>
{{< /command >}}

- Local : Extensions stored on your local machine.

{{< command >}}
tdl extension install /path/to/extension
{{< /command >}}

To install an extension even if it exists, use the --force flag:

{{< command >}}
tdl extension install --force EXTENSION
{{< /command >}}

To install multiple extensions at once, use the following command:

{{< command >}}
tdl extension install <owner>/<repo1> /path/to/extension2 ...
{{< /command >}}

To only print information without actually installing the extension, use the --dry-run flag:

{{< command >}}
tdl extension install --dry-run EXTENSION
{{< /command >}}

If you already have an extension by the same name installed, the command will fail. For example, if you have installed foo/tdl-whoami, you must uninstall it before installing bar/tdl-whoami.

Running extensions Copy Chapter

When you have installed an extension, you run the extension as you would run a native tdl command, using tdl EXTENSION-NAME. The EXTENSION-NAME is the name of the repository that contains the extension, minus the tdl- prefix.

For example, if you installed the extension from the iyear/tdl-whoami repository, you would run the extension with the following command.

{{< command >}}
tdl whoami
{{< /command >}}

Global config flags are still available when running an extension. For example, you can run the following command to specify namespace and proxy when running the tdl-whoami extension.

{{< command >}}
tdl -n foo --proxy socks5://localhost:1080 whoami
{{< /command >}}

Flags specific to an extension can also be used. For example, you can run the following command to enable verbose mode when running the tdl-whoami extension.

{{< hint info >}}
Remember to write global flags before extension subcommands and write extension flags after extension subcommands:
{{< command >}}
tdl <global-config-flags> <extension-name> <extension-flags>
{{< /command >}}

{{< /hint >}}

{{< command >}}
tdl -n foo whoami -v
{{< /command >}}

You can usually find specific information about how to use an extension in the README of the repository that contains the extension.

Viewing installed extensions Copy Chapter

To view all installed extensions, use the extension list subcommand. This command will list all installed extensions, along with their authors and versions.

{{< command >}}
tdl extension list
{{< /command >}}

Updating extensions Copy Chapter

To update an extension, use the extension upgrade subcommand. Replace the EXTENSION parameters with the name of extensions.

{{< command >}}
tdl extension upgrade EXTENSION1 EXTENSION2 ...
{{< /command >}}

To update all installed extensions, keep the EXTENSION parameter empty.

{{< command >}}
tdl extension upgrade
{{< /command >}}

To upgrade an extension from a GitHub private repository, you must set up a GitHub personal access token(with Contents read permission) in your environment with the GITHUB_TOKEN variable.

{{< command >}}
export GITHUB_TOKEN=YOUR_TOKEN
tdl extension upgrade EXTENSION
{{< /command >}}

To only print information without actually upgrading the extension, use the --dry-run flag:

{{< command >}}
tdl extension upgrade --dry-run EXTENSION
{{< /command >}}

Uninstalling extensions Copy Chapter

To uninstall an extension, use the extension remove subcommand. Replace the EXTENSION parameters with the name of extensions.

{{< command >}}
tdl extension remove EXTENSION1 EXTENSION2 ...
{{< /command >}}

To only print information without actually uninstalling the extension, use the --dry-run flag:

{{< command >}}
tdl extension remove --dry-run EXTENSION
{{< /command >}}

Developing extensions Copy Chapter

Please refer to the tdl-extension-template repository for instructions on how to create, build, and publish extensions for tdl.

---

Content/En/Guide/Forward Copy Section

---
title: "Forward"
weight: 35
---

Forward

Forward messages with automatic fallback and message routing

One-liner to forward messages from https://t.me/telegram/193 to Saved Messages:

{{< command >}}
tdl forward --from https://t.me/telegram/193
{{< /command >}}

Custom Source Copy Chapter

{{< include "snippets/link.md" >}}

You can forward messages from links and exported JSON files:

{{< command >}}
tdl forward \
--from https://t.me/telegram/193 \
--from https://t.me/telegram/195 \
--from tdl-export.json \
--from tdl-export2.json
{{< /command >}}

Custom Destination Copy Chapter

{{< include "snippets/chat.md" >}}

Specific Chat Copy Section

Forward to specific one chat:

{{< command >}}
tdl forward --from tdl-export.json --to CHAT
{{< /command >}}

Message Routing Copy Section

Forward to different chats by message router which is based on expression.

List all available fields:

{{< command >}}
tdl forward --from tdl-export.json --to -
{{< /command >}}

Forward to CHAT1 if message contains foo, otherwise forward to Saved Messages:

{{< hint info >}}
You must return a string or struct as the target CHAT, and empty string means forward to Saved Messages.
{{< /hint >}}

{{< command >}}
tdl forward --from tdl-export.json \
--to 'Message.Message contains "foo" ? "CHAT1" : ""'
{{< /command >}}

Forward to CHAT1 if message contains foo, otherwise forward to reply to message/topic 4 in CHAT2:

{{< command >}}
tdl forward --from tdl-export.json \
--to 'Message.Message contains "foo" ? "CHAT1" : { Peer: "CHAT2", Thread: 4 }'
{{< /command >}}

Pass a file name if the expression is complex:

{{< details "router.txt" >}}
Write your expression like switch:

Message.Message contains "foo" ? "CHAT1" :
From.ID == 123456 ? "CHAT2" :
Message.Views > 30 ? { Peer: "CHAT3", Thread: 101 } :
""

{{< command >}}
tdl forward --from tdl-export.json --to router.txt
{{< /command >}}

Mode Copy Chapter

Forward messages with automatic fallback strategy.

Available modes:
- direct (default)
- clone

Direct Copy Section

Prefer to use official forward API.

If the chat or message is not allowed to use official forward API, it will be automatically downgraded to clone mode.

{{< command >}}
tdl forward --from tdl-export.json --mode direct
{{< /command >}}

Clone Copy Section

Forward messages by copying them, which doesn't have forwarded header.

Some message content can't be copied, such as poll, invoice, etc. They will be ignored.

{{< command >}}
tdl forward --from tdl-export.json --mode clone
{{< /command >}}

Edit Copy Chapter

Edit the message before forwarding based on expression.

{{< hint info >}}
- You must pass the first message of grouped photos to edit the caption.
- You can pass any message of grouped documents to edit the corresponding comment.
{{< /hint >}}

You can reference relevant fields from the original message in the expression.

List all available fields:
{{< command >}}
tdl forward --from tdl-export.json --edit -
{{< /command >}}

Append Test Forwarded Message to the original message:
{{< command >}}
tdl forward --from tdl-export.json --edit 'Message.Message + " Test Forwarded Message"'
{{< /command >}}

Write styled message with HTML:
{{< command >}}
tdl forward --from tdl-export.json --edit \
'Message.Message + <b>Bold</b> <a href="https://example.com">Link</a>'
{{< /command >}}

Pass a file name if the expression is complex:

{{< details "edit.txt" >}}

repeat(Message.Message, 2) + 
<a href="https://www.google.com">Google</a>
<a href="https://www.bing.com">Bing</a>
<b>bold</b>
<i>italic</i>
<code>code</code>
<tg-spoiler>spoiler</tg-spoiler>
<pre><code class="language-go">
package main
import "fmt"
func main() {
    fmt.Println("hello world")
}
</code></pre>
 + From.VisibleName

{{< command >}}
tdl forward --from tdl-export.json --edit edit.txt
{{< /command >}}

Dry Run Copy Chapter

Print the progress without actually sending messages, which is useful for message routing debugging.

{{< command >}}
tdl forward --from tdl-export.json --dry-run
{{< /command >}}

Silent Copy Chapter

Send messages without notification.

{{< command >}}
tdl forward --from tdl-export.json --silent
{{< /command >}}

No Grouped Detection Copy Chapter

By default, tdl will detect grouped messages and forward them as an album.

You can disable this behavior by --single to forward it as a single message.

{{< command >}}
tdl forward --from tdl-export.json --single
{{< /command >}}

Descending Order Copy Chapter

Forward messages in descending order for each source.

{{< command >}}
tdl forward --from tdl-export.json --desc
{{< /command >}}

---

Content/En/Guide/Global Config Copy Section

---
title: "Global Config"
weight: 10
---

Global Config

Global config is some CLI flags that can be set in every command.

{{< hint info >}}
Set Global Config EVERYTIME!

Global config does not mean that the configuration will be persisted or only need to be set once in global settings, they will only take effect in the current command.
You need to set them in each command.
{{< /hint >}}

-n/--ns -n/--ns')" title="Copy chapter prompt for LLMs"> Copy Chapter

Each namespace represents a Telegram account. Default: default.

If you want to add another account, just add -n YOUR_ACCOUNT_NAME option to every command:

{{< command >}}
tdl -n iyear
{{< /command >}}

--proxy --proxy')" title="Copy chapter prompt for LLMs"> Copy Chapter

Set the proxy. Default: "".

Format: protocol://username:password@host:port

{{< command >}}
tdl --proxy socks5://localhost:1080
tdl --proxy http://localhost:8080
tdl --proxy https://localhost:8081
{{< /command >}}

--storage --storage')" title="Copy chapter prompt for LLMs"> Copy Chapter

Set the storage. Default: type=bolt,path=~/.tdl/data

Format: type=DRIVER,opt1=val1,opt2=val2,...

Available drivers:

| Driver | Options | Description |
|:----------------:|:------------------------------:|---------------------------------------------------------------------------------------------------------------|
| bolt (Default) | path=/path/to/data-directory | Store data in separate database files. So you can use it in multiple processes(must be different namespaces). |
| file | path=/path/to/data.json | Store data in a single JSON file, which is useful for debugging. |
| legacy | path=/path/to/data.kv | Deprecated. Store data in a single database file. So you can't use it in multiple processes. |
| - | - | Wait for more drivers... |

{{< command >}}
tdl --storage type=bolt,path=/path/to/data-dir
{{< /command >}}

--ntp --ntp')" title="Copy chapter prompt for LLMs"> Copy Chapter

Set ntp server host. If it's empty, system time will be used. Default: "".

{{< command >}}
tdl --ntp pool.ntp.org
{{< /command >}}

--reconnect-timeout --reconnect-timeout')" title="Copy chapter prompt for LLMs"> Copy Chapter

Set Telegram client reconnect timeout. Default: 2m.

{{< hint info >}}
Set higher timeout or 0(INF) if your network is poor.
{{< /hint >}}

{{< command >}}
tdl --reconnect-timeout 1m30s
{{< /command >}}

--debug --debug')" title="Copy chapter prompt for LLMs"> Copy Chapter

Enable debug level log. Default: false.

{{< command >}}
tdl --debug
{{< /command >}}

--pool --pool')" title="Copy chapter prompt for LLMs"> Copy Chapter

Set the DC pool size of Telegram client. Default: 8.

{{< hint info >}}
Set higher timeout or 0(INF) if you want faster speed.
{{< /hint >}}

{{< command >}}
tdl --pool 2
{{< /command >}}

--delay --delay')" title="Copy chapter prompt for LLMs"> Copy Chapter

set the delay between each task. Default: 0s.

{{< hint info >}}
Set higher delay time if you want to avoid Telegram's flood control.
{{< /hint >}}

{{< command >}}
tdl --delay 5s
{{< /command >}}

--disable-progress-ps --disable-progress-ps')" title="Copy chapter prompt for LLMs"> Copy Chapter

Disable progress CPU/memory usage stats, which may cause display issues in some terminals. Default: false.

{{< command >}}
tdl --disable-progress-ps
{{< /command >}}

---

Content/En/Guide/Login Copy Section

---
type: "docs"
title: "Login"
weight: 20
bookHref: "/getting-started/quick-start/#login"
---

Login

---

Content/En/Guide/Migration Copy Section

---
title: "Migration"
weight: 50
---

Migration

Backup or recover your data

Backup Copy Chapter

Backup all namespace data to a file. Default: <date>.backup.tdl.

{{< command >}}
tdl backup
{{< /command >}}

Or specify the output file:

{{< command >}}
tdl backup -d /path/to/custom.tdl
{{< /command >}}

Recover Copy Chapter

Recover your data from a tdl backup file. Existing namespace data will be overwritten.

{{< command >}}
tdl recover -f /path/to/custom.backup.tdl
{{< /command >}}

Migrate Copy Chapter

Migrate your data to another storage

See Storage Flag for storage option details.

Migrate current storage to file storage:
{{< command >}}
tdl migrate --to type=file,path=/path/to/data.json
{{< /command >}}

Migrate custom source storage to file storage:
{{< command >}}
tdl migrate --storage type=bolt,path=/path/to/data-directory --to type=file,path=/path/to/data.json
{{< /command >}}

---

Content/En/Guide/Template Copy Section

---
title: "Template Guide"
bookHidden: true
bookToC: false
---

Template Guide

This guide is intended to introduce variables and functions that are available in the tdl template.

Template syntax is based on Go's text/template package.

Download Copy Chapter

Variables (beta) Copy Section

| Var | Desc |
|:--------------:|:----------------------------------------:|
| DialogID | Telegram dialog id |
| MessageID | Telegram message id |
| MessageDate | Telegram message date(timestamp) |
| FileName | Telegram file name |
| FileCaption | Telegram file caption, aka. text message |
| FileSize | Human-readable file size, like 1GB |
| DownloadDate | Download date(timestamp) |

Functions (beta) Copy Section

| Func | Desc | Usage | Example |
|:------------:|:------------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------:|:-------------------------------------------------------------------------------------:|
| repeat | Repeat STRING N times | repeat STRING N | {{ repeat "test" 3 }} |
| replace | Perform replacement on STRING with PAIRS | replace STRING PAIRS... | {{ replace "Test" "t" "T" "e" "E" }} |
| upper | Convert STRING to uppercase | upper STRING | {{ upper "Test" }} |
| lower | Convert STRING to lowercase | lower STRING | {{ lower "Test" }} |
| snakecase | Convert STRING to snake_case | snakecase STRING | {{ snakecase "Test" }} |
| camelcase | Convert STRING to camelCase | camelcase STRING | {{ camelcase "Test" }} |
| kebabcase | Convert STRING to kebab-case | kebabcase STRING | {{ kebabcase "Test" }} |
| rand | Generate random number in range MIN to MAX | rand MIN MAX | {{ rand 1 10 }} |
| now | Get current timestamp | now | {{ now }} |
| formatDate | Format TIMESTAMP with format<br/>Default: 20060102150405 | formatDate TIMESTAMP <br/> formatDate TIMESTAMP "format" | {{ formatDate 1600000000 }}<br/> {{ formatDate 1600000000 "2006-01-02-15-04-05"}} |
| filenamify | Convert STRING to a valid filename with the best effort. Optional MaxLength can be used to limit string length | filenamify STRING MaxLength | {{ filenamify .FileName 32 }} |

Examples: Copy Section

{{ .DialogID }}_{{ .MessageID }}_{{ replace .FileCaption / _ \ _ : _ }}
{{ .FileName }}_{{ formatDate .DownloadDate }}_{{ .FileSize }}
{{ .FileName }}_{{ formatDate .DownloadDate "2006-01-02-15-04-05"}}_{{ .FileSize }}
{{ lower (replace .FileName   _) }}
{{ formatDate (now) }}

Default: Copy Section

{{ .DialogID }}_{{ .MessageID }}_{{ filenamify .FileName }}

---

Content/En/Guide/Upload Copy Section

---
title: "Upload"
weight: 40
---

Upload

Upload Files Copy Chapter

Upload specified files and directories to Saved Messages:

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir
{{< /command >}}

Custom Destination Copy Chapter

Upload to custom chat.

{{< include "snippets/chat.md" >}}

Specific Chat Copy Section

Upload to specific one chat:

{{< command >}}
tdl up -p /path/to/file -c CHAT
{{< /command >}}

Upload to specific topic in a forum chat:

{{< command >}}
tdl up -p /path/to/file -c CHAT --topic TOPIC_ID
{{< /command >}}

Message Routing Copy Section

Upload to different chats by message router which is based on expression.

{{< hint warning >}}
The --to flag is conflicted with the -c/--chat and --topic flags. You can only use one of them.
{{< /hint >}}

List all available fields:

{{< command >}}
tdl up -p /path/to/file --to -
{{< /command >}}

Upload to CHAT1 if MIME contains video, otherwise upload to Saved Messages:

{{< hint info >}}
You must return a string or struct as the target CHAT, and empty string means upload to Saved Messages.
{{< /hint >}}

{{< command >}}
tdl up -p /path/to/file \
--to 'MIME contains "video" ? "CHAT1" : ""'
{{< /command >}}

Upload to CHAT1 if MIME contains video, otherwise upload to reply to message/topic 4 in CHAT2:

{{< command >}}
tdl up -p /path/to/file \
--to 'MIME contains "video" ? "CHAT1" : { Peer: "CHAT2", Thread: 4 }'
{{< /command >}}

Pass a file name if the expression is complex:

{{< details "router.txt" >}}
Write your expression like switch:

MIME contains "video" ? "CHAT1" :
FileExt contains ".mp3" ? "CHAT2" :
FileName contains "chat3" > 30 ? {Peer: "CHAT3", Thread: 101} :
""

{{< /details >}}

{{< command >}}
tdl up -p /path/to/file --to router.txt
{{< /command >}}

Custom Parameters Copy Chapter

Upload with 8 threads per task, 4 concurrent tasks:

{{< command >}}
tdl up -p /path/to/file -t 8 -l 4
{{< /command >}}

Custom Caption Copy Chapter

Custom caption is based on expression.

List all available fields:

{{< command >}}
tdl up -p /path/to/file --caption -
{{< /command >}}

Custom simple caption:
{{< command >}}
tdl up -p /path/to/file --caption 'FileName + " - uploaded by tdl"'
{{< /command >}}

Write styled message with HTML:
{{< command >}}
tdl up -p /path/to/file --caption \
'FileName + <b>Bold</b> <a href="https://example.com">Link</a>'
{{< /command >}}

Pass a file name if the expression is complex:

{{< details "caption.txt" >}}

repeat(FileName, 2) + 
<a href="https://www.google.com">Google</a>
<a href="https://www.bing.com">Bing</a>
<b>bold</b>
<i>italic</i>
<code>code</code>
<tg-spoiler>spoiler</tg-spoiler>
<pre><code class="language-go">
package main
import "fmt"
func main() {
    fmt.Println("hello world")
}
</code></pre>
 + MIME

{{< /details >}}

{{< command >}}
tdl up -p /path/to/file --caption caption.txt
{{< /command >}}

Filters Copy Chapter

Upload files with extension filters:

{{< hint warning >}}
The extension is only matched with the file name, not the MIME type. So it may not work as expected.

Whitelist and blacklist can not be used at the same time.
{{< /hint >}}

Whitelist: Only upload files with .jpg .png extension

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir -i jpg,png
{{< /command >}}

Blacklist: Upload all files except .mp4 .flv extension

{{< command >}}
tdl up -p /path/to/file -p /path/to/dir -e mp4 -e flv
{{< /command >}}

Delete Local Copy Chapter

Delete the uploaded file after uploading successfully:

{{< command >}}
tdl up -p /path/to/file --rm
{{< /command >}}

Photo Copy Chapter

Upload images as photos instead of documents:

{{< command >}}
tdl up -p /path/to/file --photo
{{< /command >}}

---

Content/En/More/Data Copy Section

---
title: "Data"
weight: 30
---

Data

Your account information will be stored in the ~/.tdl directory.

Log files will be stored in the ~/.tdl/log directory.

---

Content/En/More/Env Copy Section

---
title: "Env"
weight: 20
---

Env

{{< hint info >}}
The values of all environment variables have a lower priority than flags.
{{< /hint >}}

Avoid typing the same flag values repeatedly every time by setting environment variables.

| NAME | FLAG |
|:-------------------------:|:-----------------------:|
| TDL_NS | -n/--ns |
| TDL_PROXY | --proxy |
| TDL_STORAGE | --storage |
| TDL_DEBUG | --debug |
| TDL_SIZE | -s/--size |
| TDL_THREADS | -t/--threads |
| TDL_LIMIT | -l/--limit |
| TDL_POOL | --pool |
| TDL_NTP | --ntp |
| TDL_RECONNECT_TIMEOUT | --reconnect-timeout |
| TDL_DISABLE_PROGRESS_PS | --disable-progress-ps |
| TDL_TEMPLATE | dl --template |

{{< hint warning >}}
- TDL_STORAGE format in env is different from that in flags: {"type": "bolt", "path": "/path/to/data-dir"} (JSON object).
{{< /hint >}}

---

Content/En/More/Troubleshooting Copy Section

---
title: "Troubleshooting"
weight: 40
---

Troubleshooting

Best Practices Copy Chapter

How to minimize the risk of blocking?

- Login with the official client session.
- Use the default download and upload options as possible. Do not set too large threads and size.
- Do not use the same account to login on multiple devices at the same time.
- Don't download or upload too many files at once.
- Become a Telegram premium user. 😅

FAQ Copy Chapter

#### Q: Why no response after entering the command? And why there is msg_id too high in the log?

A: Check if you need to use a proxy (use proxy flag); Check if your system's local time is correct (use ntp flag
or calibrate system time)

If that doesn't work, run again with --debug flag. Then file a new issue and paste your log in the issue.

#### Q: Desktop client stop working after using tdl?

A: If your desktop client can't receive messages, load chats, or send messages, you may encounter session conflicts.

You can try re-login with tdl login and select YES for logout, which will delete the session files to separate
sessions.

#### Q: How to migrate session to another device?

A: You can use the tdl backup and tdl recover commands to export and import sessions.
See Migration for more details.

#### Q: Is this a form of abuse?

A: No. The download and upload speed is limited by the server side. Since the speed of official clients usually does
not
reach the account limit, this tool was developed to download files at the highest possible speed.

#### Q: Will this result in a ban?

A: I am not sure. All operations do not involve dangerous actions such as actively sending messages to other people.
But
it's safer to use a long-term account.

---

Content/En/Reference/Expr Copy Section

---
title: "Expr Guide"
bookHidden: true
---

Expr Guide

Expr is powered by expr, which is a simple, lightweight, yet powerful expression
engine.

Expression engine docs: https://expr.medv.io/docs/Language-Definition

It's powerful but may be a little hard to new users. So feel free to file an issue if you have any questions about the
expression engine.

---