MAX

Configuration — MAX

Configure MAX CLI profiles, local paths, environment variables and background-service settings.

Keep settings you would otherwise repeat on every command. This guide explains their locations and priority so you can change a value and check which setting takes effect.

Change and check settings →

Use this page when you repeatedly type the same option or want max to behave differently for one account. You will learn where the settings file lives, which basic settings to change, how to change one value and how to check the effective value. No file is needed to start: every setting has a built-in default.

Terms used below:

  • Configuration file (config.json) — the text file storing your saved choices.
  • Profile — named settings for one MAX account or bot, such as work. Put its name before the command: max work chats list. See profiles and bots.
  • Option (flag) — a word added to a command, such as --limit 5. It affects only that run.
  • Environment variable — a named value passed to max by a terminal or agent process, such as MAX_PROFILE=work.
  • Default — the value max uses when you specify no other value.

What you can configure

These settings are changed most often. The configuration reference gives each setting's exact type and all override methods.

SettingPurposeBuilt-in default
limitRows displayed without --limit20
sends_per_hourMessages a profile may send per hour; stops sending loops30; bots have no limit until set in bot
requests_per_minuteRequest rate after an initial short burst; 0 disables pacing (limits and waits)20
permissionsRead, ask before changes or act without asking (permissions)All allowed except deletion and some other irreversible changes ask first; auto-reply sending is disabled
recordSave successful runs too, not only failed ones (diagnostics)true
record_inputWhether a run record keeps the command line as you typed it; secrets are always hidden (diagnostics)true
keep_runs_for_daysDays to retain run records30
colorTable coloursBased on terminal
sender_colorsDifferent colour for each message authorfalse
timeout_msMilliseconds to wait for one MAX response; use --timeout for the whole commandTransport-dependent
serveStart background max personal serve when a command needs MAX (one shared login)true
transcribe_modelSpeech-recognition model for voice messagesgigaam-v3
update_checkReport new max versions once a daytrue

There is no place for secrets in this file: no token, phone number or chat id. Tokens use the system keyring or, if unavailable, a file only you can read (token storage).

Example configuration file

The first command that reads the settings creates an initial file; max personal doctor does not create it. Here it is with one profile added:

{
  "defaults": { "limit": 20, "keep_runs_for_days": 30, "sends_per_hour": 30, "update_check": true, "skill_hint": true },
  "profiles": {
    "work": { "limit": 50 }
  }
}
  • defaults applies to all profiles.
  • profiles.work applies only to work and overrides defaults.

Thus max work chats list shows 50 rows, while max personal chats list shows 20. Add --limit 5 for five rows in one command. Remove the profile's limit to use defaults again.

Full example with all sections
{
  "defaults": {
    "limit": 20,
    "keep_runs_for_days": 14,
    "sends_per_hour": 30,
    "requests_per_minute": 20,
    "update_check": true,
    "skill_hint": true,
    "transcribe_model": "gigaam-v3"
  },
  "profiles": {
    "personal": {
      "limit": 50,
      "color": true,
      "sender_colors": true,
      "record": true
    },
    "work": {
      "permissions": { "messages": "readonly", "messages.send": "allow" },
      "sends_per_hour": 10,
      "serve": false
    }
  },
  "personal": {
    "defaults": { "search_catch_up": true }
  },
  "bot": {
    "defaults": { "permissions": { "bot": "readonly", "bot.messages.send": "allow" } },
    "profiles": {
      "shop": { "sends_per_hour": 200, "read_other_bots": false }
    }
  }
}

What each part does:

  • defaults: every profile receives these values unless it overrides them. update_check, skill_hint and transcribe_model are allowed only here because the program and speech-recognition downloads are shared by all profiles.
  • profiles.personal: more rows, colours and recording every run, only for personal.
  • profiles.work: reading and sending messages are allowed; other message changes are denied. At most 10 sends per hour. No background server starts: each command connects to MAX itself.
  • personal.defaults: applies only to personal-account commands, never max … bot. Here messages sync also prepares downloaded chats for search.
  • bot.defaults: applies only to bot commands (max shop bot …). Bots can read and send, and do nothing else.
  • bot.profiles.shop: shop can send 200 messages per hour and cannot read other bots' saved data on this computer. read_other_bots is allowed only in bot; serve, sender_colors are not accepted there.

File location

SystemPath
Linux and macOS~/.config/max-cli/config.json
Windows%APPDATA%\max-cli\Config\config.json

max config show prints this computer's actual path and each setting with its value, where the value came from, the built-in value, and what the setting does. In PowerShell, use max.cmd instead of max. An existing file is never replaced with the initial file.

max config migrate adds to defaults every setting missing from the file, with its built-in value, so every setting is visible and editable right in the file. Your values, their order, and unknown keys stay as they are. Any write by max to the file, such as config set, does the same; config unset does not write the removed setting back.

Three ways to set a value

  • File: the value persists for future commands. max personal config set limit 50 saves it.
  • Environment variable: applies to one terminal or agent process. For example, MAX_PROFILE selects a profile and MAX_TIMEOUT limits command duration. Not every setting has a variable.
  • Option: --limit 5 affects only one command.

Which value takes precedence?

Options override environment variables, followed by the profile's file value, file defaults, then built-in defaults. Each setting supports only certain methods; the configuration reference lists them.

Change a value

Edit the file with any text editor or let max do it. config set validates before writing, so it never saves a file the next command would reject.

max personal config set limit 50                 # профилю, с которым вы работаете
max work config set limit 50            # профилю work
max config set sends_per_hour 10 --defaults   # всем профилям
max personal config unset limit                  # вернуть значение по умолчанию
max config show                         # проверить, что действует и откуда взялось каждое значение

A misspelled setting is an error rather than a silent default: every command stops and names the invalid key (file typos).

Profiles and bots

A profile stores settings for one account or bot. Put its name before the command, such as max work config show. To act as a bot, add bot after the name. Profiles and bots explains creating profiles and switching between them.

Next steps