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 schemaversion: "2". Message rows expose content, replytomsgid, mediagroupid, and ordered lowercase attachments[]; do not expect legacy singular attachment or raw parser fields.

Ensure the executable is available

When developing or testing this repository's current source, skip global package installation. Require Node.js 22 or later, run pnpm install, and use pnpm dev <args>, for example pnpm dev search --help. Do not insert an extra --; pnpm dev -- search ... passes that token to the CLI and can fail.

For any other user-requested tg task, first run command -v tg. If the user asks only for instructions, explain the setup without changing their system.

If tg is installed, do not reinstall or upgrade it automatically. Verify the installed executable and inspect live help:

tg --version
tg --help
tg <command> --help

If tg is missing, check the runtime first:

node --version
npm --version

Continue only when both commands succeed and Node.js is version 22 or later. If Node.js is missing or too old, use an existing user-managed version manager when available; ask before installing or changing a system-level runtime or package manager.

Install the published package, then continue the original task:

npm install --global @will-17173/telegram-cli

Never retry a permission failure with sudo. Prefer an existing user-managed Node.js installation; otherwise install to a user-owned prefix for the current shell:

npm install --global --prefix "$HOME/.local" @will-17173/telegram-cli
export PATH="$HOME/.local/bin:$PATH"

Do not modify a shell startup file without authorization. After installation, require these checks to succeed before running Telegram commands:

hash -r
command -v tg
tg --version
tg --help

If the binary is still missing, inspect the npm global prefix and PATH, report the failure, and stop before running Telegram commands.

Choose the operation

Read [references/command-reference.md](references/command-reference.md) before composing an exact command, downloading media, starting Web or Guard, handling automation output, managing groups, or troubleshooting authentication and flood limits.

Operating workflow

1. Run the relevant --help; prefer it over memorized flags.
2. For account-dependent work, inspect tg account list --json and use an explicit account.
3. Route by source and persistence: search uses synchronized SQLite; search-online and transient read use Telegram; history/sync/repair persist into SQLite. Do not copy read time flags to history/sync, which use limit/delay controls.
4. Treat inbox as read-only discovery; never assume it marks messages read.
5. Resolve chats with chats --json and folders with folder list --json; prefer numeric IDs after discovery because names/titles may be ambiguous.
6. Parse structured envelopes rather than terminal tables. For batch sync failures use refresh and inspect data.failures; sync-all omits that field.
7. Immediately before a remote write, verify the target, check write-access status, and obtain explicit authorization for that mutation. Starting an armed Guard authorizes an ongoing class of configured actions, so summarize its enabled scope before requesting authorization.

Common mistakes

• pnpm dev -- ...: remove the extra separator.
• Assuming sync --limit 5000 backfills a new chat: first sync is capped at 500; use history for deeper history.
• Expecting repair --dry-run to write data: remove --dry-run after reviewing the gap table.
• Expecting sync-all to expose partial failures: use refresh and inspect data.failures.
• Reusing an old database after a breaking media schema change: run tg data reset --yes, then sync again.
• Expecting listen --no-media to suppress --save or --auto-download: it only hides rendered media rows; the explicit save and download flags still write their respective data.
• Starting Guard with write access enabled merely to inspect it: an armed Guard can immediately execute saved rules; inspect with write access off, then obtain authorization before enabling writes and restarting it.
• Using an ambiguous chat name: retry with its numeric chat ID.
• Looking up an uncached numeric non-contact with contact info <user-id> alone: add --chat <group> or use contact info <group> <user-id> so Telegram can resolve the user from group message context.
• Using Markdown for archive automation: it does not preserve full partial-failure details; use JSON/YAML.
• Passing a 2FA password in arguments, environment variables, stdin automation, chat, or logs: ownership transfer accepts only its secure interactive prompt.
• Expecting send to appear immediately in local search: synchronize afterward.