Commands¶

tg --help shows 74 commands. This page is generated from Cobra help output.

Every command supports the global flags shown by tg --help: --account, --full, --json, --human, --lock-wait, --read-only, and --version where applicable.

Index¶

Command	What
`tg account-sessions`	List authorized Telegram sessions
`tg accounts-add`	Create a new account directory
`tg accounts-list`	List known accounts
`tg accounts-remove`	Delete an account directory
`tg accounts-show`	Show the currently selected account and its paths
`tg accounts-use`	Select an existing account
`tg backfill`	Backfill cached messages for a chat
`tg backfill-entities`	Populate the local entity cache so chat_id-keyed sends work
`tg ban-from-chat`	ban-from-chat user in chat
`tg block-user`	Block a user
`tg chat-description`	Edit chat description
`tg chat-invite-link`	Export an invite link
`tg chat-members`	List chat members
`tg chat-photo`	Edit chat photo
`tg chat-pinned-list`	List pinned dialogs for a chat
`tg chat-title`	Edit chat title
`tg chats-info`	Show chat info for comma-separated chat ids
`tg completion`	Generate the autocompletion script for tg for the specified shell.
`tg contacts`	List cached contacts
`tg delete-msg`	Delete one or more messages (revoke for everyone by default)
`tg demote`	demote user in chat
`tg discover`	Discover dialogs and cache chat metadata
`tg doctor`	Diagnose tgctl-go setup
`tg download-album`	Download one cached Telegram media group
`tg download-media`	Download media attached to a message
`tg edit-msg`	Edit a previously sent message
`tg export`	Export cached Telegram history locally
`tg folder-add-chat`	Mutate folder chat membership
`tg folder-create`	Create a dialog folder
`tg folder-delete`	Delete a dialog folder
`tg folder-edit`	Edit a dialog folder
`tg folder-remove-chat`	Mutate folder chat membership
`tg folder-show`	Show one dialog folder
`tg folders-list`	List dialog folders
`tg folders-reorder`	Reorder dialog folders
`tg forward`	Forward one or more messages between chats
`tg get-msg`	Print one cached message in full
`tg help`	Help provides help for any command in the application.
`tg import-telethon-session`	Adopt a Python tgctl/Telethon session as the current Go account's session
`tg kick`	kick user in chat
`tg leave-chat`	Leave a group or channel (typed confirm required)
`tg list-msgs`	List cached messages in a chat with optional date filters
`tg listen`	Listen for live Telegram updates
`tg login`	Interactively authorize this account against Telegram
`tg mark-read`	Mark history read up to and including --up-to
`tg me`	Print authenticated user info
`tg pin-msg`	Pin a message in a chat
`tg promote`	promote user in chat
`tg react`	Send a reaction to a message
`tg search`	Search cached messages in a chat
`tg send`	Send a text message
`tg send-by-username`	Send a text message by resolving an @username (no entity cache required)
`tg set-permissions`	Set default chat permissions
`tg setup`	Create or update a private .env with Telegram app credentials
`tg show`	Show recent cached messages in a chat
`tg stats`	Show local cache statistics
`tg sync`	Synchronize cached messages and optionally follow updates
`tg sync-contacts`	Sync Telegram contacts into the local DB
`tg terminate-session`	Terminate one of your authorized Telegram sessions
`tg topic-create`	Create a forum topic
`tg topic-edit`	Edit a forum topic
`tg topic-pin`	Pin a forum topic
`tg topic-unpin`	Unpin a forum topic
`tg topics-list`	List forum topics
`tg unban-from-chat`	unban-from-chat user in chat
`tg unblock-user`	Unblock a previously blocked user
`tg unpin-msg`	Unpin a previously pinned message
`tg unread`	List recently cached incoming messages
`tg upload-album`	Upload a 2–10 item media album
`tg upload-document`	Upload a document
`tg upload-photo`	Upload a photo
`tg upload-video`	Upload a video
`tg upload-voice`	Upload an OGG/Opus voice message
`tg version`	Print build version

`tg account-sessions`¶

List authorized Telegram sessions

Use

tg account-sessions [flags]

Example

tg account-sessions --json

Flags

Flag	Description
`-h, --help`	help for account-sessions
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg accounts-add`¶

Create a new account directory

Use

tg accounts-add <name> [flags]

Example

tg accounts-add work --json

Flags

Flag	Description
`-h, --help`	help for accounts-add
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg accounts-list`¶

List known accounts

Use

tg accounts-list [flags]

Example

tg accounts-list --json

Flags

Flag	Description
`-h, --help`	help for accounts-list
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg accounts-remove`¶

Delete an account directory

Use

tg accounts-remove <name> [flags]

Example

tg accounts-remove work --confirm work --json

Flags

Flag	Description
`--confirm string`	Typed account name to confirm removal
`-h, --help`	help for accounts-remove
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg accounts-show`¶

Show the currently selected account and its paths

Use

tg accounts-show [flags]

Example

tg accounts-show --json

Flags

Flag	Description
`-h, --help`	help for accounts-show
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg accounts-use`¶

Select an existing account

Use

tg accounts-use <name> [flags]

Example

tg accounts-use work --json

Flags

Flag	Description
`-h, --help`	help for accounts-use
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg backfill`¶

Backfill cached messages for a chat

Use

tg backfill <chat> [flags]

Example

tg backfill 123456789 --max-messages 100 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`--download-media`	Download media during backfill
`-h, --help`	help for backfill
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-db-size-mb int`	Maximum main database plus WAL allocation in MiB (0 disables the cap)
`--max-media-size-mb int`	Maximum size per downloaded media file in MiB (0 disables the limit) (default 100)
`--max-messages int`	Maximum cached messages per chat (maximum 10000) (default 100)
`--overwrite-media`	Overwrite existing backfill media files
`--throttle-seconds float`	Seconds to sleep between Telegram history pages

`tg backfill-entities`¶

Populate the local entity cache so chat_id-keyed sends work

Use

tg backfill-entities [flags]

Example

tg backfill-entities --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`-h, --help`	help for backfill-entities
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Max dialogs to fetch in one pass (Telegram caps at ~200) (default 200)

`tg ban-from-chat`¶

ban-from-chat user in chat

Use

tg ban-from-chat <chat> <user-id> [flags]

Example

tg ban-from-chat <group-chat-id> 123456789 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for ban-from-chat
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg block-user`¶

Block a user

Use

tg block-user <user> [flags]

Example

tg block-user 123456789 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for block-user
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chat-description`¶

Edit chat description

Use

tg chat-description <chat> <value> [flags]

Example

tg chat-description <group-chat-id> "Description" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for chat-description
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chat-invite-link`¶

Export an invite link

Use

tg chat-invite-link <chat> [flags]

Example

tg chat-invite-link <group-chat-id> --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for chat-invite-link
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chat-members`¶

List chat members

Use

tg chat-members <chat> [flags]

Example

tg chat-members <group-chat-id> --limit 50 --json

Flags

Flag	Description
`-h, --help`	help for chat-members
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum members (default 50)

`tg chat-photo`¶

Edit chat photo

Use

tg chat-photo <chat> <value> [flags]

Example

tg chat-photo <group-chat-id> ./photo.png --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for chat-photo
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chat-pinned-list`¶

List pinned dialogs for a chat

Use

tg chat-pinned-list <chat> [flags]

Example

tg chat-pinned-list 123456789 --json

Flags

Flag	Description
`-h, --help`	help for chat-pinned-list
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chat-title`¶

Edit chat title

Use

tg chat-title <chat> <value> [flags]

Example

tg chat-title <group-chat-id> "New title" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for chat-title
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg chats-info`¶

Show chat info for comma-separated chat ids

Use

tg chats-info <chat-ids> [flags]

Example

tg chats-info 123456789 --json

Flags

Flag	Description
`-h, --help`	help for chats-info
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg completion`¶

Generate the autocompletion script for tg for the specified shell.

Use

tg completion [flags]
tg completion [command]

Example

tg completion zsh > ~/.zsh/completions/_tg

Flags

Flag	Description
`-h, --help`	help for completion

`tg contacts`¶

List cached contacts

Use

tg contacts [flags]

Example

tg contacts --json

Flags

Flag	Description
`-h, --help`	help for contacts
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum contacts (default 100)

`tg delete-msg`¶

Delete one or more messages (revoke for everyone by default)

Use

tg delete-msg <chat> <message-ids> [flags]

Example

tg delete-msg 123456789 1 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--for-everyone`	Force revoke for everyone
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for delete-msg
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--no-for-everyone`	Force delete only for self

`tg demote`¶

demote user in chat

Use

tg demote <chat> <user-id> [flags]

Example

tg demote 987654321 123456789 --allow-write --confirm 987654321 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for demote
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg discover`¶

Discover dialogs and cache chat metadata

Use

tg discover [flags]

Example

tg discover --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`-h, --help`	help for discover
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum dialogs to fetch (default 200)

`tg doctor`¶

Diagnose tgctl-go setup

Use

tg doctor [flags]

Example

tg doctor --json

Flags

Flag	Description
`-h, --help`	help for doctor
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg download-album`¶

Download one cached Telegram media group

Use

tg download-album <chat> [message-id] [flags]

Example

tg download-album <chat> [message-id] [flags] --json

Flags

Flag	Description
`--allow-write`	Required for album media/cache writes
`--dry-run`	Print album metadata without contacting Telegram
`--fuzzy`	Allow title-based chat selectors
`--grouped-id int`	Telegram grouped_id to download
`-h, --help`	help for download-album
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum download size per item in MiB (0 = unlimited) (default 100)
`--message-id int`	Anchor message id (or pass it as the second argument)
`--output string`	Output directory (default account media//)
`--overwrite`	Overwrite existing media files

`tg download-media`¶

Download media attached to a message

Use

tg download-media <chat> <message-id> [flags]

Example

tg download-media 123456789 42 --max-size-mb 100 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required because the download updates the local media cache
`--fuzzy`	Allow title-based chat selectors
`-h, --help`	help for download-media
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum download size in MiB (0 = unlimited) (default 100)
`--output string`	Output directory (default account media//)
`--overwrite`	Overwrite an existing media file

`tg edit-msg`¶

Edit a previously sent message

Use

tg edit-msg <chat> <message-id> <new-text> [flags]

Example

tg edit-msg 123456789 1 "updated" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for edit-msg
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg export`¶

Export cached Telegram history locally

Use

tg export <chat> [flags]

Example

tg export <chat> [flags] --json

Flags

Flag	Description
`--format string`	Export format: jsonl, csv, or html (default "jsonl")
`-h, --help`	help for export
`--human`	Force human-readable output (default on a TTY)
`--include-media`	Include media paths relative to the account media root
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum rows (0 means all cached rows)
`--manifest string`	Write an archive manifest JSON file
`--manifest-hash`	Include SHA-256 hashes in --manifest
`--output string`	Output file, or - for stdout (default "-")
`--since string`	Inclusive lower date/time bound
`--until string`	Inclusive upper date/time bound
`--verify string`	Verify a local archive manifest instead of exporting

`tg folder-add-chat`¶

Mutate folder chat membership

Use

tg folder-add-chat <id> <chat> [flags]

Example

tg folder-add-chat 2 123456789 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folder-add-chat
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg folder-create`¶

Create a dialog folder

Use

tg folder-create <name> [flags]

Example

tg folder-create "support" --include-chats 123456789 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--emoji string`	Folder emoji
`--exclude-chats string`	Comma-separated chat ids to exclude
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folder-create
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--include-chats string`	Comma-separated chat ids to include
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg folder-delete`¶

Delete a dialog folder

Use

tg folder-delete <id> [flags]

Example

tg folder-delete 2 --allow-write --confirm 2 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folder-delete
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg folder-edit`¶

Edit a dialog folder

Use

tg folder-edit <id> [flags]

Example

tg folder-edit 2 --name "support" --allow-write --json

Flags

Flag	Description
`--add string`	Comma-separated chat ids to add
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--emoji string`	Folder emoji
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folder-edit
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--name string`	New folder name
`--remove string`	Comma-separated chat ids to remove

`tg folder-remove-chat`¶

Mutate folder chat membership

Use

tg folder-remove-chat <id> <chat> [flags]

Example

tg folder-remove-chat 2 123456789 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folder-remove-chat
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg folder-show`¶

