![\"npm](\"https://img.shields.io/npm/v/mmx-cli.svg\")
\n ![\"License:](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"Node.js](\"https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg\"){kind=icon}
= 18\" />\n![\"MiniMax\"](\"https://file.cdn.minimax.io/public/MMX-capabilities.png\")
\n\n\n The official CLI for the MiniMax AI Platform
\n Built for AI agents. Generate text, images, video, and speech — from any agent or terminal.\n
\n \n \n = 18\" />\n
\n 中文文档 · Global Platform · CN Platform · Example\n
\n\n## Features\n\n- **Text** — Multi-turn chat, streaming, system prompts, JSON output\n- **Image** — Text-to-image with aspect ratio and batch controls\n- **Video** — Async video generation with progress tracking\n- **Speech** — TTS with 30+ voices, speed control, streaming playback; speech-to-text transcription (json, verbose_json, srt, vtt)\n- **Vision** — Image understanding and description\n- **Search** — Web search powered by MiniMax\n- **Dual Region** — Seamless Global (`api.minimax.io`) and CN (`api.minimaxi.com`) support\n\n![\"MiniMax\"](\"https://file.cdn.minimax.io/public/MMX-CLI-help.png\")
\n\n## Install\n\n```bash\n# For AI agents (OpenClaw, Cursor, Claude Code, etc.): add skill to your agent\nnpx skills add MiniMax-AI/cli -y -g\n\n# Or install CLI globally for terminal use\nnpm install -g mmx-cli\n```\n\n> Requires [Node.js](https://nodejs.org) 18+\n\n> **Requires a MiniMax Token Plan** — [Global](https://platform.minimax.io/subscribe/token-plan) · [CN](https://platform.minimaxi.com/subscribe/token-plan)\n\n## Quick Start\n\n```bash\n# Authenticate (interactive — choose MiniMax OAuth or paste an API key)\nmmx auth login\n\n# Or non-interactive\nmmx auth login --api-key sk-xxxxx\n\n# Start creating\nmmx text chat --message \"What is MiniMax?\"\nmmx image \"A cat in a spacesuit\"\nmmx speech synthesize --text \"Hello!\" --out hello.mp3\nmmx speech transcribe --file meeting.mp3\nmmx video generate --prompt \"Ocean waves at sunset\"\nmmx search \"MiniMax AI latest news\"\nmmx vision photo.jpg\nmmx quota\n```\n\n## Releasing\n\nMaintainers publish releases by pushing a SemVer Git tag; the release workflow\nderives the npm package version from that tag. See [the release guide](docs/releasing.md).\n\n## Commands\n\n### `mmx text`\n\n`text chat` and `text repl` default to `MiniMax-M3.1-Flash-Preview`. An explicit `--model` or saved `default-text-model` takes precedence. This preview currently requires M Plan or MiniMax Code; with a pay-as-you-go key, select `MiniMax-M3` explicitly. See the [model guide](https://platform.minimax.io/docs/guides/text-generation#agent).\n\n```bash\nmmx text chat --message \"Write a poem\"\nmmx text chat --model MiniMax-M3.1-Flash-Preview --message \"Hello\" --stream\nmmx text chat --system \"You are a coding assistant\" --message \"Fizzbuzz in Go\"\nmmx text chat --message \"user:Hi\" --message \"assistant:Hey!\" --message \"How are you?\"\ncat messages.json | mmx text chat --messages-file - --output json\n```\n\n### `mmx image`\n\n```bash\nmmx image \"A cat in a spacesuit\"\nmmx image generate --prompt \"A cat\" --n 3 --aspect-ratio 16:9\nmmx image generate --prompt \"Logo\" --out-dir ./out/\n```\n\n### `mmx video`\n\n```bash\n# Hailuo-2.3 (Video Generation V1)\nmmx video generate --prompt \"Ocean waves at sunset\" --download sunset.mp4\nmmx video generate --prompt \"A robot painting\" --async\n\n# MiniMax-H3 (Video Generation V2)\nmmx video generate --api-key \"$MINIMAX_API_KEY\" --model MiniMax-H3 --prompt \"Ocean waves at sunset\"\nmmx video generate --api-key \"$MINIMAX_API_KEY\" --model MiniMax-H3 --prompt \"The subject walks forward\" --image start.jpg\nmmx video generate --api-key \"$MINIMAX_API_KEY\" --model MiniMax-H3 --prompt \"Keep the same character\" --reference-image character.png --reference-video motion.mp4\n\nmmx video task get --task-id 123456\nmmx video task get --task-id 424010985738629 --model MiniMax-H3\nmmx video download --file-id 176844028768320 --out video.mp4\n```\n\nFor MiniMax-H3, local files and Base64 data URIs are preflight-checked against the documented limits: image 30 MB, reference video 50 MB, reference audio 15 MB, and total JSON request body 64 MB. The API validates dimensions, aspect ratio, duration, frame rate, and codecs for all media.\n\n`--region` is an existing global CLI option, not an H3 parameter. Normal video generation does not need it; the CLI uses the saved or automatically detected region. H3 defaults to 2K, 5 seconds, and 16:9 for text-to-video.\n\n### `mmx speech`\n\n```bash\nmmx speech synthesize --text \"Hello!\" --out hello.mp3\nmmx speech synthesize --text \"Stream me\" --stream | mpv -\nmmx speech synthesize --text \"Hi\" --voice English_magnetic_voiced_man --speed 1.2\necho \"Breaking news\" | mmx speech synthesize --text-file - --out news.mp3\nmmx speech voices\n```\n\n```bash\n# Speech-to-text (asr-1.0)\nmmx speech transcribe --file meeting.mp3\nmmx speech transcribe --file call.mp3 --language zh\nmmx speech transcribe --file talk.mp3 --response-format verbose_json --output json\nmmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt\nmmx speech transcribe --file long.mp3 --stream\n```\n\n`mmx speech transcribe` accepts wav, aiff, flac, m4a, mp3, aac, opus, and ogg files up to\n50 MB and 500 seconds. Audio above 50 MB is rejected locally before upload; the 500 second\nlimit is enforced by the API. Omitting `--language` enables mixed-language recognition.\n`--response-format json` (default) prints the transcript, `verbose_json` adds speakers and\nper-segment timestamps, and `srt` / `vtt` return subtitle documents. `n_speakers` and\n`segments` are part of the response, so pass `--output json` to see them. `--stream` prints\nincremental text and requires `json`; when stdout is not a terminal it accumulates into a single\nJSON result unless `--output text` is passed. `mmx speech recognize` is an alias for\n`mmx speech transcribe`.\n\n### `mmx vision`\n\n```bash\nmmx vision photo.jpg\nmmx vision describe --image https://example.com/img.jpg --prompt \"What breed?\"\nmmx vision describe --file-id file-123\n```\n\n### `mmx search`\n\n```bash\nmmx search \"MiniMax AI\"\nmmx search query --q \"latest news\" --output json\n```\n\n> The `/v1/coding_plan/search` API returns at most 10 results per call and does not currently expose a pagination parameter (see #107). Refine your query if you need different results.\n\n### `mmx auth`\n\n```bash\nmmx auth login # interactive: pick OAuth (Global / China) or paste an API key\nmmx auth login --api-key sk-xxxxx # save an API key directly\nmmx auth login --recommend # skip the menu, pick OAuth region interactively\nmmx auth login --recommend --region=global # OAuth → api.minimax.io\nmmx auth login --recommend --region=cn # OAuth → api.minimaxi.com\nmmx auth status\nmmx auth refresh\nmmx auth logout\n```\n\n`mmx auth status` is the canonical way to verify active authentication.\n\n**OAuth** uses the [Device Authorization Grant (RFC 8628)](https://tools.ietf.org/html/rfc8628) with PKCE —\nthe CLI opens your browser, you enter a code, and `access_token` + `refresh_token`\nare saved to `~/.mmx/config.json`. Tokens refresh automatically (5-min buffer);\nmanual refresh via `mmx auth refresh`.\n\n**API key** auth auto-detects the correct region by probing both Global and CN.\nUseful for CI/CD (`mmx auth login --api-key sk-xxxxx`), or pass per-command via `--api-key`.\n\nOAuth and API key are mutually exclusive — logging in with one clears the other.\nCredential priority: `--api-key` flag > OAuth (config) > `api_key` (config).\n\n### Environment variables\n\n| Variable | Description |\n|---|---|\n| `MINIMAX_REGION` | `global` or `cn`. |\n| `MINIMAX_BASE_URL` | Override the API base URL. |\n| `MINIMAX_OUTPUT` | `text` or `json`. |\n| `MINIMAX_TIMEOUT` | Request timeout in seconds. |\n| `MINIMAX_VERBOSE` | `1` to enable verbose HTTP logging. |\n| `MMX_CONFIG_DIR` | Directory containing the `config.json` file (default: `~/.mmx`). Set this when `mmx` runs from a subprocess, service, or CI job whose home directory differs from where you logged in. |\n\n### `mmx config` · `mmx quota`\n\n```bash\nmmx quota\nmmx config show\nmmx config set --key region --value cn\nmmx config set --key default-text-model --value MiniMax-M3.1-Flash-Preview\nmmx config export-schema | jq .\n```\n\n### `mmx agent setup`\n\nConfigure MiniMax for Claude Code, Codex, Grok Build, OpenCode, Hermes, Pi, or [Oh my Pi](https://github.com/can1357/oh-my-pi) while preserving unrelated settings. Run without options for the interactive wizard; supplying options makes the command non-interactive and suitable for scripts.\n\n```bash\nmmx agent setup\nmmx agent setup --agent codex --agent claude-code --api-key \"$MINIMAX_API_KEY\" --region global\nmmx agent setup --all --api-key \"$MINIMAX_API_KEY\" --region cn --output json\nmmx agent setup --agent oh-my-pi --api-key \"$MINIMAX_API_KEY\" --region global\n# --agent omp is an alias for --agent oh-my-pi\n```\n\n`agent setup` defaults to `MiniMax-M3.1-Flash-Preview` for subscription keys and to `MiniMax-M3` for pay-as-you-go keys (`sk-api-...`). In non-interactive mode, `--model` overrides this selection.\n\nThe command verifies the key and selected region before writing. Existing files are backed up when changed; use `--dry-run` to preview without a live request. In the interactive wizard, compatible agents that are missing from `PATH` can be installed from a second multi-select list using their official packages or installer scripts. The Hermes install uses its official core CLI stages and skips optional system packages, Node workspace, browser, computer-use, setup, and gateway stages. After installation, mmx applies the MiniMax configuration while preserving installer settings. Agents that fail a platform or prerequisite check are explained and left configuration-only. Non-interactive invocations remain configuration-only, and the command never launches an agent.\n\nOh my Pi uses its native `~/.omp/agent/models.yml` and `config.yml` (existing `.yaml` files are updated in place). Configuration honors `OMP_PROFILE` / `PI_PROFILE`, `PI_CONFIG_DIR`, and the default-profile `PI_CODING_AGENT_DIR` override. Run `omp` once to migrate legacy JSON-only configuration before using setup. Interactive installation uses the official prebuilt-binary installer, so it does not require Bun or npm.\n\n### `mmx update`\n\n```bash\nmmx update\nmmx update latest\n```\n\n## Thanks to\n\n\n