> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/reference/cli-reference.md). # CLI Reference The `viesus` command-line tool is the most common interface for batch image enhancement on Windows and Linux. It reads image files (singly or by list), applies the VIESUS enhancement pipeline, and writes output — built to be called from shell scripts, schedulers, or any orchestration tool. This page documents every flag, input method, and output convention. To run it in a container see [Docker for CLI](/reference/docker/cli.md); for throughput data see [Benchmarks](/operations/benchmarks.md), and for fixes see [Troubleshooting](/support/troubleshooting.md). ## Syntax ```bash viesus [options] [-l imagelist | -f file1 [file2 ...]] ``` {% hint style="warning" %} The `-f` option must be the **last** parameter on the command line — everything after it is treated as input files. {% endhint %} *** ## Input methods

Method	Flag	Description
File list	`-l <imagelist>`	Process images listed in a text file (one path per line)
Direct files	`-f <file1> [file2 ...]`	Process specified image files directly

*** ## Core options

Flag	Argument	Description
`-b <path>`	String	Base path for saving enhanced image results
`-p <file>`	String	Path to parameter/configuration JSON file
`-i`	—	Save enhanced images with the same filename (overwrites the original)
`-s`	—	Save enhanced images in the same folder with default suffix `_viesus`
`-n <suffix>`	String	Save enhanced images with a custom suffix. Only valid when `-b` is not used.
`-e`	—	Enhance only images containing valid EXIF data
`-a`	—	Force re-enhancement of already processed images (not recommended)
`-T <n>`	Integer	Number of worker threads. Defaults to physical CPU core count.

## Information options

Flag	Description
`-I`	Display license information. For GUID libraries, the GUID must be specified using `-g GUID`.
`-v`	Display VIESUS library version
`-h`	Show help information

*** ## Output behavior When processing images, VIESUS writes a results text file alongside the enhanced images. The file contains one line per processed image with its error code, plus processing statistics.

Input source	Results file name
`-f` direct files	`Images.res`
`-l ImageList.lst`	`ImageList.res`

*** ## Output naming

Flag combination	Example input	Example output	Location
`-s`	`photo.jpg`	`photo_viesus.jpg`	Same folder as input
`-n "_custom"`	`photo.jpg`	`photo_custom.jpg`	Same folder as input
`-b "output" -s`	`photo.jpg`	`photo_viesus.jpg`	`output/` folder
`-i`	`photo.jpg`	`photo.jpg`	Same location (overwrites)

{% hint style="warning" %} **`-i` overwrites the original.** Back up source images before using it. There is no undo. {% endhint %} *** ## Image list format The simplest image list has one image path per line: ```powershell C:\Photos\image1.jpg C:\Photos\image2.png D:\Pictures\vacation\sunset.jpg ``` You can also specify a destination path per image using a colon separator: ```powershell C:\Photos\image1.jpg:D:\Output\image1_enhanced.jpg C:\Photos\image2.png:D:\Output\image2_enhanced.png ``` ### Creating an image list {% tabs %} {% tab title="Windows" %} ```powershell # All JPG files recursively dir /b /s *.JPG > Images.lst # Multiple extensions dir /b /s *.jpg *.png *.tiff > Images.lst # Specific folder dir /b "C:\Photos\*.jpg" > Images.lst ``` {% endtab %} {% tab title="Linux" %} ```bash # All JPG files recursively find /path/to/images -name "*.jpg" > images.lst # Multiple extensions find /path/to/images \( -name "*.jpg" -o -name "*.png" \) > images.lst ``` {% endtab %} {% endtabs %} *** ## Examples ### Process a folder of images with a config ```bash # Create image list (Windows) dir /b /s *.JPG > Images.lst # Process using image list viesus -l Images.lst -s -p "TempFolder\Viesus_Configuration.json" -n "_myConfig" -b "TempFolder" ``` ### Process individual files with a custom suffix ```bash viesus -s -n "_enhanced" -p "config.json" -f image1.jpg image2.jpg image3.jpg ``` ### Process files and save to a different directory ```bash viesus -b "C:\output" -s -p "settings.json" -f "C:\input\photo.jpg" ``` ### Professional batch — EXIF-filtered, custom suffix, 8 threads ```bash viesus -l photos.lst -e -s -n "_pro" -p "professional.json" -b "enhanced" ``` *** ## Best practices * **Use image lists for large batches** — calling `-f` with thousands of files exceeds command-line length limits on Windows. * **Test on a small subset first** — validate your config before kicking off a 100,000-image run. * **Back up before `-i`** — it overwrites originals with no recovery path. * **Monitor disk space when using `-b`** — output files can match or exceed source size, especially after AI Upscaling. * **Use `-e` to skip non-photographic images** — improves throughput when the source contains screenshots or graphics. ## Performance tips * **Batch size**: process in batches that fit in memory rather than passing one giant list. * **Storage**: use SSD storage for both input and output paths to avoid I/O bottlenecks. * **Parallelism**: run multiple CLI instances in parallel rather than increasing threads inside one — single-threaded is fastest per image. See [Performance Tuning](/operations/performance-tuning.md). * **Network paths**: avoid processing over SMB / NFS where possible — copy locally, process, copy back. * **EXIF filtering**: `-e` saves time on heterogeneous source folders. For deeper guidance, see [Operations → Performance Tuning](/operations/performance-tuning.md) and [Benchmarks](/operations/benchmarks.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.viesus.com/reference/cli-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.