Show one dialog folder

Use

tg folder-show <id> [flags]

Example

tg folder-show 2 --json

Flags

Flag	Description
`-h, --help`	help for folder-show
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg folders-list`¶

List dialog folders

Use

tg folders-list [flags]

Example

tg folders-list --json

Flags

Flag	Description
`-h, --help`	help for folders-list
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--query string`	Filter by title

`tg folders-reorder`¶

Reorder dialog folders

Use

tg folders-reorder <id-csv> [flags]

Example

tg folders-reorder 2,3,4 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for folders-reorder
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg forward`¶

Forward one or more messages between chats

Use

tg forward <from-chat> <to-chat> <message-ids> [flags]

Example

tg forward 123456789 123456789 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for forward
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--topic int`	Forum topic id on destination

`tg get-msg`¶

Print one cached message in full

Use

tg get-msg <chat> <message-id> [flags]

Example

tg get-msg 123456789 1 --json

Flags

Flag	Description
`-h, --help`	help for get-msg
`--human`	Force human-readable output (default on a TTY)
`--include-deleted`	Look up tombstoned messages too
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg help`¶

Help provides help for any command in the application.

Use

tg help [command] [flags]

Example

tg help send

Flags

Flag	Description
`-h, --help`	help for help

`tg import-telethon-session`¶

Adopt a Python tgctl/Telethon session as the current Go account's session

Use

tg import-telethon-session <path> [flags]

Example

tg import-telethon-session ~/path/to/tg.session --json

Flags

Flag	Description
`-h, --help`	help for import-telethon-session
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg kick`¶

kick user in chat

Use

tg kick <chat> <user-id> [flags]

Example

tg kick <group-chat-id> 123456789 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for kick
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg leave-chat`¶

Leave a group or channel (typed confirm required)

Use

tg leave-chat <chat> [flags]

Example

tg leave-chat <group-chat-id> --allow-write --confirm <group-chat-id> --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for leave-chat
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg list-msgs`¶

List cached messages in a chat with optional date filters

Use

tg list-msgs <chat> [flags]

Example

tg list-msgs 123456789 --limit 10 --json

Flags

Flag	Description
`-h, --help`	help for list-msgs
`--human`	Force human-readable output (default on a TTY)
`--include-deleted`	Include tombstoned messages
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Max messages to return (default 50)
`--reverse`	Oldest first
`--since string`	YYYY-MM-DD inclusive lower bound
`--until string`	YYYY-MM-DD inclusive upper bound

`tg listen`¶

Listen for live Telegram updates

Use

tg listen [flags]

Example

tg listen --once --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`-h, --help`	help for listen
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--once`	Exit after one filter-matching update
`--only-dms`	Emit only 1-on-1 user messages; skip groups/channels
`--only-groups`	Emit only group/channel messages; skip 1-on-1 DMs

`tg login`¶

Interactively authorize this account against Telegram

Use

tg login [flags]

Example

tg login

Flags

Flag	Description
`-h, --help`	help for login
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--qr`	Authorize by scanning a Telegram QR code (API credentials still required)
`--qr-uri`	Print the QR login URI instead of rendering terminal blocks

`tg mark-read`¶

Mark history read up to and including --up-to

Use

tg mark-read <chat> [flags]

Example

tg mark-read 123456789 --up-to 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for mark-read
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--up-to int`	Mark read up to and including this message id; 0 means latest

`tg me`¶

Print authenticated user info

Use

tg me [flags]

Example

tg me --json

Flags

Flag	Description
`-h, --help`	help for me
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--offline`	Read cached self user info without connecting to Telegram

`tg pin-msg`¶

Pin a message in a chat

Use

tg pin-msg <chat> <message-id> [flags]

Example

