*Epic CLI Manual — [index](../MANUAL.md)*

# 4. Report modes

## 4.1 `--preflight`

```
java -jar java-epic-cli.jar --preflight <source>
```

The master intake report — one JSON document on stdout describing everything downstream
production needs to know. The source is never modified. This is the mode both consumer
codebases parse most heavily; its schema is the most contract-bound thing the tool ships.

**Document level:**

| Field | Meaning |
|---|---|
| `size`, `name` | File size and name. |
| `creator`, `author`, `title`, `subject`, `keywords` | PDF Info metadata. |
| `variables` | Illustrator template variables parsed out of the AI private data (Artwork template support) — name plus current value per variable. |

**Per page:**

| Field | Meaning |
|---|---|
| `rotationInDegrees` | Page rotation. |
| `mediaBox`, `cropBox`, `bleedBox`, `trimBox`, `artBox`, `boundingBox` | Page geometry, points (1/72"). |
| `rgbColorspacesExist`, `cmykColorspacesExist`, `grayscaleColorspacesExist`, `spotColorspacesExist` | Which color families appear on the page — **including inside raster images and recursively inside nested form XObjects**. |
| `processColors` | CMYK channel usage (see 4.3). |
| `spotColors` | Spot color list with CMYK equivalents, `utilized`, and (when applicable) `hiddenOnly` (see 4.2). |
| `liveTextExists`, `fonts` | Live text presence and a per-font report: name, `embedded`, `subset`. |
| `vectorElementsExist`, `strictlyVector` | Vector content flags. |
| `rasterImagesExist`, `rasterImages`, `minimumEffectiveDpi` | Raster inventory: per-image pixel dimensions, placed size, `effectiveDpiX`/`effectiveDpiY`; the document-level worst case in `minimumEffectiveDpi`. |
| `thinLine`, `thinLineContour` | Populated only when combined with `--thin-line` (see 4.4). |

```
java -jar java-epic-cli.jar --preflight artwork.pdf > report.json
java -jar java-epic-cli.jar --preflight s3://artwork-bucket/incoming/job42.pdf
```

**Reading the report defensively:** if spot detection or thin-line data ever looks emptier
than the file plainly warrants, suspect a stale or dirty-tree jar build before suspecting the
data — see [§15](15-troubleshooting-and-landmines.md).

## 4.2 `--list-spot-colors`

```
java -jar java-epic-cli.jar --list-spot-colors <source>
```

JSON array of every spot (Separation / DeviceN colorant) color defined in the document, in
discovery order: `name`, CMYK equivalent (from the colorspace's tint transform), `utilized`.

**`utilized` semantics** — the flag answers "does this ink actually appear on a page?":

- vector fills and strokes count;
- usage nested inside form XObjects counts (the walker is recursive);
- raster images whose colorspace is that spot count — and their **pixels are sampled**, so a
  plate that is present but entirely blank reports `utilized: false`. A grayscale image with
  a spot swatch applied in Illustrator is detected.

**`hiddenOnly` (additive field):** a color additionally reports `hiddenOnly: true` when every
use of it sits inside optional content that the document's default configuration switches OFF
(`OCProperties /D /OFF`) — ink an OC-honoring RIP will not render. Typical sources: a hidden
`!` backer plate emitted by the `--backers` OCG fallback, or any Illustrator-saved file with a
hidden layer. The field is absent otherwise, and `utilized` stays `true` for such ink — it is
painted, just switched off.

## 4.3 `--list-process-colors`

```
java -jar java-epic-cli.jar --list-process-colors <source>
```

JSON report of CMYK process channel usage — which of cyan/magenta/yellow/black actually
carry ink, from both vector art and raster image data.

## 4.4 `--thin-line=P:N[:MODE]`

```
java -jar java-epic-cli.jar --thin-line=0.5:0.75 artwork.pdf overlays.png
java -jar java-epic-cli.jar --thin-line=0.5:0.75:contour artwork.pdf s3://bucket/tl/p%d.png
```

Finds strokes thinner than `P` points (**positive** / ink violations) and gaps or knockouts
narrower than `N` points (**negative** violations) — both cause problems on press (broken
hairlines, plugged counters). Writes one violation-overlay PNG per page to `[output]` and a
JSON report per page to stdout.

- `MODE` = `raster` (default; rendered-pixel analysis) or `contour` (vector contour
  analysis). The two populate `thinLine` / `thinLineContour` respectively when combined with
  `--preflight`.
- The per-page JSON carries the spec values echoed back (`positiveSpecPt`,
  `negativeSpecPt`), violation booleans, and the measured minima: `minPositiveWidthPt`,
  `minNegativeGapPt`, plus per-direction chord minima (`minPositiveChordHPt/VPt/D45Pt/D135Pt`
  and the negative equivalents) and the coordinates where the worst case was found
  (`minPositiveXPt/YPt`, `minNegativeXPt/YPt`).
- **Output naming:** multi-page documents expand the page number into `[output]` — a `%d`
  token is replaced with the 1-based page number, otherwise `_N` is inserted before the
  extension (`overlays.png` → `overlays_1.png`, `overlays_2.png`). With an S3 output each
  overlay is uploaded individually.