---
description: "Customize Patcher's PDF and HTML report branding. Header, footer, font, logo, and HTML accent color via the CLI wizard, plist, or PatcherClient."
---

(customization)=

# Customization

:::{rst-class} lead
Tailor Patcher's PDF and HTML reports to match your organization's branding.
:::

---

::::{highlights}
{iconify}`octicon:pencil-16` Header & Footer
: Set the title line and footer credit on every report.

{iconify}`octicon:typography-16` Font
: Swap in a custom typeface for the PDF.

{iconify}`octicon:image-16` Logo & Color
: Add a company logo and an HTML accent color.
::::

The sample below shows where each element ends up.

```{image} ../_static/example_pdf.png
:alt: Example PDF
:width: 750px
:align: center
```

:::{admonition} Important
:class: warning
UI customization affects **PDF and HTML reports only**. Excel and JSON exports never read these settings.
:::

## How Customization Works

Different methods to get to the same end result. Pick whichever fits your environment.

::::{tab-set}

:::{tab-item} {iconify}`mdi:bash` Interactive
:sync: wizard

```bash
$ patcherctl reset UI
```

The wizard prompts for header text, footer text, font choice, logo, and HTML header color. Patcher then writes the result to your property list. Run it once when onboarding, or any time you want to refresh your branding.
:::

:::{tab-item} {iconify}`material-icon-theme:xml` PlistBuddy
:sync: plist

```bash
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:header_text 'AnyOrg Patch Report'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```

Best for scripted provisioning where you want to seed Patcher's branding before any user runs the wizard. For the full plist schema (including non-UI keys), see {ref}`property_list_file`.
:::

:::{tab-item} {iconify}`material-icon-theme:python` Python
:sync: library

```python
from patcher import PatcherClient

async with PatcherClient(
    client_id="...",
    client_secret="...",
    server="https://yourorg.jamfcloud.com",
    ui_config={
        "header_text": "AnyOrg Patch Report",
        "footer_text": "Made with <3 from IT",
        "font_name": "Helvetica",
        "reg_font_path": "/path/to/Helvetica-Regular.ttf",
        "bold_font_path": "/path/to/Helvetica-Bold.ttf",
        "logo_path": "/path/to/logo.png",
        "header_color": "#6432bdff",
    },
) as patcher:
    titles = await patcher.fetch_patches()
    await patcher.export(titles, output_dir="~/reports", formats={"pdf"})
```

Pass values directly to {class}`~patcher.core.patcher_client.PatcherClient`. Values stay in memory for the lifetime of the client, nothing is written to disk, making it the natural fit for CI/CD pipelines, ephemeral runners, or services that need per-tenant branding.
:::
::::

## Customizable Elements

### Editing the Header & Footer Text

`header_text` sits at the top of every report. `footer_text` sits at the bottom of every PDF page with the page number appended automatically after it. Both are plain strings, no length restriction.

::::{tab-set}

:::{tab-item} {iconify}`material-icon-theme:xml` PlistBuddy
:sync: plist

```{code-block} bash
:caption: Set header text

$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:header_text 'AnyOrg Patch Report'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```
<br>

```{code-block} bash
:caption: Set footer text

$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:footer_text 'Made with <3 from IT'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```

:::

:::{tab-item} {iconify}`material-icon-theme:python` Python
:sync: library

```python
ui_config = {
    "header_text": "AnyOrg Patch Report",
    "footer_text": "Made with <3 from IT",
}
```

:::

::::

### Customizing the Font

The PDF font is controlled by a display name, and paths to the regular and bold weighted font files. The default is [Google's Assistant](https://fonts.google.com/specimen/Assistant) which is bundled with Patcher.

:::{caution}
Custom fonts can introduce alignment or spacing quirks in the PDF. Run a test export after switching to verify everything still lines up the way you expect.
:::

::::{tab-set}

:::{tab-item} {iconify}`material-icon-theme:xml` PlistBuddy
:sync: plist

```{code-block} bash
:caption: Configuring font options

# Font name
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:font_name 'Helvetica'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist

# Regular font
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:reg_font_path '/path/to/Helvetica-Regular.ttf'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist

# Bold font
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:bold_font_path '/path/to/Helvetica-Bold.ttf'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```

:::

:::{tab-item} {iconify}`material-icon-theme:python` Python
:sync: library

```python
ui_config = {
    "font_name": "Helvetica",
    "reg_font_path": "/path/to/Helvetica-Regular.ttf",
    "bold_font_path": "/path/to/Helvetica-Bold.ttf",
}
```

:::

::::

### Customizing the HTML Report Header Color

`header_color` is the accent color used on the HTML report's header banner. It accepts a hex string with or without the `#` prefix, and optionally an alpha channel (`#RRGGBBAA`). The default is `#6432bdff` (Patcher purple).

::::{tab-set}

:::{tab-item} {iconify}`material-icon-theme:xml` PlistBuddy
:sync: plist

```bash
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:header_color '#0071bc'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```

:::

:::{tab-item} {iconify}`material-icon-theme:python` Python
:sync: library

```python
ui_config = {
    "header_color": "#0071bc",
}
```

:::

::::

## Company Logo

A logo on the PDF report ties branding together. Patcher places the logo in the report header alongside the header text.

### Supported Logo Requirements

::::{markers}
:icon: octicon:check-16

:::{marker} File formats
PNG, JPEG, or any [Pillow-supported image format](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#fully-supported-formats).
:::

:::{marker} Validation
Patcher loads the file via Pillow before accepting it, so corrupt or unreadable images are rejected at runtime.
:::

:::{marker} Path requirements
Use an absolute path. The wizard copies the file to `~/Library/Application Support/Patcher/logo.png` and stores that path in the plist, so you only need the file to exist long enough for the copy.
:::
::::

:::{tip}
Need to generate a logo file from an existing icon? SAP's [`macOS-icon-generator`](https://github.com/SAP/macOS-icon-generator) produces standardized PNG icons at the right resolutions. To copy an absolute path from Finder: hold ⌥, right-click the file, and select **Copy "filename" as Pathname**.
:::

### Configuring a Logo

::::{tab-set}

:::{tab-item} {iconify}`mdi:bash` CLI wizard
:sync: wizard

```{code-block} bash
:caption: Prompt for logo path during UI walkthrough

$ patcherctl reset UI
```

If you provide one, Patcher copies the file to its Application Support directory and writes the resulting path to the plist.
:::

:::{tab-item} {iconify}`material-icon-theme:xml` PlistBuddy
:sync: plist

```bash
$ /usr/libexec/PlistBuddy \
  -c "Set :UserInterfaceSettings:logo_path '/path/to/logo.png'" \
  ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
```

If you set the path manually, copy the logo file somewhere stable yourself. Patcher won't move it.

:::

:::{tab-item} {iconify}`material-icon-theme:python` Python
:sync: library

```python
ui_config = {
    "logo_path": "/path/to/logo.png",
}
```

The path is consulted at export time. Make sure the file is readable by whatever process runs Patcher.

:::

::::

## Persistence

When you customize via the CLI (wizard or PlistBuddy), values are written to Patcher's property list and persist across runs. When you customize via the library (`ui_config=`), values stay in memory for the lifetime of the `PatcherClient` and disappear when the process exits.

For the full plist schema, the v2 format-change history, and details on every other key Patcher stores there, see {ref}`property_list_file`.