MAX CLI for AI agents and bots
Connect your personal MAX account or a bot to your agent.
max is a command-line tool that lets your AI agent read MAX, find messages and help you reply. You can also use it directly
from a terminal. It runs on Windows, macOS and Linux.
You are in the MAX documentation. Use the messenger switch at the top to open Telegram.
On this page
- Choose what to connect
- Start with your personal account
- Try it after connecting
- Find the guide for your task
Choose what to connect
- Personal account: your chats, history and contacts, as on another device. Start with installation and login.
- Bot: messages and actions in the bot's name, using its token. Open the bot guide.
These are separate connections. Bots use the official MAX Bot API; personal accounts use an internal API that may change without notice. See security for limitations and how credentials are stored.
Start with your personal account
Connect through your agent
Open the agent installation guide and copy the short request. Your agent will install the tool, help you log in and check the connection. You scan the QR code.
Then follow the guide for your agent: Codex, Claude Code, Cursor, Gemini CLI or Hermes. Apps that use MCP have a separate MCP guide.
Start in a terminal
Open the installation guide and choose the terminal instructions. After installing, run guided setup for QR login and agent skills:
max personal setupmax personal chats list --limit 5personal is the profile name: choose any name at the first login and repeat it in every command.
Setup checks your account and up to five chats. Running it again reuses your session; it does not download full history or start the background service.
See login and profiles for other login methods and additional accounts.
Try it after connecting
Ask your agent to catch up on unread messages, find a message, recall agreements or prepare a reply. Reading does not mark messages as read. Sending, deleting and other changes require separate commands; you can restrict the agent's access.
max search all searches messages, imported mail and notes stored on this computer at once. Message search (max search messages) asks both the local archive and the messenger by default (--backend both); use --backend archive for local-only results. The query language is strict Lucene and does not correct typos; --discover also tries close spellings in the local archive. Prepare saved history before archive-only search, counting or rankings, and check coverage before treating an empty result as proof that a message is absent. Without a chat, the MAX server returns one best match from each chat. Counts, rankings and queries unsupported by the server use saved history. Search guide.
Find the guide for your task
| Task | Guide |
|---|---|
| Read, search and send messages in your own name | Everyday commands |
| Log in, log out or add another account | Login and profiles |
| Connect a bot, send messages and add buttons | Bots |
| Follow unanswered questions and moderate a group | Your groups |
| Search syntax, dates and filters | Message search |
| Search local history and export conversations | Message archive |
| Find a ready request for your agent | Usage recipes |
| Fix an error | Troubleshooting |
| Look up an exact command or option | Command reference |
| Manage contacts, aliases and private notes | People |
| Compare activity and inspect ranking evidence | Rankings |
| Send, download and read files | Attachments |
| Transcribe voice messages locally | Voice transcription |
| Configure optional model APIs | External models |
| Restrict reads, writes and confirmations | Permissions |
| Choose a personal or bot profile | Profiles and bots |
| Look up setting types and precedence | Configuration reference |
The left sidebar lists shared guides and both messengers. The right sidebar lists sections of the current page. Start with installation; use the detailed reference when you have a specific task.