Telegram CLI

Telegram CLI Skill

Enables the agent to interact with Telegram on behalf of the user via Telethon (MTProto protocol).

Path conventions

Paths in this skill are relative to the directory containing this SKILL.md, not to the workspace root or the shell's current ./.

• Scripts in this skill use paths like scripts/...
• When a command below says python scripts/..., resolve that script path against the skill's absolute Base Directory
• On Linux/macOS, use python3 if python is unavailable
• In command examples below, replace <skill-base-dir> with the skill's actual absolute Base Directory

⚠️ Security Rules (Mandatory)

• NEVER ask for 2FA password, verification codes, or other transient secrets in chat
• NEVER display or repeat the contents of ~/.libragent/telegram_config.json
• Collect transient secrets (verification codes, 2FA passwords) exclusively through requireUserInput=true shell prompts — never in chat
• For verification codes and 2FA, prefer requireUserInput=true with python setup.py --code-stdin / --password-stdin (LibrAgent auto-pipes UI input to child stdin on Windows when these flags are present)
• ALWAYS use setup.py to persist credentials and session
• If the user accidentally pastes a password or code in chat, acknowledge receipt, do NOT echo it back, and immediately run setup to store it properly

Overview

Telegram integration involves these steps:

1. Detect config — run check_config.py to check if account is configured
2. Setup (first time only) — gather API ID/Hash, phone number, then run setup.py with hidden prompts for code/password
3. Dispatch action — classify the user's request and call telegram_cli.py with the right action
4. Present results — format and summarize the output for the user

Dependencies

Required dependencies (should already be installed):

• telethon: pip3 install telethon (MTProto client library)

References

These reference files are located in the skill directory:

• cli-reference.md — CLI commands, options, outputs, and errors reference

Step 1: Detect Config

Always start by checking if the account is configured:

python "<skill-base-dir>/scripts/check_config.py"

• Exit code 0 with "status": "ok" → configured and authorized, proceed to Step 3
• Exit code 1 → missing config/session or not authorized (missing, missing_session, unauthorized, auth_restart_needed), go to Step 2
• Exit code 2 → config exists but is incomplete/corrupt, go to Step 2 to reconfigure/overwrite it
• "status": "auth_restart_needed" → delete ~/.libragent/telegram_session.session and restart from Step A (send_code)

Step 2: Account Setup (First Time or Reset)

Do not run python "<skill-base-dir>/scripts/setup.py" bare inside LibrAgent. That old terminal wizard asks for multiple prompts and can time out under the current prompt-resume shell contract.

Instead:

2.1: Guide API ID/Hash Acquisition

If the user doesn't have API credentials, guide them to:

1. Visit https://my.telegram.org
2. Log in with their phone number
3. Click "API development tools"
4. Fill in App title and Short name (can be anything)
5. Copy the api_id and api_hash

2.2: Two-Step Authentication Flow

1. Collect API credentials in chat

Ask the user for:

• api_id (integer)
• api_hash (string)
• phone (international format, e.g., +821012345678)

2. Interactive setup commands

Step A — Send verification code:

python "<skill-base-dir>/scripts/setup.py" `
  --api-id 12345678 `
  --api-hash "abcdef0123456789..." `
  --phone "+821012345678" `
  --action send_code

This outputs a JSON confirmation that the code was sent. On AuthRestartError, the script clears the partial session and retries once. If it still fails, you get "status": "auth_restart_needed" — run send_code again.

Step B — Sign in with verification code:

Execute workspace__runInPersistentShell (or workspace__runInPersistentPowerShell) with:

• requireUserInput=true

• inputType=text

• inputPrompt=텔레그램 인증 코드를 입력하세요:

• Command:

  python "<skill-base-dir>/scripts/setup.py" --action sign_in --code-stdin
  

LibrAgent auto-detects --code-stdin and pipes the UI input into Python stdin (stdinDelivery=child).

Fallback if piping is unavailable on an older build:

$code = Read-Host; python "<skill-base-dir>/scripts/setup.py" --action sign_in --code-value $code

Step C — Handle 2FA (if Step B returns "password_needed"):

• requireUserInput=true

• inputType=password

• inputPrompt=텔레그램 2FA 비밀번호를 입력하세요:

• Command:

  python "<skill-base-dir>/scripts/setup.py" --action sign_in --password-stdin
  

After successful setup, re-run check_config.py to confirm "status": "ok", then proceed to Step 3.

