{"id":51678732,"url":"https://github.com/will-17173/telegram-cli","last_synced_at":"2026-07-16T11:01:26.185Z","repository":{"id":370706579,"uuid":"1296343682","full_name":"will-17173/telegram-cli","owner":"will-17173","description":"Multi-account Telegram CLI for syncing chats, searching messages locally, listening in real time, and managing messages from your terminal.","archived":false,"fork":false,"pushed_at":"2026-07-15T06:04:33.000Z","size":1350,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-15T10:36:09.838Z","etag":null,"topics":["agent-skills","cli","message-sync","mtcute","mtproto","sqlite","telegram","telegram-cli","typescript"],"latest_commit_sha":null,"homepage":"https://will-17173.github.io/telegram-cli/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/will-17173.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-07-10T09:47:25.000Z","updated_at":"2026-07-15T06:04:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/will-17173/telegram-cli","commit_stats":null,"previous_names":["will-17173/telegram-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/will-17173/telegram-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-17173%2Ftelegram-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-17173%2Ftelegram-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-17173%2Ftelegram-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-17173%2Ftelegram-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/will-17173","download_url":"https://codeload.github.com/will-17173/telegram-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-17173%2Ftelegram-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35541271,"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-07-16T02:00:06.687Z","response_time":83,"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":["agent-skills","cli","message-sync","mtcute","mtproto","sqlite","telegram","telegram-cli","typescript"],"created_at":"2026-07-15T10:30:34.809Z","updated_at":"2026-07-16T11:01:26.178Z","avatar_url":"https://github.com/will-17173.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram CLI\n\n[Project website](https://will-17173.github.io/telegram-cli/) · [Telegram CLI documentation](https://will-17173.github.io/telegram-cli/docs/) · [Telegram group](https://t.me/tg_cli_chat) · [简体中文 README](README.zh-CN.md)\n\nTelegram CLI is a TypeScript command-line interface (CLI) for live Telegram data, local SQLite search, and remote management. It aims to be the most capable Telegram CLI for people and artificial intelligence (AI) agents that need dependable Telegram access from one `tg` command. Account sessions and synced messages stay on your machine.\n\n## Why Telegram CLI stands out\n\nTelegram CLI combines online reads, local persistence, file archives, live listeners, remote writes, group administration, account isolation, a local web UI, and structured output in one tool.\n\nIt is designed for AI agents:\n\n- **Stable command contracts**: finite commands support JSON, YAML, Markdown, exit statuses, and stable error codes\n- **Local-first data access**: synced messages stay in SQLite so agents can search and analyze Telegram history without repeated network reads\n- **Explicit account control**: `--account` selects the intended session for one command\n- **Write safety**: a write-access gate separates read-only automation from commands that modify Telegram\n- **Agent skill support**: the `using-telegram-cli` skill teaches supported agents how to authenticate, sync, query, and avoid unsafe writes\n\n## Read the documentation\n\nRead the [complete Telegram CLI documentation](https://will-17173.github.io/telegram-cli/docs/) for installation, workflows, every command, automation, safety, and troubleshooting.\n\n## Choose a Telegram workflow\n\nChoose a workflow by the data freshness you need, where the result should go, and whether the command changes Telegram.\n\n### Read current Telegram data\n\nUse online commands when you need the latest server state. These commands do not add returned messages to SQLite.\n\n```sh\ntg inbox\ntg read @team --since 2h\ntg search-online \"incident\" --chat @team --json\n```\n\nYou can also inspect contacts, notification settings, folders, and group details without importing messages.\n\n### Build a searchable local history\n\nSync one chat or many chats into the selected account’s SQLite database. Search and analyze the stored copy without reconnecting to Telegram.\n\n```sh\ntg sync @team\ntg search \"release\" --chat @team\ntg recent --chat @team --hours 24\n```\n\nLocal commands can also filter, summarize, and export stored messages.\n\n### Browse local data in a web UI\n\nRun a local-only management UI for stored messages:\n\n```sh\ntg web\n```\n\nThe server binds to `127.0.0.1`, has no login screen, and is intended for local use only. It can browse local SQLite data and trigger read-only sync for the selected chat.\n\n### Follow live messages and download files\n\nThe `listen` command streams new messages from one chat or many chats. It persists normalized `attachments[]`, can download incoming primary media, and can run interactive reply or group actions. `--no-media` only hides rendered media rows; persistence and `--auto-download` still use the normalized attachment data.\n\n```sh\ntg listen @team --auto-download\n```\n\n### Download historical media\n\nUse `download` for existing messages: a single message, a specific attachment, a grouped album, an inclusive message range, one local date, or a whole chat from newest to oldest. Without `--attachment`, a single message downloads every downloadable item. `--attachment N` is one-based and message-local; for `--grouped-id`, numbering is flattened by message ID and then message-local attachment index. Each transfer refetches the fresh Telegram message and matches the stored descriptor before downloading, so stable errors include `attachment_not_found`, `attachment_not_downloadable`, `attachment_changed`, and `media_access_denied`.\n\n```sh\ntg download --chat @team --msg-id 814 --output ./media\ntg download @channel 42 --attachment 2\ntg download --chat @team --date 2026-07-15 --concurrency 2\ntg download --chat @channel --grouped-id 2637798265 --output ./album-media\ntg download --chat @channel --all --output ./channel-media\n```\n\n### Keep a Markdown archive\n\nThe `archive` command writes incremental Markdown and optional media files. It tracks archive progress separately and does not populate SQLite. Default account archives are reset by `tg data reset`; custom `--output` directories are never deleted automatically, so remove old custom archives manually or choose an empty directory after breaking upgrades.\n\n```sh\ntg archive @team --download-media\n```\n\nLater runs append new messages and retry referenced media that is still missing.\n\n### Reset local data after breaking storage upgrades\n\nThis release uses a fresh message schema and structured output schema version 2. Old SQLite databases are intentionally not migrated. Reset local data, then re-sync or rebuild archives:\n\n```sh\ntg data reset --yes\ntg data reset --all-accounts --yes\ntg sync-all\n```\n\nStructured message rows expose `content`, `reply_to_msg_id`, `media_group_id`, and ordered lowercase `attachments[]`.\n\n### Send messages and manage groups\n\nSend text, files, or captioned media groups from the terminal. Inspect and manage group members, administrators, invites, forum topics, and messages.\n\n```sh\ntg send @team \"Release is ready\" --file ./report.pdf\ntg group members @team --type admins\ntg group member mute @team @alice 2h --yes\n```\n\nTelegram CLI also manages contacts, notification settings, and chat folders. The write-access gate covers commands that change Telegram.\n\n### Automate across isolated accounts\n\nEach registered account has a separate session and SQLite database. Select an account for one command without changing the default.\n\n```sh\ntg stats --account work --json\n```\n\nFinite commands support JSON, YAML, and Markdown output. Failures return nonzero exit statuses and stable error codes.\n\n## Install\n\nInstall Node.js 22.12.0 or later, then install Telegram CLI from npm:\n\n```sh\nnpm install -g @will-17173/telegram-cli\n```\n\n## Get started\n\nAuthenticate one account, list its chats, sync one chat, and search the local copy:\n\n```sh\ntg account add\ntg status\ntg chats\ntg sync @team\ntg search \"release\" --chat @team\n```\n\nReplace `@team` with a chat name, username, or numeric identifier (ID). Run `tg --help` or a command such as `tg sync --help` to inspect available options.\n\n## Know where data goes\n\nCheck a command’s execution scope before you run it:\n\n| Scope | Commands | Effect |\n| --- | --- | --- |\n| Online read | `inbox`, `read`, `search-online` | Queries Telegram without storing returned messages. |\n| Local persistence | `history`, `sync`, `sync-all`, `refresh` | Stores fetched messages in the selected account’s SQLite database. |\n| Local read | `search`, `recent`, `stats`, `export`, `web` | Reads local SQLite data without connecting to Telegram. |\n| File archive | `archive` | Reads Telegram and writes Markdown or media files without writing to SQLite. |\n| Remote write | `send`, `edit`, `delete`, notification, folder, and group actions | Changes Telegram messages or settings. |\n\nEach account has a separate session and SQLite database. Add `--account work` to select an account for one command without changing the default.\n\nUse `sync \u003cchat\u003e` to update a chat from the newest locally stored message. Use `history \u003cchat\u003e` to continue backfilling older messages from the oldest locally stored message; if the chat has no local rows yet, `history` starts from the newest Telegram messages.\n\n## Protect remote data\n\nDisable remote writes before read-only workflows or automation:\n\n```sh\ntg config write-access off\ntg config write-access status\n```\n\nRun `tg config write-access on` when you intend to modify Telegram again. Enabling the gate does not authorize a specific write.\n\nKeep Telegram application programming interface (API) credentials, proxy credentials, session files, SQLite databases, exports, and archives private.\n\n## Use with coding agents\n\nUse JSON or YAML when a script or coding agent needs structured output:\n\n```sh\ntg search \"release\" --account work --json\n```\n\nFailures return a nonzero exit status and a stable error code. The explicit `--account` option keeps automation on the intended account.\n\nInstall the [`using-telegram-cli` agent skill](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) in a supported coding agent:\n\n```sh\nnpx skills add https://github.com/will-17173/telegram-cli \\\n  --skill using-telegram-cli\n```\n\nThe skill covers authentication, synchronization, queries, and write safety.\n\n## Develop\n\nUse pnpm with Node.js 22.12.0 or later:\n\n```sh\npnpm install\npnpm dev --help\npnpm test\npnpm typecheck\npnpm build\n```\n\n## License\n\nLicensed under [GPL-3.0-only](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill-17173%2Ftelegram-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwill-17173%2Ftelegram-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill-17173%2Ftelegram-cli/lists"}