Setup and maintenance
Login, profiles, configuration, the background server, the local store, diagnostics, agent connection and updates.
This reference covers setup and maintenance commands. Use it to look up login, profiles, configuration, the background server, the local store, diagnostics and agent connection.
Login, profiles, configuration, the background server, the local store, diagnostics, agent connection and updates.
Global options
Apply to every command.
Commands
max session
the stored MAX session for this profile
max session start
log this profile in to MAX
max session start [method]| Argument | Requirement | Meaning |
|---|---|---|
method | optional | token (pasted or piped), qr, qr-chrome or sms. One of: token, qr, qr-chrome, sms. Default: token. |
max session end
log this profile out on MAX's side and forget the session here
Changes something in MAX.
max session endmax setup
set up your personal MAX account and connect your agent
Changes something in MAX.
max setup [options]| Option | Purpose |
|---|---|
--agent <agent> | install the skill for this agent; asks at a terminal, otherwise none. One of: none, codex, cursor, claude, gemini, all. |
--method <method> | how to log in when there is no session. One of: token, qr, qr-chrome, sms. Default: qr. |
max account
the logged-in account
max account list
every profile on this computer, and the account each is logged in as; asks the messenger nothing
max account listmax account show
who this profile is logged in as; the phone number shows its last four digits
max account show [options]| Option | Purpose |
|---|---|
--show-phone | print the whole phone number. |
max account update
change the name, the description or the photo everyone sees on your profile
Changes something in MAX.
max account update [options]| Option | Purpose |
|---|---|
--first-name <name> | your first name. |
--last-name <name> | your last name. |
--description <text> | about you. |
--photo <file> | a new profile photo — an image file. |
max account sessions
where else this account is logged in — not max session, which is this tool's own login
max account sessions list
every device and app logged in to this account; nothing is ended
max account sessions listmax account sessions end
log out every other device, your phone included; this one stays
Changes something in MAX.
max account sessions end [options]| Option | Purpose |
|---|---|
--others | every session but this one. |
max account privacy
who may find, call or add the account
max account privacy show
the account's privacy settings; reading changes nothing
max account privacy showmax account privacy set
change who may find, call or add the account; the settings not named stay
Changes something in MAX.
max account privacy set [options]| Option | Purpose |
|---|---|
--find-by-phone <who> | who finds the account by its number: everyone, contacts or nobody. |
--phone-number <who> | who sees the number: everyone, contacts or nobody. |
--calls <who> | who may call: everyone, contacts or nobody. |
--chat-invites <who> | who may add the account to groups and channels: everyone, contacts or nobody. |
--hide-online <on|off> | hide online status and last seen. |
max store
the local store of messages
max store status
per chat: messages stored, the oldest and newest, and the stretches held completely
max store status [chat]| Argument | Requirement | Meaning |
|---|---|---|
chat | optional | a chat: its id, or part of its title. |
max store gaps
inspect recorded interior coverage gaps and explicitly fetch them
max store gaps plan
local coverage plan; missing message ids alone do not imply missing history
max store gaps plan <chat>| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
max store gaps repair
fetch bounded interior gaps and recheck coverage; never delete unseen messages
max store gaps repair <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--limit <n> | total messages in this repair, 500 by default. |
--max-gaps <n> | at most this many gaps, 5 by default. |
--repair-time <duration> | time budget for the repair, 30s by default. Default: 30s. |
--page-size <n> | messages per provider page. |
--pause <duration> | provider pause between pages. Default: 5s. |
--fingerprint <hash> | refuse if this previously inspected coverage plan changed. |
--catch-up | prepare local search after repair; overrides searchCatchUp. |
--no-catch-up | skip local search preparation after repair. |
--catch-up-chunks <n> | maximum local chunks prepared. |
--catch-up-messages <n> | maximum stored messages read for preparation. |
--catch-up-time <duration> | preparation time within the repair's remaining budget. |
--background | repair as an existing store job; inspect store jobs show. |
max store jobs
background sync jobs
max store jobs list
background sync jobs, newest first
max store jobs list [options]| Option | Purpose |
|---|---|
--state <state> | only jobs in this state. One of: running, done, partial, failed, cancelled, died. |
max store jobs show
one background job — the newest when none is named — and what the store now holds of its chat
max store jobs show [job]max store jobs cancel
stop a running background job after its current page; a later sync resumes where it stopped
max store jobs cancel <job>| Argument | Requirement | Meaning |
|---|---|---|
job | required | the job id. |
max store jobs retry
start a partial, failed or died job again, as a new job; the sync resumes where the store stopped
max store jobs retry [job] [options]| Argument | Requirement | Meaning |
|---|---|---|
job | optional | the job id. |
| Option | Purpose |
|---|---|
--failed | every chat whose newest job partial, failed or died. |
max store jobs clear
forget finished jobs and remove their logs; a running job is kept
Changes something on this computer only.
max store jobs clearmax store export
a chat's stored messages, oldest first: --jsonl one message per line, --json one { items, page, limit, hasMore } object; never asks the messenger
max store export [chats] [options]| Option | Purpose |
|---|---|
--format <format> | jsonl: one message per line, the default with --output; markdown: a transcript with a heading per day, replies and forwards quoted. |
--since-time <time> | only from this ISO 8601 time, or 30m / 2h / 1d ago, on. |
--output <file> | write JSON lines, or the transcript, to this new file, readable only by you. |
--to <dir> | write into this folder, a file per chat and a manifest; run again on it for only what changed since. |
--kind <kinds> | with --to: every stored chat of these kinds, comma-separated: dialog, group, channel, saved. |
--all | with --to: every stored chat of this account. |
--encrypt | compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened. |
max store clear
delete from the store the chats this account has left, with their messages
max store clear [options]| Option | Purpose |
|---|---|
--left | the chats this account has left — the only thing this clears. |
--allow-dangerous | yes, delete — it cannot be undone, and a chat you left cannot be fetched again. |
max store info
the store file: where it is, its size, its schema and how many rows it holds; changes nothing
max store infomax store check
whether the store is healthy — integrity, search indexes, disk, and which chats are behind
max store checkmax store migrate
bring the store up to this build's schema, then normalize, index and stem the messages and notes stored before it
max store migratemax store reindex
rebuild the word index, its typo vocabulary, the stems, the files' word index, the notes' indexes and who took part in what, from what is stored; loses nothing
max store reindexmax store backup
copy the store into a new file, while it is in use; never overwrites a file
max store backup <file> [options]| Argument | Requirement | Meaning |
|---|---|---|
file | required | the new file. |
| Option | Purpose |
|---|---|
--encrypt | compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened. |
max store restore
put a backup in place of the store; the store it replaces is kept beside it, never deleted
max store restore <file>| Argument | Requirement | Meaning |
|---|---|---|
file | required | a file store backup wrote; one written with --encrypt asks for its password. |
max store decrypt
open a file written with --encrypt into a new file; asks for its password
max store decrypt <file> [options]| Argument | Requirement | Meaning |
|---|---|---|
file | required | a file store backup --encrypt or store export --encrypt wrote. |
| Option | Purpose |
|---|---|
--output <file> | the new file, readable only by you. |
max store repair
bring every table to this build's shape, deleting nothing: a table of the wrong shape is kept as a copy beside a new one
max store repair [options]| Option | Purpose |
|---|---|
--dry-run | say what it would do, and change nothing. |
max store reset
back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes
max store reset [options]| Option | What it does |
|---|---|
--no-backup | delete the store without backing it up first. |
max store copies
the tables store repair kept as copies
max store copies delete
delete one copy store repair kept, named exactly; refuses any other table
max store copies delete <name>max flood
the waits MAX asked this profile to keep, and a hold on its writes
max flood clear
forget them, lift the hold and the profile's pace, once MAX no longer limits the account; changes nothing there
max flood clearmax models
models that run on this machine
max models audio
speech models for transcribing voice messages
max models audio list
the speech models, most suitable first, which are downloaded, and which one is the default
max models audio listmax models audio download
download a speech model once, checked against the sha256 this version expects
max models audio download <model>max models text
embedding models for searching conversations by meaning
max models text list
the embedding models, most suitable first, which are downloaded, and which one is the default
max models text listmax models text download
download an embedding model once, checked against the sha256 this version expects
max models text download <model> [options]| Option | Purpose |
|---|---|
--accept-terms | accept the model's licence terms, for a model that has its own. |
max models text key
API keys for embedding and analysis providers
max models text key set
store a key, typed at a hidden prompt or piped on stdin — never as an argument
max models text key set <provider>| Argument | Requirement | Meaning |
|---|---|---|
provider | required | openai, anthropic, or the host of a --base-url server that wants a key. |
max models text key remove
forget a stored key
max models text key remove <provider>| Argument | Requirement | Meaning |
|---|---|---|
provider | required | openai, anthropic, or a server's host. |
max serve
stay connected to MAX and stream new messages to max watch, until Ctrl-C
max serve [options]| Option | Purpose |
|---|---|
--idle <duration> | stop after this long with nobody using it — 15m, 1h is 60m. |
max server
max serve in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit
max server start
start serve in the background — through the unit if one is installed — and answer once it connects
max server start [options]| Option | Purpose |
|---|---|
--idle <duration> | stop after this long with nobody using it — 15m, 1h. |
max server stop
stop this profile's serve — through the unit if it runs under one
max server stopmax server restart
stop it and start it again
max server restart [options]| Option | Purpose |
|---|---|
--idle <duration> | stop after this long with nobody using it — 15m, 1h. |
max server status
whether serve runs for this profile, since when, who started it, and the unit if there is one
max server statusmax server logs
serve's latest log lines — from the journal under systemd, else its log file
max server logs [options]| Option | Purpose |
|---|---|
-n, --lines <n> | how many lines. Default: 50. |
max server install
write a systemd user unit or a launchd agent for this profile; starts nothing
max server installmax server uninstall
remove this profile's unit; stop it first
max server uninstallmax watch
print new messages as they arrive, from a running max serve
max watch [options]| Option | Purpose |
|---|---|
--events | also print edits, deletions, reactions, reads and chat changes; every line then names its event. |
max config
the settings in force, and where each one came from
max config show
the profile, the profiles that exist, and each setting with where it came from
max config show [options]| Option | Purpose |
|---|---|
--bot | the settings a bot command on this profile gets, rather than the personal account's. |
max config migrate
replace legacy access settings with permissions, preserving effective levels
Changes something on this computer only.
max config migrate [options]| Option | Purpose |
|---|---|
--dry-run | show the migration without writing the file. |
max config set
save a setting to the configuration file
Changes something on this computer only.
max config set <setting> <value> [options]| Argument | Requirement | Meaning |
|---|---|---|
setting | required | one of: limit, timeoutMs, color, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, senderColors, catchUpMarksRead, searchCatchUp, serve, mcpTools, readOtherBots, updateCheck, skillHint, transcribeModel, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin. |
value | required | a number, true or false, or for allow a list like send,reaction. |
| Option | Purpose |
|---|---|
--defaults | change what every profile gets, rather than this profile. |
--personal | only for personal accounts — the personal section of the file. |
--bot | only for bots — the bot section of the file. |
max config unset
remove a setting from the configuration file
Changes something on this computer only.
max config unset <setting> [options]| Argument | Requirement | Meaning |
|---|---|---|
setting | required | one of: limit, timeoutMs, color, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, senderColors, catchUpMarksRead, searchCatchUp, serve, mcpTools, readOtherBots, updateCheck, skillHint, transcribeModel, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin. |
| Option | Purpose |
|---|---|
--defaults | change what every profile gets, rather than this profile. |
--personal | only for personal accounts — the personal section of the file. |
--bot | only for bots — the bot section of the file. |
max doctor
the state this installation is in, without contacting MAX unless --online
max doctor [options]| Option | Purpose |
|---|---|
--online | also log in once, read one chat and start the MCP server; sends nothing. |
max doctor report
what a problem report holds and where it goes; writes nothing
max doctor report create
write a problem report to a file, and print how to send it
max doctor report create [options]| Option | Purpose |
|---|---|
--run <id> | the run the report is about; the newest failed one if not given. |
--output <file> | where to write it; a new file in this directory if not given. |
max runs
recorded runs — what this tool did, and when
max runs list
recorded runs, newest first
max runs list [options]| Option | Purpose |
|---|---|
--limit <n> | how many to show. Default: 20. |
max runs show
one run: what it was, how it ended and what went wrong; -v for every event
max runs show <run-id>max runs search
search recorded diagnostic metadata and events; no message contents
max runs search [query] [options]| Argument | Requirement | What it is |
|---|---|---|
query | optional | case-insensitive literal diagnostic text. |
| Option | What it does |
|---|---|
--status <status> | run outcome. One of: success, failed, partial, running. |
--error-code <code> | one stable error code. |
--operation <name> | one operation, such as messages.download. |
--profile <name> | one recorded profile. |
--since-time <time> | runs starting on or after an ISO time or 2h / 1d ago. |
--limit <n> | matches per page, at most 100. Default: 20. |
--page <n> | result page. Default: 1. |
max runs path
the directory holding one run
max runs path <run-id>max skill
the instructions an agent is given for this tool
max skill show
print SKILL.md — max skill install puts it where Claude Code, Codex and Gemini CLI look for it
max skill show [name]| Argument | Requirement | Meaning |
|---|---|---|
name | optional | one of the skills shipped for a task: follow-ups, link-conversations. |
max skill install
write SKILL.md to ~/.claude/skills/max-cli/ (Claude Code) and ~/.agents/skills/max-cli/ (Codex, Gemini CLI)
max skill install [options]| Option | Purpose |
|---|---|
--for <agents> | which agents to install for. One of: claude, agents, all. Default: all. |
max commands
commands, options and exit codes as JSON — inspect one command path per call
max commands schema
one command's argv and result schemas, effects, permissions and retry guidance
max commands schema <path>| Argument | Requirement | Meaning |
|---|---|---|
path | required | one command path, for example: stats messages show. |
max upgrade
upgrade max with the package manager that installed it; --check only looks
max upgrade [options]| Option | Purpose |
|---|---|
--check | say whether a newer version exists, and install nothing. |
max complete
shell completion: max complete zsh prints the script to source
max complete [words]| Argument | Requirement | Meaning |
|---|---|---|
words | optional |
max mcp
serve this profile to an agent over MCP, on stdin and stdout — claude mcp add max -- max mcp
max mcp [options]| Option | Purpose |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | deprecated: use permissions.messages.send in config; does not grant access. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-mark-read | deprecated: use permissions.chats.mark-read in config; does not grant access. |
--allow-delete | deprecated: use permissions.messages.delete in config; does not grant access. |
--allow-moderate | deprecated: use permissions.chats.moderate and group rules; does not grant access. |
--http | serve over HTTP on 127.0.0.1 for ChatGPT and Claude in the browser, behind your tunnel; the profile's permissions decide. |
--http-confirmation <mode> | no longer used — writes show no form; the profile's permissions decide. |
--port <port> | the local port for --http (default 8765). |
--public-url <url> | the tunnel's https address the browser apps use, e.g. https://.ts.net. |
--revoke | forget every login given to a browser app; each must log in again. |
max mcp config
print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing
max mcp config [options]| Option | Purpose |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | deprecated: use permissions.messages.send in config; does not grant access. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-mark-read | deprecated: use permissions.chats.mark-read in config; does not grant access. |
--allow-delete | deprecated: use permissions.messages.delete in config; does not grant access. |
--allow-moderate | deprecated: use permissions.chats.moderate and group rules; does not grant access. |
max mcp setup
add this profile's local MCP server to Codex or Claude Code
Changes something on this computer only.
max mcp setup <client> [options]| Argument | Requirement | Meaning |
|---|---|---|
client | required | codex or claude-code. |
| Option | Purpose |
|---|---|
--allow-writes | acknowledge that this profile offers writing tools. |
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | deprecated: use permissions.messages.send in config; does not grant access. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-mark-read | deprecated: use permissions.chats.mark-read in config; does not grant access. |
--allow-delete | deprecated: use permissions.messages.delete in config; does not grant access. |
--allow-moderate | deprecated: use permissions.chats.moderate and group rules; does not grant access. |
max mcp doctor
check this profile's local MCP handshake and tool list
max mcp doctor [options]| Option | Purpose |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | deprecated: use permissions.messages.send in config; does not grant access. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-mark-read | deprecated: use permissions.chats.mark-read in config; does not grant access. |
--allow-delete | deprecated: use permissions.messages.delete in config; does not grant access. |
--allow-moderate | deprecated: use permissions.chats.moderate and group rules; does not grant access. |
Exit codes
Scripts should branch on the code, not the message: wording may change, codes remain stable.
| Code | Meaning |
|---|---|
0 | Success |
2 | validation_error |
3 | configuration_error |
4 | authentication_error |
5 | permission_error |
6 | not_found |
7 | confirmation_required |
8 | rate_limited |
9 | timeout |
10 | network_error |
11 | provider_error |
12 | provider_unavailable |
13 | invalid_response |
14 | outcome_unknown |
130 | cancelled |
1 | Any other error |
0, and only 0, means the operation succeeded. 14 — outcome_unknown — means the message may have been sent: its outcome is neither confirmed nor failed. Retry only with the same --send-id.