Universal Commands

Universal commands work across the entire MediaProc CLI, regardless of which plugins you have installed. These commands provide essential utilities for plugin management, workflow automation, system diagnostics, and productivity features.

Quick Reference

🔌 Plugin Management

  • add - Install plugins

  • remove - Remove plugins

  • list - List plugins & commands

  • validate - Check installations

  • update - Update plugins

  • detect - Auto-detect & recommend

⚡ Workflow & Automation

  • batch - Queue processing jobs

  • template - Save command templates

  • workspace - Project workspaces

  • watch - Auto-process files

📊 Analysis & Stats

  • history - View & replay commands

  • stats - Usage statistics

  • compare - Compare files

  • benchmark - Performance tests

🛠️ Utilities

  • doctor - System diagnostics

  • search - Search commands

  • help - Get help

Plugin Management Commands

add

Install MediaProc plugins from the official registry.

mediaproc add <plugin-names...>

Options:

  • --verbose - Show detailed installation logs

Examples:

# Install single plugin
mediaproc add image

# Install multiple plugins
mediaproc add image video audio

# With verbose output
mediaproc add video --verbose

remove

Remove installed plugins from your system.

mediaproc remove <plugin-names...>

Examples:

# Remove single plugin
mediaproc remove image

# Remove multiple plugins
mediaproc remove image video audio

list

List installed plugins or view commands available in a plugin.

mediaproc list [plugin-name]

Examples:

# List all installed plugins
mediaproc list

# List commands in specific plugin
mediaproc list image

update

Update plugins to their latest versions.

mediaproc update [plugin-name]

Examples:

# Update all plugins
mediaproc update

# Update specific plugin
mediaproc update image

detect

Auto-detect file types and recommend appropriate plugins.

mediaproc detect <directory>

Examples:

# Analyze current directory
mediaproc detect .

# Analyze specific folder
mediaproc detect ./my-media-files

Workflow & Automation Commands

batch

Manage a queue of batch processing jobs with priority support.

# Add job to queue
mediaproc batch add <command> [files...] [options]

# List queued jobs
mediaproc batch list

# Start processing
mediaproc batch start

# Pause/resume queue
mediaproc batch pause
mediaproc batch resume

# Remove job
mediaproc batch remove <job-id>

# Clear all jobs
mediaproc batch clear

Options:

  • -p, --priority <number> - Job priority (higher first, default: 5)
  • --args <args> - Additional command arguments
  • -w, --workers <number> - Parallel workers (default: 4)

Examples:

# Add resize job
mediaproc batch add "image resize" *.jpg --args "-w 800" -p 10

# Start with 8 workers
mediaproc batch start -w 8

# List all jobs
mediaproc batch list

template

Save frequently used commands as reusable templates.

# Save template
mediaproc template save <name> <command> [options]

# List templates
mediaproc template list

# Run template
mediaproc template run <name> [params...]

# Delete template
mediaproc template delete <name>

Options:

  • -d, --description <text> - Template description

Use {param} syntax for parameterized templates.

Examples:

# Save template
mediaproc template save web-resize \
  "image resize {input} -w {width} -o {output}" \
  -d "Resize for web"

# Run template
mediaproc template run web-resize photo.jpg 1920 out.jpg

# List templates
mediaproc template list

workspace

Create project-specific workspaces with presets and rules.

# Create workspace
mediaproc workspace create <name> [options]

# List workspaces
mediaproc workspace list

# Load workspace
mediaproc workspace load <name>

# Add rule
mediaproc workspace rule add <pattern> <command>

Options:

  • -d, --description <text> - Description
  • --preset <type> - Preset (web, mobile, print, social)

Examples:

# Create with preset
mediaproc workspace create my-site --preset web

# Add rules
mediaproc workspace rule add "*.jpg" "image optimize -q 85"

# Load workspace
mediaproc workspace load my-site

watch

Monitor directories and automatically process new files.

mediaproc watch <directory> [options]

Options:

  • --on-image <cmd> - Command for new images
  • --on-video <cmd> - Command for new videos
  • --on-audio <cmd> - Command for new audio
  • --on-any <cmd> - Command for any file
  • --ignore <patterns> - Patterns to ignore
  • --recursive - Watch subdirectories
  • --debounce <ms> - Debounce delay (default: 1000)

Examples:

# Watch and optimize images
mediaproc watch ./uploads --on-image "image optimize -q 85"

# Multiple rules
mediaproc watch ./media \
  --on-image "image convert -f webp" \
  --on-video "video compress -p medium"

# Recursive with ignore patterns
mediaproc watch ./content \
  --recursive \
  --ignore "node_modules,*.tmp"

Analysis & Statistics Commands

history

View, search, and replay previously executed commands.

# Show recent history
mediaproc history [options]

# Replay command
mediaproc history replay <id>

# Search history
mediaproc history search <query>

Options:

  • -n, --limit <number> - Number of entries (default: 20)
  • --clear - Clear all history
  • --export <file> - Export as shell script
  • --json - Output as JSON

Examples:

# Show last 20 commands
mediaproc history

# Search for commands
mediaproc history search resize

