# Diagnostics: what a command did (/en/docs/max/diagnostics)

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 [#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` [#show---trace]

```sh
max personal chats list --trace
```

```text
→ 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:

```sh
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:

```sh
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 [#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.

```sh
max shop bot messages list -100 --trace
```

```text
→ 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` [#save---record]

```sh
max personal chats list --record
max personal runs list                 # что делалось, новое сверху
max personal runs show <id>            # один запуск: чем кончился и куда ходил
max personal runs path <id>            # каталог, для jq и grep
```

A run directory:

```text
~/.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:

```json
{ "run_id": "…", "command": "chats list", "profile": "personal", "status": "failed",
  "requests": 0, "error_code": "authentication_error", "duration_ms": 12 }
```

## Every run is saved automatically [#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](/llms.mdx/docs/max/search/content.md#%D1%81%D0%BE%D1%85%D1%80%D0%B0%D0%BD%D1%91%D0%BD%D0%BD%D1%8B%D0%B5-%D0%BF%D0%BE%D0%B8%D1%81%D0%BA%D0%B8-%D0%B8-%D0%B8%D1%81%D1%82%D0%BE%D1%80%D0%B8%D1%8F) for controls.

## Recording less [#recording-less]

```sh
max personal config set record false         # этот профиль: только неудачные запуски
max personal chats list --no-record          # этот запуск: ничего
```

The same in the settings file:

```json
{ "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 [#retention]

A failed run lasts **30 days** (`keep_runs_for_days`), a successful one **7 days** (`keep_successful_runs_for_days`), in [configuration](/llms.mdx/docs/max/configuration/content.md). 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 [#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:

```json
{ "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:

```sh
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 [#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` [#check-installation-max-personal-doctor]

```sh
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 [#problem-report]

```sh
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](https://github.com/WireCatLabs/max-cli/issues). Read the file before submitting. It has no message text; chat and message ids are replaced with labels. See [reporting a problem](/llms.mdx/docs/max/troubleshooting/content.md#%D0%BA%D0%B0%D0%BA-%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B8%D1%82%D1%8C-%D0%BE-%D0%BF%D1%80%D0%BE%D0%B1%D0%BB%D0%B5%D0%BC%D0%B5) 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 [#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:

```sh
# какие запуски закончились плохо
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 [#next-steps]

- [Errors and recovery](/llms.mdx/docs/max/troubleshooting/content.md)
- [What is saved on disk](/llms.mdx/docs/max/security/content.md)

## Search errors and partial runs [#search-errors-and-partial-runs]

```sh
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.