tg pin-msg 123456789 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for pin-msg
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--silent`	Pin silently (no notification)

`tg promote`¶

promote user in chat

Use

tg promote <chat> <user-id> [flags]

Example

tg promote 987654321 123456789 --allow-write --confirm 987654321 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for promote
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg react`¶

Send a reaction to a message

Use

tg react <chat> <message-id> <emoji> [flags]

Example

tg react 123456789 1 "👍" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--big`	Send a big reaction (Premium)
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for react
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg search`¶

Search cached messages in a chat

Use

tg search <chat> <query> [flags]

Example

tg search 123456789 "shipping" --limit 20 --json

Flags

Flag	Description
`--case-sensitive`	Case-sensitive matching
`-h, --help`	help for search
`--human`	Force human-readable output (default on a TTY)
`--include-deleted`	Include tombstoned messages
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Max messages to return (default 50)

`tg send`¶

Send a text message

Use

tg send <chat> <text> [flags]

Example

tg send 123456789 "hello" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for send
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--no-webpage`	Disable link preview
`--reply-to int`	Reply-to message id
`--silent`	Send silently (no notification)
`--topic int`	Forum topic id

`tg send-by-username`¶

Send a text message by resolving an @username (no entity cache required)

Use

tg send-by-username <@user|@channel> <text> [flags]

Example

tg send-by-username @username "hello" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--dry-run`	Print payload preview without contacting Telegram
`-h, --help`	help for send-by-username
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--no-webpage`	Disable link preview
`--reply-to int`	Reply-to message id
`--silent`	Send silently

`tg set-permissions`¶

Set default chat permissions

Use

tg set-permissions <chat> [permissions] [flags]

Example

tg set-permissions <group-chat-id> --send-messages --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for set-permissions
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--send-messages`	Allow sending messages

`tg setup`¶

Create or update a private .env with Telegram app credentials

Use

tg setup [flags]

Example

tg setup [flags] --json

Flags

Flag	Description
`--api-hash string`	Telegram app API hash (never printed)
`--api-id string`	Telegram app API ID (never printed)
`--env-file string`	Environment file to create or update (default ".env")
`-h, --help`	help for setup
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg show`¶

Show recent cached messages in a chat

Use

tg show <chat> [flags]

Example

tg show 123456789 --limit 5 --json

Flags

Flag	Description
`-h, --help`	help for show
`--human`	Force human-readable output (default on a TTY)
`--include-deleted`	Include tombstoned messages
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Max messages to return (default 20)
`--reverse`	Show oldest first

`tg stats`¶

Show local cache statistics

Use

tg stats [flags]

Example

tg stats --json

Flags

Flag	Description
`-h, --help`	help for stats
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg sync`¶

Synchronize cached messages and optionally follow updates

Use

tg sync <chat> [flags]

Example

tg sync <chat> [flags] --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`--backoff-max-seconds float`	Maximum reconnect delay in seconds (default 30)
`--download-media`	Download media during catch-up
`--follow`	Continue listening after the initial catch-up
`-h, --help`	help for sync
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-media-size-mb int`	Maximum media file size during catch-up (default 100)
`--max-messages int`	Maximum history messages to reconcile (default 100)
`--once`	With --follow, stop after one matching live event
`--overwrite-media`	Overwrite existing catch-up media

`tg sync-contacts`¶

Sync Telegram contacts into the local DB

Use

tg sync-contacts [flags]

Example

tg sync-contacts --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for local DB writes
`-h, --help`	help for sync-contacts
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg terminate-session`¶

Terminate one of your authorized Telegram sessions

Use

tg terminate-session <session-hash> [flags]

Example

tg terminate-session <session-hash> --allow-write --confirm <session-hash> --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for terminate-session
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg topic-create`¶

Create a forum topic

Use

tg topic-create <chat> <title> [flags]

Example

tg topic-create <forum-chat-id> "Support" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for topic-create
`--human`	Force human-readable output (default on a TTY)
`--icon-color int`	Topic icon color
`--icon-emoji-id int`	Topic icon custom emoji id
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg topic-edit`¶

Edit a forum topic

Use

