Add command-specific options to --help, fix auth precedence, improve error hints

- Add Options section to each command's --help output listing all flags
  with descriptions and defaults
- Add Getting Help section to root help page
- Add command reference table with flags to README
- Reorder credential resolution: flag > OAuth > config.yaml > env var
- Show minimum plan required in model access and quota errors
- Region-aware upgrade URL in error hints (minimax.io vs minimaxi.com)

Author: tars90percent

README.md

@@ -69,7 +69,32 @@ minimax vision describe --image photo.jpg --prompt "What is this?"
 
 ## Commands
 
-### text
+Run `minimax <command> --help` to see the full list of options, defaults, and usage examples for any command.
+
+| Command | Description | Command-specific flags |
+|---|---|---|
+| `auth login` | Authenticate via OAuth or API key | `--method`, `--api-key`, `--no-browser` |
+| `auth status` | Show current authentication state | — |
+| `auth refresh` | Manually refresh OAuth token | — |
+| `auth logout` | Revoke tokens and clear stored credentials | — |
+| `text chat` | Send a chat completion | `--model`, `--message`, `--messages-file`, `--system`, `--max-tokens`, `--temperature`, `--top-p`, `--stream`, `--tool` |
+| `speech synthesize` | Synchronous TTS, up to 10k chars | `--model`, `--text`, `--text-file`, `--voice`, `--speed`, `--volume`, `--pitch`, `--format`, `--sample-rate`, `--bitrate`, `--channels`, `--language`, `--subtitles`, `--pronunciation`, `--sound-effect`, `--out`, `--out-format`, `--stream` |
+| `image generate` | Generate images | `--prompt`, `--aspect-ratio`, `--n`, `--subject-ref`, `--out-dir`, `--out-prefix` |
+| `video generate` | Create a video generation task | `--model`, `--prompt`, `--first-frame`, `--callback-url`, `--wait`, `--poll-interval`, `--download` |
+| `video task get` | Query video task status | `--task-id` |
+| `video download` | Download a completed video by file ID | `--file-id`, `--out` |
+| `music generate` | Generate a song | `--prompt`, `--lyrics`, `--lyrics-file`, `--auto-lyrics`, `--format`, `--sample-rate`, `--bitrate`, `--stream`, `--out`, `--out-format` |
+| `search query` | Search the web via MiniMax | `--q` |
+| `vision describe` | Describe an image using MiniMax VLM | `--image`, `--prompt` |
+| `quota show` | Display Token Plan usage and remaining quotas | — |
+| `config show` | Show current configuration | — |
+| `config set` | Set a config value | `--key`, `--value` |
+
+All commands also accept [global flags](#global-flags) (`--api-key`, `--output`, `--quiet`, `--verbose`, etc.).
+
+### Examples
+
+#### text
 
 ```bash
 # Simple chat
@@ -87,7 +112,7 @@ minimax text chat --message "user:Tell me a story" --stream
 cat conversation.json | minimax text chat --messages-file -
 ```
 
-### speech
+#### speech
 
 ```bash
 # Generate speech and save to file
@@ -103,7 +128,7 @@ minimax speech synthesize --text "Stream this" --stream | mpv --no-terminal -
 minimax speech synthesize --text "Fast narration" --voice English_expressive_narrator --speed 1.5 --out fast.mp3
 ```
 
-### image
+#### image
 
 ```bash
 # Generate an image
@@ -116,7 +141,7 @@ minimax image generate --prompt "Logo design" --aspect-ratio 1:1 --n 3 --out-dir
 minimax image generate --prompt "Portrait in oil painting style" --subject-ref ./photo.jpg
 ```
 
-### video
+#### video
 
 ```bash
 # Submit a video generation task
@@ -135,7 +160,7 @@ minimax video task get --task-id 106916112212032
 minimax video download --file-id 176844028768320 --out video.mp4
 ```
 
-### music
+#### music
 
 ```bash
 # Generate with custom lyrics
@@ -148,7 +173,7 @@ minimax music generate --prompt "Upbeat pop" --lyrics-file song.txt --out summer
 minimax music generate --prompt "Jazz lounge" --auto-lyrics --out jazz.mp3
 ```
 
-### search
+#### search
 
 ```bash
 # Web search
@@ -158,7 +183,7 @@ minimax search query --q "MiniMax AI"
 minimax search query --q "latest news" --output json
 ```
 
-### vision
+#### vision
 
 ```bash
 # Describe a local image
@@ -171,7 +196,7 @@ minimax vision describe --image https://example.com/photo.jpg
 minimax vision describe --image screenshot.png --prompt "Extract the text from this screenshot"
 ```
 
-### quota
+#### quota
 
 ```bash
 # Show usage and remaining quotas
@@ -181,7 +206,7 @@ minimax quota show
 minimax quota show --output json
 ```
 
-### config
+#### config
 
 ```bash
 # Show current configuration
@@ -197,7 +222,7 @@ minimax config set --key output --value json
 minimax config set --key timeout --value 600
 ```
 
-### auth
+#### auth
 
 ```bash
 # Login with API key

src/auth/resolver.ts

@@ -6,10 +6,9 @@ import { CLIError } from '../errors/base';
 import { ExitCode } from '../errors/codes';
 
 export async function resolveCredential(config: Config): Promise<ResolvedCredential> {
-  // 1. --api-key flag (passed through config.apiKey which includes flag + env precedence)
+  // 1. --api-key flag
   if (config.apiKey) {
-    const source = process.env.MINIMAX_API_KEY === config.apiKey ? 'env' : 'flag';
-    return { token: config.apiKey, method: 'api-key', source };
+    return { token: config.apiKey, method: 'api-key', source: 'flag' };
   }
 
   // 2. OAuth credentials file
@@ -24,6 +23,11 @@ export async function resolveCredential(config: Config): Promise<ResolvedCredent
     return { token: config.fileApiKey, method: 'api-key', source: 'config.yaml' };
   }
 
+  // 4. Environment variable
+  if (config.envApiKey) {
+    return { token: config.envApiKey, method: 'api-key', source: 'env' };
+  }
+
   throw new CLIError(
     'No credentials found.',
     ExitCode.AUTH,

src/command.ts

@@ -1,10 +1,16 @@
 import type { Config } from './config/schema';
 import type { GlobalFlags } from './types/flags';
 
+export interface OptionDef {
+  flag: string;
+  description: string;
+}
+
 export interface Command {
   name: string;
   description: string;
   usage?: string;
+  options?: OptionDef[];
   examples?: string[];
   execute(config: Config, flags: GlobalFlags): Promise<void>;
 }
@@ -13,6 +19,7 @@ export interface CommandSpec {
   name: string;
   description: string;
   usage?: string;
+  options?: OptionDef[];
   examples?: string[];
   run(config: Config, flags: GlobalFlags): Promise<void>;
 }
@@ -22,6 +29,7 @@ export function defineCommand(spec: CommandSpec): Command {
     name: spec.name,
     description: spec.description,
     usage: spec.usage,
+    options: spec.options,
     examples: spec.examples,
     execute: spec.run,
   };

src/commands/auth/login.ts

@@ -18,6 +18,11 @@ export default defineCommand({
   name: 'auth login',
   description: 'Authenticate via OAuth or API key',
   usage: 'minimax auth login [--method oauth|api-key] [--api-key <key>] [--no-browser]',
+  options: [
+    { flag: '--method <method>', description: 'Auth method: oauth (default), api-key' },
+    { flag: '--api-key <key>', description: 'API key to store' },
+    { flag: '--no-browser', description: 'Use device-code flow instead of browser' },
+  ],
   examples: [
     'minimax auth login',
     'minimax auth login --no-browser',

src/commands/config/set.ts

@@ -14,6 +14,10 @@ export default defineCommand({
   name: 'config set',
   description: 'Set a config value',
   usage: 'minimax config set --key <key> --value <value>',
+  options: [
+    { flag: '--key <key>', description: 'Config key (region, base_url, output, timeout, api_key)' },
+    { flag: '--value <value>', description: 'Value to set' },
+  ],
   examples: [
     'minimax config set --key output --value json',
     'minimax config set --key timeout --value 600',

src/commands/image/generate.ts

@@ -15,6 +15,14 @@ export default defineCommand({
   name: 'image generate',
   description: 'Generate images (image-01)',
   usage: 'minimax image generate --prompt <text> [flags]',
+  options: [
+    { flag: '--prompt <text>', description: 'Image description' },
+    { flag: '--aspect-ratio <ratio>', description: 'Aspect ratio (e.g. 16:9, 1:1)' },
+    { flag: '--n <count>', description: 'Number of images to generate (default: 1)' },
+    { flag: '--subject-ref <params>', description: 'Subject reference (type=character,image=path)' },
+    { flag: '--out-dir <dir>', description: 'Download images to directory' },
+    { flag: '--out-prefix <prefix>', description: 'Filename prefix (default: image)' },
+  ],
   examples: [
     'minimax image generate --prompt "A cat in a spacesuit on Mars" --aspect-ratio 16:9',
     'minimax image generate --prompt "Logo design" --n 3 --out-dir ./generated/',

src/commands/music/generate.ts

@@ -13,6 +13,18 @@ export default defineCommand({
   name: 'music generate',
   description: 'Generate a song (music-2.5)',
   usage: 'minimax music generate --prompt <text> [--lyrics <text>] [--out <path>] [flags]',
+  options: [
+    { flag: '--prompt <text>', description: 'Music style description' },
+    { flag: '--lyrics <text>', description: 'Song lyrics' },
+    { flag: '--lyrics-file <path>', description: 'Read lyrics from file (use - for stdin)' },
+    { flag: '--auto-lyrics', description: 'Auto-generate lyrics from prompt' },
+    { flag: '--format <fmt>', description: 'Audio format (default: mp3)' },
+    { flag: '--sample-rate <hz>', description: 'Sample rate (default: 44100)' },
+    { flag: '--bitrate <bps>', description: 'Bitrate (default: 256000)' },
+    { flag: '--stream', description: 'Stream raw audio to stdout' },
+    { flag: '--out <path>', description: 'Output file path' },
+    { flag: '--out-format <fmt>', description: 'Output format: hex (default), url' },
+  ],
   examples: [
     'minimax music generate --prompt "Indie folk, melancholic" --lyrics-file song.txt --out my_song.mp3',
     'minimax music generate --prompt "Upbeat pop" --auto-lyrics --out summer.mp3',

src/commands/search/query.ts

@@ -23,6 +23,9 @@ export default defineCommand({
   name: 'search query',
   description: 'Search the web via MiniMax',
   usage: 'minimax search query --q <query>',
+  options: [
+    { flag: '--q <query>', description: 'Search query string' },
+  ],
   examples: [
     'minimax search query --q "MiniMax AI"',
     'minimax search query --q "latest news" --output json',

src/commands/speech/synthesize.ts

@@ -13,6 +13,26 @@ export default defineCommand({
   name: 'speech synthesize',
   description: 'Synchronous TTS, up to 10k chars (speech-2.8-hd / 2.6 / 02)',
   usage: 'minimax speech synthesize --text <text> --out <path> [flags]',
+  options: [
+    { flag: '--model <model>', description: 'Model ID (default: speech-2.8-hd)' },
+    { flag: '--text <text>', description: 'Text to synthesize' },
+    { flag: '--text-file <path>', description: 'Read text from file (use - for stdin)' },
+    { flag: '--voice <id>', description: 'Voice ID (default: English_expressive_narrator)' },
+    { flag: '--speed <n>', description: 'Speech speed multiplier' },
+    { flag: '--volume <n>', description: 'Volume level' },
+    { flag: '--pitch <n>', description: 'Pitch adjustment' },
+    { flag: '--format <fmt>', description: 'Audio format (default: mp3)' },
+    { flag: '--sample-rate <hz>', description: 'Sample rate (default: 32000)' },
+    { flag: '--bitrate <bps>', description: 'Bitrate (default: 128000)' },
+    { flag: '--channels <n>', description: 'Audio channels (default: 1)' },
+    { flag: '--language <code>', description: 'Language boost' },
+    { flag: '--subtitles', description: 'Include subtitle timing data' },
+    { flag: '--pronunciation <from/to>', description: 'Custom pronunciation (repeatable)' },
+    { flag: '--sound-effect <effect>', description: 'Add sound effect' },
+    { flag: '--out <path>', description: 'Output file path' },
+    { flag: '--out-format <fmt>', description: 'Output format: hex (default), url' },
+    { flag: '--stream', description: 'Stream raw audio to stdout' },
+  ],
   examples: [
     'minimax speech synthesize --text "Hello, world!" --out hello.mp3',
     'echo "Breaking news." | minimax speech synthesize --text-file - --out news.mp3',

src/commands/text/chat.ts

@@ -57,6 +57,17 @@ export default defineCommand({
   name: 'text chat',
   description: 'Send a chat completion (M2.7 / M2.7-highspeed)',
   usage: 'minimax text chat --message <role:content> [flags]',
+  options: [
+    { flag: '--model <model>', description: 'Model ID (default: MiniMax-M2.7)' },
+    { flag: '--message <role:content>', description: 'Message in role:content format (repeatable)' },
+    { flag: '--messages-file <path>', description: 'JSON file with messages array (use - for stdin)' },
+    { flag: '--system <text>', description: 'System prompt' },
+    { flag: '--max-tokens <n>', description: 'Maximum tokens to generate' },
+    { flag: '--temperature <n>', description: 'Sampling temperature' },
+    { flag: '--top-p <n>', description: 'Nucleus sampling threshold' },
+    { flag: '--stream', description: 'Stream response tokens (default: on in TTY)' },
+    { flag: '--tool <json-or-path>', description: 'Tool definition as JSON or file path (repeatable)' },
+  ],
   examples: [
     'minimax text chat --message "user:What is MiniMax?"',
     'minimax text chat --model MiniMax-M2.7-highspeed --system "You are a coding assistant." --message "user:Write fizzbuzz in Python"',