Maxcli

maxcli

CLI skill for personal MAX Messenger automation through maxcli.

Install

Install this skill from GitHub:

npx skills add dapi/maxcli --skill maxcli --agent '*' -g -y

Install or update the CLI from GitHub with uv:

uv tool install --force "git+https://github.com/dapi/maxcli.git@v0.3.0"

Use pipx install --force "git+https://github.com/dapi/maxcli.git@v0.3.0" when uv is unavailable.

Authenticate once:

maxcli auth +79990000000

auth asks for the MAX code and, if enabled, a hidden 2FA password prompt. Tokens are stored outside the repo in ~/.config/maxcli/config.json.

Execution Rules

• Use maxcli for personal MAX account access. Do not use the official Bot API unless the user explicitly asks for bot integration.
• Run MAX commands sequentially. The transport is based on unofficial internal APIs and can be brittle under concurrent sessions.
• Prefer --json for agent workflows.
• Never print, paste, commit, or expose tokens from ~/.config/maxcli/config.json.
• If maxcli is not found, install it from GitHub with uv tool install or pipx install as shown above.
• If authentication is missing, ask the user to run maxcli auth <phone> locally when a 2FA password is required.
• If command shape is uncertain, verify it with maxcli <command> --help.
• MAX internal APIs are unstable. If a command fails at handshake/auth level, inspect the error before retrying repeatedly.

Core Commands

Account

maxcli me --json
maxcli chats list --limit 50 --json
maxcli chats search "project name" --limit 20 --json
maxcli token-path
maxcli token-clear
maxcli token-clear --remote

Resolve Direct Chats

maxcli resolve --phone +79990000000 --json
maxcli resolve --user-id <user_id> --json
maxcli resolve --chat-id <chat_id> --json

Use chat_id from resolve for later send, history, or listen commands.

Find Named Chats

maxcli chats search "Papado AI company OS" --json
maxcli chats search "Papado" --limit 20 --fetch-pages 10 --json
maxcli chats list --limit 50 --json

Use chats search before guessing chat ids. Increase --fetch-pages when the chat is older than the initial sync window.

Send Text

maxcli send --chat-id <chat_id> "Hello" --json
maxcli send --phone +79990000000 "Hello" --json
maxcli send --chat-id <chat_id> --file ./report.pdf "See attached" --json
maxcli send --chat-id <chat_id> --file ./image.png --json
maxcli send --chat-id <chat_id> --file ./a.txt --file ./b.txt --json
maxcli send --chat-id <chat_id> --stdin --json < message.txt
maxcli send --chat-id <chat_id> --reply-id <message_id> "Reply text" --json
maxcli send --chat-id <chat_id> --silent "Quiet text" --json

Read History

maxcli history --chat-id <chat_id> --limit 20 --json
maxcli history --phone +79990000000 --limit 20 --json
maxcli history --user-id <user_id> --limit 20 --json

Use the attaches[].index value from JSON output for downloads.

Download Attachments

maxcli download --chat-id <chat_id> --message-id <message_id> --attach-index 0 --output ./downloads/ --json
maxcli download --chat-id <chat_id> --message-id <message_id> --attach-index 0 --output ./file.pdf --force --json

The command searches recent history for the message id. Increase --limit if the message is older than the default lookup window.

Listen

maxcli listen --json
maxcli listen --chat-id <chat_id> --json

Stop listening with Ctrl+C.

Current Boundaries

• maxcli currently supports direct chat resolution by phone, user id, or known chat id.
• Named chat search/listing is available through maxcli chats search and maxcli chats list.
• File attachments are supported for send, JSON metadata inspection, and downloads where MAX exposes a retrievable URL. Reactions, editing, deleting, groups, and full-text search are not stable public surfaces yet unless the CLI exposes them.