tg topic-edit <chat> <topic-id> [flags]

Example

tg topic-edit <forum-chat-id> 1 --title "Renamed" --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for topic-edit
`--human`	Force human-readable output (default on a TTY)
`--icon-emoji-id int`	New icon custom emoji id
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--title string`	New topic title

`tg topic-pin`¶

Pin a forum topic

Use

tg topic-pin <chat> <topic-id> [flags]

Example

tg topic-pin <forum-chat-id> 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for topic-pin
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg topic-unpin`¶

Unpin a forum topic

Use

tg topic-unpin <chat> <topic-id> [flags]

Example

tg topic-unpin <forum-chat-id> 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for topic-unpin
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg topics-list`¶

List forum topics

Use

tg topics-list <chat> [flags]

Example

tg topics-list <forum-chat-id> --json

Flags

Flag	Description
`-h, --help`	help for topics-list
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum topics (default 50)
`--query string`	Filter query

`tg unban-from-chat`¶

unban-from-chat user in chat

Use

tg unban-from-chat <chat> <user-id> [flags]

Example

tg unban-from-chat <group-chat-id> 123456789 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for unban-from-chat
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg unblock-user`¶

Unblock a previously blocked user

Use

tg unblock-user <user> [flags]

Example

tg unblock-user 123456789 --allow-write --confirm 123456789 --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for unblock-user
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)

`tg unpin-msg`¶

Unpin a previously pinned message

Use

tg unpin-msg <chat> <message-id> [flags]

Example

tg unpin-msg 123456789 1 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for unpin-msg
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--silent`	Pin silently (no notification)

`tg unread`¶

List recently cached incoming messages

Use

tg unread [flags]

Example

tg unread --json

Flags

Flag	Description
`-h, --help`	help for unread
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--limit int`	Maximum messages (default 50)

`tg upload-album`¶

Upload a 2–10 item media album

Use

tg upload-album <chat> <file>... [flags]

Example

tg upload-album <chat> <file>... [flags] --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--caption string`	Album caption (placed on the first item)
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for upload-album
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum size per item in MiB (default 100)
`--media-kind string`	Album media kind: auto, photo, video, audio, or document (default "auto")
`--reply-to int`	Reply-to message id
`--silent`	Send silently
`--supports-streaming`	Mark video items as streamable

`tg upload-document`¶

Upload a document

Use

tg upload-document <chat> <file> [flags]

Example

tg upload-document 123456789 ./file.txt --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--caption string`	Media caption
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--filename string`	Override uploaded filename
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for upload-document
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum upload size in MiB (default 100)
`--reply-to int`	Reply-to message id
`--silent`	Send silently

`tg upload-photo`¶

Upload a photo

Use

tg upload-photo <chat> <file> [flags]

Example

tg upload-photo 123456789 ./photo.png --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--caption string`	Media caption
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for upload-photo
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum upload size in MiB (default 100)
`--reply-to int`	Reply-to message id
`--silent`	Send silently

`tg upload-video`¶

Upload a video

Use

tg upload-video <chat> <file> [flags]

Example

