Bot Command Reference¶

This document describes the user-facing bot interface implemented in the current code.

Source of truth:

• pytmbot/handlers/handler_manager.py
• pytmbot/settings.py
• pytmbot/plugins/monitor/config.py
• pytmbot/plugins/outline/config.py
• pytmbot/keyboards/keyboards.py
• pytmbot/middleware/callback_ack.py
• pytmbot/handlers/bot_handlers/fallback.py

Slash Commands¶

Always available in the core bot:

Provided only when the plugin is loaded:

Reply Keyboard Sections¶

Main menu buttons:

• 🖥️ Server
• 🐳 Docker
• 👀 Quick view
• 🩺 Health
• 🧩 Plugins
• ℹ️ About

Server section buttons:

• 📈 Load average
• ⚡ CPU
• 🧠 Memory load
• 🌡️ Sensors
• ⚙️ Processes
• ⏱️ Uptime
• 💾 File system
• 🌐 Network

Docker section buttons:

• 📦 Containers
• 🖼️ Images

Authentication buttons:

• 📱 Get 2FA QR code
• 🔢 Enter 2FA code

Plugin buttons:

• come from loaded plugin index metadata
• monitor adds 📊 Monitoring
• outline adds 🪐 Outline VPN

Button text is matched by its label, so the leading emoji is optional: typing CPU or ⚡ CPU opens the same view, while longer phrases that merely contain a label are ignored.

2FA Input¶

TOTP verification accepts a six-digit code:

• 123456
• /123456

Sensitive flows request 2FA only when the action is marked as requiring it.

Codes and the QR code are accepted only in a private chat with the bot. In a group, the bot replies with an Open private chat link (/start 2fa); confirm there, then repeat the action in the group.

Inline Flows¶

The bot also exposes callback-driven flows that are not slash commands:

• container list pagination and detail screens
• container logs, runtime info, volumes, and networks
• container actions (start, stop, restart); Stop and Restart ask for confirmation, and a second press while an action is running is refused
• image list pagination, metadata screens, and image update checks (run in the background with a 60-second limit; only Docker Hub images are checked, other registries and locally built images are listed as not checked)
• bot update guide after /check_bot_updates
• active sessions from Uptime
• quick-view refresh
• health refresh
• detailed network, CPU, memory, and process drill-down views
• plugin-specific inline navigation

Notes¶

• There are no separate slash commands for individual server views such as CPU or memory.
• Those views are entered through the reply keyboard or inline navigation after /server or Quick view.
• Command access is still gated by allowlists, middleware, and optional 2FA.

Reply Keyboard Behavior¶

• Section menus (main, server, docker, plugins) use persistent reply keyboards so Telegram clients (notably iOS) keep the menu visible while you browse inline screens.
• Reply keyboard accents use KeyboardButton.style: primary for Server / Docker / Quick view / Health in the main menu, and danger for back-navigation buttons in section and plugin menus. Back-navigation buttons always sit on their own full-width bottom row so the label does not wrap on phones.
• Container action buttons use inline button styles: danger for Stop, primary for Restart, and success for Start.
• Text-only bot replies re-attach the matching section keyboard automatically.
• Structured screens (server metrics, Docker lists and details, menus, update checks, /getmyid, plugin screens) are Telegram Rich Messages with native tables; oversized content is trimmed to Telegram limits, and a rejected rich payload falls back to a plain-text message.
• Every inline button press is acknowledged, so the client spinner never hangs; failures show a short "Something went wrong. Please try again." toast.
• Only the latest "Use the menu below to continue." follow-up is kept per chat; older copies are deleted.
• Unrecognized text from an allowed user in a private chat gets a short hint pointing back to the menu instead of silence; a mistyped code during 2FA gets the 2FA hint instead.
• Container and image details show environment variables as keys only (values masked, except harmless keys such as PATH, TZ, LANG); passwords in URLs and secret-looking command-line values are masked as well. Command arguments are shown only to admins in a private chat with the bot; other users, and groups, see just the executable (for example mysqld) and the instruction of each image history step.
• Container buttons reference containers by their 12-character short ID, so names are never guessed or case-folded.
• Ephemeral messages removed by auto-delete (for example /getmyid, QR setup, exported Docker logs) send a short follow-up that restores the appropriate menu keyboard.

Related Docs¶

• auth_control.md
• plugins.md
• architecture.md