Skip to main content

Creating a Config Templates Repository

This page explains how to create a repository compatible with the config-templates provider type. This allows you to create reusable configuration templates and include files that can be shared across multiple Recyclarr configurations.

When You Need This​

Use the config-templates type when you want to:

  • Create reusable configuration snippets (includes) for quality profiles, custom format assignments, etc.
  • Build complete configuration templates for the recyclarr config create command
  • Share standardized configurations across teams or the community

Required Structure​

A config-templates compatible repository needs either includes.json, templates.json, or both at the repository root.

Directory Layout Example​

my-templates-repo/
├── includes.json              # Maps include IDs to YAML files
├── templates.json             # Maps template IDs to YAML files
├── radarr/
│   ├── includes/
│   │   └── quality-profiles/
│   │       ├── hd-bluray.yml
│   │       └── uhd-bluray.yml
│   └── templates/
│       └── movies-hd.yml
└── sonarr/
    ├── includes/
    │   └── quality-profiles/
    │       └── tv-hd.yml
    └── templates/
        └── tv-shows.yml

Include Files​

Includes are partial YAML configurations that can be referenced from your main config using the include directive.

The includes.json File​

Maps include IDs to their YAML file paths:

[
  {
    "id": "radarr-quality-hd",
    "template": "radarr/includes/quality-profiles/hd-bluray.yml",
    "hidden": false
  },
  {
    "id": "radarr-quality-uhd",
    "template": "radarr/includes/quality-profiles/uhd-bluray.yml",
    "hidden": false
  },
  {
    "id": "sonarr-quality-hd",
    "template": "sonarr/includes/quality-profiles/tv-hd.yml",
    "hidden": false
  }
]

Include JSON Fields​

FieldRequiredDescription
idYesUnique identifier used in config's include directive
templateYesPath to the YAML file relative to repository root
hiddenNoWhen true, hides from recyclarr list output. Default: false

Example Include YAML​

An include file contains partial configuration that gets merged into the main config:

# radarr/includes/quality-profiles/hd-bluray.yml
quality_profiles:
  - name: HD Bluray
    reset_unmatched_scores:
      enabled: true
    upgrade:
      allowed: true
      until_quality: Bluray-1080p
      until_score: 10000
    min_format_score: 0
    quality_sort: top
    qualities:
      - name: Bluray-1080p
      - name: Bluray-720p

Using Includes in Config​

Reference includes by their ID:

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: !secret radarr_api_key

    include:
      - template: radarr-quality-hd

Template Files​

Templates are complete configuration files used with the recyclarr config create command to scaffold new configurations.

The templates.json File​

Maps template IDs to their YAML file paths:

[
  {
    "id": "radarr-movies-hd",
    "template": "radarr/templates/movies-hd.yml",
    "hidden": false
  },
  {
    "id": "sonarr-tv-hd",
    "template": "sonarr/templates/tv-shows.yml",
    "hidden": false
  }
]

Template JSON Fields​

FieldRequiredDescription
idYesUnique identifier used with recyclarr config create -t
templateYesPath to the YAML file relative to repository root
hiddenNoWhen true, hides from recyclarr list output. Default: false

Example Template YAML​

A template file is a complete, working configuration:

# radarr/templates/movies-hd.yml
radarr:
  movies-hd:
    base_url: http://localhost:7878
    api_key: !secret radarr_api_key

    quality_definition:
      type: movie

    quality_profiles:
      - name: HD Movies
        reset_unmatched_scores:
          enabled: true
        upgrade:
          allowed: true
          until_quality: Bluray-1080p
          until_score: 10000
        min_format_score: 0
        quality_sort: top
        qualities:
          - name: Bluray-1080p
          - name: WEB 1080p
            qualities:
              - WEBDL-1080p
              - WEBRip-1080p

    custom_formats:
      - trash_ids:
          - ed38b889b31be83fda192888e2286d83  # BR-DISK
          - 90cedc1fea7ea5d11298bebd3d1d3223  # EVO (no WEBDL)
        assign_scores_to:
          - name: HD Movies

Using Templates​

Create a new config from a template:

recyclarr config create -t radarr-movies-hd

ID Naming Best Practices​

Since IDs must be globally unique across all providers, use descriptive prefixes:

  • Include IDs: radarr-quality-hd, sonarr-cf-anime
  • Template IDs: radarr-movies-4k, sonarr-anime-v4

If you're overriding official templates, use the exact same ID to replace them.

Using Your Repository​

Add your config-templates repository to settings.yml:

resource_providers:
  # As a supplemental source (adds to official)
  - name: my-templates
    type: config-templates
    clone_url: https://github.com/yourname/my-templates.git
    reference: main

  # Or as a replacement (replaces official)
  - name: my-templates
    type: config-templates
    clone_url: https://github.com/yourname/my-templates.git
    reference: main
    replace_default: true

For local directories:

resource_providers:
  - name: my-local-templates
    type: config-templates
    path: /home/user/my-templates

Reference Implementation​

The official Recyclarr config-templates repository serves as the reference implementation:

Overriding Official Templates​

To override an official include or template:

  1. Create your repository with the same structure
  2. Use the exact same ID as the official template you want to replace
  3. Add your repository to resource_providers

Since your provider is listed after the implicit official provider (bottom-up precedence), your version takes precedence for matching IDs.

resource_providers:
  - name: my-overrides
    type: config-templates
    clone_url: https://github.com/yourname/template-overrides.git
    reference: main

Any IDs in your repository that match official IDs will override them. IDs that don't match will be added alongside the official templates.