tg upload-video 123456789 ./video.mp4 --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--caption string`	Media caption
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for upload-video
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum upload size in MiB (default 100)
`--reply-to int`	Reply-to message id
`--silent`	Send silently
`--supports-streaming`	Mark video as streamable

`tg upload-voice`¶

Upload an OGG/Opus voice message

Use

tg upload-voice <chat> <file> [flags]

Example

tg upload-voice 123456789 ./voice.ogg --allow-write --json

Flags

Flag	Description
`--allow-write`	Required for any Telegram-side write
`--caption string`	Media caption
`--confirm string`	Typed confirm against the resolved id
`--dry-run`	Print payload preview without contacting Telegram
`--fuzzy`	Allow title-based selectors for write commands
`-h, --help`	help for upload-voice
`--human`	Force human-readable output (default on a TTY)
`--idempotency-key string`	Per-account replay-safe key
`--json`	Force JSON envelope output (default when stdout is not a TTY)
`--max-size-mb int`	Maximum upload size in MiB (default 100)
`--reply-to int`	Reply-to message id
`--silent`	Send silently

`tg version`¶

Print build version

Use

tg version [flags]

Example

tg version --json

Flags

Flag	Description
`-h, --help`	help for version
`--human`	Force human-readable output (default on a TTY)
`--json`	Force JSON envelope output (default when stdout is not a TTY)

Commands¶

Index¶

tg account-sessions¶

tg accounts-add¶

tg accounts-list¶

tg accounts-remove¶

tg accounts-show¶

tg accounts-use¶

tg backfill¶

tg backfill-entities¶

tg ban-from-chat¶

tg block-user¶

tg chat-description¶

tg chat-invite-link¶

tg chat-members¶

tg chat-photo¶

tg chat-pinned-list¶

tg chat-title¶

tg chats-info¶

tg completion¶

tg contacts¶

tg delete-msg¶

tg demote¶

tg discover¶

tg doctor¶

tg download-album¶

tg download-media¶

tg edit-msg¶

tg export¶

tg folder-add-chat¶

tg folder-create¶

tg folder-delete¶

tg folder-edit¶

tg folder-remove-chat¶

tg folder-show¶

tg folders-list¶

tg folders-reorder¶

tg forward¶

tg get-msg¶

tg help¶

tg import-telethon-session¶

tg kick¶

tg leave-chat¶

tg list-msgs¶

tg listen¶

tg login¶

tg mark-read¶

tg me¶

tg pin-msg¶

tg promote¶

tg react¶

tg search¶

tg send¶

tg send-by-username¶

tg set-permissions¶

tg setup¶

tg show¶

tg stats¶

tg sync¶

tg sync-contacts¶

tg terminate-session¶

tg topic-create¶

tg topic-edit¶

tg topic-pin¶

tg topic-unpin¶

tg topics-list¶

tg unban-from-chat¶

tg unblock-user¶

tg unpin-msg¶

tg unread¶

tg upload-album¶

tg upload-document¶

tg upload-photo¶

tg upload-video¶

tg upload-voice¶

tg version¶

`tg account-sessions`¶

`tg accounts-add`¶

`tg accounts-list`¶

`tg accounts-remove`¶

`tg accounts-show`¶

`tg accounts-use`¶

`tg backfill`¶

`tg backfill-entities`¶

`tg ban-from-chat`¶

`tg block-user`¶

`tg chat-description`¶

`tg chat-invite-link`¶

`tg chat-members`¶

`tg chat-photo`¶

`tg chat-pinned-list`¶

`tg chat-title`¶

`tg chats-info`¶

`tg completion`¶

`tg contacts`¶

`tg delete-msg`¶

`tg demote`¶

`tg discover`¶

`tg doctor`¶

`tg download-album`¶

`tg download-media`¶

`tg edit-msg`¶

`tg export`¶

`tg folder-add-chat`¶

`tg folder-create`¶

`tg folder-delete`¶

`tg folder-edit`¶

`tg folder-remove-chat`¶

`tg folder-show`¶

`tg folders-list`¶

`tg folders-reorder`¶

`tg forward`¶

`tg get-msg`¶

`tg help`¶

`tg import-telethon-session`¶

`tg kick`¶

`tg leave-chat`¶

`tg list-msgs`¶

`tg listen`¶

`tg login`¶

`tg mark-read`¶

`tg me`¶

`tg pin-msg`¶

`tg promote`¶

`tg react`¶

`tg search`¶

`tg send`¶

`tg send-by-username`¶

`tg set-permissions`¶

`tg setup`¶

`tg show`¶

`tg stats`¶

`tg sync`¶

`tg sync-contacts`¶

`tg terminate-session`¶

`tg topic-create`¶

`tg topic-edit`¶

`tg topic-pin`¶

`tg topic-unpin`¶

`tg topics-list`¶

`tg unban-from-chat`¶

`tg unblock-user`¶

`tg unpin-msg`¶

`tg unread`¶

`tg upload-album`¶

`tg upload-document`¶

`tg upload-photo`¶

`tg upload-video`¶

`tg upload-voice`¶

`tg version`¶