From 6e68ca0b56cb8a8e46b6eae70a9f08c13744768f Mon Sep 17 00:00:00 2001 From: yuanhe Date: Sat, 28 Mar 2026 12:09:15 +0800 Subject: [PATCH] docs: add agent skill guide, simplify README Co-Authored-By: Claude Opus 4.6 --- README.md | 218 +++++---------------------------- skill/SKILL.md | 325 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 353 insertions(+), 190 deletions(-) create mode 100644 skill/SKILL.md diff --git a/README.md b/README.md index 9ffdbc6..0b3d434 100644 --- a/README.md +++ b/README.md @@ -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 --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 ` | API key (overrides all other auth) | -| `--region ` | `global` (default) or `cn` | -| `--base-url ` | Override API base URL | -| `--output ` | `text`, `json`, or `yaml` | -| `--quiet` | Suppress non-essential output to stderr | -| `--verbose` | Print HTTP request/response details | -| `--timeout ` | 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 -- # 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 ` 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 diff --git a/skill/SKILL.md b/skill/SKILL.md new file mode 100644 index 0000000..ec5a79d --- /dev/null +++ b/skill/SKILL.md @@ -0,0 +1,325 @@ +# MiniMax CLI — Agent Skill Guide + +Use `minimax` to generate text, images, video, speech, music, and perform web search via the MiniMax AI platform. + +## Prerequisites + +```bash +# Auth (persisted to ~/.minimax/credentials.yaml) +minimax auth login --api-key sk-xxxxx + +# Or pass per-call +minimax text chat --api-key sk-xxxxx --message "Hello" +``` + +Region is auto-detected. Override with `--region global` or `--region cn`. + +--- + +## Agent Flags + +Always use these flags in non-interactive (agent/CI) contexts: + +| Flag | Purpose | +|---|---| +| `--non-interactive` | Fail fast on missing args instead of prompting | +| `--quiet` | Suppress spinners/progress; stdout is pure data | +| `--output json` | Machine-readable JSON output | +| `--async` | Return task ID immediately (video generation) | +| `--dry-run` | Preview the API request without executing | +| `--yes` | Skip confirmation prompts | + +--- + +## Commands + +### text chat + +Chat completion. Default model: `MiniMax-M2.7`. + +```bash +minimax text chat --message [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--message ` | string, **required**, repeatable | Message text. Prefix with `role:` to set role (e.g. `"system:You are helpful"`, `"user:Hello"`) | +| `--messages-file ` | string | JSON file with messages array. Use `-` for stdin | +| `--system ` | string | System prompt | +| `--model ` | string | Model ID (default: `MiniMax-M2.7`) | +| `--max-tokens ` | number | Max tokens (default: 4096) | +| `--temperature ` | number | Sampling temperature (0.0, 1.0] | +| `--top-p ` | number | Nucleus sampling threshold | +| `--stream` | boolean | Stream tokens (default: on in TTY) | +| `--tool ` | string, repeatable | Tool definition JSON or file path | + +```bash +# Single message +minimax text chat --message "user:What is MiniMax?" --output json --quiet + +# Multi-turn +minimax text chat \ + --system "You are a coding assistant." \ + --message "user:Write fizzbuzz in Python" \ + --output json + +# From file +cat conversation.json | minimax text chat --messages-file - --output json +``` + +**stdout**: response text (text mode) or full response object (json mode). + +--- + +### image generate + +Generate images. Model: `image-01`. + +```bash +minimax image generate --prompt [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--prompt ` | string, **required** | Image description | +| `--aspect-ratio ` | string | e.g. `16:9`, `1:1` | +| `--n ` | number | Number of images (default: 1) | +| `--subject-ref ` | string | Subject reference: `type=character,image=path-or-url` | +| `--out-dir ` | string | Download images to directory | +| `--out-prefix ` | string | Filename prefix (default: `image`) | + +```bash +minimax image generate --prompt "A cat in a spacesuit" --output json --quiet +# stdout: image URLs (one per line in quiet mode) + +minimax image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet +# stdout: saved file paths (one per line) +``` + +--- + +### video generate + +Generate video. Default model: `MiniMax-Hailuo-2.3`. This is an async task — by default it polls until completion. + +```bash +minimax video generate --prompt [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--prompt ` | string, **required** | Video description | +| `--model ` | string | `MiniMax-Hailuo-2.3` (default) or `MiniMax-Hailuo-2.3-Fast` | +| `--first-frame ` | string | First frame image | +| `--callback-url ` | string | Webhook URL for completion | +| `--download ` | string | Save video to specific file | +| `--async` | boolean | Return task ID immediately | +| `--no-wait` | boolean | Same as `--async` | +| `--poll-interval ` | number | Polling interval (default: 5) | + +```bash +# Non-blocking: get task ID +minimax video generate --prompt "A robot." --async --quiet +# stdout: {"taskId":"..."} + +# Blocking: wait and get file path +minimax video generate --prompt "Ocean waves." --download ocean.mp4 --quiet +# stdout: ocean.mp4 +``` + +### video task get + +Query status of a video generation task. + +```bash +minimax video task get --task-id [--output json] +``` + +### video download + +Download a completed video by task ID. + +```bash +minimax video download --task-id [--out ] +``` + +--- + +### speech synthesize + +Text-to-speech. Default model: `speech-2.8-hd`. Max 10k chars. + +```bash +minimax speech synthesize --text [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--text ` | string | Text to synthesize | +| `--text-file ` | string | Read text from file. Use `-` for stdin | +| `--model ` | string | `speech-2.8-hd` (default), `speech-2.6`, `speech-02` | +| `--voice ` | string | Voice ID (default: `English_expressive_narrator`) | +| `--speed ` | number | Speed multiplier | +| `--volume ` | number | Volume level | +| `--pitch ` | number | Pitch adjustment | +| `--format ` | string | Audio format (default: `mp3`) | +| `--sample-rate ` | number | Sample rate (default: 32000) | +| `--bitrate ` | number | Bitrate (default: 128000) | +| `--channels ` | number | Audio channels (default: 1) | +| `--language ` | string | Language boost | +| `--subtitles` | boolean | Include subtitle timing data | +| `--pronunciation ` | string, repeatable | Custom pronunciation | +| `--sound-effect ` | string | Add sound effect | +| `--out ` | string | Save audio to file | +| `--stream` | boolean | Stream raw audio to stdout | + +```bash +minimax speech synthesize --text "Hello world" --out hello.mp3 --quiet +# stdout: hello.mp3 + +echo "Breaking news." | minimax speech synthesize --text-file - --out news.mp3 +``` + +--- + +### music generate + +Generate music. Model: `music-2.5`. + +```bash +minimax music generate --prompt [--lyrics ] [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--prompt ` | string | Music style description | +| `--lyrics ` | string | Song lyrics | +| `--lyrics-file ` | string | Read lyrics from file. Use `-` for stdin | +| `--format ` | string | Audio format (default: `mp3`) | +| `--sample-rate ` | number | Sample rate (default: 44100) | +| `--bitrate ` | number | Bitrate (default: 256000) | +| `--out ` | string | Save audio to file | +| `--stream` | boolean | Stream raw audio to stdout | + +At least one of `--prompt` or `--lyrics` is required. + +```bash +minimax music generate --prompt "Upbeat pop" --lyrics "La la la..." --out song.mp3 --quiet +``` + +--- + +### vision describe + +Image understanding via VLM. Provide either `--image` or `--file-id`, not both. + +```bash +minimax vision describe (--image | --file-id ) [flags] +``` + +| Flag | Type | Description | +|---|---|---| +| `--image ` | string | Local path or URL (auto base64-encoded) | +| `--file-id ` | string | Pre-uploaded file ID (skips base64) | +| `--prompt ` | string | Question about the image (default: `"Describe the image."`) | + +```bash +minimax vision describe --image photo.jpg --prompt "What breed?" --output json +``` + +**stdout**: description text (text mode) or full response (json mode). + +--- + +### search query + +Web search via MiniMax. + +```bash +minimax search query --q +``` + +| Flag | Type | Description | +|---|---|---| +| `--q ` | string, **required** | Search query | + +```bash +minimax search query --q "MiniMax AI" --output json --quiet +``` + +--- + +### quota show + +Display Token Plan usage and remaining quotas. + +```bash +minimax quota show [--output json] +``` + +--- + +## Tool Schema Export + +Export all commands as Anthropic/OpenAI-compatible JSON tool schemas: + +```bash +# All tool-worthy commands (excludes auth/config/update) +minimax config export-schema + +# Single command +minimax config export-schema --command "video generate" +``` + +Use this to dynamically register minimax commands as tools in your agent framework. + +--- + +## Exit Codes + +| Code | Meaning | +|---|---| +| 0 | Success | +| 1 | General error | +| 2 | Usage error (bad flags, missing args) | +| 3 | Authentication error | +| 4 | Quota exceeded | +| 5 | Timeout | +| 10 | Content filter triggered | + +--- + +## Piping Patterns + +```bash +# stdout is always clean data — safe to pipe +minimax text chat --message "Hi" --output json | jq '.content' + +# stderr has progress/spinners — discard if needed +minimax video generate --prompt "Waves" 2>/dev/null + +# Chain: generate image → describe it +URL=$(minimax image generate --prompt "A sunset" --quiet) +minimax vision describe --image "$URL" --quiet + +# Async video workflow +TASK=$(minimax video generate --prompt "A robot" --async --quiet | jq -r '.taskId') +minimax video task get --task-id "$TASK" --output json +minimax video download --task-id "$TASK" --out robot.mp4 +``` + +--- + +## Configuration Precedence + +CLI flags → environment variables → `~/.minimax/config.yaml` → defaults. + +```bash +# Persistent config +minimax config set --key region --value cn +minimax config show + +# Environment +export MINIMAX_API_KEY=sk-xxxxx +export MINIMAX_REGION=cn +```