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
# Glob pattern with output directory
$ convertessa ./photos/*.heic --to jpg --out ~/Desktop/converted
✓ 24 files converted · all on-device
Global flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --to <format> | string | — | Target format. Required. Case-insensitive — jpg, JPG, and jpeg all work. |
| --out <dir> | path | Input directory | Output directory. Created automatically if it doesn't exist. |
| --quality <n> | 1–100 | 85 | Output quality for lossy formats (JPEG, WebP, AVIF). Ignored for lossless formats. |
| --overwrite | flag | false | Overwrite existing output files. By default, a suffix is appended to avoid collisions. |
| --quiet | flag | false | Suppress per-file output lines. Prints only a final summary. |
| --install-cli | flag | — | Link the CLI binary to /usr/local/bin/convertessa. Run once after installing the app. |
| --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 names are case-insensitive. Common aliases are accepted: jpg = jpeg, mkv = matroska, 7z = 7-zip.
Examples
Extract audio from a video file:
$ convertessa interview.mov --to mp3 --quality 192
✓ interview.mp3 · 18.4 MB · 3.1s
Batch convert images for the web:
$ convertessa ./assets/*.png --to avif --quality 75 --out ./dist/images
✓ 48 files converted · avg 0.2s each
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