Skip to content
mahyartdbPublic

About

Telegram user-account CLI - messages, chats, groups, contacts, privacy, live streaming, MCP server. No bot tokens.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Tele

Tele-Cli

Telegram automation from your terminal. Multi-account. Parallel. Scriptable. No bot tokens.

Release License CI Rust


Install

npm (all platforms; the matching binary installs automatically):

npm install -g @qmahyar/telecli

Binary: 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 --release

Shell 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.1

Quick start

1. 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/.env

tele 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 code

Pass 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 network

Full 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.

What you get

  • 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 --help for 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 --json and --jsonl with a stable envelope. tele listen streams events as JSONL.
  • MCP server: tele mcp exposes 93 tools for Claude, Cursor, and any MCP client.
  • Duplex server: tele serve runs a JSONL request/response protocol over stdin/stdout for embedding.
  • Agent skill: tele skill prints a complete SKILL.md for driving tele from any coding agent.
  • Dry-run everywhere: --dry-run validates and prints the exact intended action without any network call.
  • Raw TL access: tele raw invokes 25 typed Telegram API methods through an allowlist. Every call needs the --allow-raw ack.

Multi-account

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 = 1080

Machine output

Every 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.

For agents

Tele ships its own skill. An agent loads it into context in one command:

tele skill

To make it discoverable across sessions, install it into the detected agent skill directories (Claude Code, OpenCode, Cursor — or any dir with --dir):

tele skill install

The 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.

MCP

{
  "mcpServers": {
    "tele": {
      "command": "tele",
      "args": ["mcp", "--account", "work"]
    }
  }
}

Add --read-only to hide destructive tools, or --groups msg,dialog to filter tool groups.

Security

  • 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-phone opts in; contact list and takeout export print them unless --redact-phones). Never paste raw output into tickets or logs without checking.
  • tele raw has full account power. Treat it like your Telegram client. Every invocation requires the --allow-raw ack (allow_raw:true over serve/MCP), including --dry-run previews.

See docs/security.md for the threat model.

Repository layout

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

Documentation

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

License

MIT. Built by QMahyar. Powered by grammers.

About

Telegram user-account CLI - messages, chats, groups, contacts, privacy, live streaming, MCP server. No bot tokens.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages