### Installing and Running the Buildarr Plugin (Bash)

Source: https://context7.com/buildarr/buildarr/llms.txt

This bash script demonstrates the basic steps for installing and running the Example Buildarr plugin. It first installs the plugin using pip and then executes the `buildarr run` command, which automatically discovers and loads the registered plugin.

```bash
# Install plugin
pip install buildarr-example

# Plugin is automatically discovered by Buildarr
buildarr run

# Output will show loaded plugin:

```

--------------------------------

### Buildarr Instance Configuration for Sonarr

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

An example `buildarr.yml` configuration file that defines settings for Buildarr itself and specifies the connection details for a Sonarr instance. This includes watch configuration, update schedules, and instance-specific Sonarr settings.

```yaml
---

buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

sonarr:
  # Configuration common to all Sonarr instances can be defined here.
  # settings:
  #   ...
  instances:
    # Name of the instance as referred to by Buildarr.
    # Assign instance-specific configuration to it.
    sonarr:
      hostname: "sonarr"
      port: 8989
      protocol: "http"
      # Define instance-specific Sonarr settings here.
      settings:
        ...

```

--------------------------------

### Docker Compose Configuration for Buildarr and Sonarr

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

An example `docker-compose.yml` file demonstrating how to configure services for Buildarr and a Sonarr instance. It specifies images, container names, restart policies, ports, volumes, environment variables, and service dependencies.

```yaml
version: "3.7"

services:
  sonarr:
    image: linuxserver/sonarr:3.0.9
    container_name: sonarr
    restart: always
    ports:
      - 127.0.0.1:8989:8989
    volumes:
      - ./sonarr:/config
      - /path/to/downloads:/downloads
      - /path/to/videos:/videos
    environment:
      TZ: Pacific/Auckland
      PUID: "1000"
      PGID: "1000"

  buildarr:
    image: callum027/buildarr:latest
    container_name: buildarr
    restart: always
    volumes:
      - type: bind
        source: ./buildarr
        target: /config
        read_only: true
    environment:
      TZ: Pacific/Auckland
      PUID: "1000"
      PGID: "1000"
    depends_on:
      - sonarr

```

--------------------------------

### Run Buildarr as Daemon (Python)

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Starts Buildarr in daemon mode for scheduling periodic updates. This ensures that your stack is regularly synchronized. Assumes Buildarr is installed and configured.

```bash
buildarr daemon
```

--------------------------------

### Buildarr Example YAML Configuration for Sonarr

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

An example of a `buildarr.yml` file demonstrating how to configure Buildarr settings and a Sonarr instance. It specifies watch intervals and Sonarr instance details including hostname, port, protocol, and general settings.

```yaml
---
# buildarr.yml
# Buildarr example configuration file.

# Buildarr configuration (all settings have sane default values)
buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

# Sonarr instance configuration
sonarr:
  hostname: "localhost"
  port: 8989
  protocol: "http"
  settings:
    # General settings (all options supported except for changing the API key)
    general:
      hostname:
        instance_name: "Sonarr (Buildarr Example)"

```

--------------------------------

### Buildarr Configuration File Example (YAML)

Source: https://context7.com/buildarr/buildarr/llms.txt

An example of a basic Buildarr configuration file using YAML format. This file defines the settings for a single instance of an *Arr application.

```yaml
---
# buildarr.yml

```

--------------------------------

### Example Plugin Configuration Models (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

These Python classes define the configuration structure for the Example Buildarr plugin. `ExampleInstanceConfig` handles settings for individual instances, including connection details and linking to other services. `ExampleConfig` provides global settings and supports multi-instance configurations.

```python
# buildarr_example/config/__init__.py
from typing import Optional
from typing_extensions import Self, Annotated

from buildarr.config import ConfigPlugin
from buildarr.types import NonEmptyStr, Port, InstanceReference

class ExampleInstanceConfig(ConfigPlugin["ExampleSecrets"]):
    """
    Configuration for an Example application instance.
    """

    # Connection settings
    hostname: NonEmptyStr = "example"
    port: Port = 7878
    protocol: str = "http"
    api_key: Optional[str] = None

    # Link to another instance (creates dependency)
    prowlarr_instance: Annotated[
        Optional[str],
        InstanceReference("prowlarr")
    ] = None

    @property
    def host_url(self) -> str:
        """Build the base URL for API requests."""
        return f"{self.protocol}://{self.hostname}:{self.port}"

    @classmethod
    def from_remote(cls, secrets: "ExampleSecrets") -> Self:
        """
        Fetch configuration from remote instance.
        """
        from ..api import api_get

        # Fetch remote configuration
        remote_config = api_get(secrets, "/api/v3/config")

        # Parse using remote map helper
        local_attrs = cls.get_local_attrs(
            remote_map=cls._remote_map,
            remote_attrs=remote_config,
        )

        return cls(**local_attrs)

    def update_remote(
        self,
        tree: str,
        secrets: "ExampleSecrets",
        remote: Self,
    ) -> bool:
        """
        Update remote instance configuration.

        Returns True if changes were made.
        """
        from ..api import api_put

        # Compare local and remote, get changes
        updated, updated_attrs = self.get_update_remote_attrs(
            tree=tree,
            remote=remote,
            check_unmanaged=True,
        )

        if updated:
            # Push changes to remote
            api_put(secrets, "/api/v3/config", updated_attrs)
            return True

        return False

class ExampleConfig(ConfigPlugin["ExampleSecrets"]):
    """
    Global plugin configuration with multi-instance support.
    """

    # These become defaults for all instances
    hostname: NonEmptyStr = "example"
    port: Port = 7878
    protocol: str = "http"

    # Multi-instance support
    instances: Dict[str, ExampleInstanceConfig] = {}

```

--------------------------------

### Install Buildarr Standalone (Python)

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Installs Buildarr as a standalone Python application within a virtual environment. Requires Python 3.8+. This method is recommended for users who want to integrate Buildarr into existing setups managed by configuration management tools.

```bash
python3 -m venv buildarr-venv
. buildarr-venv/bin/activate
python3 -m pip install buildarr
```

--------------------------------

### Example Buildarr Configuration

Source: https://github.com/buildarr/buildarr/blob/main/docs/usage.md

An example of a Buildarr YAML configuration file. This file defines services like Sonarr, specifying instance names, settings, media management, and import list configurations. It serves as the input for generating a Docker Compose file.

```yaml
---
sonarr:
  instances:
    sonarr-hd: {}
    sonarr-4k:
      settings:
        media_management:
          root_folders:
            - /tmp/videos
        profiles:
          language_profiles:
            definitions:
              English:
                languages:
                  - "English"
        import_lists:
          definitions:
            "Sonarr (HD)":
              type: "sonarr"
              root_folder: "/tmp/videos"
              quality_profile: "Any"
              language_profile: "English"
              full_url: "http://sonarr-hd:8989"
              instance_name: "sonarr-hd"

```

--------------------------------

### Buildarr Example YAML Configuration for Sonarr

Source: https://github.com/buildarr/buildarr/blob/main/README.md

An example `buildarr.yml` file demonstrating how to configure Buildarr's update schedule and settings for a Sonarr instance. This configuration specifies watch settings, update days and times, and Sonarr's general instance settings.

```yaml
---
# buildarr.yml
# Buildarr example configuration file.

# Buildarr configuration (all settings have sane default values)
buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

# Sonarr instance configuration
sonarr:
  hostname: "localhost"
  port: 8989
  protocol: "http"
  settings:
    # General settings (all options supported except for changing the API key)
    general:
      host:
        instance_name: "Sonarr (Buildarr Example)"

```

--------------------------------

### Define Buildarr Plugin Entry Points using Setuptools

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

Examples demonstrating how to define entry points for Buildarr plugins using different Setuptools configuration files (setup.py, setup.cfg, pyproject.toml). This allows Buildarr to discover and load custom plugins.

```python
from setuptools import setup

setup(
    # ...,
    entry_points={
        "buildarr.plugins": [
            "example = buildarr_example.plugin:ExamplePlugin",
        ],
    },
)
```

```ini
[options.entry_points]
buildarr.plugins =
    example = buildarr_example.plugin:ExamplePlugin
```

```toml
[project.entry-points."buildarr.plugins"]
"example" = "buildarr_example.plugin:ExamplePlugin"
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

This command installs the pre-commit hooks for the Buildarr project, which automatically format code and check for type consistency before each commit.

```bash
$ pre-commit install
```

--------------------------------

### Example Plugin Manager Implementation (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

This Python code defines the manager class for the Example Buildarr plugin. `ExampleManager` inherits from `buildarr.manager.ManagerPlugin` and is intended for implementing custom logic for plugin operations. The provided example shows that default implementations handle most common tasks, and overrides are only necessary for specific custom behavior.

```python
# buildarr_example/manager.py
from buildarr.manager import ManagerPlugin
from .config import ExampleConfig
from .secrets import ExampleSecrets

class ExampleManager(ManagerPlugin[ExampleConfig, ExampleSecrets]):
    """
    Manager for Example plugin operations.

    Most methods can use the default implementations from ManagerPlugin.
    Override only if custom behavior is needed.
    """

    # Default implementations handle:
    # - get_instance_config(): Merge global and instance configs
    # - uses_trash_metadata(): Check TRaSH metadata usage
    # - render(): Render dynamic attributes
    # - is_initialized()/initialize(): Instance initialization
    # - from_remote(): Fetch remote config
    # - update_remote(): Update remote instance
    # - delete_remote(): Remove unmanaged resources
    # - to_compose_service(): Generate Docker Compose service

    pass
```

--------------------------------

### Run Buildarr Standalone (Python)

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Executes Buildarr to update a stack after installation and configuration. This command initiates a one-time update process. For scheduling periodic updates, use the 'daemon' command.

```bash
buildarr run
```

--------------------------------

### Buildarr Daemon: Start, Watch, and Schedule Configuration Management

Source: https://context7.com/buildarr/buildarr/llms.txt

Starts Buildarr as a continuous configuration management service. Options include specifying a custom config file, enabling file watching for immediate updates, configuring update schedules (day and time), and setting the log level.

```bash
# Start daemon with default config (buildarr.yml)
buildarr daemon

# Specify custom config file
buildarr daemon /path/to/config.yml

# Enable config file watching for immediate updates
buildarr daemon --watch

# Configure update schedule
buildarr daemon --update-day monday --update-day wednesday --update-time 03:00

# Set log level
buildarr --log-level DEBUG daemon

# Expected output:
# 2023-11-12 10:00:29,220 buildarr:1 buildarr.cli.daemon [INFO] Buildarr version 0.7.0 (log level: INFO)
# 2023-11-12 10:00:29,220 buildarr:1 buildarr.cli.daemon [INFO] Loading configuration file '/config/buildarr.yml'
# 2023-11-12 10:00:29,775 buildarr:1 buildarr.cli.daemon [INFO] Finished loading configuration file
# 2023-11-12 10:00:29,779 buildarr:1 buildarr.cli.daemon [INFO] Applying initial configuration
# 2023-11-12 10:00:39,850 buildarr:1 buildarr.config.base [INFO] <sonarr> (default) sonarr.settings.general.host.instance_name: 'Sonarr' -> 'Sonarr (Buildarr Example)'
# 2023-11-12 10:00:52,875 buildarr:1 buildarr.cli.daemon [INFO] The next run will be at 2023-11-13 03:00
# 2023-11-12 10:00:52,875 buildarr:1 buildarr.cli.daemon [INFO] Buildarr ready.
```

--------------------------------

### Pull Buildarr Docker Image

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Pulls the latest Buildarr Docker image from Docker Hub. This image bundles Buildarr with several implementing plugins for out-of-the-box functionality.

```bash
docker pull callum027/buildarr:latest
```

--------------------------------

### Define Example Buildarr Plugin Structure (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

This Python code defines the main structure of an Example Buildarr plugin. It inherits from `buildarr.plugins.Plugin` and specifies associated configuration, manager, and secrets models. The `__version__` variable and plugin metadata are also defined here.

```python
from buildarr.plugins import Plugin
from .config import ExampleConfig
from .manager import ExampleManager
from .secrets import ExampleSecrets

__version__ = "0.1.0"

class ExamplePlugin(Plugin):
    """
    Example Buildarr plugin for managing Example application instances.
    """

    # Plugin metadata
    cli = None  # Optional Click command group for plugin-specific CLI commands
    config = ExampleConfig  # Configuration model class
    manager = ExampleManager  # Manager class for operations
    secrets = ExampleSecrets  # Secrets metadata model
    version = __version__
```

--------------------------------

### Define Buildarr Plugin Entry Points using Poetry

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

An example showing how to define entry points for Buildarr plugins using Poetry's configuration file (pyproject.toml). This method is used for projects managed with Poetry.

```toml
[tool.poetry.plugins."buildarr.plugins"]
"example" = "buildarr_example.plugin:ExamplePlugin"
```

--------------------------------

### Basic Buildarr Configuration with Sonarr Instance

Source: https://github.com/buildarr/buildarr/blob/main/docs/configuration.md

An example of a `buildarr.yml` file that configures Buildarr's update schedule and manages a single Sonarr instance. It specifies connection details and settings for the Sonarr application.

```yaml
---

buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

sonarr:
  hostname: "sonarr.example.com"
  port: 8989
  protocol: "http"
  settings:
    ...

```

--------------------------------

### Run Buildarr Docker Container (Daemon Mode)

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Starts the Buildarr Docker container in detached mode, ensuring it restarts automatically. It binds the configuration directory and sets the PUID/PGID environment variables. By default, the container runs in daemon mode.

```bash
docker run -d --name buildarr --restart=always -v /path/to/config:/config -e PUID=<PUID> -e PGID=<PGID> callum027/buildarr:latest
```

--------------------------------

### Simplify Buildarr Configuration with Includes (YAML)

Source: https://github.com/buildarr/buildarr/blob/main/docs/release-notes.md

Demonstrates how to simplify Buildarr configurations by leveraging the `includes` option for multiple files. This feature allows for more flexible structuring, such as separating sensitive parameters into different files. The example shows a before and after scenario, highlighting the reduced complexity in the final configuration.

```yaml
---

prowlarr:
  instances:
    prowlarr:
      settings:
        indexers:
          indexers:
            definitions:
              "Nyaa.si":
                grab_limit: 104  # Override the value in the original file.

```

--------------------------------

### Example Plugin Secrets Model (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

This Python code defines the secrets model for the Example Buildarr plugin. `ExampleSecrets` inherits from `buildarr.secrets.SecretsPlugin` and specifies sensitive connection details such as hostname, port, protocol, and API key. The `SecretStr` type is used for the API key to ensure it's automatically obfuscated in logs.

```python
# buildarr_example/secrets.py
from buildarr.secrets import SecretsPlugin
from buildarr.types import NonEmptyStr, Port, SecretStr

class ExampleSecrets(SecretsPlugin["ExampleConfig"]):
    """
    Secrets metadata for Example instance connections.
    """

    hostname: NonEmptyStr
    port: Port
    protocol: str
    api_key: SecretStr  # Automatically obfuscated in logs

    @property
    def host_url(self) -> str:
        """Build the base URL for API requests."""
        return f"{self.protocol}://{self.hostname}:{self.port}"
```

--------------------------------

### Sonarr Instance Linking Configuration (YAML)

Source: https://github.com/buildarr/buildarr/blob/main/docs/release-notes.md

Example YAML configuration demonstrating how to link Sonarr instances for use as import lists. It highlights the `instance_name` attribute for referencing another Sonarr instance and using names instead of IDs for quality profiles, language profiles, and tags.

```yaml
sonarr:
  instances:
    sonarr-hd:
      hostname: "localhost"
      port: 8989
    sonarr-4k:
      hostname: "localhost"
      port: 8990
      settings:
        import_lists:
          definitions:
            Sonarr (HD):
              type: "sonarr"
              # Global import list options.
              root_folder: "/path/to/videos"
              quality_profile: "4K"
              language_profile: "English"
              # Sonarr import list-specific options.
              full_url: "http://sonarr:8989"
              instance_name: "sonarr-hd"
              source_quality_profiles:
                - "HD/SD"
              source_language_profiles:
                - "English"
              source_tags:
                - "shows"
```

--------------------------------

### Configure Docker Volume Permissions

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Creates a directory for Buildarr's configuration and secrets, then sets strict permissions. The ownership must be set to the PUID and PGID that will be configured for the container to ensure proper access.

```bash
mkdir --mode=700 /path/to/config
sudo chown -R <PUID>:<PGID> /path/to/config
```

--------------------------------

### Run Buildarr Docker Container (One-Off Update)

Source: https://github.com/buildarr/buildarr/blob/main/docs/installation.md

Executes a single Buildarr stack update using the Docker image. The container will exit after the update is complete. This is useful for testing configurations. The --rm flag ensures the container is removed after execution.

```bash
docker run --rm -v /path/to/config:/config -e PUID=<PUID> -e PGID=<PGID> callum027/buildarr:latest run
```

--------------------------------

### Generated Docker Compose File

Source: https://github.com/buildarr/buildarr/blob/main/docs/usage.md

The resulting Docker Compose file generated from the example Buildarr configuration. It defines services for Sonarr instances and Buildarr itself, including image tags, volumes, hostnames, restart policies, and service dependencies. This file can be used to deploy the stack.

```yaml
---
version: '3.7'
services:
  sonarr_sonarr-hd:
    image: lscr.io/linuxserver/sonarr:latest
    volumes:
      - type: volume
        source: sonarr_sonarr-hd
        target: /config
    hostname: sonarr-hd
    restart: always
  sonarr_sonarr-4k:
    image: lscr.io/linuxserver/sonarr:latest
    volumes:
      - type: volume
        source: sonarr_sonarr-4k
        target: /config
    hostname: sonarr-4k
    restart: always
    depends_on:
    - sonarr_sonarr-hd
  buildarr:
    image: callum027/buildarr:0.4.0
    command:
    - daemon
    - /config/buildarr.yml
    volumes:
    - type: bind
      source: /opt/buildarr
      target: /config
      read_only: true
    restart: always
    depends_on:
    - sonarr_sonarr-hd
    - sonarr_sonarr-4k
volumes:
- sonarr_sonarr-4k
- sonarr_sonarr-hd

```

--------------------------------

### Buildarr Configuration with Separate Secret File

Source: https://github.com/buildarr/buildarr/blob/main/docs/configuration.md

An example showcasing how to use `includes` to load sensitive information, like API keys, from a separate configuration file (`buildarr-secret.yml`). This enhances security by keeping secrets isolated.

```yaml
---

includes:
  - buildarr-secret.yml

buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

sonarr:
  hostname: "sonarr.example.com"
  port: 8989
  protocol: "http"
  settings:
    ...

```

```yaml
---

sonarr:
  api_key: 1a2b3c4d5e1a2b3c4d5e1a

```

--------------------------------

### Use get_local_attrs and get_update_remote_attrs in Python

Source: https://context7.com/buildarr/buildarr/llms.txt

Illustrates the practical application of `get_local_attrs` for converting remote API data into local configuration objects and `get_update_remote_attrs` for detecting and preparing configuration changes for updates. This example focuses on the `QualityDefinitionConfig` class, showing how to fetch data, apply specific decoders, and send updates via PUT requests.

```python
from typing import Optional
from buildarr.config import ConfigBase

class QualityDefinitionConfig(ConfigBase):
    """Quality definition configuration."""

    min_size: float
    max_size: Optional[float]
    preferred_size: float

    @classmethod
    def from_remote(cls, secrets):
        """
        Fetch remote configuration and convert to local format.
        """
        from ..api import api_get

        # Fetch from remote API
        remote_data = api_get(secrets, "/api/v3/qualitydefinition")

        # Parse with remote map
        local_attrs = cls.get_local_attrs(
            remote_map=[
                ("min_size", "minSize", {}),
                ("max_size", "maxSize", {"decoder": lambda v: v if v != 0 else None}),
                ("preferred_size", "preferredSize", {}),
            ],
            remote_attrs=remote_data,
        )

        return cls(**local_attrs)

    def update_remote(self, tree: str, secrets, remote) -> bool:
        """
        Compare local and remote, update if different.
        """
        from ..api import api_put

        # Get changes
        updated, updated_attrs = self.get_update_remote_attrs(
            tree=tree,
            remote=remote,
            check_unmanaged=False,  # Don't check for unmanaged attributes
        )

        if updated:
            # updated_attrs contains only the changed attributes
            # in remote API format
            api_put(secrets, f"/api/v3/qualitydefinition/{remote.id}", updated_attrs)
            return True

        return False
```

--------------------------------

### Define Remote-to-Local Mappings in Python

Source: https://context7.com/buildarr/buildarr/llms.txt

Demonstrates how to define attribute mappings between local Python/YAML names and remote API names within a `ConfigBase` subclass. It includes examples of simple 1:1 mappings, mappings with custom decoder/encoder functions for data transformation, and mappings that represent nested fields. The `_remote_map` class variable is crucial for this configuration.

```python
from typing import ClassVar, List, Optional
from buildarr.config import ConfigBase, RemoteMapEntry

class MediaManagementConfig(ConfigBase):
    """
    Configuration for media management settings.
    """

    # Local attributes (Python/YAML naming)
    auto_unmonitor_deleted_episodes: bool = False
    recycling_bin: Optional[str] = None
    chmod_folder: Optional[str] = None

    # Remote map: (local_name, remote_name, options)
    _remote_map: ClassVar[List[RemoteMapEntry]] = [
        # Simple 1:1 mapping
        ("auto_unmonitor_deleted_episodes", "autoUnmonitorPreviouslyDownloadedEpisodes", {}),

        # With decoder/encoder for transformations
        ("recycling_bin", "recycleBin", {
            "decoder": lambda v: v or None,  # Empty string -> None
            "encoder": lambda v: v or "",    # None -> empty string
        }),

        # With is_field flag for nested API structures
        ("chmod_folder", "chmodFolder", {
            "is_field": True,
            "field_default": None,
            "decoder": lambda v: v or None,
            "encoder": lambda v: v or "",
        }),
    ]

    @classmethod
    def from_remote(cls, secrets):
        """Fetch and parse remote configuration."""
        from ..api import api_get

        remote_attrs = api_get(secrets, "/api/v3/config/mediamanagement")

        return cls(**cls.get_local_attrs(
            remote_map=cls._remote_map,
            remote_attrs=remote_attrs,
        ))

    def update_remote(self, tree: str, secrets, remote) -> bool:
        """Update remote configuration if changes detected."""
        from ..api import api_put

        # Compare and get changes
        updated, updated_attrs = self.get_update_remote_attrs(
            tree=tree,
            remote=remote,
            check_unmanaged=True,
        )

        if updated:
            # Log changes
            self._log_update_remote_attrs(
                tree=tree,
                remote=remote,
                updated_attrs=updated_attrs,
            )

            # Push to remote
            api_put(secrets, "/api/v3/config/mediamanagement", updated_attrs)
            return True

        return False
```

--------------------------------

### Buildarr Plugin Registration in pyproject.toml (TOML)

Source: https://context7.com/buildarr/buildarr/llms.txt

This TOML snippet shows how to register the 'buildarr-example' plugin in the `pyproject.toml` file. It specifies project metadata, dependencies (including `buildarr`), and importantly, defines an entry point under `[project.entry-points.'buildarr.plugins']` to make the plugin discoverable by Buildarr.

```toml
[project]
name = "buildarr-example"
version = "0.1.0"
description = "Buildarr plugin for Example application"
dependencies = [
    "buildarr>=0.7.0",
]

[project.entry-points."buildarr.plugins"]
example = "buildarr_example.plugin:ExamplePlugin"
```

--------------------------------

### Loading Buildarr Configuration Programmatically (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

Shows how to load Buildarr's main configuration and instance-specific configurations using Python functions. This enables dynamic loading of settings from a YAML file and accessing them via the global state object.

```python
from pathlib import Path
from buildarr.config import load_config, load_instance_configs
from buildarr.state import state
from buildarr.plugins import load as load_plugins

# Load plugins first
load_plugins()

# Load configuration file
config_path = Path("buildarr.yml")
load_config(path=config_path)

# Access loaded configuration
print(f"Buildarr config: {state.config.buildarr}")
print(f"Sonarr config: {state.config.sonarr}")

# Load instance-specific configurations
load_instance_configs()

# Access instance configurations
for plugin_name, instances in state.instance_configs.items():
    for instance_name, config in instances.items():
        print(f"{plugin_name}.{instance_name}:")
        print(f"  Host: {config.hostname}:{config.port}")
        print(f"  Protocol: {config.protocol}")
```

--------------------------------

### Accessing Global State Information (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

Illustrates how to access and utilize global state managed by Buildarr, including loaded plugins, configurations, managers, instance details, secrets, and execution order. It also shows how to use context managers for scoped access.

```python
from buildarr.state import state

# Access loaded plugins
for plugin_name, plugin in state.plugins.items():
    print(f"Plugin: {plugin_name} v{plugin.version}")
    # Output: Plugin: sonarr v0.6.0

# Access loaded configuration
buildarr_config = state.config.buildarr
print(f"Watch config: {buildarr_config.watch_config}")
print(f"Update times: {buildarr_config.update_times}")

# Access plugin managers
sonarr_manager = state.managers["sonarr"]

# Access instance configurations
for plugin_name, instances in state.instance_configs.items():
    for instance_name, config in instances.items():
        print(f"{plugin_name}.{instance_name}: {config.hostname}:{config.port}")

# Access secrets
for plugin_name, instances in state.secrets.items():
    for instance_name, secrets in instances.items():
        print(f"{plugin_name}.{instance_name}: {secrets.host_url}")

# Access execution order (after dependency resolution)
print("Execution order:", state.execution_order)
# Output: [("prowlarr", "default"), ("sonarr", "default"), ("radarr", "default")]

# Context managers
from buildarr.state import state

# Track current plugin/instance
with state.current_plugin("sonarr"):
    with state.current_instance("default"):
        # Code here has context of sonarr.default instance
        print(f"Current: {state.plugin_name}.{state.instance_name}")

```

--------------------------------

### Dump Sonarr Configuration using Buildarr CLI

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

Command-line instruction to dump the configuration of a Sonarr instance using the Buildarr Docker image. This is useful for retrieving an existing configuration to insert into the `buildarr.yml` file. It requires the Sonarr instance URL and will prompt for the API key.

```bash
$ docker run -it --rm callum027/buildarr:latest sonarr dump-config http://sonarr.example.com:8989

```

--------------------------------

### Buildarr Plugin Rendering Stages (Python)

Source: https://github.com/buildarr/buildarr/blob/main/docs/release-notes.md

Illustrates the introduction of a new post-initialisation rendering stage for Buildarr plugins. This stage runs after instance initialization, allowing plugins access to instance secrets for rendering configurations. This is useful for dynamic configuration options, as demonstrated by its use in the upcoming Radarr plugin.

```python
# This is a conceptual example and not direct code from the text.
# Represents the addition of a new rendering stage in Buildarr plugins.

class BuildarrPlugin:
    def pre_initialize_render(self, config):
        # Existing rendering stage
        pass

    def post_initialize_render(self, config, instance_secrets):
        # New rendering stage, uses instance secrets
        pass

```

--------------------------------

### Buildarr Configuration with Included Files for Instance Types

Source: https://github.com/buildarr/buildarr/blob/main/docs/configuration.md

Demonstrates using the `includes` directive in `buildarr.yml` to separate configurations for different application types, such as Sonarr and Radarr, into distinct files. This promotes modularity and organization.

```yaml
---

includes:
  - sonarr.yml
  - radarr.yml

buildarr:
  watch_config: true
  update_days:
    - "monday"
    - "tuesday"
    - "wednesday"
    - "thursday"
    - "friday"
    - "saturday"
    - "sunday"
  update_times:
    - "03:00"

```

```yaml
---

sonarr:
  hostname: "sonarr.example.com"
  port: 8989
  protocol: "http"
  settings:
    ...

```

```yaml
---

radarr:
  hostname: "radarr.example.com"
  port: 7878
  protocol: "http"
  settings:
    ...

```

--------------------------------

### Exporting Custom Configurations to YAML (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

Illustrates how to define a custom configuration class inheriting from Buildarr's ConfigPlugin and then export an instance of this configuration to a YAML string or file. This is useful for creating and managing application settings.

```python
from buildarr.config import ConfigPlugin

class ExampleConfig(ConfigPlugin):
    """Example configuration."""

    hostname: str = "localhost"
    port: int = 8989
    api_key: str = "secret123"

# Create configuration
config = ExampleConfig(
    hostname="example.com",
    port=7878,
    api_key="myapikey",
)

# Export to YAML string
yaml_output = config.model_dump_yaml(exclude_unset=True)
print(yaml_output)

