# Apply an overlay

Speakeasy provides two options for applying overlays:

- Option One: Add the overlay directly to the Speakeasy workflow file, ensuring automatic application with every generation
- Option Two: Output a new OpenAPI document with the overlay applied, creating an updated reference document

## Option One: Add an overlay to a Speakeasy workflow

The Speakeasy workflow supports using an overlay file to modify a source OpenAPI document. For more information on sources, refer to the documentation on [core Speakeasy concepts](/docs/sdks/core-concepts#sources).

### 1. Install the Speakeasy CLI

```bash
brew install speakeasy-api/tap/speakeasy
```

### 2. Choose the source 

Run `speakeasy configure sources` and select or create a source to add an overlay to the Speakeasy workflow file.

### 3. Add an overlay

### 4. Provide the overlay file path

/>

The overlay will now apply to the OpenAPI document as part of the Speakeasy workflow. Execute the workflow by running `speakeasy run`.

## Option Two: Create a new OpenAPI document with an overlay

Creating a new OpenAPI document provides the ideal option for generating a new reference document.

### 1. Install the Speakeasy CLI

```bash
brew install speakeasy-api/tap/speakeasy
```

### 2. Validate the overlay

Validate the overlay before applying it to ensure adherence to the OpenAPI Overlay Specification using this command:

```bash
speakeasy overlay validate -o overlays.yaml
```

### 3. Apply the overlay

Apply the overlay to the OpenAPI document with this command. Replace `input-openapi.yaml` with the path to the original OpenAPI document, and `overlays.yaml` with the path to the overlay file:

```bash
speakeasy overlay apply -s input-openapi.yaml -o overlays.yaml > combined.yaml
```

This command merges changes from the overlay file with the original OpenAPI document and outputs the result to a new file named `combined.yaml`.

### 4. Review the merged results

The `combined.yaml` file contains the original OpenAPI document updated with modifications from the overlay. Review this file to confirm changes are applied as expected.