Diagnostics: what a command did — MAX
Check the MAX CLI environment, configuration and connection, and gather a diagnostic report.
Use this page when a command fails, hangs or takes too long and you want to know why. You will learn to inspect requests as they happen, save a run record, check installation and submit a problem report without message text.
Terms used below:
- Run — one invocation of
max, from startup to exit. - Run record — a directory describing one run: command, outcome and one line per MAX request. The request lines never contain message text, people's names or chat names. The record may keep the command line as you typed it, without secrets (more).
max personal doctorchecks installation: version, login, settings and local archive.- Problem report — a JSON file combining
max personal doctorresults and a failed run, for a GitHub issue.
What you can do
| Task | Command | Saved data |
|---|---|---|
| Inspect requests as they happen | max … --trace | Nothing; stderr output only |
| Save one run | max … --record | Run record |
| Find a run later | max personal runs list | Every run is saved automatically |
| Save only failed runs | max personal config set record false | A failed run's record |
| Check installation | max personal doctor, max personal doctor --online | Nothing |
| Prepare a problem report | max personal doctor reports create | One file you choose to submit |
Show: --trace
max personal chats list --trace→ session.init op 6 seq 1 432 B
← session.init op 6 seq 1 89ms 335 B 38 reg-country-code
→ session.login op 19 seq 2 871 B
← session.login op 19 seq 2 202ms 48.0 kB 25 chats 6 contacts
→ contacts.info op 32 seq 3 154 B 3 contacts
← contacts.info op 32 seq 3 91ms 6.5 kB 10 contacts→ is a request, ← a response and • a response that did not go over the network. Each line then shows the operation, protocol opcode, request sequence number, named IDs, duration, frame size and counts of returned items.
Everything goes to stderr, keeping --json output intact:
max personal chats list --json --trace > chats.json # данные в файл, диагностика на экранA terminal displays the lines above. A pipe receives one JSON object per line, as with data:
max personal chats list --json --trace 2>&1 >/dev/null | jq -c 'select(.event == "response")'--trace overrides --quiet: a flag you explicitly add always applies.
Bot commands
For max <имя> bot …, each HTTP request to the Bot API gets a line with its operation, IDs from the URL (chat, message, person, comment), HTTP status, duration and response size.
max shop bot messages list -100 --trace→ getMyInfo GET /me
← getMyInfo GET /me 200 143ms 211 B
→ getMessages GET /messages chat -100
← getMessages GET /messages 200 chat -100 187ms 6.2 kBA failure shows the error code and MAX's key, such as 404 not_found not.found, but never the response text. File uploads (--file, uploads put) have a separate pair of lines such as upload.image, upload.video, and so on, showing size, HTTP status and duration. Neither upload URLs nor filenames appear: the URL itself grants access.
Save: --record
max personal chats list --record
max personal runs list # что делалось, новое сверху
max personal runs show <id> # один запуск: чем кончился и куда ходил
max personal runs path <id> # каталог, для jq и grepA run directory:
~/.local/share/max-cli/runs/2026-09-19/20260919T234428Z-chats-list-9df39e/
run.json что это было, когда, какой профиль, сколько длилось, чем кончилось
events.jsonl по объекту JSON на запрос, без единого управляющего символаEach request in events.jsonl is marked "level": "wire" and with its transport: "transport": "max-ws" for a frame of the personal protocol (with opcode and seq), "transport": "http" for the Bot API (method and path with :id in place of IDs, without the query string). A Bot API request has attempt: 1 for the first try, 2 and up for a retry. After a 429 refusal or a read failure, the log first has the response with "outcome": "error", then the retry with "attempt": 2 and "wait_ms", the milliseconds the client waited before it (MAX's Retry-After or its own pause). Retries of messages send while MAX answers attachment.not.ready are marked the same way: each retry's frame carries attempt and "wait_ms": 1000.
The directory has permissions 0700; both files use 0600. run.json is written twice: at startup with status running, then with the outcome. An events directory therefore always has a run description.
The outcome is saved on every exit path, including a command that fails before connecting:
{ "run_id": "…", "command": "chats list", "profile": "personal", "status": "failed",
"requests": 0, "error_code": "authentication_error", "duration_ms": 12 }Every run is saved automatically
A run is saved even without --record, successful ones too. A failed run is saved for any error: an invalid flag, an unknown command, a preflight failure, or commands that do not contact MAX (models, server, watch, upgrade). Its run.json has argv, the command line as you typed it: a chat name, a search query, message text. Secrets in it are always hidden, and what you typed can be hidden with the record_input setting (more).
A successful run that recorded no events is one line in the day's list, with no directory; runs show finds it there. Commands that run until stopped (watch, serve, mcp serve) and commands WireCat Desktop runs for itself keep a successful run only with --record. --no-record saves nothing, not even a failed run.
Successful search and statistics requests keep separate history containing query parameters, not returned messages. See saved searches and history for controls.
Recording less
max personal config set record false # этот профиль: только неудачные запуски
max personal chats list --no-record # этот запуск: ничегоThe same in the settings file:
{ "profiles": { "personal": { "record": false } } }With "record": false, successful runs are not recorded; failed runs still are. A successful run keeps the command line as typed, for example the text of a sent message; record_input decides whether to keep it (more). --no-record or "record": false also disables search history.
Retention
A failed run lasts 30 days (keep_runs_for_days), a successful one 7 days (keep_successful_runs_for_days), in configuration. The runs directory never grows beyond runs_size_limit_mb (200 MB): the oldest successful runs are removed first. Old records are removed only when a new record is written. Entire days are removed by directory name, without opening their contents to decide.
What you typed
A run record's run.json can contain argv: the words after max, as you typed them. They show exactly what was run:
{ "command": "messages list", "argv": ["personal", "messages", "list", "Семья", "--token=[redacted]"] }A secret is always replaced by [redacted], whatever the settings. A secret is the value of a flag whose name contains token, password, secret, credential, cookie, authorization or API key; a password inside an address; a long string without spaces that looks like a key; the body of bot api … --body. max does not accept a phone number on the command line: if you still type one after contacts lookup, the command refuses, and the record shows [redacted].
To keep what you typed out of run records:
max personal config set record_input false # этот профиль
max config set record_input false --defaults # все профилиThen argv keeps the command words, flag names, the profile name and values that cannot be anyone's words: short numbers, dates, durations, true and false. Everything else becomes [redacted]. If the settings file cannot be read, what you typed is hidden too: record_input may have been turned off in that very file.
What is never recorded
| Recorded | Never recorded |
|---|---|
| operation, opcode, request number | chat name |
chat ID, send number (send), message ID | person's name |
| how many bytes went and came | message text |
| how many milliseconds did the response take | phone number |
| how many chats, contacts, messages were returned | token |
error code and short error key MAX of the form login.token | error text received from MAX |
warning - code, for example reactions_unread | warning text |
| when it crashes - the type of error and lines of code where it happened | crash error text |
version, environment (node or bun), system | home directory path |
The table covers the event lines and the run's outcome. The command line in argv is separate, above.
Not even truncated or hashed. Events are built from explicitly named fields, not by filtering a copy of the request, so an unexpected field cannot enter the log. session.login contains a token field, but no logging code reads it.
Identifiers are recorded. A chat id is a number that is unusable without its associated session. It makes diagnostics useful because a real complaint concerns a specific chat.
MAX error text is excluded because a server error can quote submitted data, including a message. Only a key with lowercase Latin letters, digits, dots and hyphens, such as proto.payload, is recorded. Any other response text is omitted.
The same applies to reports assembled from runs.
Check installation: max personal doctor
max personal doctor # никуда не подключается
max personal doctor --online # ещё и входит в MAX один раз; ничего не отправляетWithout --online, it reports without connecting to MAX the information commands depend on:
- Whether a token exists, its source, keyring entry and any environment-variable relocation. It never prints the token, only presence and source.
- Login count and last login; every local profile: personal account, bot or both.
- Shared storage: JSON
item.storeincludes path, schema and saved chat/message counts. The check neither creates nor updates storage. - Run-record directory.
- The MAX web-client version
maxpresents and when it was inspected. After 60 days,max personal doctorwarns that MAX might stop accepting it; updatingmaxcan help. - Runtime (Node or Bun and location), package manager, which
maxa new terminal finds, whether keyring and SQLite load, and whether speech-recognition files are downloaded. If the command reference is missing fromPATH, it prints exact commands to add it: PowerShell on Windows, anexportline on Linux/macOS. - Any login pause imposed after MAX rejects excessive logins.
For a bot profile, max <имя> doctor reports the bot token's source, observed chat count and profile file locations: state, cache, run records, bot files, send journal and shared message storage.
--online performs one login, reads one listed chat, then launches MCP as a client would and requests its tool list. It sends nothing and marks nothing read. Login counts toward MAX's login limit and is not retried after failure. A failed component returns a non-0 exit code. With a bot token, it also asks the Bot API whose token it is and prints the bot name and id. Without a personal token, it skips personal-account login.
Problem Report
max personal doctor reports create # о последнем неудачном запуске
max personal doctor reports create --run <id> # об этом запускеIf configuration cannot be read, first run max doctor --json. In config.issues it lists every problem in the file: its kind, the key, the line and column for invalid JSON, and the config unset command that removes the key. Setting values are not included in the answer. Even with problems in the file, doctor answers and exits with code 0. In files.problems it names the settings file and its folder if other users can read them, and prints the chmod that fixes this to stderr. Creating a report file requires a write-permission check, so fix the invalid setting first.
The command writes a JSON file containing max personal doctor results and the run, then prints a link to a new GitHub issue. Read the file before submitting. It has no message text; chat and message ids are replaced with labels. See reporting a problem for its remaining contents.
If there is no failed run, run the failing command again to save its error automatically.
What to do with the recordings
Records are JSON, so jq can inspect them. max personal runs list --json returns { items, page: { limit, has_more } }; items contains run.json records, newest first:
# какие запуски закончились плохо
max personal runs list --json | jq '.items[] | select(.status=="failed") | {run_id, command, error_code}'
# сколько времени ушло на вход в последних запусках
for id in $(max personal runs list --json | jq -r '.items[].run_id'); do
jq -r 'select(.operation=="session.login" and .event=="response") | "\(.duration_ms)ms"' \
"$(max personal runs path "$id" --json | jq -r .item.path)/events.jsonl"
donemax personal runs show displays the same events as a table without repeated bookkeeping fields, keeping durations on screen. The full file, including those fields, is in the directory printed by max personal runs path.
Next steps
Search errors and partial runs
max personal search runs error_code:rate_limited --json
max personal search runs status:partial 'started_at>=2026-10-01' --jsonsearch runs matches literal diagnostic text in metadata and safe events. Put status:, error_code:, operation:, profile: and started_at: comparisons or ranges in the query. --limit and --page choose the page. Each page allows up to 100 runs and
each run returns at most 100 matched events, with events_truncated for additional events.
A failed batch item or history page creates status: "partial" with failed IDs, stages and
codes; message contents and provider error payloads are not copied into that record. Partial
records are kept by default unless recording was explicitly disabled. Search does not record itself.
MCP max_read with command: "search runs" accepts these arguments: query (including conditions and time bounds), limit and page. It reads only the active profile's diagnostic runs, does not connect to MAX and does not open
raw background-job logs. The original partial result names the failed items and their error codes; diagnostic records
keep only safe identifiers and codes.