# Replay command
mediaproc history replay 42

# Export as script
mediaproc history --export workflow.sh

compare

Compare two files for size, quality, and metadata differences.

mediaproc compare <file1> <file2> [options]

Options:

  • --preview - Visual preview
  • --detailed - Detailed comparison
  • --json - Output as JSON

Examples:

# Basic comparison
mediaproc compare original.jpg optimized.jpg

# Detailed with metadata
mediaproc compare before.mp4 after.mp4 --detailed

# Visual preview
mediaproc compare img1.png img2.png --preview

benchmark

Run performance benchmarks to test system capabilities.

mediaproc benchmark [options]

Options:

  • --system - System capabilities
  • --plugin <name> - Benchmark plugin
  • --operation <name> - Benchmark operation
  • --file <path> - Test file
  • --iterations <n> - Iterations (default: 5)
  • --json - Output as JSON

Examples:

# System benchmark
mediaproc benchmark --system

# Operation benchmark
mediaproc benchmark --plugin image \
  --operation resize \
  --file test.jpg \
  --iterations 10

Utility Commands

doctor

Run comprehensive system diagnostics and health checks.

mediaproc doctor [options]

Options:

  • --verbose - Detailed diagnostics
  • --fix - Auto-fix issues

Checks:

  • ✓ Node.js version
  • ✓ FFmpeg installation
  • ✓ Sharp/libvips
  • ✓ Plugin validation
  • ✓ System resources
  • ✓ Dependencies
  • ✓ Configuration

Examples:

# Basic diagnostics
mediaproc doctor

# Detailed output
mediaproc doctor --verbose

# Auto-fix issues
mediaproc doctor --fix

Search for commands across all installed plugins.

mediaproc search <query> [options]

Options:

  • -p, --plugin <name> - Search in specific plugin
  • -l, --limit <number> - Result limit (default: 10)
  • --json - Output as JSON

Features:

  • Fuzzy matching
  • Category filtering
  • Relevance scoring
  • Description search

Examples:

# Search all plugins
mediaproc search resize

# Plugin-specific
mediaproc search compress --plugin video

# Limit results
mediaproc search convert --limit 5

help

Display comprehensive help information.

# General help
mediaproc help
mediaproc --help

# Command help
mediaproc <command> --help

# Plugin help
mediaproc <plugin> help
mediaproc <plugin> <command> --help

Examples:

# All commands
mediaproc help

# Specific command
mediaproc help batch

# Plugin commands
mediaproc image help

# Plugin command
mediaproc image resize --help

Best Practices

💡 Pro Tips

  • Start with doctor: Run mediaproc doctor before processing important files

  • Use templates: Save time with mediaproc template save

  • Batch processing: Queue jobs with mediaproc batch for efficiency

  • Automate with watch: Monitor folders with mediaproc watch

  • Track usage: Review stats with mediaproc stats

  • Workspaces for projects: Use mediaproc workspace for organization

  • Compare results: Verify quality with mediaproc compare

  • Search when unsure: Find commands with mediaproc search

Template Example Workflow

# 1. Save template for common task
mediaproc template save blog-image \
  "image resize {input} -w 1200 -q 90 -o {output}"

# 2. Use template repeatedly
mediaproc template run blog-image photo1.jpg photo1-blog.jpg
mediaproc template run blog-image photo2.jpg photo2-blog.jpg

Batch Processing Workflow

# 1. Queue multiple jobs
mediaproc batch add "image optimize" folder1/*.jpg
mediaproc batch add "image optimize" folder2/*.png
mediaproc batch add "image convert" folder3/*.jpg --args "-f webp"

# 2. Start processing with 8 workers
mediaproc batch start -w 8

# 3. Monitor progress
mediaproc batch list

Workspace Setup

# 1. Create workspace
mediaproc workspace create my-project --preset web

# 2. Add processing rules
mediaproc workspace rule add "*.jpg" "image optimize -q 85"
mediaproc workspace rule add "*.png" "image convert -f webp"

# 3. Load and work
mediaproc workspace load my-project

Exit Codes

CodeMeaning
0Success
1General error
2Invalid arguments
3Plugin not found
4File not found
5Permission denied
6Dependency missing
Exit Codes

See exit-codes

Advanced Usage

Combine Commands with Shell

# Count resize commands in history
mediaproc history | grep resize | wc -l

# Use jq for JSON parsing
mediaproc stats --json | jq '.totalFiles'

# Chain batch jobs
mediaproc batch add "image resize" *.jpg --args "-w 1920"
mediaproc batch add "image optimize" *.jpg --args "-q 85"
mediaproc batch start

Watch Multiple Directories

# Background processes
mediaproc watch ./folder1 --on-image "image optimize" &
mediaproc watch ./folder2 --on-video "video compress" &

Export and Share Workflows

# Export your workflow
mediaproc history --export workflow.sh

# Share with team
# Team can run: bash workflow.sh

See Also

CLI Overview

General CLI introduction and getting started

Plugin Management

Managing plugins in detail

Image Plugin

Image processing commands

Video Plugin

Video processing commands

Found an issue? Help us improve this page.

Edit on GitHub →