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

# 2. Invocation fundamentals

```
java -jar java-epic-cli.jar [options] <mode ...> <source> [output]
```

## Java runtime

- Built for **Java 8 bytecode**; verified on JDK 8, 11, 17, and 23.
- **Never run on the JDK 21 line.** A `java.awt.geom.Area` regression in JDK 21 fragments
  `--extract-objects` output roughly 55×. Pin production to 8/11/17/23.
- Memory: the jar uses bounded-scratch PDF handling and is deliberately frugal. Most modes
  run real production files at `-Xmx768m`; `--backers` has run at ~96 MB; preflighting a
  76 MB Illustrator master needs ~256 MB. Don't reflexively hand it multi-GB heaps.

## Mode grammar

- Leading mode flags are **case-insensitive and prefix-matched** (`--PREFLIGHT` works).
- **Transform modes combine** and run in the order given:
  `--rotate90 --mirror in.pdf out.pdf` rotates then mirrors.
- If a **listing mode** (`--list-spot-colors` / `--list-process-colors`) appears anywhere in
  the command, every other mode is skipped — listings are read-only and exclusive.
- **Standalone modes** (`--spool`, `--compile`, `--vectorize`/`--rvp`, `--extract-objects`,
  `--simplify-curves`, `--backers`, `--derivatives`) have their own option surfaces and do
  not combine with anything else. The ones that take a primary argument take it with `=`:
  `--compile=req.json`, `--backers=art.pdf`, `--derivatives=batch.zip`. The positional form
  (`--backers art.pdf`) is an error: you get `{"status":"error","reason":"unknown option:
  ..."}` on stdout and exit 1. (`--extract-objects` accepts both `--extract-objects=f.pdf`
  and `--extract-objects f.pdf` — bare non-flag arguments there are promoted to `--input=`.)
- **Omitting `[output]` on a transform overwrites the source in place.** Always pass an
  output path unless in-place editing is genuinely what you want.
- Report modes never modify the source.

## stdout / stderr / exit codes

**stdout is machine output.** Report and standalone modes print exactly one JSON document to
stdout; all diagnostics go to stderr. Never merge the streams (`2>&1`) into something you
parse.

| Exit | Meaning |
|---|---|
| `0` | Success. For `--derivatives` this includes partially-failed batches (per-dataset status in the JSON). |
| `1` | Command syntax / usage error, or a failed `--compile`/`--simplify-curves` run (error JSON on stdout). |
| `2` | File, S3, or environment fault (unreadable input, missing credentials, unreadable package). |
| `3` | `--imposition` only: a placement `recolor` entry named a separation the source PDF doesn't contain. The message lists the separations the file actually has. |

`--quiet` (alias `--q`) suppresses all stdout/stderr; the exit code becomes the only result —
**except `--compile`, which always prints its single JSON result object** regardless.

`--version` prints the version and exits.

## The help system

```
java -jar java-epic-cli.jar --help              # mode overview
java -jar java-epic-cli.jar --help=<topic>      # preflight | colors | thin-line | split |
                                                # transforms | imposition | s3 | spooler |
                                                # compile | vectorize | backers | derivatives
java -jar java-epic-cli.jar --vectorize --help              # RVP's own page
java -jar java-epic-cli.jar --vectorize --help=<topic>      # colour | antialiasing |
                                                            # outlines | examples
```

The RVP sub-topics are genuinely worth reading — they are short essays on why the tracer
behaves the way it does (Lab-space color decisions, antialiasing recovery, coverage tracing).

## S3 everywhere

Anywhere a file path is accepted — `<source>`, `[output]`, `--imposition` plans, `--compile`
requests and artwork references, `--thin-line` overlays — an S3 URL may be used instead:

```
s3://bucket-name/path/to/object.pdf
aws://bucket-name/path/to/object.pdf     (same meaning)
```

Sources are downloaded to a temp directory before processing; outputs are uploaded when
processing finishes. Multi-file modes (`--split`, `--thin-line`) upload each produced file
individually, expanding the page number into the object key. S3 paths without credentials
fail with exit 2.