Configuration reference

A complete list of keys, default values, scopes and environment variables. For everyday setup, start with the guide; see the CLI contract for execution and output rules.

No configuration is required. Without a file or environment variables, built-in defaults apply. A configuration file is useful when you want to stop repeating the same flag.

Setting precedenceCopy Anchor Link

Flag → environment variable → file → built-in default. This precedence is shared across the entire program, so commands cannot interpret it differently.

Within the file, the most specific entry wins. For a personal-account command using work: personal.profiles.work → profiles.work → personal.defaults → defaults. For max work bot …, the same order applies with bot replacing personal. A profile-specific entry takes precedence over a section-wide entry.

max chats list --limit 5          # флаг: 5
MAX_PROFILE=personal max chats list   # переменная выбирает профиль
# "limit": 50 у профиля в файле — когда флага нет
# "limit": 30 в "defaults" — когда и у профиля нет
# 20 — когда нет ничего

Two explicit exceptions take precedence over this order:

• MAX_TOKEN takes precedence over the keychain. If set, it is used instead, as in CI.
• MAX_CONFIG_DIR, MAX_STATE_DIR relocate max settings and login state, including the keychain entry associated with a profile.

Current effective settingsCopy Anchor Link

max config show            # профиль, какие профили есть, файл и каждая настройка
max work config show       # то же для профиля work
max config show --json     # то же одним объектом

Each setting shows its source: flag, default or config file: with its key, such as config file: bot.profiles.test. The profile source is first word, MAX_PROFILE, MAX_PROFILE_LOCK, config file: defaultProfile or default.

With --json, the response also includes storeSettings: shared archive settings (searchStemmers.*) and their origin, store or default.

max test config show --bot shows settings as max test bot … will receive them: bots have their own section and sending limit. If the file is absent, loading configuration creates it with ordinary defaults. An existing file is not overwritten. If a MAX_*_DIR variable is set, the command reports it on stderr: those variables give the profile a different keyring entry, so a login performed without them looks like “no session”.

Output contains no secrets: the configuration file has no fields in which to store them.

Access permissionsCopy Anchor Link

deny blocks reading and writing; readonly allows reading; ask requires confirmation; allow performs an action without asking. In a terminal, ask shows a prompt defaulting to “no”. JSON mode has no prompt: use --yes, or --allow-dangerous for message deletion. MCP has no confirmation forms: ask permits an invoked write, while deny and readonly still block it. --permission ключ=уровень temporarily overrides process permissions. Older confirmation flags no longer determine access; in the CLI, ask levels still require a response or explicit flag. See MCP for connection details.

A more specific key overrides its resource. This example allows reading messages and deleting them without confirmation, while forbidding other message writes:

{ "profiles": { "work": { "permissions": { "messages": "readonly", "messages.delete": "allow" } } } }

This example does not restrict contacts, chats, reactions or other resources. Bot keys start with bot, such as bot.messages.send. config show reports effective permissions and their source. config set rejects an unknown command key with code 2, including inside a whole permissions object. config unset lets you remove an old unknown key. Reading an existing file with such a key prints a warning on stderr and continues.

Permissions from different sections of the file add up, but the nearest section decides first, then the key length. A key set on a profile overrides the same key and all keys under it in personal.defaults and defaults. Here, the agent profile does not delete messages: its messages overrides messages.delete from defaults.

{
  "defaults": { "permissions": { "messages.delete": "allow" } },
  "profiles": { "agent": { "permissions": { "messages": "readonly" } } }
}

This works both ways: messages: allow on a profile also overrides messages.delete: deny from defaults, and then deletion asks again, as by default. Legacy readOnly and allow apply in the section where they are written.

Preview the changes before converting an older file:

max config migrate --dry-run
max config migrate

Migration preserves effective permissions, MAX settings and moderation checkpoints. Legacy rule levels forbid/flag/confirm become deny/ask/ask. --dry-run writes nothing. Once permissions exists, attempts to change readOnly, allow or mcpTools are refused with guidance for the replacement setting. MAX_PROFILE_LOCK forbids migrating the entire file; preview remains available.

