pdf-editor-compdf

# PDF Editor — PDF Document Processing CLI Tool

## Platform Detection (Agent must execute automatically)

Before running any CLI command, the Agent must automatically detect the platform (read `env.platform`: `win32`→Windows, `darwin`→Mac; or run `uname -s`). **Do NOT ask the user about their platform.**

| Variable | [Windows] | [Mac] |
|------|-----------|-------|
| `<CLI>` | `{skill_root}/scripts/win/compdf_cli.exe` | `{skill_root}/scripts/mac/compdf_cli` |
| `<LICENSE_PATH>` | `{skill_root}/scripts/win/license_key_windows.xml` | `{skill_root}/scripts/mac/license_key_mac.xml` |
| `<LICENSE_API_BODY>` | `{"email":"<email>"}` | `{"email":"<email>"}` |
| `<ICC_SRGB>` | `{skill_root}/scripts/win/PDFA/sRGB2014.icc` | `{skill_root}/scripts/mac/PDFA/sRGB2014.icc` |
| `<ICC_FOGRA>` | `{skill_root}/scripts/win/PDFA/CoatedFOGRA39.icc` | `{skill_root}/scripts/mac/PDFA/CoatedFOGRA39.icc` |
| Shell syntax | `cmd` + `REM` | `bash` + `#` |

> `{skill_root}` = the absolute path of the directory containing this SKILL.md.

## CLI Download & Installation (Required on first use)

The CLI binary is not included in the Skill package. It is downloaded from the **official ComPDFKit distribution server** (`download.compdf.com`) operated by PDF Technologies, Inc. The Agent must complete the following steps before the first execution:

1. Check whether `<CLI>` exists → skip if it does
2. **Inform the user** that the CLI binary will be downloaded from `download.compdf.com` (official ComPDFKit CDN)
3. Download the appropriate archive for the platform:
   - **[Windows]**: `https://download.compdf.com/skills/winCLI/win.zip`
   - **[Mac]**: `https://download.compdf.com/skills/macCLI/mac.zip`
4. Extract the archive to the `{skill_root}/scripts/` directory (the zip already contains a `win/` or `mac/` prefix, so the correct directory structure is formed automatically after extraction)
5. **[Mac]** After extraction, run: `chmod +x {skill_root}/scripts/mac/compdf_cli`
6. Verify: run `<CLI> --help` to confirm the binary is executable

> Download is performed once on first use only; no re-download is needed on subsequent runs.

## License Activation (Required on first use)

1. Check whether `<LICENSE_PATH>` exists → skip if it does
2. Ask the user for their email address (explain: the email is sent to the official ComPDFKit license server to obtain a free trial license; **no other data is transmitted**)
3. **After the user confirms**, send `POST https://wms.compdf.com/api/license/skillsTrial`, Body: `<LICENSE_API_BODY>`
   - `code=200`: write the `data.license` XML to `<LICENSE_PATH>`
   - `code=500`: prompt the user to retry with a different email address
4. Run `<CLI> --help` to verify activation

## Common Options

The following options apply to **all commands** (they are not repeated in individual command references):

| Option | Description | Default |
|------|------|--------|
| `--output, -o <path>` | Output file path or directory | Directory of the input file |
| `--name <filename>` | Output filename | `{original_filename}_{command_name}.pdf` |
| `--overwrite` | Allow overwriting existing files | No |

## Command Reference

### split — Split PDF

`<CLI> split <input.pdf> [options]`

| Option | Description | Default |
|------|------|--------|
| `--mode <all\|range>` | `all`=split into individual pages, `range`=split by range | `all` |
| `--range <range>` | Page range, e.g. `"1-3"` (range mode only) | — |

Output naming: `all` → `{original_filename}_page_{page_number}.pdf`; `range` → `{original_filename}_pages_{start}-{end}.pdf`

### merge — Merge PDFs

`<CLI> merge <file1.pdf> <file2.pdf> [file3.pdf ...] [options]`

> Encrypted PDFs are skipped automatically; if fewer than 2 unencrypted files remain, the command fails.

### extract — Extract Pages

`<CLI> extract <input.pdf> --range <range> [options]`

| Option | Description |
|------|------|
| `--range <range>` | **Required**, e.g. `"2-5"` or `"3"` |

### rotate — Rotate Pages

`<CLI> rotate <input.pdf> --pages <range> --angle <90|180|270> [options]`

| Option | Description |
|------|------|
| `--pages <range>` | Required, page range |
| `--angle <90\|180\|270>` | Required, rotation angle |

### delete — Delete Pages

`<CLI> delete <input.pdf> --pages <range> [options]`

| Option | Description |
|------|------|
| `--pages <range>` | Required, page range to delete |

### insert — Insert Pages/Images

```
<CLI> insert <target.pdf> --source <source.pdf> --pages <range> --at <position> [options]
<CLI> insert <target.pdf> --image <imagePath> --at <position> --width <width> --height <height> [options]
```

| Option | Description |
|------|------|
| `--source <source.pdf>` | Source PDF (mutually exclusive with `--image`) |
| `--image <imagePath>` | Image path (mutually exclusive with `--source`) |
| `--pages <range>` | Page range from the source PDF; `--source` mode only |
| `--at <position>` | Required, insert before page N (1-based) |
| `--width <width>` / `--height <height>` | Image page dimensions; `--image` mode only (A4: 595×842) |

### convert — Standard Format Conversion

`<CLI> convert <input.pdf> --standard <format> [options]`

| Option | Description | Default |
|------|------|--------|
| `--standard` | **Required**: `pdfa-1a` `pdfa-1b` `pdfa-2a` `pdfa-2b` `pdfa-2u` `pdfx-4` `pdfe-1` `pdfua-1` | — |
| `--icc <path>` | ICC profile file | `<ICC_SRGB>` or `<ICC_FOGRA>` |
| `--title <title>` | PDF/UA title (`pdfua-1` only) | Input filename |
| `--language <language>` | PDF/UA language (`pdfua-1` only) | Win: `en-US` / Mac: `en` |

`--language` supported values: Win `en-US`/`zh-CN`/`ja-JP`/`ko-KR`/`fr-FR`/`de-DE` | Mac `en`/`zh`/`ja`/`ko`

**Examples**:
```
<CLI> convert "report.pdf" --standard pdfa-1a --overwrite
<CLI> convert "report.pdf" --standard pdfua-1 --title "My Document" --language zh-CN --overwrite
```

### optimize — Document Optimization & Compression

`<CLI> optimize <input.pdf> [options]`

| Option | Description | Default |
|------|------|--------|
|