Log in to Better-TG-CLI
A login key lets you log in to your Telegram account through the CLI without creating your own API keys on my.telegram.org. Confirm your email with a code: one email, one login key, good for logging in on up to 3 computers; asking again replaces it. Your messages and session stay on your computer only. Already have your own keys? Skip to installation.
Your login key
Shown only once. Save it and do not send it to an agent or anyone else: you will need it at the login step, and again on your other computers (up to 3).
Passing the login key to the CLI… If the CLI page did not open, copy the key and paste it there.
How to install
Paste the prompt into your agent
Claude Code, Codex, Cursor or any other agent with a terminal. It installs the CLI and the skill and opens the login page.
Connect my Telegram through Better-TG-CLI (https://github.com/TheVilfer/better-tg-cli): 1. Install the CLI: `brew install thevilfer/tap/better-tg-cli`. Without Homebrew: `npm install -g better-tg-cli` (needs Node 20+). On Windows: `scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket` and `scoop install better-tg-cli`. 2. Run `telegram onboard --json` (in the background if your timeout is shorter than 15 minutes). A page opens where I get a login key, scan a QR code and enter my password myself. Wait for the `done` event. Don’t ask me for codes, passwords or the login key, and don’t fill in the page yourself. 3. Install the skill for yourself: `telegram skill install`. 4. Check the login with `telegram whoami` and briefly tell me what you can now do in Telegram.
Go through the login page
The agent opens it in the browser on your computer. There you get a login key (your email is confirmed with a code and the key comes back by itself), scan the QR code in Telegram (Settings → Devices → Link Desktop Device) and enter your cloud password if you have one. The agent sees none of it.
Done
Ask your agent, for example: “what’s unread in my Telegram?” It can write on your behalf only after you allow it: telegram write-access on --for 1h.
Claude Desktop has no terminal, so it can’t do this. Use PRO mode for it.
Install the CLI
macOS or Linux, in a terminal:
brew install thevilfer/tap/better-tg-cli
No Homebrew? npm install -g better-tg-cli (Node 20+). On Windows: scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket, then scoop install better-tg-cli.
Log in to Telegram yourself
Login is interactive, so you do it, not the agent:
telegram auth --login-key --qr
Paste the login key from this page and scan the QR code in Telegram: Settings → Devices → Link Desktop Device. With your own keys from my.telegram.org: telegram auth --qr. On versions before 0.37 the flag is --invite.
Connect your agent
Install the plugin
In Claude Code, type these one by one. The plugin is the skill and the MCP server in one.
/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli
Restart Claude Code
Then ask, for example: “what’s unread in my Telegram?”
Install the plugin
In a regular terminal:
codex plugin marketplace add TheVilfer/better-tg-cli
codex plugin add better-tg-cli@better-tg-cli
Open Codex again
The skill and the MCP server load by themselves. Ask: “what did Alice write?”
Install the MCP server
Cursor asks for confirmation: click Install.
Add the skill (optional)
It teaches the agent to work with Telegram carefully:
npx skills add TheVilfer/better-tg-cli -g -a cursor -y
Download the extension
Double-click the file: Claude shows a card, click Install. The extension needs neither Node nor brew.
Ask in the chat
For example: “summarize what’s unread in Telegram”.
Done
By default the agent only reads. It can write on your behalf once you allow it:
telegram write-access on --for 1h