name	telegram-agent-cli
description	Telegram automation CLI with structured output, runtime-state inspection, interactive REPL, scenario testing, and MCP server for AI agents

telegram-agent-cli

Description

Telegram automation CLI with structured output, runtime-state inspection, interactive REPL, scenario testing, and MCP server for AI agents

This skill reuses the approved description contract across Cargo metadata, SKILL.md, README, and help text.

Prerequisites

Install telegram-agent-cli so it is available on PATH for the skill runtime.
A Telegram API ID and API hash from https://my.telegram.org (for user accounts).
A bot token from BotFather (for bot accounts).
A Rust toolchain (rustup, cargo) is only needed when developing from source.

Installation for Skill Runtime

Prefer a package-manager install that exposes the bare telegram-agent-cli command:

npm install -g telegram-agent-cli
pnpm add -g telegram-agent-cli
bun install -g telegram-agent-cli
telegram-agent-cli --help

If global installs are unavailable, use a one-shot package execution fallback:

npm exec --package=telegram-agent-cli -- telegram-agent-cli --help
pnpm dlx telegram-agent-cli --help
bunx telegram-agent-cli --help

The npm wrapper downloads a matching prebuilt binary during install or on first run. After installation, the canonical skill interface remains the bare telegram-agent-cli command.

Invocation

telegram-agent-cli [OPTIONS] <COMMAND>
telegram-agent-cli help [COMMAND_PATH ...] [--format yaml|json|toml]
telegram-agent-cli paths
telegram-agent-cli context show [--as <ACCOUNT>]
telegram-agent-cli account <COMMAND>
telegram-agent-cli send --as <ACCOUNT> --to <PEER> --text <TEXT>
telegram-agent-cli message <COMMAND>
telegram-agent-cli repl --as <ACCOUNT> --chat <PEER>
telegram-agent-cli run <SCENARIO_PATH>
telegram-agent-cli mcp

The canonical agent-facing contract uses the bare command name shown above. cargo run -- ... and ./target/release/telegram-agent-cli ... are developer-only fallbacks for source checkouts and should not be treated as the final installed skill interface.

Global Options

Flag	Type	Default	Description
`--format`, `-f`	`table` \| `yaml` \| `toml` \| `json` \| `ndjson`	`yaml`	Structured output format for one-shot commands and structured help
`--help`, `-h`	—	—	Plain-text help only; never emits YAML/JSON/TOML
`--version`, `-V`	—	—	Print version and exit

Commands

Command	Kind	Purpose
`help`	leaf	Return structured help for the requested command path
`paths`	leaf	Inspect config, data, state, and cache directories
`context show`	leaf	Display the current Active Context and effective account
`account add-user`	leaf	Register a Telegram user account with API credentials
`account add-bot`	leaf	Register a Telegram bot account with a bot token
`account list`	leaf	List configured accounts and login state
`account use`	leaf	Set the default account for future commands
`account login`	leaf	Authenticate an account by QR flow or credentials
`account logout`	leaf	Clear stored session for an account
`alias set`	leaf	Bind a memorable alias to a resolved Telegram peer
`alias list`	leaf	List saved alias-to-peer mappings
`peer resolve`	leaf	Resolve a username, alias, or ID into a Telegram peer
`list contacts`	leaf	List direct-contact peers for the selected account
`list chats`	leaf	List groups and channels for the selected account
`doctor`	leaf	Inspect local configuration and storage state
`export`	leaf	Export scenario run events as structured output
`send`	leaf	Send a text message to a Telegram peer
`send-file`	leaf	Send a file to a Telegram peer
`send-photo`	leaf	Send a photo to a Telegram peer
`wait`	leaf	Wait for one matching message from a target chat
`message recv`	leaf	Read recent messages from a Telegram chat
`message follow`	leaf	Stream new matching messages from a Telegram chat
`message wait`	leaf	Wait for one matching message (message family)
`message click-button`	leaf	Click an inline button in a bot message
`message list-actions`	leaf	Discover inline buttons, reply keyboards, and bot commands
`message trigger-action`	leaf	Trigger an action discovered from list-actions
`message unread`	leaf	Show unread message statistics
`message forward`	leaf	Forward messages between chats
`message edit`	leaf	Edit an existing message's text
`message pin`	leaf	Pin a message in a chat
`message unpin`	leaf	Unpin a pinned message
`message download`	leaf	Download media from a message
`bot set-commands`	leaf	Set the bot command menu shown in chat
`bot set-info`	leaf	Set the bot description and about text
`run`	leaf	Execute a scripted test scenario file
`repl`	leaf	Open an interactive REPL session for testing
`mcp`	leaf	Start as an MCP tool server for AI agents over stdio

Input

