Basic usage
Pass one or more input files and specify the target format with --to:
# Single file
$ convertessa photo.heic --to jpg
✓ photo.jpg · 1.2 MB · 0.4s
# Multiple files
$ convertessa a.heic b.heic c.heic --to avif
✓ 3 files converted · 1.2s
# Glob pattern with output directory
$ convertessa ./photos/*.heic --to jpg -o ~/Desktop/converted
✓ 24 files converted · 5.2s
Global flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --to <format> | string | — | Target format. Required. Case-insensitive — jpg, JPG, and jpeg all work. |
| -o, --output <path> | path | alongside input | Output file (single input) or directory (multiple inputs; created if missing). Default: same directory as the input, same name with the new extension. |
| --quality <value> | 0–100 or preset | max | Output quality for lossy formats (JPEG, WebP, AVIF, MP3, …). Presets: web (60) | balanced (80) | high (90) | max (100). Ignored for lossless formats. |
| --strip-metadata | flag | keep | Strip metadata (EXIF/GPS, ID3 tags, container tags) from the output file. |
| --force | flag | refuse | Overwrite existing output files. By default the CLI refuses and fails that file rather than silently overwriting. |
| --quiet | flag | false | Suppress all output except errors. |
| --debug | flag | false | Print per-file pipeline detail (resolved paths, engine route, full errors) to stderr. Cannot be combined with --quiet. |
| --version | flag | — | Print the Convertessa version and exit. |
| --help | flag | — | Print usage and exit. |
Formats & targets
The CLI supports the same formats as the app. See the conversion explorer on the homepage — pick an input format and see every output it supports.
Format identifiers are case-insensitive and match file extensions: use jpg or jpeg, mkv, 7z, etc. Run convertessa targets <file> to list every format a specific file can convert to, or convertessa suggestions-json to print the full suggestion table.
Examples
Extract audio from a video file:
$ convertessa interview.mov --to mp3 --quality balanced
✓ interview.mp3 · 18.4 MB · 3.1s
Batch convert images for the web:
$ convertessa ./assets/*.png --to avif --quality 75 -o ./dist/images
✓ 48 files converted · 9.6s
Convert a Word document to Markdown:
$ convertessa report.docx --to md
✓ report.md · 42 KB · 0.8s
Convert an EPUB for a Kindle:
$ convertessa book.epub --to mobi
✓ book.mobi · 2.1 MB · 1.2s
Debug a conversion:
$ convertessa photo.heic --to jpg --quality 90 --debug
[debug] input: /Users/dale/photo.heic (heic, 3.4 MB)
[debug] route: LibVipsImageEngine → jpeg, quality 90
[debug] output: /Users/dale/photo.jpg
✓ photo.jpg · 1.2 MB · 0.4s