Using Telegram CLI

Overview

Use tg as an account-aware Telegram client and local SQLite message index. Choose commands by data source, persistence, and whether they mutate Telegram.

Mandatory rules

• Request explicit user authorization before either enabling write access or executing any remote mutation. Authorization to enable writes is not authorization for a mutation. Several mutations have no built-in confirmation.
• Check tg config write-access status --json before a planned mutation. The gate covers remote mutations only; read-only Telegram calls, local SQLite/file operations, account lifecycle, and configuration remain available while it is off.
• Treat tg guard start with write access enabled as continuous remote-mutation automation. Review its enabled groups, rules, and policies and obtain explicit authorization before starting an armed Guard; with write access disabled, Telegram write actions are recorded as dry runs.
• Never provide, solicit in plain text, or automate an ownership-transfer password. group admin transfer-owner prompts for it securely in an interactive TTY after --yes; it is not suitable for non-interactive CI.
• Treat API hashes, proxy URLs, sessions, account metadata, exported messages, and databases as secrets. Never print config list --show-secrets, expose a credential-bearing proxy, or commit DATA_DIR.
• Select an account explicitly with --account <name> in automation. Do not change the current account merely to run one command.
• Select exactly one of --json, --yaml, or --markdown for finite commands. Use JSON or YAML for automation and stable ok/error fields; Markdown is human-facing and may omit structured failure details. Non-TTY output otherwise defaults to YAML. listen excludes these flags.
• Check the process exit status and structured ok. For automated archive partial-failure accounting, use JSON/YAML and inspect error.code plus error.details.completed, error.details.failed, and error.details.warnings; never report complete success when any chat or media failed.
• Structured envelopes use schema_version: "2". Message rows expose content, reply_to_msg_id, media_group_id, and ordered lowercase attachments[]; do not expect legacy singular attachment or raw parser fields.

Ensure the executable is available