Authentication
To send messages as a user, you need to sign in to your account once. tguser uses MTProto
via Kurigram, so api_id and api_hash are required.
Step 1. Get api_id and api_hash
- Open https://my.telegram.org and log in with your phone number.
- Go to the API development tools section.
- Create an application (any title and description will do).
- Copy the api_id (a number) and api_hash (a string).
These are secrets. Do not publish them or commit them to a repository.
Step 2. Sign In
tguser loginThe command will prompt you, in order, for:
api_idandapi_hash— if they are not set yet (they will be saved to~/.config/tguser/.env);- your phone number in
+1…format — if--phoneorTGUSER_PHONE_NUMBERis not set (after a successful sign-in it is saved to~/.config/tguser/.envas well); - the confirmation code from Telegram;
- your two-factor authentication password — only if it is enabled.
On success, a panel with the account’s name, username, and id is shown.
Passing Parameters Up Front
You can provide values as flags to avoid entering them interactively:
tguser login --api-id 1234567 --api-hash 0123456789abcdef0123456789abcdef --phone +15551234567| Flag | Description |
|---|---|
--api-id | api_id from my.telegram.org |
--api-hash | api_hash from my.telegram.org |
--phone | Phone number (falls back to TGUSER_PHONE_NUMBER) |
The same values can come from the environment instead of flags:
export TGUSER_API_ID=1234567
export TGUSER_API_HASH=0123456789abcdef0123456789abcdef
export TGUSER_PHONE_NUMBER=+15551234567
tguser loginThe confirmation code and 2FA password are still requested interactively.
Check the Current Account
tguser whoamiPrints a table: ID, name, username, phone.
Sign Out
tguser logoutEnds the session on Telegram’s side and removes the local session file
~/.config/tguser/tguser.session.
Where the Session Is Stored
After signing in, a session file ~/.config/tguser/tguser.session is created. As long as it
exists and is valid, you don’t need to login again — the sending commands work right away.
⚠️ Never delete this file. It stores your Telegram authorization key; without it every command stops working and you have to go through the interactive
tguser loginagain (phone, code, cloud password). To sign out, usetguser logout— it properly terminates the session on Telegram’s side and removes the file itself. The same applies to the chat database~/.config/tguser/tguser.db. Both files are explained in 03. Configuration.
For more on file locations and variables, see 03. Configuration.