{"id":13611625,"url":"https://github.com/paul-nameless/tg","last_synced_at":"2026-02-19T07:31:39.411Z","repository":{"id":38627562,"uuid":"168571188","full_name":"paul-nameless/tg","owner":"paul-nameless","description":"terminal telegram client","archived":false,"fork":false,"pushed_at":"2025-06-12T17:59:23.000Z","size":1911,"stargazers_count":1060,"open_issues_count":52,"forks_count":81,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-11-27T17:38:36.584Z","etag":null,"topics":["client","telegram","term","terminal","tg","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paul-nameless.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}},"created_at":"2019-01-31T18:01:50.000Z","updated_at":"2025-11-25T19:25:43.000Z","dependencies_parsed_at":"2024-01-12T18:39:13.054Z","dependency_job_id":"cd840d62-54f9-44d7-a1f8-6aa8da4f1e85","html_url":"https://github.com/paul-nameless/tg","commit_stats":{"total_commits":379,"total_committers":20,"mean_commits":18.95,"dds":0.3192612137203166,"last_synced_commit":"2b0c0cf199b11e0bb5d283bd1df997f1241656e5"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/paul-nameless/tg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-nameless%2Ftg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-nameless%2Ftg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-nameless%2Ftg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-nameless%2Ftg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paul-nameless","download_url":"https://codeload.github.com/paul-nameless/tg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-nameless%2Ftg/sbom","scorecard":{"id":722831,"data":{"date":"2025-08-11","repo":{"name":"github.com/paul-nameless/tg","commit":"76f01d2ebd85444229bb872a37c67a40fab86560"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.9,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":1,"reason":"1 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 1/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/docker-build.yml:12","Warn: no topLevel permission defined: .github/workflows/docker-build.yml:1","Warn: no topLevel permission defined: .github/workflows/main.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: UNLICENSE:0","Info: FSF or OSI recognized license: The Unlicense: UNLICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docker-build.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/docker-build.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docker-build.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/docker-build.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docker-build.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/docker-build.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docker-build.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/docker-build.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docker-build.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/docker-build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/paul-nameless/tg/main.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating python:3.13.3-slim-bullseye to python:3.13.3-slim-bullseye@sha256:f0acec66ba3578f142b7efc6a3e5ce62a5f51639ea430df576f9249c7baf6ef2","Warn: pipCommand not pinned by hash: Dockerfile:7","Warn: pipCommand not pinned by hash: .github/workflows/main.yml:26","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/docker-build.yml:9"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 1 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-22T11:53:42.679Z","repository_id":38627562,"created_at":"2025-08-22T11:53:42.679Z","updated_at":"2025-08-22T11:53:42.679Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29606879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["client","telegram","term","terminal","tg","tui"],"created_at":"2024-08-01T19:01:59.176Z","updated_at":"2026-02-19T07:31:39.388Z","avatar_url":"https://github.com/paul-nameless.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# tg\n\n[![Join telegram chat](https://img.shields.io/badge/telegram-join%20chat-black.svg)](https://t.me/tg_term)\n\nTelegram terminal client.\n\n![tg screenshot](tg-screenshot.png)\n\n\n## Features\n\n- [X] view mediafiles: photo, video, voice/video notes, documents\n- [X] ability to send pictures, documents, audio, video\n- [X] reply, edit, forward, delete, send messages\n- [X] stickers\n- [X] notifications\n- [X] record and send voice msgs\n- [X] auto download files\n- [X] toggle chats: pin/unpin, mark as read/unread, mute/unmute\n- [X] message history\n- [X] list contacts\n- [X] show user status\n- [X] secret chats\n- [ ] search\n- [ ] bots (bot keyboard)\n\n\n## Requirements\n\nTo use tg, you'll need to have the following installed:\n\n- [Python \u003e= 3.9](https://www.python.org/downloads/)\n\n\n## Optional dependencies\n\n- [terminal-notifier](https://github.com/julienXX/terminal-notifier) - for Mac (used by default). You can change it to [dunst](https://github.com/dunst-project/dunst) for Linux or any other notifications program (see `NOTIFY_CMD` in configuration)\n- [ffmpeg](https://ffmpeg.org/) - to record voice msgs and upload videos.\n- [tdlib](https://tdlib.github.io/td/build.html?language=Python) - in case of incompatibility with built in package.\n  For example, macOS:\n  ```sh\n  brew install tdlib\n  ```\n  and then set in config `TDLIB_PATH`\n- `urlview` to choose urls when there is multiple in message, use `URL_VIEW` in config file to use another app (it should accept urls in stdin)\n- to open `stickers` and `animated` ones (thumbnail preview) you need to set in mailcap appropriate handler and have app which will open `webp` file:\n  ```ini\n  image/webp; mpv %s\n  ```\n- [ranger](https://github.com/ranger/ranger), [nnn](https://github.com/jarun/nnn) - can be used to choose file when sending, customizable with `FILE_PICKER_CMD`\n- [fzf](https://github.com/junegunn/fzf) - to create groups and secret chats (used for single and multiple user selection)\n\n## Installation\n\n### From PyPI\n\nThis option is recommended for production:\n\n```sh\npip3 install tg\ntg\n```\n\n\n### From sources\n\nThis option is recommended for development:\n\n```sh\ngit clone https://github.com/paul-nameless/tg.git\ncd tg\npip install python-telegram\npip install .\ntg\n```\n\n### Using Docker\n\n\u003e Note that voice recordings and notifications won't work when using Docker.\n\n```sh\ndocker run -it --rm ghcr.io/paul-nameless/tg\n```\n\n### From the AUR\n\nIf you're using Arch Linux, you can install tg through [its AUR package](https://aur.archlinux.org/packages/telegram-tg/):\n\nIf you're using the `yay` AUR helper, you can install the package with:\n```bash\nyay -S telegram-tg\n```\n\nIf you want to use the latest developement version via the AUR you can find it [here](https://aur.archlinux.org/packages/telegram-tg-git/)\n\n## Configuration\n\nConfig file should be stored at `~/.config/tg/conf.py`. This is simple python file.\n\n### Simple config:\n\n```python\n# should start with + (plus) and contain country code\nPHONE = \"[phone number in international format]\"\n```\n\n### Advanced configuration:\n\nAll configurable variables can be found [here](https://github.com/paul-nameless/tg/blob/master/tg/config.py)\n\n```python\nimport os\n\n# You can write anything you want here, file will be executed at start time\n# You can keep you sensitive information in password managers or gpg\n# encrypted files for example\ndef get_pass(key):\n    # retrieves key from password store\n    return os.popen(\"pass show {} | head -n 1\".format(key)).read().strip()\n\n\nPHONE = get_pass(\"i/telegram-phone\")\n# encrypt you local tdlib database with the key\nENC_KEY = get_pass(\"i/telegram-enc-key\")\n\n# log level for debugging, info by default\nLOG_LEVEL = \"DEBUG\"\n# path where logs will be stored (all.log and error.log)\nLOG_PATH = os.path.expanduser(\"~/.local/share/tg/\")\n\n# If you have problems with tdlib shipped with the client, you can install and\n# use your own, for example:\nTDLIB_PATH = \"/usr/local/Cellar/tdlib/1.6.0/lib/libtdjson.dylib\"\n\n# you can use any other notification cmd, it is simple python string which\n# can format title, msg, subtitle and icon_path paramters\n# In these exapmle, kitty terminal is used and when notification is pressed\n# it will focus on the tab of running tg\nNOTIFY_CMD = \"/usr/local/bin/terminal-notifier -title {title} -subtitle {subtitle} -message {msg} -appIcon {icon_path} -sound default -execute '/Applications/kitty.app/Contents/MacOS/kitty @ --to unix:/tmp/kitty focus-tab --no-response -m title:tg'\"\n\n# You can use your own voice recording cmd but it's better to use default one.\n# The voice note must be encoded with the Opus codec, and stored inside an OGG\n# container. Voice notes can have only a single audio channel.\nVOICE_RECORD_CMD = \"ffmpeg -f avfoundation -i ':0' -c:a libopus -b:a 32k {file_path}\"\n\n# You can customize chat and msg flags however you want.\n# By default words will be used for readability, but you can make\n# it as simple as one letter flags like in mutt or add emojies\nCHAT_FLAGS = {\n    \"online\": \"●\",\n    \"pinned\": \"P\",\n    \"muted\": \"M\",\n    # chat is marked as unread\n    \"unread\": \"U\",\n    # last msg haven't been seen by recipient\n    \"unseen\": \"✓\",\n    \"secret\": \"🔒\",\n    \"seen\": \"✓✓\",  # leave empty if you don't want to see it\n}\nMSG_FLAGS = {\n    \"selected\": \"*\",\n    \"forwarded\": \"F\",\n    \"new\": \"N\",\n    \"unseen\": \"U\",\n    \"edited\": \"E\",\n    \"pending\": \"...\",\n    \"failed\": \"💩\",\n    \"seen\": \"✓✓\",  # leave empty if you don't want to see it\n}\n\n# use this app to open url when there are multiple\nURL_VIEW = 'urlview'\n\n# Specifies range of colors to use for drawing users with\n# different colors\n# this one uses base 16 colors which should look good by default\nUSERS_COLORS = tuple(range(2, 16))\n\n# to use 256 colors, set range appropriately\n# though 233 looks better, because last colors are black and gray\n# USERS_COLORS = tuple(range(233))\n\n# to make one color for all users\n# USERS_COLORS = (4,)\n\n# cleanup cache\n# Values: N days, None (never)\nKEEP_MEDIA = 7\n\nFILE_PICKER_CMD = \"ranger --choosefile={file_path}\"\n# FILE_PICKER_CMD = \"nnn -p {file_path}\"\n\nMAILCAP_FILE = os.path.expanduser(\"~/.config/mailcap\")\n\nDOWNLOAD_DIR = os.path.expanduser(\"~/Downloads/\")  # copy file to this dir\n```\n\n### Mailcap file\n\nMailcap file is used for deciding how to open telegram files (docs, pics, voice notes, etc.). Path to the file can be overriden with `MAILCAP_FILE` in config file.\n\nExample: `~/.mailcap`\n\n```ini\n# media\nvideo/*; mpv \"%s\"\naudio/ogg; mpv --speed=1.33 \"%s\"\naudio/mpeg; mpv --no-video \"%s\"\nimage/*; qview \"%s\"\n\n# text\ntext/html; w3m \"%s\"\ntext/html; open -a Firefox \"%s\"\ntext/plain; less \"%s\"\n\n# fallback to vim\ntext/*; vim \"%s\"\n```\n\n\n## Keybindings\n\nvi like keybindings are used in the project. Can be used commands like `4j` - 4 lines down.\n\nFor navigation arrow keys also can be used.\n\n### Chats:\n\n- `j,k`: move up/down\n- `J,K`: move 10 chats up/down\n- `g`: go to top chat\n- `l`: open msgs of the chat\n- `m`: mute/unmute current chat\n- `p`: pin/unpin current chat\n- `u`: mark read/unread\n- `r`: read current chat\n- `c`: show list of contacts\n- `dd`: delete chat or remove history\n- `ng`: create new group chat\n- `ns`: create new secret chat\n- `/`: search in chats\n- `?`: show help\n\n## Msgs:\n\n- `j,k`: move up/down\n- `J,K`: move 10 msgs up/down\n- `G`: move to the last msg (at the bottom)\n- `D`: download file\n- `l`: if video, pics or audio then open app specified in mailcap file, for example:\n  ```ini\n  # Images\n  image/png; qView \"%s\"\n  audio/*; mpv \"%s\"\n  ```\n  if text, open in `less` (to view multiline msgs)\n- `e`: edit current msg\n- `\u003cspace\u003e`: select msg and jump one msg down (use for deletion or forwarding)\n- `\u003cctrl+space\u003e`: same as space but jumps one msg up\n- `y`: yank (copy) selected msgs with \u003cspace\u003e to internal buffer (for forwarding) and copy current msg text or path to file to clipboard\n- `p`: forward (paste) yanked (copied) msgs to current chat\n- `dd`: delete msg for everybody (multiple messages will be deleted if selected)\n- `i or a`: insert mode, type new message\n- `I or A`: open vim to write long msg and send\n- `v`: record and send voice message\n- `r,R`: reply to a current msg\n- `S`: calls a file picker\n- `sv`: send video\n- `sa`: send audio\n- `sp`: send picture\n- `sd`: send document\n- `o`: open url present in message (if multiple urls, `urlview` will be opened)\n- `]`: next chat\n- `[`: prev chat\n- `u`: show user info (username, bio, phone, etc.)\n- `c`: show chat info (e.g. secret chat encryption key, chat id, state, etc.)\n- `?`: show help\n- `!`: open msg with custom cmd\n\n## Publish\n\nRun task to automatically increase version and release (https://taskfile.dev):\n\n```sh\ntask release\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-nameless%2Ftg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaul-nameless%2Ftg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-nameless%2Ftg/lists"}