> 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/pdf-cli.md).

# PDF CLI

The VIESUS PDF Enhancer (`viesusPDF`) processes PDF documents containing embedded images. It opens the PDF, locates each embedded image, applies VIESUS enhancement (and optionally AI upscaling), writes the improved images back into a new PDF, and outputs a processing report. The document structure, layout, fonts, and vector elements are preserved — only the embedded raster images change.

PDF pipeline settings (hotfolder paths, resizing, file handling) live in the PDF Enhancer's own `settings.json` — see the [PDF Settings Reference](/configuration/pdf-settings.md). The per-image enhancement parameters come from `viesusini.json` (the [Parameter Reference](/configuration/parameter-reference.md)), exactly as with the image CLI.

***

## When to use the PDF Enhancer

Designed for PDFs from layout applications where images are embedded but not pre-rendered — typically photobooks, marketing catalogs, and print-ready files. It is **not** suitable for:

* Flattened / rasterized PDFs (all content is already pixels)
* Selectively enhancing only specific pages or elements — the enhancer processes all qualifying images
* Real-time request-response use — use the [Node.js module](/reference/node.js-module/overview.md) or [VIESUS Cloud](/reference/cloud-api/overview.md)

***

## Operating modes

`viesusPDF` runs in two modes:

* **Stand-alone** — process a file or folder once, from the command line. Suitable for scripted pipelines and one-time processing.
* **Hotfolder** — monitor a configured folder continuously and process PDFs as they arrive. Runs as a long-lived background process for print-production workflows.

***

## Information

<table><thead><tr><th width="156.39990234375">Flag</th><th>Description</th></tr></thead><tbody><tr><td><code>-v</code></td><td>Print version information and exit</td></tr></tbody></table>

***

## Hotfolder mode

Monitors a configured folder for new PDF files and processes them as they arrive. Use this for continuous production pipelines.

```bash
viesusPDF -h [-g <guid>] [options]
```

<table><thead><tr><th width="136.199951171875">Flag</th><th width="127.4000244140625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>-h</code></td><td>Yes</td><td>Start in hotfolder mode</td></tr><tr><td><code>-g &#x3C;guid></code></td><td>Optional</td><td>Start with a specific GUID (only for GUID-licensed libraries)</td></tr></tbody></table>

**Examples:**

```bash
# Start hotfolder
viesusPDF -h

# Start with specific GUID
viesusPDF -h -g 12345678-1234-1234-1234-123456789abc
```

Hotfolder behavior (watched folder, trigger files, archive paths) is configured in `settings.json`. See the [PDF Settings Reference](/configuration/pdf-settings.md).

***

## Stand-alone mode

Process one file or one folder of PDFs directly from the command line.

```bash
viesusPDF <source> <destFolder> <viesusIniFile> [options]
```

### Required positional arguments

<table><thead><tr><th width="104.2000732421875">Position</th><th width="161.9998779296875">Argument</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td><code>&#x3C;source></code></td><td>Path to PDF file or source folder</td></tr><tr><td>2</td><td><code>&#x3C;destFolder></code></td><td>Path to destination folder for processed files</td></tr><tr><td>3</td><td><code>&#x3C;viesusIniFile></code></td><td>Path to JSON file containing VIESUS enhancement settings</td></tr></tbody></table>

### Optional arguments

Optional flags can appear in any order after the required arguments.

#### File handling

<table><thead><tr><th width="150.5999755859375">Flag</th><th width="87.5999755859375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>deleteSrc</code></td><td>Flag</td><td>Delete source files after successful processing</td></tr><tr><td><code>archive &#x3C;path></code></td><td>String</td><td>Archive original files to the specified folder</td></tr><tr><td><code>useSoftMasked</code></td><td>Flag</td><td>Enable processing of images with soft masks</td></tr><tr><td><code>justAnalyze</code></td><td>Flag</td><td>Analyse and count images only (results go to status file)</td></tr></tbody></table>

#### Page processing

<table><thead><tr><th width="124.199951171875">Flag</th><th width="95.800048828125">Format</th><th>Description</th></tr></thead><tbody><tr><td><code>-s &#x3C;pages></code></td><td>String</td><td>Skip specified pages (stand-alone mode only)</td></tr></tbody></table>

**Page skip format:**

| Token  | Meaning              |
| ------ | -------------------- |
| `f`    | First page           |
| `l`    | Last page            |
| Number | Specific page number |

Example: `-s f,l,5,10,14` skips first, last, and pages 5, 10, 14.

#### Network and debugging

<table><thead><tr><th width="149.199951171875">Flag</th><th width="138.2000732421875">Type</th><th width="155.800048828125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>-p &#x3C;portNr></code></td><td>Integer</td><td><code>12033</code></td><td>Port number for TraceConsumer</td></tr></tbody></table>

#### Image processing

<table><thead><tr><th width="179">Flag</th><th width="104.2000732421875">Type</th><th width="97.60009765625">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>noResize</code></td><td>Flag</td><td>Off</td><td>Disable resizing of small images</td></tr><tr><td><code>-r &#x3C;targetRes></code></td><td>Integer</td><td><code>300</code></td><td>Target resolution in DPI for size calculations</td></tr><tr><td><code>-T &#x3C;resizeThres></code></td><td>Float</td><td><code>1.2</code></td><td>Minimum factor required to trigger resizing</td></tr></tbody></table>

***

## Examples

### Basic processing

```bash
viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json"
```

### With archive and source deletion

```bash
viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" deleteSrc archive "C:\archive"
```

### Skip specific pages

```bash
viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -s "1,3,5"
```

### Analysis only

```bash
viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" justAnalyze
```

### Custom resolution and resize threshold

```bash
viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -r 600 -T 1.5
```

### Production batch with all options

```bash
viesusPDF "C:\batch\pdfs" "C:\enhanced" "C:\settings\config.json" deleteSrc archive "C:\backup" useSoftMasked -r 400 -T 1.3 -p 15000
```

***

## Processing workflow

```mermaid
flowchart LR
  A[PDF Input] --> B[PDF Enhancer]
  B --> C{For each\nembedded image}
  C --> D[VIESUS Enhancement\n± AI Upscaling]
  D --> E[Write back to PDF]
  E --> F[Enhanced PDF Output]
  B --> G[XML Processing Report]
```

1. PDF opened and analyzed
2. Each embedded raster image is extracted
3. VIESUS enhancement applied (color, sharpening, noise reduction, face processing)
4. Optional AI upscaling to target print resolution
5. Enhanced images written back into the PDF structure
6. Enhanced PDF and XML report written to the destination

***

## Output files

<table><thead><tr><th width="214">File</th><th>Description</th></tr></thead><tbody><tr><td><code>&#x3C;filename>_dest.pdf</code></td><td>Enhanced PDF with improved images</td></tr><tr><td><code>&#x3C;filename>.pdf.xml</code></td><td>Processing report: image counts, statistics, error codes</td></tr></tbody></table>

The XML file is written last — an upstream system can watch for it as a completion signal.

***

## Argument details

### Source path

* **File** — processes a single PDF
* **Folder** — processes every PDF in the directory

The source must be accessible and contain valid PDFs.

### Destination folder

Must exist or be creatable by the application. Processed PDFs are written here with the same internal structure as the source.

### Configuration file

A JSON file containing VIESUS enhancement parameters. See the [PDF Settings Reference](/configuration/pdf-settings.md) for the full schema.

### Archive behavior

When `archive <path>` is specified, originals are copied to the archive folder **before** processing. The archive folder is created if it doesn't exist.

### Page skipping

Stand-alone mode only. Useful for excluding cover pages, blank pages, or known non-image content. Pages are numbered from 1.

### Resize logic

* Images below the target resolution are candidates for resizing.
* `-T resizeThres` is the minimum scale factor required to trigger enhancement — below this, the image is left untouched.
* `noResize` disables resizing entirely.

***

## Platform support

| Platform                  | Support |
| ------------------------- | ------- |
| Windows 10 / Server 2016+ | ✓       |
| Ubuntu 22.04+             | ✓       |
| Linux arm64               | ✓       |

***

## Best practices

* **Validate paths** before kicking off a batch — broken paths waste hours.
* **Use folder input for batches** — better throughput than scripting one-PDF-at-a-time.
* **Archive originals** for important workloads. Disk is cheap; lost source PDFs are expensive.
* **Set resize thresholds appropriately** — too low wastes compute; too high misses beneficial enhancements.
* **Monitor memory** with large PDFs that contain many embedded images.

## Performance considerations

* **Memory** — large PDFs with many embedded images can require significant memory; size your worker accordingly.
* **Resize threshold** — higher values reduce processing time at the cost of missed enhancements.
* **Soft masks** (`useSoftMasked`) — improves quality but increases processing time.
* **GPU** — multi-threading is not possible when using GPU features on a single GPU; scale with multiple instances/GPUs.
* **Network paths** — avoid SMB / NFS where possible.
* **`checkAdjacentImages`** — disable for complex PDFs with many small images.
* **`streamReading`** — disable when processing PDFs with compressed image content.
* **AI upscaling** — all modes except mode 6 significantly increase processing time.
* **`maxFactor`** — limit to prevent excessive memory usage on large embedded images.
* **`debug`** — disable in production.


---

# 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/pdf-cli.md?ask=<question>&goal=<endgoal>
```

`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.