Configuration fileCopy Anchor Link

~/.config/max-cli/config.json, permissions 0644. It is written by max config set below, or edited manually.

{
  "defaultProfile": "personal",
  "defaults": { "keepRunsForDays": 14 },
  "profiles": {
    "personal": { "limit": 50, "timeoutMs": 20000, "color": true },
    "work": { "limit": 10 }
  },
  "personal": {
    "defaults": { "sendsPerHour": 30 }
  },
  "bot": {
    "defaults": { "permissions": { "bot": "readonly", "bot.messages.send": "allow" } },
    "profiles": { "shop": { "sendsPerHour": 200 } }
  }
}

• defaults — all profiles, both personal accounts and bots.
• profiles.<имя> — one profile, regardless of role.
• personal.defaults, personal.profiles.<имя> — personal-account commands only.
• bot.defaults, bot.profiles.<имя> — max <имя> bot … commands only.

⚠ timeoutMs and --timeout are different. timeoutMs is the wait for one MAX response. --timeout limits the whole command. A read involves connecting, INIT, LOGIN, resolving a chat name and the request itself, so its total time can be several times timeoutMs.

Their formats deliberately differ: timeoutMs is a number of milliseconds in the file; --timeout is a command-line duration with a unit (30s, 2m, 500ms). A unit is required: --timeout 30 is rejected because confusing seconds with the nearby milliseconds field could cause a thirtyfold error either way.

There is no file setting for --timeout: a command budget belongs to a specific run, rather than a lasting preference.

--page and --all deliberately have no file settings. A saved page number is useful once, then disrupts later runs. The same applies to --order for max contacts list: contactOrder would duplicate the same option. --limit has a setting because how much to show is a lasting preference.

Secrets cannot go in this file. The schema has no token, phone-number or chat-ID field. A schema without a place for secrets is stronger than an instruction not to put them there.

Changing settings without opening the fileCopy Anchor Link

max config set limit 50                 # профилю по умолчанию
max work config set record true         # профилю work
max config set keepRunsForDays 7 --defaults   # всем профилям сразу
max work config unset limit             # убрать; снова решает defaults или встроенное
max agent config set permissions.messages readonly  # чтение сообщений без записи
max shop config set --bot sendsPerHour 200    # только боту shop
max config set --personal --defaults limit 30 # всем личным аккаунтам
max config set defaultProfile work      # какой профиль без первого слова

Values are checked with the same schema used for reading, before writing: max config set limit 0 is refused and the file stays unchanged. serve, senderColors, catchUpMarksRead, searchCatchUp and mcpTools are not accepted with --bot: bots have no server, sender colors or unread state, and legacy mcpTools applies only to personal accounts.

searchStemmers.cyrillic (russian or none) and searchStemmers.latin (spanish, english or none) are stored in the shared message archive, not the configuration file: they apply to every profile and both messengers. They therefore reject --defaults, --personal and --bot, and cannot be changed under MAX_PROFILE_LOCK. config unset restores the built-in value. After changing them, run max store reindex — see Archive maintenance.

Typos are errors, not ignored settingsCopy Anchor Link

An unknown field is rejected by name with configuration_error (exit code 3):

{"error":{"code":"configuration_error","message":"/home/you/.config/max-cli/config.json is not a valid config:\n  profiles.default.limitt: unknown setting — the known ones are limit, timeoutMs, color, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, senderColors, serve, mcpTools"}}

An incorrect type names the field and accepted value: profiles.default.limit: has to be a whole number, 1 or more, not "20".

This is intentional. Silently discarding an unknown field turns a typo into hours spent wondering why a setting has no effect.

A missing file is not an error: it means the program has not been configured.

Inspecting the resultCopy Anchor Link

Settings have several layers, so the file alone may not tell you which one won. This command explains directly:

max config show
max config show --json