# Output:
# hostname: example.com
# port: 7878
# api_key: myapikey

# Export to file
with open("config.yml", "w") as f:
    f.write(config.model_dump_yaml(exclude_unset=True))
```

--------------------------------

### Configuring Multiple Instances of the Same Application Type

Source: https://github.com/buildarr/buildarr/blob/main/docs/configuration.md

Illustrates how to manage multiple instances of the same application (e.g., Sonarr) within a single Buildarr configuration using the `instances` attribute. Global settings apply to all, while per-instance settings override them.

```yaml
sonarr:
  # Configuration common to all Sonarr instances.
  settings: 
    ...

  instances:
    # Sonarr instance 1 connection information and configuration.
    sonarr1:
      hostname: "sonarr1.example.com"
      port: 8989
      protocol: "http"
      settings:
        ...

    # Sonarr instance 1 connection information and configuration.
    sonarr2:
      hostname: "sonarr2.example.com"
      port: 8989
      protocol: "http"
      settings:
        ...

```

--------------------------------

### Run Buildarr with Docker

Source: https://github.com/buildarr/buildarr/blob/main/docs/index.md

This command runs the Buildarr Docker container in detached mode, mounts the current directory to '/config' for persistence, sets user and group IDs, and enables debug logging.

```bash
$ docker run -d --name buildarr -v $(pwd):/config -e PUID=$(id -u) -e PGID=$(id -g) callum027/buildarr:latest --log-level DEBUG run
```

--------------------------------

### Creating Custom Validators with InstanceReference (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

Shows how to create custom validators for configuration fields using `Annotated` and `InstanceReference`. This allows linking configuration to specific plugin instances and automatically manages dependencies.

```python
from typing import Optional
from typing_extensions import Annotated
from buildarr.types import InstanceReference
from buildarr.config import ConfigPlugin

class SonarrConfig(ConfigPlugin):
    """
    Sonarr configuration with Prowlarr instance link.
    """

    hostname: str = "localhost"
    port: int = 8989

    # Link to Prowlarr instance - creates dependency
    prowlarr_instance: Annotated[
        Optional[str],
        InstanceReference("prowlarr")  # Validates Prowlarr instance exists
    ] = None

    # Link to Radarr instance
    radarr_instance: Annotated[
        Optional[str],
        InstanceReference("radarr")
    ] = None

# In configuration:
# sonarr:
#   hostname: "localhost"
#   port: 8989
#   prowlarr_instance: "default"  # Must exist in prowlarr.instances or as default

# Buildarr automatically:
# 1. Validates prowlarr_instance exists
# 2. Adds dependency: Sonarr depends on Prowlarr
# 3. Initializes Prowlarr before Sonarr
# 4. Updates Prowlarr before Sonarr

```

--------------------------------

### Using Buildarr Built-in Types for Configuration (Python)

Source: https://context7.com/buildarr/buildarr/llms.txt

Demonstrates how to use various Buildarr types like SecretStr, Password, Port, NonEmptyStr, and custom Enums for defining application configurations. These types help enforce data integrity and security.

```python
from typing import Optional
from buildarr.types import (
    SecretStr,
    Password,
    Port,
    NonEmptyStr,
    LowerCaseStr,
    UpperCaseStr,
    BaseEnum,
    TrashID,
)
from buildarr.config import ConfigBase

class ApplicationConfig(ConfigBase):
    """Example configuration using Buildarr types."""

    # Non-empty string (raises error if empty)
    hostname: NonEmptyStr = "localhost"

    # Port number (1-65535)
    port: Port = 8989

    # Secret string (obfuscated in logs/dumps)
    api_key: SecretStr

    # Password (non-empty secret string)
    password: Password

    # Case-converting strings
    username: LowerCaseStr = "admin"
    protocol: UpperCaseStr = "HTTP"  # Stored as "HTTP"

    # TRaSH-Guides ID (32-character hex string)
    release_profile_id: Optional[TrashID] = None

class Protocol(BaseEnum):
    """Multi-value enumeration with aliases."""

    HTTP = (1, "http")
    HTTPS = (2, "https", "ssl")

    @classmethod
    def _missing_(cls, value):
        """Support lookup by name or any value."""
        for member in cls:
            if value in member.values or value == member.name.lower():
                return member
        return None

# Usage:
config = ApplicationConfig(
    hostname="sonarr",
    port=8989,
    api_key="secret123",
    password="secure_pass",
)

# SecretStr is obfuscated
print(config.api_key)  # Output: **********

# Get actual value
actual_key = config.api_key.get_secret_value()  # "secret123"

# Protocol enum supports multiple values
Protocol.HTTP == Protocol(1)  # True
Protocol.HTTP == Protocol("http")  # True
Protocol.HTTPS == Protocol("ssl")  # True

