Commands¶

tg --help shows all 70 commands. This page is generated from the local Cobra help output, then kept as plain Markdown for the docs site.

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 edit-msg`	Edit a previously sent message
`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 show`	Show recent cached messages in a chat
`tg stats`	Show local cache statistics
`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-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 --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 1240314255 --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 database size in MiB
`--max-messages int`	Maximum cached messages per chat (default 100)
`--throttle-seconds float`	Seconds to sleep between chats

`tg backfill-entities`¶

Populate the local entity cache so chat_id-keyed sends work

Use

tg backfill-entities [flags]

Example

tg backfill-entities --json

Flags

Flag	Description
`-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> 1240314255 --allow-write --confirm 1240314255 --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 1240314255 --allow-write --confirm 1240314255 --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 1240314255 --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 1240314255 --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 [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 1240314255 1 --allow-write --confirm 1240314255 --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 <group-chat-id> 1240314255 --allow-write --confirm 1240314255 --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 --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 edit-msg`¶

Edit a previously sent message

Use

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

Example

tg edit-msg 1240314255 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 folder-add-chat`¶

Mutate folder chat membership

Use

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

Example

tg folder-add-chat 2 1240314255 --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 1240314255 --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 1240314255 --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 1240314255 1240314255 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 1240314255 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

Standard global flags only. No write gate (this is a local-file copy, not a Telegram-side write).

Example

tg import-telethon-session ~/path/to/python/tgctl/accounts/default/tg.session

The auth_key is reused, so no SMS round-trip is needed. The destination is the current --account's tg.session file.

`tg kick`¶

kick user in chat

Use

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

Example

tg kick <group-chat-id> 1240314255 --allow-write --confirm 1240314255 --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 1240314255 --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 update

`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)

`tg mark-read`¶

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

Use

tg mark-read <chat> [flags]

Example

tg mark-read 1240314255 --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 1240314255 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 <group-chat-id> 1240314255 --allow-write --confirm 1240314255 --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 1240314255 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 1240314255 "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 1240314255 "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 show`¶

Show recent cached messages in a chat

Use

tg show <chat> [flags]

Example

tg show 1240314255 --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-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> 1240314255 --allow-write --confirm 1240314255 --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 1240314255 --allow-write --confirm 1240314255 --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 1240314255 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-document`¶

Upload a document

Use

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

Example

tg upload-document 1240314255 ./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 1240314255 ./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 1240314255 ./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 1240314255 ./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 edit-msg¶

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 show¶

tg stats¶

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-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 edit-msg`¶

`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 show`¶

`tg stats`¶

`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-document`¶

`tg upload-photo`¶

`tg upload-video`¶

`tg upload-voice`¶

`tg version`¶