It prints the chosen profile and its source, the configuration path and whether it exists, available profiles and all effective settings with their individual sources.

⚠ The profile list includes all profiles on this machine: those named in configuration, logged in as personal accounts, or configured as bots. Each is identified as personal, bot or both.

⚠ This is not a health check. It reads files without opening the cache, accessing the keyring or contacting MAX. Checking whether a session is valid requires a login and belongs to another command.

Environment variablesCopy Anchor Link

An empty string counts as unset: MAX_PROFILE= is equivalent to not setting MAX_PROFILE.

Only profile and timeout have environment-variable equivalents. These are process-wide choices. There will be no variable for --json or color: forgetting one in a shell would change output for commands that never requested it, making diagnosis harder than simply supplying a flag.

Temporary separate configurationCopy Anchor Link

Directory variables give you separate settings and login state, useful for experiments, a second account or tests. They do not change the shared message store used by tg: MESSAGING_STORE selects that separate file. Speech models remain shared.

export MAX_CONFIG_DIR=/tmp/max-try/config
export MAX_STATE_DIR=/tmp/max-try/state
export MESSAGING_STORE=/tmp/max-try/messages.db

max setup            # этот токен не виден обычной установке
max chats list

⚠ The reverse is also true: the normal installation cannot see this session. An hour was once lost to “no session” despite a valid token because variables remained set in one terminal window but not another.

Next stepsCopy Anchor Link

• Command reference — all commands, options and exit codes.
• Sessions and profiles — profiles and token storage.
• Troubleshooting — resolving problems.

MAX_CACHE_DIR now applies only to the old cache: max doctor looks there for a remaining file. For compatibility, this variable still changes the keychain entry. Use MESSAGING_STORE for the new shared store.

Embedding and analysis settings are independent and may differ by profile. MAX_EMBEDDING_PROVIDER, MAX_EMBEDDING_MODEL, MAX_EMBEDDING_BASE_URL, MAX_EMBEDDING_DIMS, MAX_ANALYSIS_PROVIDER, MAX_ANALYSIS_MODEL and MAX_ANALYSIS_BASE_URL override configuration; flags override settings. The URL must be HTTP/S with no embedded password, query or fragment. An external embedding service also receives questions from MCP search. Keys are set through models text key set openai|anthropic and are not written to config.json. An ordinary build does not run external analysis: explicit --analyze is required.

Key types and scopesCopy Anchor Link

The “profile” scope includes defaults, profiles.<имя>, personal.defaults, personal.profiles.<имя>, bot.defaults and bot.profiles.<имя>, unless a row restricts it. Unknown keys and incorrectly typed values are rejected. Default values are listed above.

Models by taskCopy Anchor Link

models.<назначение> contains only provider, model and baseUrl. Task names use lowercase Latin letters, digits and hyphens, starting with a letter. default defines shared values; analysis and replies override them field by field. Other valid names can be saved in advance; this does not enable an unimplemented use case. With no provider or with off, external calls are disabled.

For each field, precedence is MAX_MODELS_<НАЗНАЧЕНИЕ>_PROVIDER, _MODEL or _BASE_URL, then the most specific file entry for the task, then explicit legacy analysis* fields for analysis, then models.default variables and entries. Hyphens in a task name become _ in its environment variable. Provider tokens are not part of this object.

Model configuration variablesCopy Anchor Link

The seven legacy fields support MAX_EMBEDDING_PROVIDER, MAX_EMBEDDING_MODEL, MAX_EMBEDDING_BASE_URL, MAX_EMBEDDING_DIMS, MAX_ANALYSIS_PROVIDER, MAX_ANALYSIS_MODEL and MAX_ANALYSIS_BASE_URL. They take precedence over file values. MAX_MODELS_DEFAULT_PROVIDER, MAX_MODELS_DEFAULT_MODEL and MAX_MODELS_DEFAULT_BASE_URL set shared fields in the new format; replace DEFAULT with a task such as ANALYSIS. Empty variables do not override settings. Invalid values return configuration_error.