Skip to content

Commit 156b3a1

Browse files
tars90percenttars90percent
committed
Add README with installation, usage, and command reference
1 parent b540ee4 commit 156b3a1

1 file changed

Lines changed: 295 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# minimax-cli
2+
3+
Command-line interface for the [MiniMax API Platform](https://www.minimax.io) (Token Plan).
4+
5+
```
6+
__ __ ___ _ _ ___ __ __ _ __ __
7+
| \/ |_ _| \ | |_ _| \/ | / \ \ \/ /
8+
| |\/| || || \| || || |\/| | / _ \ \ /
9+
| | | || || |\ || || | | |/ ___ \/ \
10+
|_| |_|___|_| \_|___|_| |_/_/ \_\/_/\
11+
```
12+
13+
Generate text, images, video, speech, and music from the terminal. Supports both the **Global** (`api.minimax.io`) and **CN** (`api.minimaxi.com`) platforms with automatic region detection.
14+
15+
## Installation
16+
17+
### Standalone binary (recommended)
18+
19+
```bash
20+
curl -fsSL https://raw.githubusercontent.com/MiniMax-AI-Dev/minimax-cli/main/install.sh | sh
21+
```
22+
23+
Downloads a precompiled binary to `/usr/local/bin/minimax`. No runtime required.
24+
25+
### npm (requires Node 18+)
26+
27+
```bash
28+
npm install -g minimax-cli
29+
```
30+
31+
### bun
32+
33+
```bash
34+
bun install -g minimax-cli
35+
```
36+
37+
### From source
38+
39+
```bash
40+
git clone https://github.com/MiniMax-AI-Dev/minimax-cli.git
41+
cd minimax-cli
42+
bun install
43+
bun run dev -- --help
44+
```
45+
46+
## Quick start
47+
48+
```bash
49+
# Set your API key
50+
minimax auth login --api-key sk-xxxxx
51+
52+
# The CLI auto-detects your region (global or cn) on first run
53+
54+
# Chat
55+
minimax text chat --message "user:What is MiniMax?"
56+
57+
# Generate an image
58+
minimax image generate --prompt "A cat in a spacesuit on Mars"
59+
60+
# Text-to-speech
61+
minimax speech synthesize --text "Hello, world!" --out hello.mp3
62+
63+
# Search the web
64+
minimax search query --q "latest AI news"
65+
66+
# Describe an image
67+
minimax vision describe --image photo.jpg --prompt "What is this?"
68+
```
69+
70+
## Commands
71+
72+
### text
73+
74+
```bash
75+
# Simple chat
76+
minimax text chat --message "user:Hello"
77+
78+
# With system prompt and model selection
79+
minimax text chat --model MiniMax-M2.7-highspeed \
80+
--system "You are a coding assistant." \
81+
--message "user:Write fizzbuzz in Python"
82+
83+
# Streaming (default in TTY)
84+
minimax text chat --message "user:Tell me a story" --stream
85+
86+
# Multi-turn conversation from file
87+
cat conversation.json | minimax text chat --messages-file -
88+
```
89+
90+
### speech
91+
92+
```bash
93+
# Generate speech and save to file
94+
minimax speech synthesize --text "Hello, world!" --out hello.mp3
95+
96+
# Read from file or stdin
97+
echo "Breaking news." | minimax speech synthesize --text-file - --out news.mp3
98+
99+
# Stream audio to a player
100+
minimax speech synthesize --text "Stream this" --stream | mpv --no-terminal -
101+
102+
# Custom voice and speed
103+
minimax speech synthesize --text "Fast narration" --voice English_expressive_narrator --speed 1.5 --out fast.mp3
104+
```
105+
106+
### image
107+
108+
```bash
109+
# Generate an image
110+
minimax image generate --prompt "Mountain landscape at sunset"
111+
112+
# Custom aspect ratio and batch
113+
minimax image generate --prompt "Logo design" --aspect-ratio 1:1 --n 3 --out-dir ./generated/
114+
115+
# With subject reference
116+
minimax image generate --prompt "Portrait in oil painting style" --subject-ref ./photo.jpg
117+
```
118+
119+
### video
120+
121+
```bash
122+
# Submit a video generation task
123+
minimax video generate --prompt "A man reads a book. Static shot."
124+
125+
# Wait for completion and download
126+
minimax video generate --prompt "Ocean waves at sunset." --wait --download sunset.mp4
127+
128+
# With first frame image
129+
minimax video generate --prompt "Mouse runs toward camera." --first-frame ./mouse.jpg
130+
131+
# Check task status
132+
minimax video task get --task-id 106916112212032
133+
134+
# Download a completed video
135+
minimax video download --file-id 176844028768320 --out video.mp4
136+
```
137+
138+
### music
139+
140+
```bash
141+
# Generate with custom lyrics
142+
minimax music generate --prompt "Indie folk, melancholic" --lyrics "La la la..." --out song.mp3
143+
144+
# Lyrics from file
145+
minimax music generate --prompt "Upbeat pop" --lyrics-file song.txt --out summer.mp3
146+
147+
# Auto-generated lyrics
148+
minimax music generate --prompt "Jazz lounge" --auto-lyrics --out jazz.mp3
149+
```
150+
151+
### search
152+
153+
```bash
154+
# Web search
155+
minimax search query --q "MiniMax AI"
156+
157+
# JSON output for scripting
158+
minimax search query --q "latest news" --output json
159+
```
160+
161+
### vision
162+
163+
```bash
164+
# Describe a local image
165+
minimax vision describe --image photo.jpg
166+
167+
# Describe from URL
168+
minimax vision describe --image https://example.com/photo.jpg
169+
170+
# Custom prompt
171+
minimax vision describe --image screenshot.png --prompt "Extract the text from this screenshot"
172+
```
173+
174+
### quota
175+
176+
```bash
177+
# Show usage and remaining quotas
178+
minimax quota show
179+
180+
# JSON output
181+
minimax quota show --output json
182+
```
183+
184+
### config
185+
186+
```bash
187+
# Show current configuration
188+
minimax config show
189+
190+
# Set region
191+
minimax config set --key region --value cn
192+
193+
# Set default output format
194+
minimax config set --key output --value json
195+
196+
# Set request timeout
197+
minimax config set --key timeout --value 600
198+
```
199+
200+
### auth
201+
202+
```bash
203+
# Login with API key
204+
minimax auth login --api-key sk-xxxxx
205+
206+
# Check auth status
207+
minimax auth status
208+
209+
# Logout
210+
minimax auth logout
211+
```
212+
213+
## Global flags
214+
215+
| Flag | Description |
216+
|---|---|
217+
| `--api-key <key>` | API key (overrides all other auth) |
218+
| `--region <region>` | API region: `global` (default), `cn` |
219+
| `--base-url <url>` | API base URL (overrides region) |
220+
| `--output <format>` | Output format: `text`, `json`, `yaml` |
221+
| `--quiet` | Suppress non-essential output |
222+
| `--verbose` | Print HTTP request/response details |
223+
| `--timeout <seconds>` | Request timeout (default: 300) |
224+
| `--no-color` | Disable ANSI colors and spinners |
225+
| `--yes` | Skip confirmation prompts |
226+
| `--dry-run` | Show what would happen without executing |
227+
228+
## Region auto-detection
229+
230+
On first run, the CLI probes both the Global and CN quota endpoints with your API key to determine which platform it belongs to. The detected region is cached in `~/.minimax/config.yaml` so subsequent runs are instant.
231+
232+
You can override the region at any time:
233+
234+
```bash
235+
# Per-command
236+
minimax text chat --region cn --message "user:Hello"
237+
238+
# Environment variable
239+
export MINIMAX_REGION=cn
240+
241+
# Persistent
242+
minimax config set --key region --value cn
243+
```
244+
245+
## Configuration
246+
247+
The CLI reads configuration from multiple sources, in order of precedence:
248+
249+
1. Command-line flags (`--api-key`, `--region`, etc.)
250+
2. Environment variables (`MINIMAX_API_KEY`, `MINIMAX_REGION`, `MINIMAX_BASE_URL`, `MINIMAX_OUTPUT`, `MINIMAX_TIMEOUT`)
251+
3. Config file (`~/.minimax/config.yaml`)
252+
4. Defaults
253+
254+
## Output formats
255+
256+
- **text** (default in TTY) -- human-readable tables and formatted text
257+
- **json** (default in non-TTY) -- full API response, suitable for piping to `jq`
258+
- **yaml** -- YAML serialization of the full response
259+
260+
When stdout is not a TTY (e.g., piped to another program), the output automatically switches to JSON for easy parsing.
261+
262+
## Exit codes
263+
264+
| Code | Meaning |
265+
|---|---|
266+
| 0 | Success |
267+
| 1 | General error |
268+
| 2 | Usage error (bad flags, missing arguments) |
269+
| 3 | Authentication error |
270+
| 4 | Quota exceeded |
271+
| 5 | Timeout |
272+
| 10 | Content filter triggered |
273+
274+
## Building
275+
276+
```bash
277+
# Run from source
278+
bun run dev -- <command>
279+
280+
# Type check
281+
bun run typecheck
282+
283+
# Run tests
284+
bun test
285+
286+
# Build standalone binaries for all platforms
287+
bun run build
288+
289+
# Build npm-publishable bundle
290+
bun run build:npm
291+
```
292+
293+
## License
294+
295+
MIT

0 commit comments

Comments
 (0)