```

--------------------------------

### Buildarr Run: Execute One-Time Configuration Updates

Source: https://context7.com/buildarr/buildarr/llms.txt

Performs a one-time configuration update for the *Arr applications. Allows specifying a custom config file, running only specific plugins, and enabling debug mode for verbose logging.

```bash
# Run one-time update with default config
buildarr run

# Specify custom config file
buildarr run /path/to/config.yml

# Run only specific plugins
buildarr run --plugin sonarr --plugin radarr

# Debug mode with verbose logging
buildarr --log-level DEBUG run

# Expected output:
# 2023-11-12 10:00:29,932 buildarr:1 buildarr.cli.run [INFO] Loaded plugins: jellyseerr (0.3.0), prowlarr (0.5.0), radarr (0.2.0), sonarr (0.6.0)
# 2023-11-12 10:00:29,932 buildarr:1 buildarr.cli.run [INFO] Loading instance configurations
# 2023-11-12 10:00:29,973 buildarr:1 buildarr.cli.run [INFO] Running with plugins: prowlarr, sonarr, radarr, jellyseerr
# 2023-11-12 10:00:37,343 buildarr:1 buildarr.cli.run [INFO] <sonarr> (default) Connection test successful
# 2023-11-12 10:00:39,933 buildarr:1 buildarr.cli.run [INFO] <sonarr> (default) Remote configuration successfully updated
# 2023-11-12 10:00:52,843 buildarr:1 buildarr.cli.run [INFO] Finished deleting unmanaged/unused resources on remote instances
```

--------------------------------

### Buildarr Compose: Generate Docker Compose Configuration

Source: https://context7.com/buildarr/buildarr/llms.txt

Generates a Docker Compose configuration file for deploying Buildarr and associated *Arr applications. Supports specifying compose version, restart policy, filtering plugins, and ignoring hostname validation.

```bash
# Generate docker-compose.yml from Buildarr config
buildarr compose > docker-compose.yml

# Generate with specific compose version
buildarr compose --compose-version 3.8

# Set restart policy
buildarr compose --restart unless-stopped

# Filter specific plugins
buildarr compose --plugin sonarr --plugin radarr

# Ignore hostname validation (allow IPs)
buildarr compose --ignore-hostnames

# Expected output (docker-compose.yml):
# version: '3.7'
# services:
#   sonarr:
#     image: linuxserver/sonarr:latest
#     container_name: sonarr
#     environment:
#       - PUID=1000
#       - PGID=1000
#     volumes:
#       - ./sonarr:/config
#     ports:
#       - "8989:8989"
#     restart: always
#   buildarr:
#     image: callum027/buildarr:latest
#     container_name: buildarr
#     volumes:
#       - ./buildarr.yml:/config/buildarr.yml:ro
#     depends_on:
#       - sonarr
#     restart: always
```

--------------------------------

### Accessing Buildarr State in Python Plugins

Source: https://context7.com/buildarr/buildarr/llms.txt

Demonstrates how to access global state variables like instance names and configurations within a custom Buildarr manager plugin. This allows for dynamic interaction with other plugin instances and their settings.

```python
from buildarr.state import state
from buildarr.manager import ManagerPlugin

class ExampleManager(ManagerPlugin):
    """Example manager using global state."""

    def update_remote(self, tree: str, secrets, remote) -> bool:
        """Update remote instance."""

        # Access current instance name
        instance_name = state.instance_name

        # Check if another plugin instance exists
        if "prowlarr" in state.instance_configs:
            prowlarr_instances = state.instance_configs["prowlarr"]
            print(f"Prowlarr instances: {list(prowlarr_instances.keys())}")

        # Access configuration of linked instance
        config = self.get_instance_config(instance_name)
        if config.prowlarr_instance:
            prowlarr_config = state.instance_configs["prowlarr"][config.prowlarr_instance]
            prowlarr_url = prowlarr_config.host_url
            print(f"Linked Prowlarr at: {prowlarr_url}")

        return False
```

--------------------------------

### Generate Docker Compose from Buildarr Config (Bash)

Source: https://github.com/buildarr/buildarr/blob/main/docs/usage.md

This command generates a Docker Compose file from a specified Buildarr configuration file. It takes the path to the Buildarr YAML file as input and redirects the output to a Docker Compose YAML file. Ensure the Buildarr configuration is valid and accessible.

```bash
$ buildarr compose /opt/buildarr/buildarr.yml > /opt/buildarr/docker-compose.yml
```

--------------------------------

### Buildarr Test-Config: Validate Buildarr Configuration

Source: https://context7.com/buildarr/buildarr/llms.txt

Validates the Buildarr configuration file without applying any changes. Useful for ensuring the configuration syntax and values are correct before deployment. Supports testing a specific config file.

```bash
# Test configuration file validity
buildarr test-config

# Test specific config file
buildarr test-config /path/to/config.yml

# Expected output on success:
# Configuration file is valid

# Expected output on error:
# Error: Invalid configuration
# sonarr.port: Input should be less than or equal to 65535
```