CLI Reference

Convert files, batch process entire directories, watch folders, and explore formats — all from the terminal.

convx convert

Convert one or more files to a target format.

convx convert <input> --to <format> [options]

Options

Flag	Description	Example
`--to <format>`	Target output format	`--to webp`
`-q, --quality <0-100>`	Quality level (mapped per codec)	`-q 80`
`--preset <name>`	Apply a built-in preset	`--preset discord`
`-d, --output-dir <dir>`	Output directory	`-d ./out`
`-j, --jobs <n>`	Parallel jobs for batch	`-j 4`
`--overwrite`	Overwrite existing files
`--max-size <bytes>`	Target max file size	`--max-size 8MB`
`--width <px>`	Resize width	`--width 1080`
`--height <px>`	Resize height	`--height 1920`
`--fps <n>`	Video frame rate	`--fps 30`

Examples

# Basic conversion
convx convert photo.heic --to jpg

# With quality
convx convert image.png --to webp -q 80

# Using a preset
convx convert video.mov --preset discord

# Batch convert with glob
convx convert "./photos/*.png" --to webp -j 4 -d ./out --overwrite

# Size-constrained conversion
convx convert video.mp4 --to mp4 --max-size 8MB

# Video with dimensions and fps
convx convert clip.mov --to mp4 --width 1080 --height 1920 --fps 30

convx watch

Monitor a directory and auto-convert files when they appear or change.

convx watch <directory> --to <format> [options]

Options

Flag	Description
`--to <format>`	Target format for converted files
`--filter <globs>`	Only convert files matching these patterns
`--preset <name>`	Apply a preset to all conversions
`-q, --quality`	Quality level

Examples

# Watch screenshots folder, convert PNGs to WebP
convx watch ~/Screenshots --to webp --filter "*.png"

# Watch with a preset
convx watch ~/Downloads --preset heic-to-jpg --filter "*.heic,*.heif"

# Watch and convert all new images
convx watch ./incoming --to jpg -q 85

convx formats

Explore supported formats and what they can convert to.

# List all supported formats
convx formats

# Show what a specific format can convert to
convx formats --from png

# Filter by category
convx formats --category video

convx presets

List and inspect built-in presets.

# List all presets
convx presets list

# Show details for a specific preset
convx presets show discord

convx info

Inspect a file's format, size, and available conversion targets.

convx info video.mp4

convx check

Verify that everything is set up correctly and see which formats are available.

convx check

JSON output

Add --json to any command for machine-readable output, useful for scripting and automation.

convx --json convert input.png --to webp
convx --json info video.mp4
convx --json formats --from pdf

Size-constrained conversions

Set a target file size and ConvX will iteratively adjust quality to hit it. Especially useful for platform-specific limits.

# Target under 8MB (Discord free)
convx convert video.mp4 --to mp4 --max-size 8MB

# Or just use the discord preset
convx convert video.mp4 --preset discord

Quality abstraction

The -q flag takes a value from 0-100 and maps it to the appropriate setting for each format. Quality 80 means the same perceptual thing whether you're encoding WebP, MP4, or MP3. No need to remember codec-specific quality scales.