Complete Guide to MLX-VLM CLI Commands: Generate, Convert, Chat, and Serve Models

MLX-VLM exposes six core CLI commands—generate, convert, chat, chat_ui, server, and video_generate—through a unified entry point at python -m mlx_vlm, with each command implemented in dedicated modules for vision-language inference, model conversion, and API deployment.

The Blaizzy/mlx-vlm repository provides a comprehensive command-line interface for running multimodal models on Apple Silicon. Mastering the available MLX-VLM CLI commands allows developers to perform everything from single-image inference to hosting production HTTP APIs. This guide examines the dispatcher logic in mlx_vlm/__main__.py and details each subcommand's source implementation, parameters, and practical usage examples.

Overview of Available MLX-VLM CLI Commands

The CLI entry point defines a subcommands set in mlx_vlm/__main__.py (lines 9-15) that validates the first positional argument and routes execution to the appropriate module. Each command specializes in a distinct workflow within the vision-language model pipeline.

Command	Purpose	Source Location
generate	Run text generation from images, audio, or text prompts	mlx_vlm/generate.py – parse_arguments (lines 51-102)
convert	Convert model weights between formats (e.g., Hugging Face to MLX)	mlx_vlm/convert.py – configure_parser (lines 208-215)
chat	Interactive single-turn or multi-turn multimodal chat	mlx_vlm/chat.py – ArgumentParser (lines 188-194)
chat_ui	Text-based user interface for conversational interaction	mlx_vlm/chat_ui.py – ArgumentParser (lines 24-30)
server	Launch an HTTP server exposing the generation API	mlx_vlm/server.py – ArgumentParser (lines 1368-1375)
video_generate	Generate descriptions for video inputs or frame sequences	mlx_vlm/video_generate.py – ArgumentParser (lines 28-63)

Detailed Breakdown of Each MLX-VLM CLI Command

generate

The generate command executes the core text-generation pipeline. Implemented in mlx_vlm/generate.py within the parse_arguments function (lines 51-102), this command accepts image paths, audio files, or text prompts and returns model completions.

python -m mlx_vlm generate \
    --model mlx-community/nanoLLaVA-1.5-8bit \
    --image path/to/image.jpg \
    --prompt "Describe this picture."

convert

Use the convert command to transform model weights between serialization formats. According to the source in mlx_vlm/convert.py at the configure_parser function (lines 208-215), this utility supports migrating models from Hugging Face repositories to the MLX format optimized for Apple Silicon.

python -m mlx_vlm convert \
    --src huggingface \
    --model mlx-community/nanoLLaVA-1.5-8bit \
    --dst mlx \
    --out-dir ./converted

chat

The chat command provides interactive multimodal conversation capabilities. As defined in mlx_vlm/chat.py (lines 188-194), this supports both single-turn queries and multi-turn dialogues with image or audio context.

python -m mlx_vlm chat \
    --model mlx-community/nanoLLaVA-1.5-8bit \
    --image path/to/image.jpg \
    --prompt "What is happening here?"

chat_ui

For a text-based interactive experience, the chat_ui command launches a terminal interface. The argument parser resides in mlx_vlm/chat_ui.py (lines 24-30), wrapping the same generation backend as the standard chat command but with interactive input handling.

python -m mlx_vlm chat_ui \
    --model mlx-community/nanoLLaVA-1.5-8bit

The UI prompts iteratively for messages and optional media files until you exit the session.

server

Deploy models as a REST API using the server command. Implemented in mlx_vlm/server.py (lines 1368-1375), this launches an HTTP server that exposes the generation pipeline to network clients.

python -m mlx_vlm server \
    --model mlx-community/nanoLLaVA-1.5-8bit \
    --host 0.0.0.0 \
    --port 8080

Once running, submit POST requests to http://<host>:<port>/generate with JSON payloads containing your prompts and media references.

video_generate

Process video inputs using the video_generate command. Located in mlx_vlm/video_generate.py (lines 28-63), this command treats videos as frame sequences to produce temporal descriptions or summaries.

python -m mlx_vlm video_generate \
    --video path/to/video.mp4 \
    --prompt "Summarize the video." \
    --model mlx-community/Qwen2.5-VL-7B-Instruct-4bit

How the CLI Entry Point Works

The dispatcher logic in mlx_vlm/__main__.py validates commands against a hardcoded set (lines 9-15):

subcommands = {
    "generate",
    "convert",
    "chat",
    "chat_ui",
    "server",
    "video_generate",
}

When you invoke python -m mlx_vlm, the script inspects the first positional argument. If it matches a key in the subcommands set, the corresponding module is imported dynamically and its main() function executes immediately. This architecture keeps the entry point lightweight while delegating argument parsing and logic to specialized modules.

Summary

• Six core commands handle distinct MLX-VLM workflows: generate, convert, chat, chat_ui, server, and video_generate.
• Unified entry point at mlx_vlm/__main__.py routes commands to their respective implementation files.
• Source-specific implementations reside in dedicated modules (generate.py, convert.py, chat.py, etc.), each with specialized argument parsers.
• Practical coverage spans from local inference and model conversion to HTTP API serving and video processing.

Frequently Asked Questions

How do I access the MLX-VLM CLI?

Install the package from the Blaizzy/mlx-vlm repository, then invoke commands using python -m mlx_vlm <command>. The dispatcher in mlx_vlm/__main__.py handles routing to the appropriate submodule.

Can I run MLX-VLM commands without installing the package?

While you can execute the module directly from the source directory using python -m mlx_vlm, the package dependencies (MLX, transformers, etc.) must be available in your environment. Installation via pip ensures all CLI commands function correctly.

Which command should I use for batch video processing?

Use the video_generate command defined in mlx_vlm/video_generate.py. It processes video files as frame sequences and accepts prompts for temporal analysis, making it ideal for batch video captioning or summarization tasks.

Is there a difference between chat and chat_ui commands?

Yes. The chat command executes a single interaction and exits, while chat_ui launches a persistent text-based interface that maintains conversation state across multiple turns. Both use the same underlying generation logic but differ in interaction patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}