Telegram Agent CLI

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

Commands

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

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