Step 3: Dispatch Action

Classify the user's request into one of six actions and call telegram_cli.py.

Output handling (recommended for message/search actions)

On Windows, large JSON payloads can break in PowerShell (cp949). Prefer saving results to a UTF-8 file:

python "<skill-base-dir>/scripts/telegram_cli.py" --action get_messages `
  --chat "<chat_id_or_username>" `
  --limit 50 `
  --output "<workspace>/telegram_messages.json"

When --output is set, stdout prints a compact summary (status, output path, count). Read the file for full message bodies.

All CLI output uses UTF-8 (ensure_ascii=False). Errors go to stderr as UTF-8 JSON.

Output handling (Windows 필수)

On Windows, always set these before invoking any CLI command:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONUTF8 = "1"

Input encoding & PowerShell escaping (Windows / Unicode / Literal $ workaround)

On Windows, passing Unicode characters (like Korean) as command-line arguments can cause character corruption (mojibake) due to PowerShell's default encoding (cp949).

To bypass this bottleneck, it is highly recommended to write the message or query to a UTF-8 file and use --message-file or --query-file instead of --message or --query.

[!WARNING] PowerShell Here-String Interpolation Danger: If you use double-quoted Here-Strings (@" ... "@) in PowerShell, characters starting with $ are treated as variables. For example, $3,000 will evaluate $3 as an empty variable, resulting in ,000, and $1.5B will evaluate $1 as empty, resulting in .5B.

How to avoid this:

1. (Best/Recommended): Use the agent's writeFile (or workspace__writeFile) tool to directly create and write the message content to a file (e.g., <workspace>/tg_message.txt) as UTF-8. This completely bypasses any PowerShell escaping or variable interpolation issues.
2. (Alternative - Single Quotes): If you must write the file via PowerShell, use single-quoted Here-Strings (@' ... '@) which disable variable interpolation.

Send Message (Windows Recommended via writeFile)

1. Use the writeFile (or workspace__writeFile) tool to save your message (e.g. including $3,000 or Korean text) directly to <workspace>/tg_message.txt in UTF-8 format.
2. Call the CLI pointing to the file:

python "<skill-base-dir>/scripts/telegram_cli.py" --action send_message `
  --chat "<chat_id_or_username>" `
  --message-file "<workspace>/tg_message.txt"

3. Clean up the temporary file afterwards:

Remove-Item -Path "<workspace>/tg_message.txt" -ErrorAction SilentlyContinue

Search Messages (Windows Recommended via writeFile)

1. Use the writeFile (or workspace__writeFile) tool to save your query directly to <workspace>/tg_query.txt in UTF-8 format.
2. Call the CLI pointing to the file:

python "<skill-base-dir>/scripts/telegram_cli.py" --action search_messages `
  --query-file "<workspace>/tg_query.txt" `
  --output "<workspace>/telegram_search.json"

3. Clean up the temporary file afterwards:

Remove-Item -Path "<workspace>/tg_query.txt" -ErrorAction SilentlyContinue

Dispatch CLI Actions

Classify the user's request into one of the actions (send_message, get_messages, list_chats, search_messages, download_file, get_chat_info) and execute the CLI. For a detailed reference of CLI parameters, JSON output schemas, and pagination strategies, see the cli-reference.md guide.

Step 4: Present Results

• Message list: Show as a numbered table — # From Date Content
• Send confirmation: Confirm action completed with brief summary
• Chat list: Show as a table — # Name Type Members/ID Last Activity
• Search results: Same as message list, with match count
• Errors: See Error Handling in cli-reference.md

Always provide the next concrete step, never just report the error.

Output Format Guidelines

For message listings, use this format:

📨 텔레그램 메시지 (chat: @example_channel)

#  날짜              내용
1  06/01 14:23      오늘 회의는 14시에 시작됩니다.
2  06/01 13:45      [이미지]
3  06/01 12:00      새로운 기능 배포 완료

더 보려면: "다음 20개 보여줘"

For send confirmation:

✅ 텔레그램 메시지 발송 완료
  받는 곳: @example_channel
  발송 시각: 2026-06-01 14:30

For chat listings:

💬 텔레그램 채팅 목록 (총 25개)

#  이름                    유형       마지막 활동
1  ● LibrAgent Dev         채널       10분 전
2    GitHub Notifications  채널       1시간 전
3  ● 프로젝트 A            그룹(42)   3시간 전
4    김철수                개인       어제

● = 읽지 않음