Skip to content
Back to search

cli

Generate text, images, video, speech, and music by MiniMax.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/minimax-ai--cli/badge.svg)](/listings/minimax-ai--cli)

HTML

<a href="/listings/minimax-ai--cli"><img src="/api/listings/minimax-ai--cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# For AI agents (OpenClaw, Cursor, Claude Code, etc.): add skill to your agent
npx skills add MiniMax-AI/cli -y -g

# Or install CLI globally for terminal use
npm install -g mmx-cli

> Requires [Node.js](https://nodejs.org) 18+

> **Requires a MiniMax Token Plan** — [Global](https://platform.minimax.io/subscribe/token-plan) · [CN](https://platform.minimaxi.com/subscribe/token-plan)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 249 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img src="https://file.cdn.minimax.io/public/MMX-capabilities.png" alt="MiniMax" width="100%" />
  2. <p align="center">
  3. <strong>The official CLI for the MiniMax AI Platform</strong><br>
  4. Built for AI agents. Generate text, images, video, and speech — from any agent or terminal.
  5. </p>
  6. <p align="center">
  7. <a href="https://www.npmjs.com/package/mmx-cli"><img src="https://img.shields.io/npm/v/mmx-cli.svg" alt="npm version" /></a>
  8. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
  9. <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js >= 18" /></a>
  10. </p>
  11. <p align="center">
  12. <a href="README_CN.md">中文文档</a> · <a href="https://platform.minimax.io">Global Platform</a> · <a href="https://platform.minimaxi.com">CN Platform</a> · <a href="https://platform.minimax.io/docs/token-plan/minimax-cli">Example</a>
  13. </p>
  14. ## Features
  15. - **Text** — Multi-turn chat, streaming, system prompts, JSON output
  16. - **Image** — Text-to-image with aspect ratio and batch controls
  17. - **Video** — Async video generation with progress tracking
  18. - **Speech** — TTS with 30+ voices, speed control, streaming playback; speech-to-text transcription (json, verbose_json, srt, vtt)
  19. - **Vision** — Image understanding and description
  20. - **Search** — Web search powered by MiniMax
  21. - **Dual Region** — Seamless Global (`api.minimax.io`) and CN (`api.minimaxi.com`) support
  22. <img src="https://file.cdn.minimax.io/public/MMX-CLI-help.png" alt="MiniMax" width="100%" />
  23. ## Install
  24. ```bash
  25. # For AI agents (OpenClaw, Cursor, Claude Code, etc.): add skill to your agent
  26. npx skills add MiniMax-AI/cli -y -g
  27. # Or install CLI globally for terminal use
  28. npm install -g mmx-cli
  29. ```
  30. > Requires [Node.js](https://nodejs.org) 18+
  31. > **Requires a MiniMax Token Plan** — [Global](https://platform.minimax.io/subscribe/token-plan) · [CN](https://platform.minimaxi.com/subscribe/token-plan)
  32. ## Quick Start
  33. ```bash
  34. # Authenticate (interactive — choose MiniMax OAuth or paste an API key)
  35. mmx auth login
  36. # Or non-interactive
  37. mmx auth login --api-key sk-xxxxx
  38. # Start creating
  39. mmx text chat --message "What is MiniMax?"
  40. mmx image "A cat in a spacesuit"
  41. mmx speech synthesize --text "Hello!" --out hello.mp3
  42. mmx speech transcribe --file meeting.mp3
  43. mmx video generate --prompt "Ocean waves at sunset"
  44. mmx search "MiniMax AI latest news"
  45. mmx vision photo.jpg
  46. mmx quota
  47. ```
  48. ## Releasing
  49. Maintainers publish releases by pushing a SemVer Git tag; the release workflow
  50. derives the npm package version from that tag. See [the release guide](docs/releasing.md).
  51. ## Commands
  52. ### `mmx text`
  53. `text chat` and `text repl` default to `MiniMax-M3.1-Flash`. An explicit `--model` or saved `default-text-model` takes precedence. It is available with Token Plan, MiniMax Code, and pay-as-you-go keys. See the [model guide](https://platform.minimax.io/docs/guides/text-generation#agent).
  54. ```bash
  55. mmx text chat --message "Write a poem"
  56. mmx text chat --model MiniMax-M3.1-Flash --message "Hello" --stream
  57. mmx text chat --system "You are a coding assistant" --message "Fizzbuzz in Go"
  58. mmx text chat --message "user:Hi" --message "assistant:Hey!" --message "How are you?"
  59. cat messages.json | mmx text chat --messages-file - --output json
  60. ```
  61. ### `mmx image`
  62. ```bash
  63. mmx image "A cat in a spacesuit"
  64. mmx image generate --prompt "A cat" --n 3 --aspect-ratio 16:9
  65. mmx image generate --prompt "Logo" --out-dir ./out/
  66. # MiniMax-H3-Image text-to-image
  67. mmx image generate --model MiniMax-H3-Image --prompt "An orange cat basking on a windowsill, warm afternoon light, film look" --aspect-ratio 16:9 --area 2K
  68. mmx image generate --model MiniMax-H3-Image --prompt "Minimal poster" --size 2720x1536 --output-format png --n 2
  69. # MiniMax-H3-Image image editing (1-16 reference images, numbered Picture 1, 2, ... in order)
  70. mmx image generate --model MiniMax-H3-Image --prompt "Replace the cat in Picture 1 with the Shiba Inu in Picture 2, keep the background" --image cat.jpg --image https://example.com/dog.png
  71. ```
  72. Without `--image`, MiniMax-H3-Image calls `/v1/images/generations` (text-to-image); with `--image` it calls `/v1/images/edits` (image editing). Choose one way to set the output size: `--size WIDTHxHEIGHT` (area 655,360–20,000,000 px, aspect ratio 1:3–3:1), or `--aspect-ratio` plus `--area 1K|2K|4K` (default 4K). `--no-prompt-enhance` turns off prompt enhancement for text-to-image and then requires `--size` or a concrete `--aspect-ratio`. A failed image (for example one that fails the content safety check) does not stop the others; files keep their original position in the name and failures are reported on stderr (even with `--quiet`). With `--response-format base64`, the total output area (`n` × width × height) is limited to 20,000,000 px for png and 80,000,000 px for jpg/webp; with `size auto` each image counts as its `--area` level (4K = 4096 × 4096). Requests over the limit are rejected locally.
  73. The H3-Image endpoints are not idempotent, so a retry after a timeout generates and bills again. The CLI never retries them automatically and raises the timeout for these requests to at least 600 seconds, matching the server. `--seed`, `--prompt-optimizer`, and `--subject-ref` apply only to image-01.
  74. ### `mmx video`
  75. ```bash
  76. # Hailuo-2.3 (Video Generation V1)
  77. mmx video generate --prompt "Ocean waves at sunset" --download sunset.mp4
  78. mmx video generate --prompt "A robot painting" --async
  79. # MiniMax-H3 (Video Generation V2)
  80. mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "Ocean waves at sunset"
  81. mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "The subject walks forward" --image start.jpg
  82. mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "Keep the same character" --reference-image character.png --reference-video motion.mp4
  83. mmx video task get --task-id 123456
  84. mmx video task get --task-id 424010985738629 --model MiniMax-H3
  85. mmx video download --file-id 176844028768320 --out video.mp4
  86. ```
  87. For 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.
  88. `--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. Use `--resolution 768P` for 768P output.
  89. ### `mmx speech`
  90. ```bash
  91. mmx speech synthesize --text "Hello!" --out hello.mp3
  92. mmx speech synthesize --text "Stream me" --stream | mpv -
  93. mmx speech synthesize --text "Hi" --voice English_magnetic_voiced_man --speed 1.2
  94. echo "Breaking news" | mmx speech synthesize --text-file - --out news.mp3
  95. mmx speech voices
  96. ```
  97. ```bash
  98. # Speech-to-text (asr-1.0)
  99. mmx speech transcribe --file meeting.mp3
  100. mmx speech transcribe --file call.mp3 --language zh
  101. mmx speech transcribe --file talk.mp3 --response-format verbose_json --output json
  102. mmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt
  103. mmx speech transcribe --file long.mp3 --stream
  104. ```
  105. `mmx speech transcribe` accepts wav, aiff, flac, m4a, mp3, aac, opus, and ogg files up to
  106. 50 MB and 500 seconds. Audio above 50 MB is rejected locally before upload; the 500 second
  107. limit is enforced by the API. Omitting `--language` enables mixed-language recognition.
  108. `--response-format json` (default) prints the transcript, `verbose_json` adds speakers and
  109. per-segment timestamps, and `srt` / `vtt` return subtitle documents. `n_speakers` and
  110. `segments` are part of the response, so pass `--output json` to see them. `--stream` prints
  111. incremental text and requires `json`; when stdout is not a terminal it accumulates into a single
  112. JSON result unless `--output text` is passed. `mmx speech recognize` is an alias for
  113. `mmx speech transcribe`.
  114. ### `mmx vision`
  115. ```bash
  116. mmx vision photo.jpg
  117. mmx vision describe --image https://example.com/img.jpg --prompt "What breed?"
  118. mmx vision describe --file-id file-123
  119. ```
  120. ### `mmx search`
  121. ```bash
  122. mmx search "MiniMax AI"
  123. mmx search query --q "latest news" --output json
  124. ```
  125. > 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.
  126. ### `mmx auth`
  127. ```bash
  128. mmx auth login # interactive: pick OAuth (Global / China) or paste an API key
  129. mmx auth login --api-key sk-xxxxx # save an API key directly
  130. mmx auth login --recommend # skip the menu, pick OAuth region interactively
  131. mmx auth login --recommend --region=global # OAuth → api.minimax.io
  132. mmx auth login --recommend --region=cn # OAuth → api.minimaxi.com
  133. mmx auth status
  134. mmx auth refresh
  135. mmx auth logout
  136. ```
  137. `mmx auth status` is the canonical way to verify active authentication.
  138. **OAuth** uses the [Device Authorization Grant (RFC 8628)](https://tools.ietf.org/html/rfc8628) with PKCE —
  139. the CLI opens your browser, you enter a code, and `access_token` + `refresh_token`
  140. are saved to `~/.mmx/config.json`. Tokens refresh automatically (5-min buffer);
  141. manual refresh via `mmx auth refresh`.
  142. **API key** auth auto-detects the correct region by probing both Global and CN.
  143. Useful for CI/CD (`mmx auth login --api-key sk-xxxxx`), or pass per-command via `--api-key`.
  144. OAuth and API key are mutually exclusive — logging in with one clears the other.
  145. Credential priority: `--api-key` flag > OAuth (config) > `api_key` (config).
  146. ### Environment variables
  147. | Variable | Description |
  148. |---|---|
  149. | `MINIMAX_REGION` | `global` or `cn`. |
  150. | `MINIMAX_BASE_URL` | Override the API base URL. |
  151. | `MINIMAX_OUTPUT` | `text` or `json`. |
  152. | `MINIMAX_TIMEOUT` | Request timeout in seconds. |
  153. | `MINIMAX_VERBOSE` | `1` to enable verbose HTTP logging. |
  154. | `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. |
  155. ### `mmx config` · `mmx quota`
  156. ```bash
  157. mmx quota
  158. mmx config show
  159. mmx config set --key region --value cn
  160. mmx config set --key default-text-model --value MiniMax-M3.1-Flash
  161. mmx config export-schema | jq .
  162. ```
  163. ### `mmx agent setup`
  164. Configure MiniMax for Claude Code, Codex, Grok Build, OpenCode, Hermes, Pi, [Oh my Pi](https://github.com/can1357/oh-my-pi), or Zed while preserving unrelated settings. Run without options for the interactive wizard; supplying options makes the command non-interactive and suitable for scripts.
  165. ```bash
  166. mmx agent setup
  167. mmx agent setup --agent codex --agent claude-code --api-key "$MINIMAX_API_KEY" --region global
  168. mmx agent setup --all --api-key "$MINIMAX_API_KEY" --region cn --output json
  169. mmx agent setup --agent oh-my-pi --api-key "$MINIMAX_API_KEY" --region global
  170. # --agent omp is an alias for --agent oh-my-pi
  171. ```
  172. `agent setup` defaults to `MiniMax-M3.1-Flash` for both Token Plan and pay-as-you-go keys (`sk-api-...`). In non-interactive mode, `--model` overrides this selection.
  173. The 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.
  174. Oh 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.
  175. ### `mmx update`
  176. ```bash
  177. mmx update
  178. mmx update latest
  179. ```
  180. ## Thanks to
  181. <a href="https://github.com/MiniMax-AI/cli/graphs/contributors">
  182. <img src="https://contrib.rocks/image?repo=MiniMax-AI/cli" />
  183. </a>
  184. ## License
  185. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.