Agent skill

Tg CLI

CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal

Apache-2.0Auto-check passedProductivity & Automation

Install Tg CLI

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .claude/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .agents/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .cursor/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .gemini/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .github/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add jackwener/tg-cli --skill tg-cli -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install jackwener/tg-cli tg-cli --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "tg-cli" agent skill from https://github.com/jackwener/tg-cli/tree/main into .opencode/skills/tg-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tg-cli", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: tg-cli
GitHub stars: 293
Token cost: ~1.2k tokens
SKILL.md length: 225 words
Files: 40
Skills in repo: 1
Repo updated: Mar 15, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal

Productivity & Automation work in your project
SKILL.md covers Prerequisites, Authentication, Command Reference and Structured Output, plus 6 more sections
Calls uv

What it does

Tg CLI is an agent skill from jackwener/tg-cli. CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 44 other files (for example `.github/ISSUE_TEMPLATE/bug_report.yml`, `.github/ISSUE_TEMPLATE/feature_request.yml` and `.github/workflows/ci.yml`).

It sits in Productivity & Automation. It works with Telegram. The repository describes itself as: A CLI for Telegram — local-first sync, search, export via MTProto. The licence is Apache-2.0.

When your agent uses it

Productivity & Automation work in your project

Example prompts

“/tg-cli”

Requirements

Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit b54a14d. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- uv
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use uv, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tg CLI loads about 1.2k tokens when it runs. Until then it costs about 29 tokens; SKILL.md has 225 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~29
When it runs · the whole SKILL.md, loaded when a task matches: ~1.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jackwener/tg-cli at commit b54a14d, republished under its Apache-2.0 licence (© jackwener). 225 words, ~1,243 tokens.

Download SKILL.mdSave it as .claude/skills/tg-cli/SKILL.md (or your agent's skills folder). This skill also uses 39 other files; get the full folder from GitHub.

name: tg-cli
description: CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal
author: jackwener
version: 0.5.4
tags: telegram, tg, chat, monitor, cli

tg-cli Skill

CLI tool for Telegram — sync chats, search messages, filter keywords, send messages, and monitor groups.

Prerequisites

bash

# Install (requires Python 3.10+)
uv tool install kabi-tg-cli
# Or: pipx install kabi-tg-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade kabi-tg-cli
# Or: pipx upgrade kabi-tg-cli

Authentication

Uses your Telegram account (MTProto). Built-in Telegram Desktop API credentials are used by default — no application needed.

bash

tg chats              # First run: enter phone + verification code
tg whoami             # Check current user

# Optional: use your own app credentials
export TG_API_ID=123456
export TG_API_HASH=your_telegram_app_hash

Command Reference

Telegram Operations

bash

tg chats                          # List joined chats
tg chats --type group             # Filter by type
tg status                         # Check auth/session status
tg status --yaml                  # Structured auth status
tg whoami                         # Show current user info
tg whoami --yaml                  # Preferred structured output for agents
tg history CHAT -n 1000           # Fetch historical messages
tg sync CHAT                      # Incremental sync (only new)
tg sync-all                       # Low-level sync for all current dialogs
tg refresh                        # Recommended daily refresh entrypoint
tg listen                         # Real-time listener
tg listen --persist               # Reconnect automatically for a near-live cache
tg info CHAT                      # Chat details
tg send CHAT "Hello!"             # Send a message

Search & Query

bash

tg search "Rust"                     # Search stored messages
tg search "Rust" -c "牛油果" --yaml  # Filter by chat + preferred YAML output
tg search "Rust|Golang" --regex      # Regex search
tg search "Rust" --sync-first --yaml # Refresh before querying
tg recent --hours 24 -n 20 --yaml    # Browse latest messages
tg recent --hours 24 --sync-first    # Refresh before browsing recent
tg filter "Rust,Golang,Java"         # Multi-keyword filter (today)
tg filter "招聘,remote" --hours 48   # Filter last N hours
tg today --sync-first                # Refresh before reading today's messages
tg stats --sync-first                # Refresh before aggregate stats
tg top -c "牛油果" --hours 24 --sync-first
tg timeline --by hour --sync-first   # Activity bar chart

Data Management

bash

tg export CHAT -f json -o out.json   # Export messages
tg export CHAT --hours 24            # Export last 24 hours
tg purge CHAT -y                     # Delete stored messages

Structured Output

Major commands support --json and --yaml for machine-readable output. AI agents should prefer --yaml unless a strict JSON parser is required:

bash

tg search "Rust" --yaml
tg status --yaml
tg whoami --yaml
tg today --yaml
tg filter "招聘" --hours 48 --yaml

When stdout is not a TTY, tg-cli defaults to YAML automatically. Use OUTPUT=yaml|json|rich|auto to override the default output mode. All machine-readable output uses the envelope documented in SCHEMA.md.

Refresh Model

tg-cli is local-first. Query commands read from the local SQLite cache by default.

Use tg refresh as the normal entrypoint before analysis.
Use --sync-first when a single query should refresh before reading.
Use tg listen --persist if you want a near-real-time local cache.
Keep tg sync-all for lower-level scripts or schedulers.

Common Patterns for AI Agents

bash

# Quick daily workflow
tg refresh --yaml                    # Refresh everything
tg today --sync-first --yaml         # See today's messages
tg filter "Rust,Golang" --hours 24 --sync-first --yaml

# Search and export for analysis
tg search "招聘" -n 100 --yaml > jobs.yaml
tg filter "远程,remote,Web3" --hours 72 --yaml > filtered.yaml

# Send messages
tg send "GroupName" "Hello from CLI!"

Debugging

bash

tg -v sync-all       # Debug logging for troubleshooting
tg -v refresh        # See refresh behavior across dialogs
tg -v stats          # See SQL queries and timing

Error Handling

Commands exit with code 0 on success, non-zero on failure
Error messages are prefixed with ✗ or shown in red
Chat names are fuzzy-matched (partial name works)
refresh and sync-all gracefully skip chats that can't be found

Scheduling

Examples live in the repository:

examples/tg-refresh.cron
examples/systemd/tg-refresh.service
examples/systemd/tg-refresh.timer

Safety Notes

Do not ask users to share phone numbers or verification codes in chat logs.
Session data is stored locally and never uploaded.

Files

SKILL.md and 39 other files in the repository root of jackwener/tg-cli.

SKILL.md
.env.example
.github/ISSUE_TEMPLATE/bug_report.yml
.github/ISSUE_TEMPLATE/feature_request.yml
.github/workflows/ci.yml
.github/workflows/publish.yml
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md
SCHEMA.md
examples/systemd/tg-refresh.service
examples/systemd/tg-refresh.timer
examples/tg-refresh.cron
pyproject.toml
… and 24 more

Open the folder on GitHubat commit b54a14d

Compare with similar skills

Tg CLI next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tg CLI compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Tg CLI this skilljackwener/tg-cli	293	—	~1.2k	Automated safety check: Pass	Apache-2.0	6 mo ago
Process Inboxtelegramdesktop/tdesktop	33k	2 repos	~4.5k	Automated safety check: Pass	GPL-3.0	today
Perform Tasktelegramdesktop/tdesktop	33k	2 repos	~3k	Automated safety check: Pass	GPL-3.0	today
Continuetelegramdesktop/tdesktop	33k	2 repos	~9.4k	Automated safety check: Pass	GPL-3.0	today
Send User MessageTinyAGI/tinyagi	3.6k	—	~829	Automated safety check: Pass	MIT	6 mo ago
Pytdbotpytdbot/client	137	—	~4.3k	Automated safety check: Pass	MIT	9 days ago

Similar skills

Process Inbox
telegramdesktop/tdesktop
Process the local ignored ai-tdesktop inbox into durable, independently testable Telegram Desktop task records while task execution worktrees remain active.
33k GitHub starsUsed in 2 repos~4.5k tokens
Productivity & AutomationAuto-check passed
Perform Task
telegramdesktop/tdesktop
Resolve, start or resume, implement, review, test, and publish exactly one existing ai-tdesktop task by short slug or full dated id, including rare blocked retries and split-required results.
33k GitHub starsUsed in 2 repos~3k tokens
Productivity & AutomationAuto-check passed
Continue
telegramdesktop/tdesktop
Continue autonomous Telegram Desktop development from the shared ai-tdesktop repository.
33k GitHub starsUsed in 2 repos~9.4k tokens
Productivity & AutomationAuto-check passed
Send User Message
TinyAGI/tinyagi
Send a proactive message to a paired user via their channel (Discord, Telegram, or WhatsApp).
3.6k GitHub stars~829 tokensUpdated 6 mo ago
Productivity & AutomationAuto-check passed
Pytdbot
pytdbot/client
Write Telegram bots and userbots with Pytdbot (async TDLib wrapper with high-level helpers; not the Telegram Bot API).
137 GitHub stars~4.3k tokensUpdated 9 days ago
Productivity & AutomationAuto-check passed
Setup
terranc/claude-telegram-bot-bridge
Install and configure the Telegram Skill Bot. An agent skill from terranc/claude-telegram-bot-bridge.
134 GitHub stars~1.5k tokensUpdated 4 mo ago
Productivity & AutomationAuto-check: notes

Works with

Questions about Tg CLI

What does Tg CLI do?

CLI skill for Telegram to sync chats, search messages, filter keywords, and monitor groups from the terminal. Tg CLI is an agent skill from jackwener/tg-cli.

When should I use Tg CLI?

Tg CLI fits situations like: productivity & Automation work in your project.

How do I install Tg CLI in Claude Code?

Run `npx skills add jackwener/tg-cli --skill tg-cli -a claude-code`. Or copy the skill folder (the jackwener/tg-cli repository) into .claude/skills/tg-cli in your project. Claude Code loads it when a task matches its description.

How do I install Tg CLI in Codex?

Run `npx skills add jackwener/tg-cli --skill tg-cli -a codex`. Or copy the skill folder (the jackwener/tg-cli repository) into .agents/skills/tg-cli in your project. Codex loads it when a task matches its description.

Can I use Tg CLI in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jackwener/tg-cli --skill tg-cli -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tg-cli, .gemini/skills/tg-cli, .github/skills/tg-cli and .opencode/skills/tg-cli in your project.

What does Tg CLI need to run?

Going by SKILL.md and its folder, Tg CLI needs the command-line tools its instructions call (uv). Our summary lists: Python 3.

Does Tg CLI access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Tg CLI safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Tg CLI use?

Tg CLI is published under the Apache-2.0 licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tg CLI use?

About 1.2k tokens (SKILL.md is roughly 5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Tg CLI?

Skills that share tags, products or a category with Tg CLI: Process Inbox (telegramdesktop/tdesktop, 33k stars), Perform Task (telegramdesktop/tdesktop, 33k stars), Continue (telegramdesktop/tdesktop, 33k stars) and Send User Message (TinyAGI/tinyagi, 3.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tg CLI?

jackwener (a GitHub user) maintains it in jackwener/tg-cli, which has 293 GitHub stars. The repository was last updated on March 15, 2026.

Source: jackwener/tg-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Tg CLI

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

tg-cli Skill

Prerequisites

Authentication

Command Reference

Telegram Operations

Search & Query

Data Management

Structured Output

Refresh Model

Common Patterns for AI Agents

Debugging

Error Handling

Scheduling

Safety Notes

Files

Compare with similar skills

Similar skills

Process Inbox

Perform Task

Continue

Send User Message

Pytdbot

Setup

Related

Questions about Tg CLI