Tg Cli

@miolamio/tg-cli

      .------.
     /  o  o  \
    |   \__/   |
    |          |
    |  /\  /\  |
     \/  \/  \/

  tg / Telegram, from your terminal.

Agent-first Telegram CLI client built on MTProto via gramjs. Designed for Claude Code agents and power users who need structured, scriptable access to Telegram.

Install

npm install -g @miolamio/tg-cli
# or run directly
npx @miolamio/tg-cli

Requires Node.js >= 20.

Setup

The fastest way to get started — use a built-in client preset (no API credentials needed):

tg auth login --client desktop

Or bring your own credentials from [my.telegram.org](https://my.telegram.org):

export TG_API_ID=your_api_id
export TG_API_HASH=your_api_hash
tg auth login

Available presets: `desktop`, `android`, `ios`, `macos`, `web-z`, `web-k`.

The little daemon greets you during interactive login and appears in compact form in `tg --help`. Use `--quiet` to hide it or `NO_COLOR=1` for plain text.

Troubleshooting login

Run `tg --verbose auth login --client desktop` in a terminal to see connection stages. Starting with 0.4.0, transport failures include a safe category on stderr, such as `CONNECTION_CLOSED`, `ECONNRESET`, `INVALID_CHECKSUM`, or `INVALID_BUFFER (code=429)`. These diagnostics do not print error objects, session strings, or raw protocol payloads; `--quiet` suppresses them.

If TCP connects but the first authorization-key exchange fails, an open port alone does not establish that MTProto traffic can pass. Check access from the same machine and network. The SDK's `WebSocket connection failed` message can also describe a TCP failure. After unsuccessful connection retries, the CLI returns `CONNECTION_FAILED` instead of continuing into authorization on a disconnected client. This improves diagnosis; it does not bypass network restrictions. Login still requires an interactive terminal.

Since 0.5.0, if raw TCP is blocked but HTTPS/WebSocket works, select WSS: