client

TDL

Bases: BaseModel

Python SDK for the TDL (Telegram Downloader) CLI tool.

Provides a Pythonic interface to all tdl commands by wrapping the CLI binary via subprocess.

Example

from tdl_sdk import TDL, LoginType, LoginOptions

client = TDL(ns="my_session", proxy="socks5://127.0.0.1:1080")
client.login(LoginOptions(login_type=LoginType.QR))
client.download(DownloadOptions(url=["https://t.me/channel/123"]))

Methods:

Name	Description
login	Login to Telegram.
backup	Backup your data.
recover	Recover your data from a backup.
migrate	Migrate your current data to another storage.
chat_ls	List your chats.
chat_export	Export messages from (protected) chat for download.
chat_users	Export users from (protected) channels.
download	Download anything from Telegram (protected) chat.
upload	Upload anything to Telegram.
forward	Forward messages with automatic fallback and message routing.
ext_install	Install a tdl extension.
ext_list	List installed extension commands.
ext_remove	Remove an installed extension.
ext_upgrade	Upgrade a tdl extension.

global_options

global_options: GlobalOptions = Field(
    default_factory=GlobalOptions, description="Global options for all tdl commands."
)

tdl_path

tdl_path: str = Field(default='tdl', description='Path to the tdl binary.')

timeout

timeout: float | None = Field(
    default=None, description="Default timeout in seconds for all commands."
)

runner

runner: TDLRunner

TDLRunner instance built from current config.

login

login(options: LoginOptions | None = None) -> TDLResult

Login to Telegram.

Parameters:

Name	Type	Description	Default
options	LoginOptions | None	Login options. Defaults to desktop login mode.	None

Source code in src/tdl_sdk/_client.py

def login(self, options: LoginOptions | None = None) -> TDLResult:
    """Login to Telegram.

    Args:
        options: Login options. Defaults to desktop login mode.
    """
    return self.runner.run(["login"], options or LoginOptions(), timeout=self.timeout)

backup

backup(options: BackupOptions | None = None) -> TDLResult

Backup your data.

Parameters:

Name	Type	Description	Default
options	BackupOptions | None	Backup options.	None

Source code in src/tdl_sdk/_client.py

def backup(self, options: BackupOptions | None = None) -> TDLResult:
    """Backup your data.

    Args:
        options: Backup options.
    """
    return self.runner.run(["backup"], options or BackupOptions(), timeout=self.timeout)

recover

recover(options: RecoverOptions) -> TDLResult

Recover your data from a backup.

Parameters:

Name	Type	Description	Default
options	RecoverOptions	Recover options with the backup file path.	required

Source code in src/tdl_sdk/_client.py

def recover(self, options: RecoverOptions) -> TDLResult:
    """Recover your data from a backup.

    Args:
        options: Recover options with the backup file path.
    """
    return self.runner.run(["recover"], options, timeout=self.timeout)

migrate

migrate(options: MigrateOptions) -> TDLResult

Migrate your current data to another storage.

Parameters:

Name	Type	Description	Default
options	MigrateOptions	Migrate options with destination storage config.	required

Source code in src/tdl_sdk/_client.py

def migrate(self, options: MigrateOptions) -> TDLResult:
    """Migrate your current data to another storage.

    Args:
        options: Migrate options with destination storage config.
    """
    return self.runner.run(["migrate"], options, timeout=self.timeout)

chat_ls

chat_ls(options: ChatListOptions | None = None) -> TDLResult

List your chats.

Parameters:

Name	Type	Description	Default
options	ChatListOptions | None	Chat list options.	None

Source code in src/tdl_sdk/_client.py

def chat_ls(self, options: ChatListOptions | None = None) -> TDLResult:
    """List your chats.

    Args:
        options: Chat list options.
    """
    return self.runner.run(["chat", "ls"], options or ChatListOptions(), timeout=self.timeout)

chat_export

chat_export(options: ChatExportOptions | None = None) -> TDLResult

Export messages from (protected) chat for download.

Parameters:

Name	Type	Description	Default
options	ChatExportOptions | None	Chat export options.	None

Source code in src/tdl_sdk/_client.py

def chat_export(self, options: ChatExportOptions | None = None) -> TDLResult:
    """Export messages from (protected) chat for download.

    Args:
        options: Chat export options.
    """
    return self.runner.run(
        ["chat", "export"], options or ChatExportOptions(), timeout=self.timeout
    )

chat_users

chat_users(options: ChatUsersOptions) -> TDLResult

Export users from (protected) channels.

Parameters:

Name	Type	Description	Default
options	ChatUsersOptions	Chat users export options.	required

Source code in src/tdl_sdk/_client.py

def chat_users(self, options: ChatUsersOptions) -> TDLResult:
    """Export users from (protected) channels.

    Args:
        options: Chat users export options.
    """
    return self.runner.run(["chat", "users"], options, timeout=self.timeout)

download

download(options: DownloadOptions | None = None) -> TDLResult

Download anything from Telegram (protected) chat.

Parameters:

Name	Type	Description	Default
options	DownloadOptions | None	Download options.	None

Source code in src/tdl_sdk/_client.py

def download(self, options: DownloadOptions | None = None) -> TDLResult:
    """Download anything from Telegram (protected) chat.

    Args:
        options: Download options.
    """
    return self.runner.run(["download"], options or DownloadOptions(), timeout=self.timeout)

upload

upload(options: UploadOptions) -> TDLResult

Upload anything to Telegram.

Parameters:

Name	Type	Description	Default
options	UploadOptions	Upload options with paths to upload.	required

Source code in src/tdl_sdk/_client.py

def upload(self, options: UploadOptions) -> TDLResult:
    """Upload anything to Telegram.

    Args:
        options: Upload options with paths to upload.
    """
    return self.runner.run(["upload"], options, timeout=self.timeout)

forward

forward(options: ForwardOptions) -> TDLResult

Forward messages with automatic fallback and message routing.

Parameters:

Name	Type	Description	Default
options	ForwardOptions	Forward options.	required

Source code in src/tdl_sdk/_client.py

def forward(self, options: ForwardOptions) -> TDLResult:
    """Forward messages with automatic fallback and message routing.

    Args:
        options: Forward options.
    """
    return self.runner.run(["forward"], options, timeout=self.timeout)

ext_install

ext_install(name: str, options: ExtInstallOptions | None = None) -> TDLResult

Install a tdl extension.

Parameters:

Name	Type	Description	Default
name	str	Extension URL, e.g. github.com/user/tdl-ext-name.	required
options	ExtInstallOptions | None	Install options.	None

Source code in src/tdl_sdk/_client.py

def ext_install(self, name: str, options: ExtInstallOptions | None = None) -> TDLResult:
    """Install a tdl extension.

    Args:
        name: Extension URL, e.g. github.com/user/tdl-ext-name.
        options: Install options.
    """
    return self.runner.run(
        ["extension", "install"],
        options or ExtInstallOptions(),
        positional_args=[name],
        timeout=self.timeout,
    )

ext_list

ext_list(options: ExtListOptions | None = None) -> TDLResult

List installed extension commands.

Parameters:

Name	Type	Description	Default
options	ExtListOptions | None	List options.	None

Source code in src/tdl_sdk/_client.py

def ext_list(self, options: ExtListOptions | None = None) -> TDLResult:
    """List installed extension commands.

    Args:
        options: List options.
    """
    return self.runner.run(
        ["extension", "list"], options or ExtListOptions(), timeout=self.timeout
    )

ext_remove

ext_remove(name: str, options: ExtRemoveOptions | None = None) -> TDLResult

Remove an installed extension.

Parameters:

Name	Type	Description	Default
name	str	Extension name to remove.	required
options	ExtRemoveOptions | None	Remove options.	None

Source code in src/tdl_sdk/_client.py

def ext_remove(self, name: str, options: ExtRemoveOptions | None = None) -> TDLResult:
    """Remove an installed extension.

    Args:
        name: Extension name to remove.
        options: Remove options.
    """
    return self.runner.run(
        ["extension", "remove"],
        options or ExtRemoveOptions(),
        positional_args=[name],
        timeout=self.timeout,
    )

ext_upgrade

ext_upgrade(name: str, options: ExtUpgradeOptions | None = None) -> TDLResult

Upgrade a tdl extension.

Parameters:

Name	Type	Description	Default
name	str	Extension name to upgrade.	required
options	ExtUpgradeOptions | None	Upgrade options.	None

Source code in src/tdl_sdk/_client.py

def ext_upgrade(self, name: str, options: ExtUpgradeOptions | None = None) -> TDLResult:
    """Upgrade a tdl extension.

    Args:
        name: Extension name to upgrade.
        options: Upgrade options.
    """
    return self.runner.run(
        ["extension", "upgrade"],
        options or ExtUpgradeOptions(),
        positional_args=[name],
        timeout=self.timeout,
    )