Most commands do not read from stdin in one-shot mode.
repl opens an interactive readline session on stdin.
mcp reads JSON-RPC requests from stdin and writes responses to stdout.
Account selection uses --as <NAME> (default: "default", which resolves to the persisted default account).
Peer targets accept aliases, usernames (@user), or numeric IDs.
Sensitive credentials (tokens, sessions, passwords) can be provided via environment variables (--token-env, --session-env, --code-env, --password-env).

Output

Standard command results are written to stdout. Errors and diagnostics are written to stderr.

Help Channels

--help is the plain-text help channel. It always prints text and exits 0.
help is the structured help channel. It supports yaml, json, toml, and table, with YAML as the default.
Top-level invocation displays plain-text help automatically and exits 0.

Structured Results

The default one-shot result format is YAML. Every result is wrapped in a ResultEnvelope with command, status, summary, data, next_steps, and errors fields.

Example send result:

command: telegram-agent-cli send
status: ok
summary: Message sent
data:
  message_id: 42
  peer: qa-bot
next_steps:
  - action: inspect_reply
    command: telegram-agent-cli message recv --as alice --chat qa-bot --limit 1
errors: []

Example paths result:

command: telegram-agent-cli paths
status: ok
summary: Runtime paths
data:
  config_dir: /home/user/.config/telegram-cli
  data_dir: /home/user/.local/share/telegram-cli
  state_dir: /home/user/.local/share/telegram-cli/state
  cache_dir: /home/user/.cache/telegram-cli
next_steps: []
errors: []

Streaming

message follow produces a sequence of StreamEventEnvelope records, each with command, event, sequence, status, summary, data, next_steps, and final fields. NDJSON is the recommended format for streaming consumers:

telegram-agent-cli message follow --as alice --chat qa-bot --format ndjson

When managed daemon mode is enabled, daemon metadata is stored at state_dir/daemon/server.json and daemon logs are written to state_dir/daemon/server.log.

Active Context

Most commands include an active_context block showing the persisted and effective account:

context:
  persisted_context: alice
  effective_context: alice
  override_applied: false
  mutation_path: "telegram-agent-cli account use <name>"
  requires_context: true

--as <NAME> overrides the persisted context for one invocation.
account use <NAME> persists the default account.
context show inspects the current Active Context without side effects.

REPL Mode

repl opens an interactive session. REPL help remains plain text only and the default session view prioritizes readability over raw YAML.

telegram-agent-cli repl --as alice --chat qa-bot

Inside the REPL, use /help to discover available slash commands.

MCP Server

mcp starts telegram-agent-cli as a Model Context Protocol tool server over stdio, exposing Telegram operations as tools for AI agents:

telegram-agent-cli mcp

Configure in Claude Desktop or other MCP clients:

{ "command": "telegram-agent-cli", "args": ["mcp"] }

Errors

Exit Code	Meaning
`0`	Success or plain-text help
`1`	Unexpected runtime failure
`2`	Structured usage or validation error

Structured errors preserve the selected output format and include at least stable code and message fields. Sensitive fields (tokens, sessions, passwords, API hashes) are automatically redacted from output.

Example structured error (--format json):

{
  "command": "telegram-agent-cli send",
  "status": "error",
  "summary": "Command failed.",
  "data": null,
  "next_steps": [
    { "action": "inspect_help", "command": "telegram-agent-cli help send" }
  ],
  "errors": [
    { "code": "message_error", "message": "account alice was not found" }
  ]
}

Examples

Plain-text discovery:

$ telegram-agent-cli
NAME
  telegram-agent-cli - Telegram CLI for automation and bot testing

Structured help:

$ telegram-agent-cli help send --format yaml

Send a message:

$ telegram-agent-cli send --as alice --to @user --text "hello"

Wait for a bot response:

$ telegram-agent-cli wait --as alice --chat qa-bot --text-contains Welcome --timeout 5s

Run a test scenario:

$ telegram-agent-cli run fixtures/scenarios/echo.yaml

Export scenario results:

$ telegram-agent-cli export --run-id latest --format ndjson

Interactive REPL:

$ telegram-agent-cli repl --as alice --chat qa-bot

MCP server for AI agents:

$ telegram-agent-cli mcp

Created: 2026-04-02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

telegram-agent-cli

Description

Prerequisites

Installation for Skill Runtime

Invocation

Global Options

Commands

Input

Output

Help Channels

Structured Results

Streaming

Active Context

REPL Mode

MCP Server

Errors

Examples

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

telegram-agent-cli

Description

Prerequisites

Installation for Skill Runtime

Invocation

Global Options

Commands

Input

Output

Help Channels

Structured Results

Streaming

Active Context

REPL Mode

MCP Server

Errors

Examples