CLI Reference - VLM Run

The VLM Run CLI provides a powerful command-line interface for interacting with the VLM Run platform directly from your terminal.

Installation

The CLI is included when you install the VLM Run Python SDK. For the full CLI experience with rich terminal output, install with the cli extra:

# Basic installation
pip install vlmrun

# Full CLI with rich terminal output (recommended)
pip install vlmrun[cli]

Configuration

Global Options

Usage: vlmrun [OPTIONS] COMMAND [ARGS]...

  CLI for VLM Run (https://app.vlm.run)

Options:
  --base-url TEXT      Base URL for API requests [env var: VLMRUN_BASE_URL]
  --api-key TEXT       API Key for authentication [env var: VLMRUN_API_KEY]
  --debug              Enable debug logging
  -v, --version        Show version and exit
  --help               Show this message and exit

Using Environment Variables

You can set your API key and other settings using environment variables:

# Linux/macOS
export VLMRUN_API_KEY=your-api-key
export VLMRUN_BASE_URL=https://api.vlm.run/v1  # Optional
export VLMRUN_AGENT_BASE_URL=https://agent.vlm.run/v1  # Optional, for chat command

# Windows
set VLMRUN_API_KEY=your-api-key

Command Groups

The CLI is organized into logical command groups:

Command	Description
`chat`	Visual AI chat with the Orion agent
`files`	File upload and management
`models`	Model listing and information
`generate`	Generate predictions from files
`hub`	Domain and schema management
`datasets`	Dataset creation and management
`fine-tuning`	Model fine-tuning operations
`predictions`	View and manage predictions

Chat Command

The vlmrun chat command enables visual AI chat with the Orion agent directly from your terminal. Process images, videos, and documents with natural language prompts.

Basic Usage

# Describe an image
vlmrun chat "Describe this image" -i photo.jpg

# Compare multiple images
vlmrun chat "Compare these images" -i image1.jpg -i image2.jpg

# Analyze a document
vlmrun chat "Extract the key information" -i document.pdf

# Process a video
vlmrun chat "Summarize this video" -i video.mp4

Prompt Sources

The chat command supports multiple ways to provide prompts, with the following precedence:

# 1. Direct argument (highest priority)
vlmrun chat "Your prompt here" -i file.jpg

# 2. Using -p option (text, file path, or stdin)
vlmrun chat -p "Your prompt" -i file.jpg
vlmrun chat -p prompt.txt -i file.jpg
vlmrun chat -p stdin -i file.jpg

# 3. Piped stdin
echo "Describe this" | vlmrun chat - -i file.jpg
cat prompt.txt | vlmrun chat - -i file.jpg

Available Models

The chat command supports three Orion agent tiers:

Model	Description
`vlmrun-orion-1:fast`	Speed-optimized for quick responses
`vlmrun-orion-1:auto`	Auto-selects the best model (default)
`vlmrun-orion-1:pro`	Most capable, highest quality

# Use a specific model
vlmrun chat "Describe this" -i photo.jpg -m vlmrun-orion-1:pro

Command Options

vlmrun chat [OPTIONS] [PROMPT]

Arguments:
  PROMPT                    Prompt text. Use '-' for stdin.

Options:
  -p, --prompt TEXT         Prompt: text string, file path, or 'stdin'
  -i, --input PATH          Input file (image/video/document). Repeatable.
  -o, --output PATH         Artifact output directory [default: ~/.vlm/cache/artifacts/<id>]
  -m, --model TEXT          Model: vlmrun-orion-1:fast|auto|pro [default: vlmrun-orion-1:auto]
  -j, --json                Output JSON instead of formatted text
  -ns, --no-stream          Disable streaming (wait for complete response)
  -nd, --no-download        Skip artifact download
  --base-url TEXT           VLM Run Agent API base URL
  --help                    Show this message and exit

Supported File Types

The chat command supports a wide range of file types:

Category	Extensions
Images	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`, `.tiff`
Videos	`.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`
Documents	`.pdf`, `.doc`, `.docx`
Audio	`.mp3`, `.wav`, `.m4a`, `.flac`, `.ogg`

Output Formats

By default, the chat command displays rich formatted output with panels. Use --json for programmatic access:

# Rich formatted output (default)
vlmrun chat "Describe this" -i photo.jpg

# JSON output for scripting
vlmrun chat "Describe this" -i photo.jpg --json

# Pipe JSON to jq for processing
vlmrun chat "Describe this" -i photo.jpg --json | jq '.content'

Artifact Handling

When the Orion agent generates artifacts (images, videos, etc.), they are automatically downloaded to a local cache directory:

# Artifacts saved to default location
vlmrun chat "Generate a variation of this image" -i photo.jpg
# Artifacts saved to: ~/.vlm/cache/artifacts/<session_id>/

# Specify custom output directory
vlmrun chat "Generate a variation" -i photo.jpg -o ./output/

# Skip artifact download
vlmrun chat "Generate a variation" -i photo.jpg --no-download

Examples

# Image analysis
vlmrun chat "What objects are in this image?" -i scene.jpg

# Document extraction
vlmrun chat "Extract all tables from this PDF" -i report.pdf

# Video summarization
vlmrun chat "Create a summary of this video" -i meeting.mp4

# Multi-file comparison
vlmrun chat "What are the differences between these documents?" -i v1.pdf -i v2.pdf

# Using a prompt file for complex instructions
vlmrun chat -p analysis_prompt.txt -i data.pdf --json > results.json

# Batch processing with shell scripting
for file in images/*.jpg; do
  vlmrun chat "Describe this image" -i "$file" --json >> descriptions.jsonl
done

Common Operations

File Management

Upload a file to VLM Run:

# Upload a single file
vlmrun files upload path/to/image.jpg

# Upload multiple files
vlmrun files upload file1.jpg file2.jpg file3.jpg

# List uploaded files
vlmrun files list

# Get file information
vlmrun files get FILE_ID

Model Operations

# List available models
vlmrun models list

Generating Predictions

Generate predictions from various file types:

# Image prediction
vlmrun generate image path/to/image.jpg --domain document.invoice

# Document prediction
vlmrun generate document path/to/document.pdf --domain document.form

# Audio prediction
vlmrun generate audio path/to/audio.mp3 --domain audio.transcription

# Video prediction
vlmrun generate video path/to/video.mp4 --domain video.transcription

Working with Domains

# List available domains
vlmrun hub list

# View schema for a domain
vlmrun hub schema document.invoice

Managing Datasets

# Create a dataset from local files
vlmrun datasets create --directory ./images --domain document.invoice --name "Invoice Dataset" --type images

# List your datasets
vlmrun datasets list

# Get dataset details
vlmrun datasets get DATASET_ID

Fine-tuning Models

# Create a fine-tuning job
vlmrun fine-tuning create --model base_model --training-file TRAINING_FILE_ID

# List fine-tuning jobs
vlmrun fine-tuning list

# Get fine-tuning job status
vlmrun fine-tuning get JOB_ID

Advanced Usage

JSON Output

Add the --json flag to get machine-readable JSON output:

vlmrun files list --json > files.json
vlmrun chat "Describe this" -i photo.jpg --json > response.json

Using Remote Files

Generate predictions from remote URLs:

vlmrun generate image --url https://example.com/image.jpg --domain document.invoice

Detailed Help

Get detailed help for any command:

# General help
vlmrun --help

# Command-specific help
vlmrun chat --help
vlmrun generate --help
vlmrun generate image --help

Command Reference

For each command, refer to the built-in help for detailed information:

vlmrun <command> --help
vlmrun <command> <subcommand> --help

Python SDK

Python CLI

​Installation

​Configuration

​Global Options

​Using Environment Variables

​Command Groups

​Chat Command

​Basic Usage

​Prompt Sources

​Available Models

​Command Options

​Supported File Types

​Output Formats

​Artifact Handling

​Examples

​Common Operations

​File Management

​Model Operations

​Generating Predictions

​Working with Domains

​Managing Datasets

​Fine-tuning Models

​Advanced Usage

​JSON Output

​Using Remote Files

​Detailed Help

​Command Reference