MAX

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 doctor checks installation: version, login, settings and local archive.
  • Problem report — a JSON file combining max personal doctor results and a failed run, for a GitHub issue.

What you can do

TaskCommandSaved data
Inspect requests as they happenmax … --traceNothing; stderr output only
Save one runmax … --recordRun record
Find a run latermax personal runs listEvery run is saved automatically
Save only failed runsmax personal config set record falseA failed run's record
Check installationmax personal doctor, max personal doctor --onlineNothing
Prepare a problem reportmax personal doctor reports createOne 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 kB

A 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 и grep

A 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

RecordedNever recorded
operation, opcode, request numberchat name
chat ID, send number (send), message IDperson's name
how many bytes went and camemessage text
how many milliseconds did the response takephone number
how many chats, contacts, messages were returnedtoken
error code and short error key MAX of the form login.tokenerror text received from MAX
warning - code, for example reactions_unreadwarning text
when it crashes - the type of error and lines of code where it happenedcrash error text
version, environment (node or bun), systemhome 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.store includes path, schema and saved chat/message counts. The check neither creates nor updates storage.
  • Run-record directory.
  • The MAX web-client version max presents and when it was inspected. After 60 days, max personal doctor warns that MAX might stop accepting it; updating max can help.
  • Runtime (Node or Bun and location), package manager, which max a new terminal finds, whether keyring and SQLite load, and whether speech-recognition files are downloaded. If the command reference is missing from PATH, it prints exact commands to add it: PowerShell on Windows, an export line 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"
done

max 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' --json

search 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.