@mrgoonie/multix 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0](https://github.com/mrgoonie/multix-cli/compare/v0.1.1...v0.2.0) (2026-05-27)
+
+
+### Added
+
+* improve agent-facing command and skill descriptions ([#19](https://github.com/mrgoonie/multix-cli/issues/19)) ([a0f1dab](https://github.com/mrgoonie/multix-cli/commit/a0f1dab7e76295d5eb6a9d6dff237d28d2832596)), closes [#18](https://github.com/mrgoonie/multix-cli/issues/18)
+
 ## [0.1.1](https://github.com/mrgoonie/multix-cli/compare/v0.1.0...v0.1.1) (2026-05-20)
 
 

package/dist/cli.js

@@ -1240,7 +1240,7 @@ Task: ${taskId}`);
 // src/providers/byteplus/commands/index.ts
 function registerBytePlusCommands(program2) {
   const byteplus = program2.command("byteplus").description(
-    "BytePlus ModelArk: Seedream image, Seedance video, Hyper3D / Hitem3d 3D generation"
+    "BytePlus ModelArk: image (Seedream 4.0), video (Seedance 2.0 text/image/reference-to-video), and 3D (Hyper3D / Hitem3d)"
   );
   registerBytePlusGenerateCommand(byteplus);
   registerBytePlusImageToImageCommand(byteplus);
@@ -1998,7 +1998,7 @@ ${data.voices.length} voices${data.has_more ? " (more available)" : ""}`);
 // src/providers/elevenlabs/commands/index.ts
 function registerElevenLabsCommands(program2) {
   const el = program2.command("elevenlabs").description(
-    "ElevenLabs: TTS, voices, cloning, STT, voice changer, SFX, music, dubbing, isolation, alignment"
+    "ElevenLabs: text-to-speech, voice cloning, speech-to-text, voice changer, sound effects, music, dubbing, voice isolation, forced alignment"
   );
   registerTtsCommand(el);
   registerVoicesCommand(el);
@@ -3037,7 +3037,7 @@ function registerTranscribeCommand2(parent) {
 // src/providers/gemini/commands/index.ts
 function registerGeminiCommands(program2) {
   const gemini = program2.command("gemini").description(
-    "Gemini AI operations: analyze, transcribe, extract, generate images/video/speech"
+    "Gemini: analyze, transcribe, extract data, generate images (Imagen/Nano Banana), video (Veo), and speech (Flash TTS)"
   );
   registerAnalyzeCommand(gemini);
   registerTranscribeCommand2(gemini);
@@ -3722,7 +3722,9 @@ Resolutions: ${LEONARDO_VIDEO_RESOLUTIONS.join(", ")}`);
 
 // src/providers/leonardo/commands/index.ts
 function registerLeonardoCommands(program2) {
-  const leonardo = program2.command("leonardo").description("Leonardo.Ai: image/video generation, upscaling, account info");
+  const leonardo = program2.command("leonardo").description(
+    "Leonardo: image generation, video (Motion, Veo, Kling, Hailuo, Seedance, LTX), upscaling, and account info"
+  );
   registerLeonardoGenerateCommand(leonardo);
   registerLeonardoImageToImageCommand(leonardo);
   registerLeonardoVideoCommand(leonardo);
@@ -4348,7 +4350,7 @@ Generated ${saved.length} image(s):`);
 
 // src/providers/minimax/commands/index.ts
 function registerMinimaxCommands(program2) {
-  const minimax = program2.command("minimax").description("MiniMax generation: images, video, speech, and music");
+  const minimax = program2.command("minimax").description("MiniMax: generate images, video (Hailuo), speech (TTS), and music");
   registerMinimaxGenerateCommand(minimax);
   registerMinimaxImageToImageCommand(minimax);
   registerMinimaxGenerateVideoCommand(minimax);
@@ -4976,7 +4978,9 @@ function collect6(value, prev) {
 
 // src/providers/openai/commands/index.ts
 function registerOpenAICommands(program2) {
-  const openai = program2.command("openai").description("OpenAI image generation/editing, TTS, STT, and experimental Codex image driver");
+  const openai = program2.command("openai").description(
+    "OpenAI: image generation/editing (GPT-Image, Codex driver), text-to-speech (TTS), speech-to-text (STT)"
+  );
   registerOpenAIGenerateCommand(openai);
   registerOpenAIImageToImageCommand(openai);
   registerOpenAIGenerateSpeechCommand(openai);
@@ -5170,7 +5174,9 @@ async function generateOpenRouterImage(opts) {
 
 // src/providers/openrouter/commands/generate.ts
 function registerOpenRouterGenerateCommand(parent) {
-  parent.command("generate").description("Generate images via OpenRouter (uses chat completions API)").requiredOption("--prompt <text>", "Image generation prompt").option("--model <id>", "OpenRouter model id (e.g. google/gemini-3.1-flash-image-preview)").option("--aspect-ratio <ratio>", "Aspect ratio (e.g. 1:1, 16:9)", "1:1").option("--image-size <size>", "Image size hint (e.g. 1K, 2K)").option("--num-images <n>", "Number of images to generate", "1").option("--output <path>", "Copy first image to this path").option("-v, --verbose", "Verbose logging").action(
+  parent.command("generate").description(
+    "Generate images via OpenRouter (text-to-image); models: Gemini, GPT-Image, Flux, Recraft, Seedream"
+  ).requiredOption("--prompt <text>", "Image generation prompt").option("--model <id>", "OpenRouter model id (e.g. google/gemini-3.1-flash-image-preview)").option("--aspect-ratio <ratio>", "Aspect ratio (e.g. 1:1, 16:9)", "1:1").option("--image-size <size>", "Image size hint (e.g. 1K, 2K)").option("--num-images <n>", "Number of images to generate", "1").option("--output <path>", "Copy first image to this path").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
       const model = opts.model ?? resolveKey("OPENROUTER_IMAGE_MODEL") ?? DEFAULT_OPENROUTER_MODEL;
@@ -5206,7 +5212,9 @@ var DEFAULT_MODEL = "google/gemini-2.5-flash-image";
 var SOFT_LIMIT_BYTES2 = 5 * 1024 * 1024;
 var HARD_LIMIT_BYTES2 = 8 * 1024 * 1024;
 function registerOpenRouterImageToImageCommand(parent) {
-  parent.command("image-to-image").alias("i2i").description("Edit/transform images via OpenRouter (default: google/gemini-2.5-flash-image)").requiredOption("--prompt <text>", "Text prompt describing the edit").requiredOption(
+  parent.command("image-to-image").alias("i2i").description(
+    "Edit/transform images via OpenRouter (image-to-image); models: Gemini, GPT-Image, Flux, Recraft, Seedream"
+  ).requiredOption("--prompt <text>", "Text prompt describing the edit").requiredOption(
     "--ref <path>",
     "Reference image (URL or local path); repeatable (most models accept 1)",
     collect7,
@@ -5376,7 +5384,7 @@ async function downloadOpenRouterVideo(opts) {
   return dest;
 }
 function registerOpenRouterVideoStatusCommand(parent) {
-  parent.command("video-status <jobId>").description("Poll an OpenRouter video generation job").option("--wait", "Poll until status is 'completed' or 'failed'").option("--wait-timeout <ms>", "Poll timeout in ms (with --wait)", "600000").option("--download", "If completed, download the video (implies --wait)").option("--output <path>", "Copy downloaded video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
+  parent.command("video-status <jobId>").description("Poll or download an OpenRouter video generation job by job ID").option("--wait", "Poll until status is 'completed' or 'failed'").option("--wait-timeout <ms>", "Poll timeout in ms (with --wait)", "600000").option("--download", "If completed, download the video (implies --wait)").option("--output <path>", "Copy downloaded video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
     async (jobId, opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
       const shouldWait = !!(opts.wait || opts.download);
@@ -5426,7 +5434,9 @@ function registerOpenRouterVideoStatusCommand(parent) {
 
 // src/providers/openrouter/commands/image-to-video.ts
 function registerOpenRouterImageToVideoCommand(parent) {
-  parent.command("image-to-video").alias("i2v").description("Submit an image-to-video job to OpenRouter (async, returns job id)").requiredOption("--prompt <text>", "Motion/scene prompt").requiredOption("--image-url <url>", "First-frame image URL (https)").option("--last-frame-url <url>", "Optional last-frame image URL").option("--model <id>", "OpenRouter video model id (e.g. google/veo-3.1)").option("--resolution <r>", "Resolution hint (e.g. 720p, 1080p)").option("--aspect-ratio <r>", "Aspect ratio hint (e.g. 16:9, 9:16)").option("--duration <n>", "Duration seconds").option("--seed <n>", "Fixed seed").option("--wait", "Poll until status is 'completed' or 'failed'").option("--wait-timeout <ms>", "Poll timeout in ms (with --wait)", "600000").option("--download", "Download the generated video on success (implies --wait)").option("--output <path>", "Copy downloaded video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
+  parent.command("image-to-video").alias("i2v").description(
+    "Generate video from an image via OpenRouter (image-to-video, async); models: Veo, Seedance, Kling \u2014 use video-models to list all"
+  ).requiredOption("--prompt <text>", "Motion/scene prompt").requiredOption("--image-url <url>", "First-frame image URL (https)").option("--last-frame-url <url>", "Optional last-frame image URL").option("--model <id>", "OpenRouter video model id (e.g. google/veo-3.1)").option("--resolution <r>", "Resolution hint (e.g. 720p, 1080p)").option("--aspect-ratio <r>", "Aspect ratio hint (e.g. 16:9, 9:16)").option("--duration <n>", "Duration seconds").option("--seed <n>", "Fixed seed").option("--wait", "Poll until status is 'completed' or 'failed'").option("--wait-timeout <ms>", "Poll timeout in ms (with --wait)", "600000").option("--download", "Download the generated video on success (implies --wait)").option("--output <path>", "Copy downloaded video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
       const model = opts.model ?? resolveKey("OPENROUTER_VIDEO_MODEL") ?? "google/veo-3.1";
@@ -5503,7 +5513,9 @@ function registerOpenRouterImageToVideoCommand(parent) {
 
 // src/providers/openrouter/commands/video-models.ts
 function registerOpenRouterVideoModelsCommand(parent) {
-  parent.command("video-models").description("List available OpenRouter video models").option("-v, --verbose", "Verbose logging").action(async (opts) => {
+  parent.command("video-models").description(
+    "List available OpenRouter video-generation models (Veo, Seedance, Kling, and others)"
+  ).option("-v, --verbose", "Verbose logging").action(async (opts) => {
     const logger = createLogger({ verbose: opts.verbose ?? false });
     const res = await listVideoModels();
     const list = res.data ?? res.models ?? [];
@@ -5516,7 +5528,9 @@ function registerOpenRouterVideoModelsCommand(parent) {
 
 // src/providers/openrouter/commands/index.ts
 function registerOpenRouterCommands(program2) {
-  const openrouter = program2.command("openrouter").description("OpenRouter image + video generation");
+  const openrouter = program2.command("openrouter").description(
+    "OpenRouter: text-to-image, image-to-image, and video generation (image-to-video) via routed models \u2014 Veo, Seedance, Kling, and others"
+  );
   registerOpenRouterGenerateCommand(openrouter);
   registerOpenRouterImageToImageCommand(openrouter);
   registerOpenRouterImageToVideoCommand(openrouter);
@@ -5865,7 +5879,9 @@ function sleep5(ms) {
 
 // src/commands/doc/index.ts
 function registerDocCommands(program2) {
-  const doc = program2.command("doc").description("Document operations: convert PDFs, images, Office docs to Markdown via Gemini");
+  const doc = program2.command("doc").description(
+    "Document-to-Markdown: convert PDFs, images, DOCX, PPTX, and other docs to Markdown via Gemini"
+  );
   doc.command("convert").description("Convert documents to Markdown using Gemini Files API").requiredOption(
     "--input <files...>",
     "Input file(s) to convert",
@@ -6187,7 +6203,7 @@ async function splitVideo(opts) {
 // src/commands/media/index.ts
 function registerMediaCommands(program2) {
   const media = program2.command("media").description(
-    "Media optimization: compress video/audio/images, split long videos, batch process"
+    "Media processing via ffmpeg/ImageMagick: compress video/audio/images, split long videos, batch optimize directories"
   );
   media.command("optimize").description("Optimize a single media file (video, audio, or image)").requiredOption("--input <file>", "Input media file").requiredOption("--output <file>", "Output file path").option("--target-size <MB>", "Target file size in MB").option("--quality <n>", "Quality: video CRF (0-51) or image (1-100)", "85").option("--max-width <px>", "Max image/video width in pixels", "1920").option("--bitrate <rate>", "Audio bitrate (e.g. 64k)", "64k").option("--resolution <WxH>", "Force video resolution (e.g. 1920x1080)").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
@@ -6294,7 +6310,7 @@ loadEnv();
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
 var program = new Command().name("multix").description(
-  "AI multimodal CLI \u2014 Gemini \xB7 MiniMax \xB7 OpenRouter \xB7 ffmpeg \xB7 ImageMagick \xB7 doc-to-md"
+  "AI multimodal CLI \u2014 image/video/audio/3D generation, editing, transcription, and media processing via OpenAI, Gemini, MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, ffmpeg, and ImageMagick"
 ).version(pkg.version);
 registerCommands(program);
 program.parseAsync(process.argv).catch((err2) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrgoonie/multix",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AI multimodal CLI — OpenAI, Gemini, MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, ffmpeg, ImageMagick, doc-to-md",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multix
-description: AI multimodal CLI — generate and edit images (OpenAI, Codex driver, Gemini Nano Banana, Imagen, MiniMax, OpenRouter, Leonardo, BytePlus Seedream), generate video (Veo, Hailuo, Seedance, Leonardo), TTS/STT/music (OpenAI, Gemini Flash TTS, MiniMax, ElevenLabs), 3D models (Hyper3D), analyze/transcribe media, convert documents to Markdown, optimize media via ffmpeg/ImageMagick. Use whenever the user wants to create, edit, or transform images/video/audio/documents from a CLI, mentions any of: OpenAI, Codex image driver, image-to-image, i2i, image edit, watercolor/cyberpunk style transfer, reference image, OpenRouter, Nano Banana, Flux, Seedream, Veo, Hailuo, ElevenLabs voice cloning, or asks for batch media optimization.
-version: 0.1.1 # x-release-please-version
+description: AI multimodal CLI — generate and edit images (OpenAI, Codex driver, Gemini Nano Banana, Imagen, MiniMax, OpenRouter, Leonardo, BytePlus Seedream), generate video (Gemini Veo, MiniMax Hailuo, OpenRouter via Veo/Seedance/Kling, Leonardo via Motion/Veo/Kling/Hailuo/Seedance/LTX, BytePlus Seedance), TTS/STT/music (OpenAI, Gemini Flash TTS, MiniMax, ElevenLabs), 3D models (BytePlus Hyper3D/Hitem3d), analyze/transcribe media, convert documents to Markdown, optimize media via ffmpeg/ImageMagick. Use whenever the user wants to create, edit, or transform images/video/audio/3D/documents from a CLI, mentions any of: OpenAI, Codex image driver, image-to-image, i2i, image edit, watercolor/cyberpunk style transfer, reference image, OpenRouter, Nano Banana, Flux, Seedream, Veo, Hailuo, Seedance, Kling, video generation, text-to-video, image-to-video, i2v, ElevenLabs voice cloning, or asks for batch media optimization.
+version: 0.2.0 # x-release-please-version
 ---
 
 # multix — AI Multimodal CLI
@@ -12,8 +12,11 @@ Activate this skill when the user asks to:
 - Generate images from a text prompt (any provider)
 - **Edit/transform an existing image with a prompt** (image-to-image, alias `i2i`)
 - Generate video from text or from a reference image (image-to-video, alias `i2v`)
+- **Generate video via OpenRouter routed models** (Veo, Seedance, Kling — use `multix openrouter video-models` to list)
+- **Generate video via BytePlus Seedance** directly (text-to-video, image-to-video, reference-to-video)
+- **Generate video via Leonardo** (Motion, Veo, Kling, Hailuo, Seedance, LTX models)
 - Generate or clone a voice, run STT, generate music or sound effects
-- Generate 3D models (Hyper3D / Hitem3d)
+- Generate 3D models (BytePlus Hyper3D / Hitem3d)
 - Analyze, transcribe, or extract structured data from media/docs
 - Convert PDFs / DOCX / images to Markdown
 - Optimize, resize, batch-convert, or split video/audio/image files
@@ -23,7 +26,7 @@ Activate this skill when the user asks to:
 ```
 GEMINI_API_KEY        # Google AI Studio
 OPENAI_API_KEY        # OpenAI API (image, image edit, TTS, STT)
-OPENROUTER_API_KEY    # OpenRouter (multi-model gateway)
+OPENROUTER_API_KEY    # OpenRouter (multi-model gateway: image + video via Veo, Seedance, Kling)
 MINIMAX_API_KEY       # MiniMax (image/video/speech/music)
 LEONARDO_API_KEY      # Leonardo.Ai (image/video/upscale)
 BYTEPLUS_API_KEY      # BytePlus / Volcengine ARK (Seedream/Seedance/Hyper3D)
@@ -138,8 +141,9 @@ multix gemini i2v ./photo.jpg --prompt "camera pans left" [--last-frame <path>]
 # MiniMax Hailuo — async with auto-poll
 multix minimax generate-video --prompt "A dancer" --duration 6 --resolution 1080P [--first-frame <url>]
 
-# OpenRouter Veo — async, returns jobId; image input is URL only
-multix openrouter i2v --prompt "<text>" --image-url https://... [--last-frame-url <url>] [--resolution 720p]
+# OpenRouter — video via routed models (Veo, Seedance, Kling); async, URL input only
+multix openrouter i2v --prompt "<text>" --image-url https://... [--model google/veo-3.1] [--resolution 720p]
+multix openrouter video-models                       # list all available video models
 multix openrouter video-status <jobId> [--download] [--output <path>]
 
 # Leonardo MOTION2 / VEO3 / kling
@@ -154,6 +158,30 @@ multix byteplus reference-to-video --prompt "<text>" --ref-image ./hero.jpg:subj
 
 All video commands accept `--wait`, `--wait-timeout <ms>`, `--download`, `--output <path>`, `--no-thumb`.
 
+### Decision tree — which provider to pick for video generation
+
+```
+User wants to generate a video?
+  ├── Text-to-video?
+  │   ├── Gemini Veo (experimental, Google billing)        → multix gemini generate-video
+  │   ├── MiniMax Hailuo (async, auto-poll)                → multix minimax generate-video
+  │   ├── Leonardo (Motion/Veo/Kling/Hailuo/Seedance/LTX) → multix leonardo video
+  │   └── BytePlus Seedance 2.0 (direct)                  → multix byteplus video
+  ├── Image-to-video?
+  │   ├── Gemini Veo (experimental)                        → multix gemini i2v
+  │   ├── OpenRouter (Veo, Seedance, Kling — URL input)   → multix openrouter i2v --image-url <url>
+  │   ├── Leonardo (needs imageId from Leonardo upload)    → multix leonardo i2v
+  │   └── BytePlus Seedance 2.0 (local file or URL)       → multix byteplus i2v
+  └── Multi-reference video (images + videos + audio)?     → multix byteplus reference-to-video
+```
+
+### Provider selection hints for agents
+
+- **OpenRouter video** supports Veo, Seedance, Kling, and more via model routing. Image input must be a URL (not a local file). Run `multix openrouter video-models` to discover available models.
+- **BytePlus Seedance** is the best choice when `BYTEPLUS_API_KEY` is available and you need text-to-video, image-to-video (local file or URL), or multi-reference video.
+- **Leonardo** offers the widest model selection (Motion, Veo, Kling, Hailuo, Seedance, LTX) but requires a Leonardo API key.
+- If one provider's key is unavailable, fall back to another that supports the same capability.
+
 ## Speech, music, voice, 3D, docs, media
 
 ```bash
@@ -205,6 +233,41 @@ Files saved under `./multix-output/` by default. Override with `MULTIX_OUTPUT_DI
 | `BYTEPLUS_VIDEO_PARAMS_MODE` | `flags` (default) or `structured` |
 | `MULTIX_DISABLE_HOME_ENV` | `1` to skip `~/.multix/.env` |
 
+## Quick examples for agents
+
+```bash
+# Text-to-image
+multix openai generate --prompt "A sunset over mountains"
+multix gemini generate --prompt "A sunset over mountains" --aspect-ratio 16:9
+multix openrouter generate --prompt "A sunset over mountains" --num-images 2
+multix byteplus generate --prompt "A sunset over mountains" --size 2K
+
+# Image-to-image (edit an existing image)
+multix gemini i2i --prompt "make it watercolor" --ref ./photo.jpg
+multix openrouter i2i --prompt "make it cyberpunk" --ref ./photo.jpg
+
+# Text-to-video
+multix byteplus video --prompt "Ocean waves crashing on rocks" --duration 8
+multix leonardo video "Ocean waves crashing on rocks" --model kling-2.6
+multix gemini generate-video --prompt "Ocean waves crashing on rocks"
+
+# Image-to-video
+multix openrouter i2v --prompt "camera slowly pans left" --image-url https://example.com/photo.jpg
+multix byteplus i2v ./photo.jpg --prompt "camera slowly pans left"
+
+# Transcribe / analyze media
+multix gemini analyze --files ./video.mp4 --prompt "Summarize this video"
+multix gemini transcribe --files ./audio.mp3
+multix elevenlabs transcribe --input ./audio.mp3 --diarize
+
+# Compress / split media
+multix media optimize --input large.mp4 --output small.mp4 --target-size 50
+multix media split --input long-video.mp4 --chunk-duration 600
+
+# Convert document to markdown
+multix doc convert --input report.pdf --auto-name
+```
+
 ## Security & scope
 
 This skill produces shell commands for the local `multix` CLI. It does NOT execute the commands itself, exfiltrate API keys, or modify provider accounts.