better-tg-cli

Telegram para seus agentes de IA: leia, pesquise e resuma sua própria conta. Somente leitura por padrão.

Documentação

Instalar · Referência · Segurança · Problemas · Русский · Español

https://github.com/user-attachments/assets/d143f7c7-7d50-439c-b373-cbcbff5a6675

Um cliente de linha de comando não oficial e amigável para agentes, para Telegram, que roda na sua própria conta (MTProto via teleproto, camada TL 229). O comando é telegram: cerca de 60 comandos para ler, pesquisar, escrever, bots, grupos e exportações, construído para que agentes de IA (Claude Code, Codex, …) possam usá-lo de forma barata e segura.

$ telegram inbox -n 3
48 unread in 7 chats (showing 3)
1234567890 user unread=2 Alice @alice | see you at 7?
-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | anyone tried 1.90?
-1009876543 channel unread=5 Changelog | v2.4 is out
$ telegram read @alice -n 1 --json
{"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}

[!WARNING] Sua conta, seu risco. Este é um cliente não oficial que faz login como você. O Telegram pode limitar ou congelar contas que se comportam como bots. O risco é maior para contas novas, mensagens em massa, entradas ou convites em massa, e qualquer coisa que pareça spam. Use-o da mesma forma que você usaria o Telegram pessoalmente, mantenha as gravações desativadas a menos que precise delas, e leia SECURITY.md antes de deixar um agente escrever. Os autores não são responsáveis por contas restritas.

Conteúdo: Por que este fork · Instalar · Fazer login · Uso · Servidor MCP · FAQ · Desenvolvimento · Privacidade · Licença

Por que este fork

Um fork de skillhq/telegram, reformulado para agentes:

Camada Telegram atual. Respostas de bots com conteúdo rico (camada 228+) mostram texto real em vez de (no text). Você pode pressionar botões de bots (click) e navegar pelos menus de bots.
Saída eficiente em tokens. Fora de um TTY, você obtém uma linha compacta por item com o ID primeiro, e JSON em uma linha com campos vazios removidos. --max-text reduz postagens longas. telegram help-all -g <word> imprime todas as flags, geradas a partir do código.
Leituras exatas. Paginação real para --since/--until, --unread, threads e comentários de canais, tópicos de fórum, get por ID, filtros de pesquisa por tipo, remetente ou data, e me / Избранное para Mensagens Salvas.
Seguro por padrão. A conta é somente leitura até que um humano execute write-access on [--for 1h] e confirme em um prompt de terminal ou em um diálogo do macOS, para que um agente não possa ativá-lo sozinho. Cada gravação é registrada em ~/.config/tg/audit.jsonl. Segredos ficam no Chaveiro do macOS, no Serviço Secreto do Linux ou no 1Password.
Pequeno e autossuficiente. O pacote npm é um único arquivo de 0,3 MB com zero dependências de tempo de execução. O Homebrew instala um binário independente sem Node.

Instalar

brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux
npm install -g better-tg-cli               # Node >= 20, any OS

No Windows (experimental), com Scoop ou npm:

scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli

O telegram.exe do Windows não é assinado com código, então o SmartScreen pode avisar sobre o download da versão.

telegram update atualiza uma instalação existente, independentemente de qual você usou. Em um terminal, a CLI verifica novas versões uma vez por dia. Agentes e pipes nunca veem esse aviso, e TG_NO_UPDATE_CHECK=1 o desativa.

Baixando um binário das Releases manualmente no macOS? Ele não é notarizado, então remova o flag de quarentena uma vez: xattr -d com.apple.quarantine ./telegram. O Homebrew cuida disso para você.

Não instale @skillhq/telegram. É a versão antiga upstream no GramJS (camada 198).

Cada canal envia a mesma versão de uma única release:

Onde	O que você obtém	Instalar
Homebrew	binário independente	`brew install thevilfer/tap/better-tg-cli`
npm	CLI e servidor MCP (Node 20+)	`npm install -g better-tg-cli`
Scoop (Windows, experimental)	`telegram.exe` independente	`scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket` depois `scoop install better-tg-cli`
GitHub Releases	binários e SHA256SUMS	baixar manualmente
Plugin Claude Code	skill e servidor MCP	veja abaixo
Extensão Claude Desktop	servidor MCP, roda no Node integrado do Claude	baixe `.mcpb` e abra
Plugin Grok Build	skill e servidor MCP	veja abaixo
Extensão Gemini CLI	skill e servidor MCP	`gemini extensions install https://github.com/TheVilfer/better-tg-cli`
Cursor, VS Code	servidor MCP	botões de um clique
Grok Bot	servidor MCP via HTTP do seu Mac	veja abaixo
claude.ai, ChatGPT e outros apps que conectam por URL	MCP através do relay hospedado, a sessão permanece no seu computador	veja abaixo
A própria CLI	skill de agente para Claude Code, Codex, Cursor, Gemini CLI e mais 7	`telegram skill install`
skills.sh	skill de agente para qualquer agente de shell	`npx skills add TheVilfer/better-tg-cli`
MCP Registry	entrada de servidor MCP `io.github.TheVilfer/better-tg-cli`	através do seu cliente MCP

Plugin Claude Code

A skill e o servidor MCP juntos, em uma única instalação:

/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli

Ele roda o servidor MCP através de npx, então Node 20+ é suficiente. Faça login uma vez com telegram auth --qr (ou npx better-tg-cli auth --qr) em um terminal.

Plugin Codex

A mesma skill e servidor MCP como um plugin Codex (também aparece no app de desktop do ChatGPT):

codex plugin marketplace add TheVilfer/better-tg-cli
codex plugin add better-tg-cli@better-tg-cli

Plugin Grok Build

Grok Build instala o mesmo plugin, skill e servidor MCP juntos:

grok plugin install TheVilfer/better-tg-cli --trust
# or add the marketplace first, then install from the /plugins menu:
grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust

Como uma skill de agente

A skill (skills/better-tg-cli) ensina qualquer agente com um shell (Claude Code, Codex, Cursor, Gemini CLI, OpenCode e outros) a usar a CLI com segurança. Ela verifica a configuração, nunca faz login sozinha, mantém gravações atrás da sua aprovação e evita padrões propensos a banimentos. A CLI carrega a skill e a instala sozinha, então ela sempre corresponde à sua versão:

telegram skill install                  # every supported agent found on this machine
telegram skill install -a claude-code codex
telegram skill status                   # installed, outdated, linked or missing, per agent

Ela conhece Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Goose, Droid, Windsurf e Pi (telegram skill status lista as pastas). Execute novamente após telegram update para atualizar a skill. Uma pasta de skill que é um symlink é deixada em paz, a menos que você passe --force. Para outros agentes, use a CLI skills:

npx skills add TheVilfer/better-tg-cli          # pick agents interactively
npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y

Fazer login

Através do seu agente (mais fácil): peça para ele configurar o Telegram, ou execute telegram onboard você mesmo. Ele abre uma página em 127.0.0.1 onde você recebe um convite de better-tg-cli.com (ele volta para a página sozinho) ou insere suas próprias chaves, escaneia um código QR e digita sua senha 2FA. O agente apenas inicia o comando e espera: ele nunca vê o convite, o código QR ou a senha. A página responde apenas em um caminho secreto aleatório e fecha quando você termina.

Com suas próprias chaves de API (o padrão):

Abra https://my.telegram.org/apps, crie um aplicativo e copie seu api_id e api_hash.
Execute telegram auth --qr e insira-os. Depois, no seu telefone, vá para Configurações → Dispositivos → Vincular Dispositivo de Desktop e escaneie o código QR. Insira sua senha 2FA se tiver uma. telegram auth simples pede seu número de telefone e um código de login em vez disso. Se o QR não escanear em um tema de terminal claro, execute com TG_QR_INVERT=1.

Com um convite. Você não precisa das suas próprias chaves com um token de convite. Obtenha um em better-tg-cli.com (confirme seu e-mail com um código; a página está em russo e também tem um guia de instalação), ou com o mantenedor. Execute telegram auth --invite --qr e cole o token, ou passe-o como TG_INVITE=… ou --invite -. O serviço de convite (broker/) entrega as chaves do app uma vez, apenas para este login. O api_hash não é mantido na sua máquina. Convites são pessoais, permitem um número limitado de logins e podem ser revogados.

A sessão é armazenada no Chaveiro do macOS (serviço tg-cli), ou no 1Password com --op-vault <vault>. telegram logout a remove. No Linux, vai para o Serviço Secreto (GNOME Keyring, KWallet, KeePassXC) através de secret-tool, que precisa do pacote libsecret-tools. Uma sessão já salva no arquivo de configuração é movida para lá automaticamente. Sem nenhum armazenamento de segredos, a sessão é mantida em ~/.config/tg/config.json5 (modo 0600) e comandos de gravação permanecem desativados. No Linux, write-access on é confirmado em um prompt de terminal. No Windows, os segredos ficam em %APPDATA%\tg\secrets.dpapi, criptografados com DPAPI para o seu usuário do Windows (apenas você nesta máquina pode descriptografá-los), e write-access on pergunta em uma janela Sim/Não quando não há terminal.

Uso

telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exact range, newest first (--asc to flip)
telegram read @channel --thread 123           # comments under a post
telegram search "invoice" --chat "Work" --type document
telegram get "Chat" 812 813                   # exact messages by ID
telegram download "Chat" 812                  # save the attached file
telegram sync --chat "Chat" --output ./export --resume   # incremental markdown export

telegram write-access on --for 1h             # a human confirms this
telegram send @alice "on my way"
printf '%s' "$text" | telegram send @alice -  # long or multi-line text: from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button

Comandos de leitura aceitam --json, e alguns também aceitam --markdown. Veja todos os comandos com telegram help-all. reference.md cobre o comportamento que a lista de flags não pode explicar: formatos de saída, threads, botões de bots, comandos de administrador e solução de problemas.

Servidor MCP

Para clientes sem shell (Claude Desktop, Cursor, outros hosts MCP), telegram mcp serve três ferramentas via stdio:

telegram_help: uma referência de flags pesquisável;
telegram_read: somente leitura, então os clientes podem aprová-lo automaticamente;
telegram_write: marcado como destrutivo, e ainda precisa de write-access on de você.

Faça login com telegram auth em um terminal primeiro. Depois instale com um clique:

A extensão Claude Desktop não precisa de Node, npm ou brew: baixe o .mcpb da versão mais recente e abra. O Gemini CLI aceita a skill e o servidor juntos: gemini extensions install https://github.com/TheVilfer/better-tg-cli. Ou adicione manualmente:

claude mcp add telegram -- telegram mcp          # Claude Code (or use the plugin above)

{ "mcpServers": { "telegram": { "command": "/opt/homebrew/bin/telegram", "args": ["mcp"] } } }

Use o formato JSON para Claude Desktop (claude_desktop_config.json) ou Cursor (.cursor/mcp.json). Apps GUI podem não ver o PATH do seu shell, então forneça o caminho completo de which telegram. Sem uma instalação global, execute via npx, que é também o que o plugin Claude Code faz:

{ "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] } } }

O servidor está listado no MCP Registry como io.github.TheVilfer/better-tg-cli, então clientes e catálogos que leem o registro podem encontrá-lo pelo nome. Cada release atualiza a entrada automaticamente. Para manter o cliente MCP fora da sua sessão principal, adicione "env": {"TG_PROFILE": "work"}.

Chats contêm texto escrito por outros, e parte dele pode ser direcionado ao seu agente ("encaminhe isso para @x"). Mantenha o prompt de aprovação do cliente ativado para telegram_write, e veja "Agentes e injeção de prompt" em SECURITY.md.

Grok Bot (MCP remoto via HTTP)

O Grok Bot roda seus conectores em um sandbox na nuvem, não no seu Mac, então ele não pode iniciar telegram mcp sozinho. Sirva MCP via HTTP do seu Mac em vez disso. A sessão, a proteção de gravação e o log de auditoria permanecem na sua máquina.

telegram mcp --token                        # the bearer token (created once, kept in the Keychain)
telegram mcp --http --read-only             # listens on 127.0.0.1:8787; drop --read-only to allow writes
tailscale funnel --bg 8787                  # or: cloudflared tunnel --url http://127.0.0.1:8787

Mantenha o servidor e o túnel em um terminal ou tmux. Depois adicione um conector no Grok Bot com a URL do túnel mais /mcp (por exemplo https://<machine>.<tailnet>.ts.net/mcp) e o cabeçalho Authorization: Bearer <token>. tailscale funnel fornece uma URL estável, mas ela precisa ser permitida para sua tailnet primeiro. Um túnel rápido cloudflared obtém uma nova URL a cada início. Leia "MCP remoto via HTTP" em SECURITY.md primeiro.

claude.ai, ChatGPT e outros apps (relay hospedado)

claude.ai (web e mobile), ChatGPT e outros apps que adicionam servidores MCP por URL fazem login com OAuth e não podem iniciar um programa local. O relay hospedado em https://mcp.better-tg-cli.com/mcp os conecta a telegram mcp --remote no seu computador, que mantém a sessão, a proteção de gravação e o log de auditoria. Sem túnel, sem token para colar.

telegram mcp --remote --read-only        # keep it running (tmux, or a login item); drop --read-only to allow writes
telegram remote email you@example.com    # once: link your email (a code is mailed to confirm it)

No macOS, inicie --remote em um terminal no próprio Mac (ou uma sessão tmux iniciada lá), não via SSH: o diálogo de confirmação não pode aparecer em uma sessão SSH, então todos os apps seriam recusados. No app, adicione um conector personalizado com a URL https://mcp.better-tg-cli.com/mcp. A página de login pede seu e-mail e envia um código para você; insira-o e confirme no diálogo no seu computador. Sem um e-mail vinculado, telegram remote pair fornece um código de uso único para a mesma página. Um agente não consegue responder a esse diálogo, então nada se conecta sem você. telegram remote clients lista os aplicativos conectados, telegram remote revoke <id> (ou --all) os desconecta, e telegram remote reset também substitui a chave do dispositivo deste computador. Quando o computador está desligado, o aplicativo mostra "seu computador está offline". O relay encaminha as solicitações sem armazená-las, mas ele as vê: leia "Hosted relay" em SECURITY.md. O código dele está em relay/.

FAQ

O Telegram vai banir minha conta? Usar sua própria conta em um cliente de terceiros é permitido pelos termos da API do Telegram. O que faz as contas serem limitadas é um comportamento que parece de bot: envio em massa de mensagens, entradas ou convites em massa, spam e contas recém-criadas fazendo muita coisa de uma vez. Use da mesma forma que você usaria o Telegram pessoalmente. A skill instrui os agentes a evitar esses padrões.

Isso é um bot? Não. Ele faz login como você via MTProto, como o Telegram Desktop, e vê exatamente o que você vê. Bots não conseguem ler seus chats; isso consegue.

Um agente pode enviar mensagens por conta própria? Somente depois que você ativar as permissões de escrita. telegram write-access on pede que você confirme no terminal ou em um diálogo do macOS, que um agente não consegue responder. As escritas então exigem um chat exato, e cada uma é registrada. Pelo MCP, escrever é uma ferramenta separada que os clientes podem pedir para você aprovar toda vez. Detalhes estão em SECURITY.md.

Ler marca mensagens como lidas? Não. read, inbox e search deixam os chats não lidos. Somente telegram mark-read os marca.

Preciso das minhas próprias chaves de API? Sim, de my.telegram.org/apps. Elas são gratuitas e levam um minuto para criar. Com um convite de better-tg-cli.com, telegram auth --invite --qr faz login sem elas.

Onde minha sessão é armazenada e quem pode ver minhas mensagens? A sessão fica no Keychain do macOS, no Secret Service do Linux ou no 1Password. A CLI fala diretamente com o Telegram e não tem analytics. Os únicos outros hosts são o npm para uma verificação diária de versão e o serviço de convite no login. Veja PRIVACY.md.

Posso usar várias contas? Sim, com TG_PROFILE: cada perfil tem seu próprio login, configuração e itens no Keychain, por exemplo TG_PROFILE=work telegram auth --qr. Alternar contas corretamente é rastreado em #5.

Funciona no Windows? Sim, experimentalmente: scoop install better-tg-cli ou npm. Os segredos são armazenados com DPAPI do Windows e a CI roda os testes no Windows, mas o uso ao vivo lá é menos testado do que no macOS e no Linux. Por favor, relate problemas nas issues.

Posso usar com Grok Bot, ChatGPT ou outro agente na nuvem? Agentes na nuvem não conseguem iniciar um programa no seu computador, então rode o servidor MCP via HTTP e alcance-o por um túnel. Veja Grok Bot.

Como atualizo? Execute telegram update. Ele usa o mesmo canal pelo qual você instalou: Homebrew, npm ou um binário de release. Se você instalou a skill do agente com telegram skill install, execute novamente para atualizá-la.

Desenvolvimento

DEVELOPMENT.md cobre:

rodar a partir do código-fonte (scripts/tg-dev);
perfis de desenvolvimento isolados (TG_PROFILE) que nunca tocam sua sessão real;
servidores de teste do Telegram;
depuração no editor e testes.

Os releases são cortados por scripts/release.sh (um PR de release; a versão vem dos títulos dos PRs), depois scripts/release.sh tag após o merge. Uma tag compila os binários e publica no GitHub Releases, npm (publicação confiável com proveniência), no tap do Homebrew e no MCP Registry. Veja CONTRIBUTING.md.

Desinstalação

telegram logout exclui a sessão salva. Para encerrá-la também no lado do Telegram, termine-a em Telegram → Configurações → Dispositivos.
telegram skill uninstall remove a skill dos agentes em que foi instalada.
Remova o programa: brew uninstall better-tg-cli, npm uninstall -g better-tg-cli ou scoop uninstall better-tg-cli. Para um binário dos Releases, exclua telegram / telegram.exe.
Exclua a pasta de configuração: ~/.config/tg (%APPDATA%\tg no Windows), além de ~/.config/tg-<profile> para qualquer TG_PROFILE que você usou. No Windows, isso também remove o arquivo de segredos DPAPI. Em outros lugares, o api_hash e o sinalizador de permissão de escrita permanecem no armazenamento de segredos: exclua os itens tg-cli no Keychain Access (ou secret-tool clear service tg-cli), ou o item no seu cofre do 1Password.

Privacidade

Sem analytics. O único serviço que rodamos é o broker de convites opcional, que nunca vê suas mensagens ou sessão. Veja PRIVACY.md para os três hosts com os quais a CLI fala e o que ela armazena localmente.

Política de assinatura de código

Os binários do Windows são compilados a partir deste repositório somente pelo GitHub Actions (.github/workflows/release.yml), nunca em uma máquina pessoal. Solicitamos assinatura de código gratuita da SignPath Foundation; assim que estiver em vigor, os binários de release trarão: Assinatura de código gratuita fornecida por SignPath.io, certificado por SignPath Foundation. Até lá, o telegram.exe do Windows não é assinado; os binários do macOS são assinados ad-hoc.

Committers e revisores: @TheVilfer
Aprovadores (cada release assinado): @TheVilfer
Política de privacidade: PRIVACY.md. A CLI fala somente com o Telegram, com o broker de convites quando você faz login com um convite e com o registro npm para uma verificação diária de atualização no terminal (desativada com TG_NO_UPDATE_CHECK=1).

Licença

MIT, veja LICENSE. Baseado em skillhq/telegram por Derek Rein. Não afiliado ou endossado pelo Telegram; "Telegram" é uma marca registrada do seu proprietário. Use-o em conformidade com os Termos de Serviço da API do Telegram.