Telegram CLI Cheatsheet

Telegram CLI is basically full-blown Telegram client, like the Telegram app on your phone or laptop, that works in the command-line instead of with a GUI.

This article contains a collection of useful information and commands for working with Telegram CLI.

Contents

• Preamble
• Useful Information
• Commands

Preamble

Note: for installation instructions, refer to the README of the GitHub repo, or just use this Docker image, which contains Ubuntu 16.04 with Telegram CLI pre-installed.

The executable of Telegram CLI is called telegram-cli. It starts up an interactive command interpreter in which you type Telegram commands.

The main part of this article explains a subset of these commands. A complete list of all the Telegram CLI commands can be found here.

Note that you can also execute all of these commands in a one-off fashion without entering the interactive mode of Telegram CLI. For this, use the -e option when you start Telegram CLI:

telegram-cli -e "<command>"

It is advised to also specify the -W option when you execute commands via the -e option, in order to make sure all the required data has been loaded before executing your commands:

telegram-cli -W -e "<command>"

You can also get all the output in JSON format with the --json option:

telegram-cli --json -W -e "<command>"

A list with all the command-line options for the Telegram CLI executable can be printed with:

telegram-cli -h

Useful Information

Here are some things that you need to know about Telegram CLI to better understand the subsequent commands of the cheatsheet.

Peer Type Nomenclature

As explained in my other article about Telegram Basics, there are four peer types in Telegram, namely, users, bots, groups, and channels.

Furthermore, users can be private or public, bots are always public, groups are divided into basic groups and supergroups, where basic groups are always private and supergroups can be private or public, and finally, channels can be private or public.

Remember that public vs. private comes down to having or not having a username. A username makes a peer publicly accessible.

Now, Telegram CLI looks at these peer types a bit differently. Namely:

• Users and bots are referred to as users
• Basic groups are referred to as chats
• Supergroups and channels are referred to as channels

Here is an overview:

The Telegram CLI has commands that are specific to these three types of peers (user, chat, and channel). So, the thing to get used to is that you have to use the user_* commands for users and bots, the chat_* commands only for basic groups, and the channel_* commands for channels and supergroups.

Upgrade from Basic Group to Supergroup

In Telegram, when you upgrade a group from a basic group to a supergroup (remember that every group is by default a basic group, as explained in Telegram Basics), then you actually create a new peer for the supergroup, and the old one for the basic group just sticks around.

This means, if you create a group called MyGroup, use it for a bit, and then decide to upgrade to a supergroup, then you will actually have two MyGroup in the output of dialog_list (see below), one reported as a Chat, and one reported as a Channel.

The Chat version of MyGroup remains in the state immediately before the group was upgraded to a supergroup. This version is usually not accessed anymore, but it just sticks around as its own peer. The Channel version, on the other hand, is the new supergroup version of MyGroup, and it will contain all the new messages and members. This is the version that you will usually use from now on.

One consequence of this is that if you fetch all the messages from the Channel version of MyGroup with the history command, you get only the messages up to the point where the group has been upgraded to a supergroup. The remaining messages (from creation of the group until the upgrade to a supergroup) are present only in the Chat version of MyGroup.

This issue is described here and here.

The old Chat version of a group is usually accessible in Telegram CLI by appending #1 to the group name. That is, for example, MyGroup#1.

How To Specify a Peer

In the following cheatsheet commands, the <peer> option identifies the user, bot, group, or channel to which the command applies.

The value of <peer> can be one of the following:

• The display name of the peer with spaces replaced by underscores
• The username of the peer (if available) with a leading @

These two options are equivalent.

For example, if you have a supergroup with a display name of Crypto Bay Toronto and a username of cryptobayto,then the following two commands are equivalent:

channel_info Crypto_Bay_Toronto
channel_info @cryptobayto

Just remember this:

• If you use the username, then you must prepend an @
• If you use the display name, the capitalisation matters (that is, crypto_bay_toronto would not work)

