Skip to main content

Value Substitution

Recyclarr supports substituting dynamic values into your configuration YAML files. This keeps sensitive data like API keys out of your config files and enables configuration sharing without manual redaction.

Two substitution methods are available:

  • Secrets: Values stored in a secrets.yml file
  • Environment Variables: Values from your shell environment

Both use YAML tags to substitute values at runtime.

Secrets​

Secrets are defined in a secrets.yml file located in your application data directory. This file is optional.

Defining Secrets​

Define secrets as key/value pairs:

# secrets.yml
sonarr_url: http://localhost:8989
sonarr_apikey: f7e74ba6c80046e39e076a27af5a8444
radarr_url: http://localhost:7878
radarr_apikey: bf99da49d0b0488ea34e4464aa63a0e5

Key names can be anything you want, but must be unique within the file.

Using Secrets​

Reference secrets in your configuration using !secret <key_name>:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey
warning

Recyclarr fails to load configuration if a referenced secret key doesn't exist in secrets.yml.

Implicit Base URL and API Key​

The base_url and api_key properties can be set implicitly using a naming convention:

  • Base URL: <instance_name>_base_url
  • API Key: <instance_name>_api_key

Where <instance_name> matches your instance name in the config file.

Precedence​

Explicit values in your configuration always take precedence over implicit secrets. Implicit values are only used when the properties are omitted from your config.

Example​

With this secrets.yml:

movies_base_url: http://localhost:7878
movies_api_key: 2424b3643507485ea2e06382d3f0b8a3

You can omit base_url and api_key from your config:

radarr:
  movies:
    # base_url and api_key are set implicitly from secrets
    quality_definition:
      type: movie

Environment Variables​

Version Requirement

Environment variable substitution was introduced in v4.3.0.

Syntax​

!env_var VARIABLE_NAME optional_default

Where:

  • VARIABLE_NAME is the environment variable name (case-sensitive)
  • optional_default is used when the variable is undefined, empty, or whitespace-only

Usage​

radarr:
  movies:
    base_url: !env_var RADARR_URL
    api_key: !env_var RADARR_API_KEY
warning

Without a default value, Recyclarr fails to load configuration if the environment variable is missing or empty.

Default Values​

Defaults can include spaces:

!env_var MY_VAR default value here

Quotes around defaults are stripped (but not required for spaces):

!env_var MY_VAR "my default value"
# Results in: my default value

Choosing a Method​

Use secrets when:

  • You want the implicit URL/key feature
  • You share configs and want a single redaction point
  • You prefer file-based configuration

Use environment variables when:

  • Running in containers or Kubernetes where env vars are standard
  • You need default fallback values
  • You want to avoid managing an extra file