models

_BaseOptions

Bases: BaseModel

Base class for all command option models.

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

GlobalOptions

Bases: BaseModel

Global flags shared across all tdl commands.

debug

debug: bool = Field(default=False, description='Enable debug mode.')

delay

delay: str | None = Field(default=None, description="Delay between each task, e.g. '5s'.")

limit

limit: int = Field(default=2, description='Max number of concurrent tasks.')

ns

ns: str = Field(default='default', description='Namespace for Telegram session.')

ntp

ntp: str | None = Field(default=None, description='NTP server host.')

pool

pool: int = Field(default=8, description='Size of the DC pool, 0 means infinity.')

proxy

proxy: str | None = Field(
    default=None, description="Proxy address, format: protocol://username:password@host:port."
)

reconnect_timeout

reconnect_timeout: str = Field(
    default="5m", description="Telegram client reconnection backoff timeout."
)

storage

storage: dict[str, str] | None = Field(
    default=None, description="Storage options, format: type=driver,key1=value1,key2=value2."
)

threads

threads: int = Field(default=4, description='Max threads for transfer one item.')

cli_args

cli_args: list[str]

Flat list of global CLI arguments ready for subprocess.

TDLResult

Bases: BaseModel

Result from a tdl command execution.

stdout

stdout: str = Field(default='', description='Standard output from the command.')

stderr

stderr: str = Field(default='', description='Standard error from the command.')

return_code

return_code: int = Field(default=0, description='Exit code of the command.')

LoginOptions

Bases: _BaseOptions

Options for the tdl login command.

login_type

login_type: LoginType = Field(
    default=DESKTOP, alias="type", description="Login mode: desktop, code, or qr."
)

desktop

desktop: str | None = Field(
    default=None, description="Official desktop client path (auto-find if empty)."
)

passcode

passcode: str | None = Field(default=None, description='Passcode for desktop client.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

BackupOptions

Bases: _BaseOptions

Options for the tdl backup command.

dst

dst: str | None = Field(
    default=None, description="Destination file path. Default: <date>.backup.tdl."
)

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

RecoverOptions

Bases: _BaseOptions

Options for the tdl recover command.

file

file: str = Field(description='Backup file path.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

MigrateOptions

Bases: _BaseOptions

Options for the tdl migrate command.

to

to: dict[str, str] = Field(
    description="Destination storage options, e.g. {'type': 'file', 'path': '/new'}."
)

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ChatListOptions

Bases: _BaseOptions

Options for the tdl chat ls command.

chat_filter

chat_filter: str = Field(default="true", alias="filter", description="Filter chats by expression.")

output

output: ListOutput = Field(default=TABLE, description='Output format: table or json.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ChatExportOptions

Bases: _BaseOptions

Options for the tdl chat export command.

chat

chat: str | None = Field(default=None, description="Chat id or domain. None means Saved Messages.")

export_type

export_type: ExportType = Field(
    default=TIME, alias="type", description="Export type: time, id, or last."
)

export_input

export_input: list[int] | None = Field(
    default=None, alias="input", description="Input data, depends on export type."
)

output

output: str = Field(default='tdl-export.json', description='Output JSON file path.')

export_filter

export_filter: str = Field(
    default="true",
    alias="filter",
    description="Filter messages by expression. Use '-' to see available fields.",
)

export_all

export_all: bool = Field(
    default=False, alias="all", description="Export all messages including non-media."
)

raw

raw: bool = Field(default=False, description='Export raw MTProto struct (for debugging).')

with_content

with_content: bool = Field(default=False, description='Export with message content.')

reply

reply: int | None = Field(default=None, description='Specify channel post id.')

topic

topic: int | None = Field(default=None, description='Specify topic id.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ChatUsersOptions

Bases: _BaseOptions

Options for the tdl chat users command.

chat

chat: str = Field(description='Domain id (channels, supergroups, etc.).')

output

output: str = Field(default='tdl-users.json', description='Output JSON file path.')

raw

raw: bool = Field(default=False, description='Export raw MTProto struct.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

DownloadOptions

Bases: _BaseOptions

Options for the tdl download command.

url

url: list[str] | None = Field(default=None, description='Telegram message links.')

file

file: list[str] | None = Field(default=None, description='Official client exported files.')

download_dir

download_dir: str = Field(
    default="downloads",
    alias="dir",
    description="Download directory (auto-created if not exists).",
)

include

include: list[str] | None = Field(
    default=None, description="Include file extensions, e.g. ['mp4', 'mp3']."
)

exclude

exclude: list[str] | None = Field(
    default=None, description="Exclude file extensions, e.g. ['png', 'jpg']."
)

desc

desc: bool = Field(default=False, description='Download from newest to oldest.')

continue_download

continue_download: bool = Field(
    default=False, alias="continue", description="Continue the last download directly."
)

restart

restart: bool = Field(default=False, description='Restart the last download directly.')

rewrite_ext

rewrite_ext: bool = Field(
    default=False,
    alias="rewrite-ext",
    description="Rewrite file extension according to file header MIME.",
)

skip_same

skip_same: bool = Field(
    default=False,
    alias="skip-same",
    description="Skip files with same name (without ext) and size.",
)

takeout

takeout: bool = Field(
    default=False, description="Use takeout sessions for lower flood wait limits."
)

group

group: bool = Field(default=False, description='Auto detect grouped messages and download all.')

serve

serve: bool = Field(
    default=False, description="Serve media as HTTP server instead of downloading."
)

port

port: int | None = Field(
    default=None, description="HTTP server port (for serve mode). Default: 8080."
)

template

template: str | None = Field(default=None, description='Download file name template.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

UploadOptions

Bases: _BaseOptions

Options for the tdl upload command.

path

path: list[str] = Field(description='Dirs or files to upload.')

chat

chat: str | None = Field(default=None, description="Chat id or domain. None means Saved Messages.")

excludes

excludes: list[str] | None = Field(default=None, description='Exclude file extensions.')

photo

photo: bool = Field(default=False, description='Upload image as photo instead of file.')

rm

rm: bool = Field(default=False, description='Remove uploaded files after uploading.')

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ForwardOptions

Bases: _BaseOptions

Options for the tdl forward command.

forward_from

forward_from: list[str] = Field(
    alias="from", description="Messages to be forwarded, can be links or exported JSON files."
)

to

to: str = Field(description='Destination peer, can be a CHAT or router expression.')

mode

mode: ForwardMode = Field(default=DIRECT, description='Forward mode: direct or clone.')

edit

edit: str | None = Field(
    default=None, description="Edit message or caption with expression engine."
)

desc

desc: bool = Field(default=False, description='Forward messages in reverse order.')

dry_run

dry_run: bool = Field(
    default=False,
    alias="dry-run",
    description="Do not actually send, just show how they would be sent.",
)

silent

silent: bool = Field(default=False, description='Send messages silently.')

single

single: bool = Field(default=False, description="Do not auto-detect and forward grouped messages.")

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ExtInstallOptions

Bases: _BaseOptions

Options for the tdl extension install command.

force

force: bool = Field(default=False, description='Force install even if extension already exists.')

dry_run

dry_run: bool = Field(default=False, alias="dry-run", description="Only print what would be done.")

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ExtListOptions

Bases: _BaseOptions

Options for the tdl extension list command.

dry_run

dry_run: bool = Field(default=False, alias="dry-run", description="Only print what would be done.")

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ExtRemoveOptions

Bases: _BaseOptions

Options for the tdl extension remove command.

dry_run

dry_run: bool = Field(default=False, alias="dry-run", description="Only print what would be done.")

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.

ExtUpgradeOptions

Bases: _BaseOptions

Options for the tdl extension upgrade command.

dry_run

dry_run: bool = Field(default=False, alias="dry-run", description="Only print what would be done.")

cli_dict

cli_dict: dict[str, object]

CLI flag dict. Uses alias as key. Skips None and False bools.

cli_args

cli_args: list[str]

Flat list of CLI arguments ready for subprocess.