Best is, to just use the auto-complete feature of Telegram CLI.

Tip:

You can use the auto-complete feature to get an overview of all the available display names and usernames. The following lists the display names of all the known users and bots:

user_info <TAB><TAB>

And to display all the corresponding usernames, type:

user_info @<TAB><TAB>

You can do the same with channel_info for supergroups and channels, and chat_info for basic groups. The auto-complete feature is smart enough to suggest only completions for the peer category to which the preceding command applies (note that with chat_info @<TAB><TAB> there will be no output, as basic groups cannot have a username).

List of Commands

Messages

List the most recent conversations

dialog_list

This lists the peer display names, and some other information, of the most recently active conversations (most recently active conversation at the bottom).

This is more or less what you see on the home screen of most Telegram apps, but in reverse order (newest conversation at the bottom, and oldest on top).

You can also specify the number of conversations to list like this:

dialog_list [limit]

The default value for limit is 100.

Send a message to a user, bot, group, or channel

msg <peer> <text>

The <text> parameter is the text to send. It may or may not be enclosed in single or double quotes. The following values for <text> are equivalent.

"Hi there, how are you?"
'Hi there, how are you?'
Hi there, how are you?

However, if you use single or double quotes, you can also insert newlines with \n. For example, you can do something like this:

msg @santa "Hi Santa,\n\nThanks for the presents.\n\nBest,\nDaniel"

This sends the following message:

Hi Santa,
Thanks for the presents.
Best,
Daniel

Note: you can send messages like this to any user and bot, and to any group that you are a member of, but not to channels in which you are merely a subscriber, but not an admin. This is because only admins of a channel can send messages to this channel.

Get message history with a user, bot, group, or channel

history <peer> [limit]

This prints the last chunk of messages that have been sent to/from this peer. The limit option defines the number of messages to be printed (the default seems to be 40).

Important: this also marks all the messages with this peer as read.

Basic Groups, Supergroups, and Channels

Join a supergroup or channel via their username

resolve_username <username>
channel_join @<username>

The resolve_username command fixes what seems to be a glitch in Telegram CLI. If you omit it, you will likely get a FAIL: 38: can not parse arg #1 error.

Note: channel_join seems to also work with the display name (with spaces replaced by underscores). So, the following example would be valid too:

> resolve_username theprogrammingart
The Art of Programming
> channel_join The_Art_of_Programming

Join a basic group via an invite link

import_chat_link <link>

For example:

import_chat_link https://t.me/joinchat/Gx1BvRIu_lGsZE4A21EwRQ

The following options also work:

import_channel_link t.me/joinchat/Gx1BvRIu_lGsZE4A21EwRQ
import_channel_link Gx1BvRIu_lGsZE4A21EwRQ

The last option (using only the hash) is probably the preferred one.

Note that this is the only way to join a basic group other than being added by somebody else, as joining via username is not available for basic groups (because basic groups are always private and cannot have a username).

Join a supergroup or channel via an invite link

import_channel_link <link>

The rest is the same as above (join a basic group via an invite link).

Note that this works for both, private and public, supergroups and channels, as long as the supergroup or channel has generated an invite link.

Create an invite link for a basic group

export_chat_link <peer>

This invalidates any previously created invite link for this basic group.

Create an invite link for a supergroup or channel

export_channel_link <peer>

This invalidates any previously created invite link for this supergroup or channel.

Get Info

Get the display name belonging to a username

resolve_username <username>

Get information about a user or bot

user_info <peer>

Get information about a basic group

chat_info <peer>

Get information about a supergroup or channel

channel_info <peer>

Get information about the logged-in user

get_self

This outputs the same information as user_info <peer>, but about yourself.

Miscellaneous

Print help

help

This outputs the information displayed here.

You can also do:

help [command]

This prints only the line corresponding to the specified command.

Print version of Telegram CLI

version

Exit

quit

This is the equivalent of “How to get out of Vim” for Telegram CLI.