Telegram automation from your terminal. Multi-account. Parallel. Scriptable. No bot tokens.
npm (all platforms; the matching binary installs automatically):
npm install -g @qmahyar/telecliBinary: download from Releases — 13 targets including a static linux-arm64-musl build for Termux/Android.
From source (Rust 1.89+):
git clone https://github.com/mahyartdb/tele-cli.git
cd tele-cli
cargo build --releaseShell completions:
tele completions bash >> ~/.bashrc
tele completions zsh >> ~/.zshrc
tele completions fish > ~/.config/fish/completions/tele.fish
# PowerShell: tele completions powershell | Out-String | Invoke-Expression
# Man page: tele completions man > /usr/local/share/man/man1/tele.11. Get API credentials. Create an app at my.telegram.org and save your api_id and api_hash to the config directory (~/.config/tele on Linux/macOS, %APPDATA%\tele on Windows):
mkdir -p ~/.config/tele
echo 'TELE_API_ID=1234567' > ~/.config/tele/.env
echo 'TELE_API_HASH=YOUR_API_HASH_HERE' >> ~/.config/tele/.env
chmod 600 ~/.config/tele/.envtele tightens .env to owner-only on every credentials load, but set 0600 yourself too, and never commit the file. Use your real values from my.telegram.org; the placeholders above are not valid.
2. Add and log in an account. account login prompts for the login code, or use --method qr:
tele account add --name work
TELE_PHONE=+15551234567 tele account login --name work --method codePass the phone number through TELE_PHONE (login prompts for the code, not the number — there is no phone prompt): --phone works but lands in shell history and process listings, so scripts must prefer the environment variable.
3. Use it.
tele msg send --chat me --text "hello from tele" # send yourself a message
tele dialog list # recent chats
tele msg send --chat me --text "test" --dry-run # preview, no networkFull walkthrough in docs/getting-started.md. Usage recipes in docs/examples.md.
Tele drives real Telegram user accounts from the command line. Built on grammers (MTProto). No bot tokens.
- 20 command groups: accounts, messages, chats, dialogs, forum topics, contacts, profile, privacy, stories, stickers, takeout, cache, listen, serve, mcp, raw, doctor, wizard, skill, completions. Run
tele --helpfor every command and flag. - Multi-account: named sessions, tags, parallel fan-out (
--parallel 1-32) with per-account rate limiting and FloodWait handling. - Machine output: every command supports
--jsonand--jsonlwith a stable envelope.tele listenstreams events as JSONL. - MCP server:
tele mcpexposes 93 tools for Claude, Cursor, and any MCP client. - Duplex server:
tele serveruns a JSONL request/response protocol over stdin/stdout for embedding. - Agent skill:
tele skillprints a complete SKILL.md for driving tele from any coding agent. - Dry-run everywhere:
--dry-runvalidates and prints the exact intended action without any network call. - Raw TL access:
tele rawinvokes 25 typed Telegram API methods through an allowlist. Every call needs the--allow-rawack.
Accounts live in config.toml with tags. Target one account, a tag group, or all of them, and fan out in parallel:
tele msg send --account work --chat me --text "from work"
tele msg send --tag bulk --chat @channel --text "broadcast" --parallel 8# ~/.config/tele/config.toml
[accounts.work]
tags = ["bulk"]
[accounts.work.proxy]
type = "socks5"
host = "127.0.0.1"
port = 1080Every command emits one JSON envelope with per-account results:
{
"ok": true,
"command": "msg send",
"results": [
{ "account": "work", "ok": true, "data": { "id": 42 }, "error": null }
]
}Exit codes: 0 success, 1 usage error, 2 partial failure, 3 all failed, 4 auth required, 130 interrupted.
Most commands accept --chat as @username, a t.me/ link, a numeric ID, me, or +phone.
The full JSON shapes, MCP tool table, and protocol rules are the public contract in docs/cli-contract.md. Contract changes are additive; anything else is a bug.
Tele ships its own skill. An agent loads it into context in one command:
tele skillTo make it discoverable across sessions, install it into the detected agent skill directories (Claude Code, OpenCode, Cursor — or any dir with --dir):
tele skill installThe skill follows the Agent Skills spec: it carries the non-negotiable usage rules (parse --json only, exit-code meanings, dry-run before destructive commands), the command map, the output envelope, and recipes. For deeper integration, tele mcp exposes the same operations as MCP tools. The project conventions for agents working on tele are in AGENTS.md.
{
"mcpServers": {
"tele": {
"command": "tele",
"args": ["mcp", "--account", "work"]
}
}
}Add --read-only to hide destructive tools, or --groups msg,dialog to filter tool groups.
- Sessions live under the OS app data directory, are permission-restricted, and hold an OS-level exclusive lock per account.
- API keys and 2FA passwords never reach logs or JSON output. Phone numbers are redacted by default where they appear (
profile get --show-phoneopts in;contact listandtakeout exportprint them unless--redact-phones). Never paste raw output into tickets or logs without checking. tele rawhas full account power. Treat it like your Telegram client. Every invocation requires the--allow-rawack (allow_raw:trueover serve/MCP), including--dry-runpreviews.
See docs/security.md for the threat model.
src/ Rust source: kernel (config, session, client, executor, output) + commands/
tests/ contract.rs (CLI surface), selection.rs (account selection)
tl/api.tl Vendored Telegram TL schema, checked for drift against grammers
npm/ npm package: JS launcher + package.json (binaries are bundled at publish time)
docs/ Documentation, ADRs, and specs
.github/ CI, release, and issue/PR templates
| Document | Purpose |
|---|---|
| Getting started | Setup walkthrough and troubleshooting |
| Examples | Recipes for common tasks |
| CLI contract | Machine API reference: JSON shapes, exit codes, MCP tools |
| Architecture | Codebase structure and data flow |
| Security | Threat model and trust boundaries |
| Capabilities | Feature matrix with Telegram API mapping |
| Contributing | Adding commands, conventions, testing |
| Observability | Logging and output streams |
| Release | Build targets and publishing |
| Decisions | Architecture decision records |
| All docs | Full documentation index |
| Changelog | What's new in each release |