Skip to content

docs: add agent skill guide, simplify README #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanlee666 merged 1 commit into from
Mar 28, 2026
Merged

docs: add agent skill guide, simplify README #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 28 additions & 190 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,229 +1,67 @@
# minimax-cli

Command-line interface for the [MiniMax Token Plan](https://platform.minimax.io/docs/token-plan/intro).
CLI for the [MiniMax AI Platform](https://platform.minimax.io) — generate text, images, video, speech, and music from the terminal.

```
__ __ ___ _ _ ___ __ __ _ __ __
| \/ |_ _| \ | |_ _| \/ | / \ \ \/ /
| |\/| || || \| || || |\/| | / _ \ \ /
| | | || || |\ || || | | |/ ___ \/ \
|_| |_|___|_| \_|___|_| |_/_/ \_\_/\
```

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.

## What's New (v0.3.0)
Supports **Global** (`api.minimax.io`) and **CN** (`api.minimaxi.com`) with automatic region detection.

**`minimax config export-schema`** — export all commands as Anthropic/OpenAI-compatible JSON tool schemas with a single command:

```bash
minimax config export-schema | jq .
minimax config export-schema --command "video generate" | jq .
```

See [Changelog](#changelog) for full version history.

## Installation

### Standalone binary (recommended)
## Install

```bash
curl -fsSL https://raw.githubusercontent.com/MiniMax-AI-Dev/minimax-cli/main/install.sh | sh
```

### npm
Or via npm / bun:

```bash
npm install -g minimax-cli
```

### bun

```bash
bun install -g minimax-cli
```

### From source

```bash
git clone https://github.com/MiniMax-AI-Dev/minimax-cli.git && cd minimax-cli
bun install
bun run dev -- --help
```

## Quick start
## Quick Start

```bash
minimax auth login --api-key sk-xxxxx
minimax text chat --message "user:What is MiniMax?"
minimax image generate --prompt "A cat in a spacesuit on Mars"
minimax text chat --message "What is MiniMax?"
minimax image generate --prompt "A cat in a spacesuit"
minimax video generate --prompt "Ocean waves at sunset"
minimax speech synthesize --text "Hello!" --out hello.mp3
minimax music generate --prompt "Indie folk" --lyrics "La la la..."
minimax vision describe --image photo.jpg
```

## Agent & CI usage

```bash
# Async: get task ID immediately, no blocking
minimax video generate --prompt "A robot." --async --quiet
# → {"taskId":"..."}

# Pipe-friendly: stdout is pure data, stderr is progress
minimax text chat --message "Hi" | jq .

# CI: missing args fail fast with clear errors
minimax image generate --non-interactive
# → Error: Missing required argument: --prompt
minimax search query --q "MiniMax AI latest news"
```

## Commands

| Command | Description |
|---|---|
| `text chat` | Send a chat completion |
| `speech synthesize` | Text-to-speech, up to 10k chars |
| `image generate` | Generate images |
| `video generate` | Generate a video (auto-downloads on completion) |
| `video task get` | Query video task status |
| `video download` | Download a completed video |
| `music generate` | Generate a song |
| `text chat` | Chat completion (MiniMax-M2.7) |
| `image generate` | Image generation (image-01) |
| `video generate` | Video generation (Hailuo-2.3) |
| `speech synthesize` | Text-to-speech (speech-2.8-hd) |
| `music generate` | Music generation (music-2.5) |
| `vision describe` | Image understanding (VLM) |
| `search query` | Web search |
| `vision describe` | Describe an image (supports `--file-id` to skip base64) |
| `quota show` | Show usage quotas |
| `quota show` | Usage quotas |
| `config show / set` | Configuration |
| `config export-schema` | Export tool schemas as JSON |
| `config show` / `config set` | View or update configuration |
| `auth login/status/refresh/logout` | Authentication |
| `update` | Self-update |

All commands accept [global flags](#global-flags).

## Examples

```bash
# Text chat
minimax text chat --message "user:Write fizzbuzz"
minimax text chat --message "Hi" --stream

# Image generation
minimax image generate --prompt "Sunset over ocean" --aspect-ratio 16:9 --n 3

# Vision (path/URL or pre-uploaded file ID)
minimax vision describe --image photo.jpg --prompt "What breed is this?"
minimax vision describe --file-id file-123 --prompt "Extract the text"
Run `minimax <command> --help` for full options.

# Video (auto-downloads to ~/.minimax-video/ on completion)
minimax video generate --prompt "A man reads a book."
minimax video generate --prompt "A robot." --async --quiet
## Agent / CI Usage

# Speech synthesis
minimax speech synthesize --text "Hello world!" --out hello.mp3
minimax speech synthesize --text "Breaking news." --text-file - --stream | mpv -

# Music generation
minimax music generate --prompt "Indie folk" --lyrics "La la la..." --out song.mp3

# Web search
minimax search query --q "MiniMax AI latest news"

# Export Agent tool schemas
minimax config export-schema | jq .
minimax config export-schema --command "video generate" | jq .

# Auth
minimax auth login --api-key sk-xxxxx
minimax auth status
```

## Global flags

| Flag | Description |
|---|---|
| `--api-key <key>` | API key (overrides all other auth) |
| `--region <region>` | `global` (default) or `cn` |
| `--base-url <url>` | Override API base URL |
| `--output <format>` | `text`, `json`, or `yaml` |
| `--quiet` | Suppress non-essential output to stderr |
| `--verbose` | Print HTTP request/response details |
| `--timeout <seconds>` | Request timeout (default: 300) |
| `--no-color` | Disable ANSI colors and spinners |
| `--yes` | Skip confirmation prompts |
| `--dry-run` | Show what would happen without executing |
| `--non-interactive` | Disable interactive prompts (CI/agent use) |
| `--async` | Return task ID immediately without polling |
| `--version` / `--help` | Version and help |

## Output philosophy

- `stdout` → result data only (text, file paths, JSON)
- `stderr` → spinners, region detection, help text, warnings, verbose logs

```bash
# stdout is clean JSON — pipe to jq safely
minimax text chat --message "Hi" | jq .

# stderr shows spinner without polluting the pipe
minimax video generate --prompt "Ocean waves." 2>/dev/null
```

## Configuration

Precedence (highest to lowest): CLI flags → env vars → `~/.minimax/config.yaml` → defaults.

```bash
minimax config set --key region --value cn
export MINIMAX_REGION=cn
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad flags, missing arguments) |
| 3 | Authentication error |
| 4 | Quota exceeded |
| 5 | Timeout |
| 10 | Content filter triggered |

## Building
See [skill/SKILL.md](skill/SKILL.md) for the complete agent integration guide, including all command signatures, tool schema export, and piping patterns.

```bash
bun run dev -- <command> # Run from source
bun run typecheck # Type check
bun test # Run tests
bun run build # Build standalone binaries
minimax video generate --prompt "A robot." --async --quiet # non-blocking
minimax text chat --message "Hi" --output json | jq . # pipe-friendly
minimax config export-schema | jq . # tool schemas
```

## Changelog

### v0.4.0 — File Management API (🧊 Shelved)

> **🧊 Shelved:** File API returned HTTP 404 with current API key. This feature is temporarily hidden until the endpoint permissions are officially opened.
> - `minimax file upload` — upload local file, get `file_id`
> - `minimax file list` — formatted table of uploaded files
> - `minimax file delete` — remove file by ID
> - `vision describe --file-id` — use pre-uploaded file instead of base64

### v0.3.0 — Agent Tool Schema Auto-Generation

- `OptionDef` interface extended with optional `type` and `required` fields
- New `CommandRegistry.getAllCommands()` traversal method
- `src/utils/schema.ts`: parses `--flag <value>` strings into Anthropic/OpenAI-compatible tool schemas
- New command: `minimax config export-schema` — exports all tool schemas as clean JSON to stdout
- Core commands marked `required: true`: `image generate --prompt`, `text chat --message`, `video generate --prompt`, `vision describe --image`

### v0.2.0 — Agent & CI Compatibility

- `src/utils/env.ts`: `isInteractive()` and `isCI()` helpers
- `--non-interactive`: forces non-interactive mode regardless of TTY state
- `--async`: immediate task-ID return without blocking poll
- All help routes to stderr (not stdout) — `--help | jq` works cleanly
- Streaming: thinking blocks go to stderr in non-TTY mode; final text always to stdout
- Interactive fallback: missing args prompt in TTY, fail fast in CI/agent mode

### v0.1.0 — Initial release
## Output Philosophy

Text chat with streaming · Image generation with batch and subject reference · Video generation with polling and download · Music generation with lyrics · Speech synthesis with voice customization · Web search · Image understanding · OAuth and API key authentication · Automatic region detection (global vs CN) · YAML/JSON/text output formats
- `stdout` → data only (text, paths, JSON)
- `stderr` → spinners, warnings, help

## License

Expand Down
Loading
Loading