# Send Telegram MTPROTO CLI to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "tg-mtproto-cli",
    "name": "Telegram MTPROTO CLI",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/cyberash-dev/tg-mtproto-cli",
    "canonicalUrl": "https://clawhub.ai/cyberash-dev/tg-mtproto-cli",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/tg-mtproto-cli",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tg-mtproto-cli",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "tg-mtproto-cli",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-09T19:38:26.765Z",
      "expiresAt": "2026-05-16T19:38:26.765Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tg-mtproto-cli",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tg-mtproto-cli",
        "contentDisposition": "attachment; filename=\"tg-mtproto-cli-0.1.4.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "tg-mtproto-cli"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/tg-mtproto-cli"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/tg-mtproto-cli",
    "downloadUrl": "https://openagent3.xyz/downloads/tg-mtproto-cli",
    "agentUrl": "https://openagent3.xyz/skills/tg-mtproto-cli/agent",
    "manifestUrl": "https://openagent3.xyz/skills/tg-mtproto-cli/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/tg-mtproto-cli/agent.md"
  }
}
```
## Documentation

### tg — Telegram CLI via MTProto

CLI tool for reading Telegram data directly via MTProto protocol. No Bot API, no limits.

### Required binaries

BinaryInstallPurposetgnpm install -g tg-mtproto-cliCore CLIjq (optional)brew install jq or apt install jqJSON filtering in workflow examples

Source and provenance:

npm: npmjs.com/package/tg-mtproto-cli
GitHub: github.com/cyberash-dev/tg-mtproto-cli

Verify after install:

tg --version
npm ls -g tg-mtproto-cli

### Required credentials

CredentialHow to obtainStorageTelegram api_id + api_hashmy.telegram.org/appsSystem keychain (macOS Keychain / Windows Credential Vault / Linux Secret Service)Phone number + OTP codeInteractive prompt during tg authNot persisted; used once for session creation

Credentials are entered interactively via tg auth. No environment variables required.

### Runtime surface

ResourceAccessDetailsNetworkOutbound TCP to Telegram DC serversMTProto protocol, required for all commandsSession filesRead/write ~/.tg-mtproto-cli/sessions/*.sessionSQLite databases with auth keys; created by tg authSystem keychainRead/writeStores api_id, api_hash, account metadata, default accountFilesystemWrite (only tg download)Saves media to --out dir or current directory

### Guardrails

The CLI is read-only by design — it has no commands to send messages, create chats, modify groups, or perform any write operations on Telegram. The only write targets are local: session files and downloaded media.
tg download writes files only to the explicitly specified --out directory or cwd.
Session files contain sensitive auth material — do not read, copy, or expose ~/.tg-mtproto-cli/sessions/ contents.
Do not log or display api_id / api_hash values.
If tg auth is needed, inform the user — it requires interactive input (phone, OTP) and cannot be automated.

### Chat identification

Chats can be referenced by:

Username: @username or username
Numeric ID: -1001234567890 (groups/supergroups use negative IDs)
Phone: +1234567890 (for private chats)

To find a chat's numeric ID, use tg chats --json | jq '.[] | {id, title}'.

### List chats

tg chats [--type private|group|supergroup|channel] [--limit 50] [--offset 0]

### Read messages

tg messages <chat> [-n 100] [--all] [--topic <id>] [--after <datetime>]

FlagDescription-n <count>Number of messages (default: 100)--allEntire history (shows progress)--topic <id>Forum topic (get IDs via tg topics <chat>)--after <datetime>Only messages after this time

--after formats: 2026-02-22, 2026-02-22T10:00, 10:00 (today).

When --after + -n are combined: filter by date first, then take last N.

### List forum topics

tg topics <chat>

Returns topic IDs needed for --topic flag.

### Download media

tg download <chat> <messageId> [--out <dir>]

Downloads the media attachment from a specific message. Get message IDs from tg messages output (shown as #<id>).

### Account management

tg auth                          # authenticate (interactive)
tg logout [alias]                # remove session
tg accounts                      # list accounts
tg accounts rename <old> <new>   # rename alias
tg default <alias>               # set default

### Global flags

FlagEffect--account <alias>Use specific account instead of default--jsonJSON output (for scripting/piping)

### JSON output

All commands support --json for structured output. Dates are ISO 8601.

tg chats --json
tg messages @chat -n 10 --json
tg download @chat 42 --json

### Message JSON schema

{
  "id": 42,
  "chatId": -1001234567890,
  "senderName": "John",
  "text": "Hello",
  "date": "2026-02-22T10:15:00.000Z",
  "media": { "type": "photo", "fileName": null, "mimeType": "image/jpeg", "size": 262525 },
  "replyToId": null,
  "isOutgoing": false
}

media is null when no attachment. media.type: photo, video, document, audio, voice, sticker.

### Extract text from a chat since a date

tg messages @channel --after 2026-02-01 --json | jq -r '.[].text // empty'

### Find messages with photos

tg messages @chat -n 500 --json | jq '[.[] | select(.media.type == "photo")]'

### Download all photos from recent messages

for id in $(tg messages @chat -n 50 --json | jq -r '.[] | select(.media.type == "photo") | .id'); do
  tg download @chat "$id" --out ./photos
done

### Read a forum topic

tg topics -1001234567890          # find topic ID
tg messages -1001234567890 --topic 42 -n 20

### Multi-account usage

tg chats --account work
tg messages @chat -n 10 --account personal

### Exit codes

CodeMeaning0Success1Runtime error (invalid args, chat not found)2Auth required (no account, expired session) — run tg auth

### Troubleshooting

"No default account" → run tg auth or use --account <alias>
"Session expired" → run tg auth to re-authenticate
Chat not found → use numeric ID from tg chats --json
Empty messages → check chat ID sign (groups are negative)
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: cyberash-dev
- Version: 0.1.4
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-09T19:38:26.765Z
- Expires at: 2026-05-16T19:38:26.765Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/tg-mtproto-cli)
- [Send to Agent page](https://openagent3.xyz/skills/tg-mtproto-cli/agent)
- [JSON manifest](https://openagent3.xyz/skills/tg-mtproto-cli/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/tg-mtproto-cli/agent.md)
- [Download page](https://openagent3.xyz/downloads/tg-mtproto-cli)