{"id":50606468,"url":"https://github.com/pageton/gotg-cli","last_synced_at":"2026-06-05T23:30:42.425Z","repository":{"id":355133783,"uuid":"1226762590","full_name":"pageton/gotg-cli","owner":"pageton","description":"Telegram MTProto debug and invoke CLI — call any TL method, trace API calls, and expose Telegram as an MCP server for LLM-driven interaction","archived":false,"fork":false,"pushed_at":"2026-05-02T02:57:23.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T03:28:05.783Z","etag":null,"topics":["cli","debug","gotd","llm","mcp","mtproto","telegram","tl-schema"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pageton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-01T20:02:34.000Z","updated_at":"2026-05-02T02:57:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pageton/gotg-cli","commit_stats":null,"previous_names":["pageton/gotg-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pageton/gotg-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageton%2Fgotg-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageton%2Fgotg-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageton%2Fgotg-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageton%2Fgotg-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pageton","download_url":"https://codeload.github.com/pageton/gotg-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageton%2Fgotg-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33964367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","debug","gotd","llm","mcp","mtproto","telegram","tl-schema"],"created_at":"2026-06-05T23:30:40.595Z","updated_at":"2026-06-05T23:30:42.406Z","avatar_url":"https://github.com/pageton.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- prettier-ignore --\u003e\n\u003cdiv align=\"center\"\u003e\n\n# tgdev\n\n**Telegram MTProto debug and invoke CLI**\n\nCall any TL method, trace API calls with correlation IDs, and expose Telegram as an MCP server for LLM-driven interaction.\n\n[Install](#install) • [Quick start](#quick-start) • [Commands](#commands) • [MCP Setup](#mcp-setup) • [Session Management](#session-management) • [Configuration](#configuration)\n\n[![Go Reference](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square\u0026logo=go)](https://go.dev)\n[![MCP](https://img.shields.io/badge/MCP-1.5-orange?style=flat-square)](https://modelcontextprotocol.io)\n[![gotd/td](https://img.shields.io/badge/gotd-td-00ADD8?style=flat-square\u0026logo=go)](https://github.com/gotd/td)\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n- **Invoke any TL method** — call the full Telegram API from the terminal with JSON parameters\n- **Persistent listener** — long-running client with IPC server for fast repeated invocations\n- **Lifecycle tracing** — correlation IDs link updates to API calls to responses\n- **MCP server** — expose Telegram as tools for Claude, GPT, or any MCP-compatible LLM\n- **Multiple auth methods** — bot token, phone login, session string, or SQLite database\n- **Auto-completion** — shell completions for bash, zsh, and fish with full method discovery\n\n## Install\n\n```bash\ngo install github.com/pageton/gotg-cli/cmd/tgdev@latest\n```\n\nOr build from source:\n\n```bash\ngo build -o tgdev ./cmd/tgdev/\n```\n\nWith version info:\n\n```bash\ngo build -ldflags \"-X main.version=$(git describe --tags --always) \\\n  -X main.commit=$(git rev-parse --short HEAD) \\\n  -X main.buildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \\\n  -o tgdev ./cmd/tgdev/\n```\n\nRequires Go 1.25+.\n\n## Quick start\n\n```bash\n# Terminal 1 — start a persistent listener\ntgdev listen --db ~/tgdev.db --api-id 12345 --api-hash YOUR_HASH --bot-token YOUR_TOKEN\n\n# Terminal 2 — invoke through the listener (fast, reuses connection)\ntgdev invoke messages.sendMessage '{\"Message\":\"hello\",\"Peer\":{\"_\":\"inputPeerUser\",\"UserID\":123,\"AccessHash\":\"...\"}}'\n```\n\n\u003e [!TIP]\n\u003e When `tgdev listen` is running, all `invoke` calls go through a Unix domain socket — no reconnection overhead. Without a listener, `invoke` creates a standalone connection (slower, requires auth flags).\n\n### Get your API credentials\n\n1. Log in at [my.telegram.org](https://my.telegram.org)\n2. Go to **API Development Tools**\n3. Create an application to get your `api_id` and `api_hash`\n\n### Get current account info\n\n```bash\ntgdev getme --api-id 12345 --api-hash YOUR_HASH --bot-token YOUR_TOKEN\n```\n\nOr through a running listener:\n\n```bash\ntgdev getme\n```\n\n## Commands\n\n| Command | Description |\n| ----------------------------- | --------------------------------------------------------- |\n| `tgdev invoke \u003cmethod\u003e [json]` | Invoke a TL method via listener or standalone connection |\n| `tgdev listen` | Start persistent client with update stream and IPC server |\n| `tgdev trace` | Full lifecycle tracing with correlation IDs |\n| `tgdev methods [prefix]` | List available TL methods |\n| `tgdev getme` | Get current user/bot info (`users.getFullUser`) |\n| `tgdev export-session` | Export session string from SQLite database |\n| `tgdev mcp` | Start MCP server (stdio or HTTP) |\n| `tgdev completion \u003cshell\u003e` | Generate shell completions (bash, zsh, fish) |\n| `tgdev version` | Print version |\n| `tgdev help` | Show usage |\n\n### Invoke\n\n```bash\n# Through a running listener\ntgdev invoke users.getFullUser '{\"ID\":{\"_\":\"inputUserSelf\"}}'\n\n# Standalone (no listener needed)\ntgdev invoke users.getFullUser '{\"ID\":{\"_\":\"inputUserSelf\"}}' --api-id 12345 --api-hash HASH --bot-token TOKEN\n\n# JSON output\ntgdev invoke --format json users.getFullUser '{\"ID\":{\"_\":\"inputUserSelf\"}}'\n```\n\n### Listen\n\nStarts a persistent Telegram client that logs incoming updates and accepts invoke commands over IPC.\n\n```bash\ntgdev listen --db ~/tgdev.db --api-id 12345 --api-hash HASH --bot-token TOKEN\n```\n\n### Trace\n\nLike `listen`, but adds correlation IDs that link updates, handler invocations, API calls, and responses together.\n\n```bash\ntgdev trace --db ~/tgdev.db --api-id 12345 --api-hash HASH --bot-token TOKEN\n```\n\nOutput example:\n\n```\n[1] \u003e\u003e messages.sendMessage\n[1]    {Message:\"hello\", Peer:{...}}\n[1] \u003c\u003c messages.sendMessage [12ms]\n[1]    {ID:42, Date:1709123456}\n[2] UPDATE updateNewMessage\n```\n\n### Methods\n\n```bash\n# List all methods\ntgdev methods\n\n# Filter by prefix\ntgdev methods messages.\n\n# JSON output\ntgdev methods --format json messages.send\n```\n\n## MCP Setup\n\ntgdev exposes Telegram as an MCP server, letting LLMs call any TL method as a tool.\n\n### Quick Setup\n\n**stdio mode** (Claude Code, Cursor, local MCP clients):\n\n```bash\ntgdev mcp --api-id 12345 --api-hash YOUR_HASH --bot-token YOUR_TOKEN\n```\n\n**HTTP mode** (remote/multi-client):\n\n```bash\ntgdev mcp --http :8080 --api-id 12345 --api-hash YOUR_HASH --bot-token YOUR_TOKEN\n```\n\n**With persistent listener** (fastest, reuses connection):\n\n```bash\n# Terminal 1: start listener\ntgdev listen --db ~/tgdev.db --api-id 12345 --api-hash YOUR_HASH --bot-token YOUR_TOKEN\n\n# Terminal 2: start MCP server\ntgdev mcp\n```\n\n\u003e [!TIP]\n\u003e When `tgdev listen` or `tgdev trace` is running, MCP tools route through the listener's IPC socket.\n\u003e Otherwise, the MCP server creates its own standalone connection.\n\n### Full Setup Guide\n\nFor detailed setup instructions, configuration examples, and troubleshooting:\n\n- **[Complete MCP Setup Guide](docs/setup-mcp.md)** — stdio/HTTP modes, auth methods, client configs, security\n\n### MCP Client Configuration\n\n**Claude Code (`.claude/mcp.json`):**\n\n```json\n{\n  \"mcpServers\": {\n    \"tgdev\": {\n      \"command\": \"tgdev\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"TGDEV_API_ID\": \"12345\",\n        \"TGDEV_API_HASH\": \"YOUR_HASH\",\n        \"TGDEV_BOT_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Cursor (`~/.cursor/mcp.json`):**\n\n```json\n{\n  \"mcpServers\": {\n    \"tgdev\": {\n      \"command\": \"tgdev\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n\u003e [!IMPORTANT]\n\u003e Prefer environment variables (`TGDEV_*`) over CLI flags for secrets.\n\u003e CLI args are visible in `ps aux` output.\n\n### Available MCP Tools\n\n| Tool | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `tgdev_list_methods` | List TL methods with prefix filtering and cursor pagination |\n| `tgdev_describe_method` | Show fields, types, and constructor hints for a method |\n| `tgdev_invoke` | Invoke any TL method with JSON params |\n| `tgdev_get_me` | Get current account info |\n| `tgdev_listener_status` | Check if a listener is reachable on the IPC socket |\n| `tgdev_config_info` | Show non-secret MCP configuration |\n\n### JSON Parameter Format\n\nInterface fields (like `InputPeer`, `InputUser`) use a `\"_\"` constructor key:\n\n```json\n{\n  \"Peer\": {\"_\": \"inputPeerUser\", \"UserID\": 123, \"AccessHash\": \"...\"},\n  \"Message\": \"Hello!\"\n}\n```\n\nTo discover constructor names: use `tgdev_describe_method` tool.\n\n\n## Session Management\n\ntgdev supports multiple session formats. Use [telegram-tools](https://github.com/pageton/telegram-tools) (client-side web app) to:\n\n- **Generate** session strings via Telegram auth (phone or bot token) in gotg, GramJS, Kurigram, mtcute, or Telethon formats\n- **Convert** between formats — paste a session string, auto-detect its format, convert to any other\n- **Analyze** session strings — decode and inspect DC, auth key, user ID, isBot flag\n- **Test DC connectivity** — ping all Telegram production and test data centers\n\n\u003e [!NOTE]\n\u003e Session strings grant full account access — treat them like passwords.\n\u003e Prefer environment variables (`TGDEV_SESSION`) or config file over CLI flags to avoid exposing in `ps aux`.\n\n### Quick session setup\n\n1. Visit [telegram-tools](https://pageton.github.io/telegram-tools/) (client-side, no backend)\n2. Authenticate with phone number or bot token\n3. Export session in **gotg** format\n4. Use with tgdev:\n\n   ```bash\n   # Via CLI flag (visible in ps aux)\n   tgdev listen --session \"YOUR_SESSION_STRING\" --api-id 12345 --api-hash HASH\n\n   # Via environment variable (recommended)\n   export TGDEV_SESSION=\"YOUR_SESSION_STRING\"\n   tgdev listen --api-id 12345 --api-hash HASH\n\n   # Via config file (safest)\n   echo '{\"session\": \"YOUR_SESSION_STRING\", \"api_id\": 12345, \"api_hash\": \"HASH\"}' \u003e ~/.tgdev.json\n   chmod 0600 ~/.tgdev.json\n   tgdev listen\n   ```\n\n### Session formats supported by tgdev\n\n| Format | Source | Detection Method |\n|--------|--------|-------------------|\n| gotg native | `session.StringSession()` | JSON, standard base64 |\n| Pyrogram | `session.PyrogramSession()` | URL-safe base64, 271 bytes decoded |\n| Telethon | `session.TelethonSession()` | Prefix `1` + URL-safe base64, 263/275 bytes |\n| GramJS | `session.GramjsSession()` | Prefix `1` + standard base64 |\n| mtcute | `session.MtcuteSession()` | URL-safe base64, prefix byte 0x03 |\n\n`tgdev` auto-detects session format via `detectSessionFormat()` in `cmd/tgdev/main.go`.\n\n### Export session from SQLite\n\nIf you already have a SQLite database from `tgdev listen --db ~/tgdev.db`:\n\n```bash\ntgdev export-session --db ~/tgdev.db\n```\n\nThe output is a gotg-compatible session string. Use `--session-type` to specify format if auto-detection fails.\n\n### Session string safety\n\n- Never commit session strings to version control\n- Use `chmod 0600 ~/.tgdev.json` for config file\n- IPC socket is mode 0600 (owner-only access)\n- `--debug` logs full API payloads to stderr — contains session tokens\n\n\nConfig file: `~/.tgdev.json` (auto-restricted to `0600` permissions).\n\n```json\n{\n  \"api_id\": 12345,\n  \"api_hash\": \"your_api_hash\",\n  \"bot_token\": \"123:ABC\",\n  \"database_path\": \"~/tgdev.db\"\n}\n```\n\n### Auth methods\n\n| Method | Flag | Notes |\n| --------------- | ------------- | --------------------------------- |\n| Bot token | `--bot-token` | Fastest for bots |\n| Phone number | `--phone` | Interactive user login |\n| Session string | `--session` | Telethon/Pyrogram/gotg format |\n| SQLite database | `--db` | Persistent sessions (recommended) |\n\n### Credential priority\n\nCLI flags \u003e environment variables \u003e config file.\n\n### Environment variables\n\n| Variable | Maps to |\n| ----------------- | ------------- |\n| `TGDEV_API_ID` | `--api-id` |\n| `TGDEV_API_HASH` | `--api-hash` |\n| `TGDEV_BOT_TOKEN` | `--bot-token` |\n| `TGDEV_SESSION` | `--session` |\n| `TGDEV_PHONE` | `--phone` |\n\n### Global flags\n\n```\n--api-id INT        Telegram API ID\n--api-hash STRING   Telegram API Hash\n--session STRING    Session string\n--bot-token STRING  Bot token\n--phone STRING      Phone number\n--db PATH           SQLite database path for persistent sessions\n--db-name STRING    Session name within the database (default: \"default\")\n--socket PATH       Unix socket path for IPC (default: $XDG_RUNTIME_DIR/tgdev.sock)\n--config PATH       Config file path (default: ~/.tgdev.json)\n--no-color          Disable colored output\n--debug             Enable verbose debug output (logs full request/response payloads)\n--format FORMAT     Output format: text (default), json\n```\n\n\u003e [!WARNING]\n\u003e `--debug` logs full API request and response payloads to stderr. Do not use in shared terminals\n\u003e or redirect to persistent logs — the output may contain session tokens and other sensitive data.\n\n## Architecture\n\n```\n.\n├── cmd/tgdev/              CLI entrypoint and command implementations\n│   ├── main.go            Command dispatch, flag parsing, client creation\n│   └── version.go         Build version variables (injected via ldflags)\n├── invoke/                 TL method registry, JSON unmarshal, invocation, response formatting\n│   ├── registry.go        Bidirectional lookup: TL schema names ↔ Go types\n│   ├── invoke.go          Generic TL method invocation via raw RPC\n│   ├── invoker.go         DebugInvoker middleware: logging, timing, correlation\n│   ├── unmarshal.go       JSON → gotd struct with interface constructor resolution\n│   ├── format.go          InvokeJSON: JSON-serialized response path\n│   └── pretty.go         Color definitions and duration formatting\n├── internal/\n│   ├── config/            Config loading, validation, credential layering\n│   │   └── config.go     CLI flags \u003e env vars \u003e config file (~/.tgdev.json)\n│   ├── ipc/              Unix domain socket IPC server and client\n│   │   └── ipc.go        InvokeRequest/Response JSON protocol\n│   └── mcpserver/        MCP server with tool definitions\n│       └── server.go      tgdev_list_methods, tgdev_invoke, etc.\n├── trace/                 Correlation ID tracing, update listener, RPC middleware\n│   ├── tracer.go         Tracer: combines invoke logging + update tracking\n│   └── listener.go       UpdateListener for gotg dispatcher\n├── tg-dev-agent/          Skill: Telegram bot testing via tgdev + MCP\n├── go.mod                 Module: github.com/pageton/gotg-cli (Go 1.25.0)\n└── README.md              User-facing documentation\n```\n\nThe `invoke` package provides bidirectional lookup between TL schema names and gotd Go types using reflection over the full `tg.TypesMap()` and `tg.TypesConstructorMap()` registries. The `trace` package adds correlation IDs that link updates to handler invocations to API calls to responses.\n\n## Dependencies\n\n- [gotd/td](https://github.com/gotd/td) — MTProto client library\n- [pageton/gotg](https://github.com/pageton/gotg) — Telegram framework (local replace directive)\n- [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk) — MCP server SDK\n- [fatih/color](https://github.com/fatih/color) — Colored terminal output\n- [modernc.org/sqlite](https://modernc.org/sqlite) — Pure-Go SQLite driver\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpageton%2Fgotg-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpageton%2Fgotg-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpageton%2Fgotg-cli/lists"}