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