### Install Caupain on Debian/Ubuntu

Source: https://context7.com/deezer/caupain/llms.txt

Install Caupain on Debian or Ubuntu systems by adding the Deezer repository.

```bash
# Debian/Ubuntu
sudo mkdir -p /usr/local/share/keyrings
sudo curl -sfLo /usr/local/share/keyrings/deezer.gpg https://research.deezer.com/debian-repo/gpg.key
echo "deb [signed-by=/usr/share/local/keyrings/deezer.gpg] https://research.deezer.com/debian-repo/ stable main" | sudo tee -a /etc/apt/sources.list.d/deezer.list
sudo apt update && sudo apt install caupain
```

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

### Install Caupain via Chocolatey

Source: https://context7.com/deezer/caupain/llms.txt

Install Caupain on Windows using Chocolatey.

```bash
# Windows via Chocolatey
choco install caupain
```

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

### Gradle Plugin Installation

Source: https://context7.com/deezer/caupain/llms.txt

Install the 'caupain' Gradle plugin by adding its definition to the `libs.versions.toml` file and applying it in the root build script.

```toml
# gradle/libs.versions.toml
[plugins]
caupain = { id = "com.deezer.caupain", version = "1.9.1" }
```

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

### Caupain Configuration File Example

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Defines Maven repositories for dependency hosting and plugin hosting within a TOML configuration file. Custom repositories, including those with authentication, can be specified.

```toml
# Configures the Maven repositories where the dependencies are hosted.
# If none are specified, the default repositories "google" and "mavenCentral" are used.
# Repositories are queried in the order they are specified.
repositories = [
    "mavenCentral", # Default repositories "google","mavenCentral" and "gradlePluginPortal" are provided as shortcuts
    { url = "http://www.your.repo/maven" }, # You can also specify a custom repository
    { url = "http://www.your.secure.repo/maven", user = "my-user", password = "my-password" }, # You can also specify password credentials
    { url = "http://www.your.secure.repo/maven", authHeaderName = "my-header-name", authHeaderValue = "my-header-value" } # Or header credentials
]
# Configures the Maven repositories where the plugins are hosted.
# If none are specified, the default repositories "gradlePluginPortal", "google" and "mavenCentral" are used.
# Repositories are queried in the order they are specified.
```

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

### Install Caupain Gradle Plugin

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Add this to your `libs.versions.toml` to define the plugin alias. Replace `latestVersion` with the desired plugin version.

```toml
caupain = "com.deezer.caupain:latestVersion"
```

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

### Add Debian Repository and Install Caupain on Linux

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

These commands are used to add the Deezer repository to your Debian-based Linux system and then install Caupain.

```bash
sudo mkdir -p /usr/local/share/keyrings
sudo curl -sfLo /usr/local/share/keyrings/deezer.gpg https://research.deezer.com/debian-repo/gpg.key
echo "deb [signed-by=/usr/share/local/keyrings/deezer.gpg] https://research.deezer.com/debian-repo/ stable main" | sudo tee -a /etc/apt/sources.list.d/deezer.list
sudo apt update
```

```bash
sudo apt install caupain
```

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

### Install Caupain via Chocolatey on Windows

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Use this command to install Caupain on Windows using the Chocolatey package manager.

```powershell
choco install caupain
```

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

### Configure Plugin Repositories

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Specify custom plugin repositories using a TOML array. This example shows how to define a single repository named 'google'.

```toml
pluginRepositories = [ "google" ]
```

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

### Apply Gradle Plugin in Root Build Script

Source: https://context7.com/deezer/caupain/llms.txt

Apply the installed 'caupain' plugin in the root `build.gradle.kts` file using the `alias` function.

```kotlin
// root build.gradle.kts
plugins {
    alias(libs.plugins.caupain)
}
```

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

### Filter Dependencies by Version Prefix

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Apply a version filter to restrict updates for a specific dependency. This example filters for versions starting with '1.'.

```toml
{ group = "com.google.guava", name = "guava", versionFilter = "1.+" }
```

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

### Install Caupain via Homebrew on macOS

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Use this command to install Caupain on macOS using the Homebrew package manager.

```bash
brew install deezer/repo/caupain
```

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

### Filter Plugins by Version

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Apply a version filter to a specific plugin ID. This example filters for versions starting with '1.'.

```toml
{ id = "filtered.plugin.id", versionFilter = "1.+" }
```

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

### Filter Dependencies by Group Glob

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Apply a version filter to all dependencies within a group matching a glob pattern. This example filters for versions starting with '1.'.

```toml
{ group = "com.google.**", versionFilter = "1.+" }
```

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

### Filter Dependencies by Version Range

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Use a version range filter to specify acceptable update versions for a dependency. This example accepts versions greater than '1.2' and less than or equal to '1.5'.

```toml
{ group = "com.google.guava", name = "guava", versionFilter = "(1.2, 1.5]" }
```

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

### Configure Repository Component Filtering

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Define repository filtering using a TOML array of tables to specify which components are searched in each repository. This example uses a predefined 'mavenCentral' repository and excludes specific components.

```toml
[[ repositories ]]
default = "mavenCentral"
```

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

### Enable Version Catalog Summary

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Enable the 'showVersionsReferences' switch to display a summary block based on the content of the 'versions' block in the version catalog.

```kotlin
caupain {
    // Other configuration...
    showVersionsReferences = true
}
```

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

### Build Caupain Binary

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

This command builds the Caupain binary for the current architecture from the source code.

```bash
./gradlew :cli:buildCurrentArchBinary
```

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

### Configure Version Catalog Paths

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Specify the path to the version catalog file. Multiple paths can be defined to use several version catalogs.

```kotlin
// Version catalog path. Default is "gradle/libs.versions.toml".
versionCatalogFile = file("path/to/libs.versions.toml")
```

```kotlin
// You can also define multiple version catalogs. Warning: defining this will override the previous single path
versionCatalogFiles.from("path/to/libs.versions.toml", "path/to/other/libs.versions.toml")
```

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

### Specify Version Catalog Path

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Define the path to the version catalog file. The default path is 'gradle/libs.versions.toml'.

```toml
versionCatalogPath = "another/path/to/libs.versions.toml"
```

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

### Configure Snapshot Repository

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Add this repository to your `settings.gradle.kts` to enable fetching snapshot versions of the plugin.

```kotlin
pluginManagement {
    repositories {
        maven("https://central.sonatype.com/repository/maven-snapshots/") {
            mavenContent {
                snapshotsOnly()
            }
        }
        // ... your other repositories
    }
}
```

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

### Define Multiple Version Catalogs

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Configure multiple version catalog files. This will override any single path previously defined.

```toml
versionCatalogPaths = [ "libs.versions.toml", "another/path/to/libs.versions.toml" ]
```

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

### Enable Version References Summary

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Show a summary of updates from the version block in the version catalog. This is useful for quickly identifying updates when using version blocks extensively.

```toml
showVersionsReferences = true
```

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

### Include Dependencies by Key

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Configure inclusions in your Gradle build script by specifying dependency keys. Only dependencies matching these keys will be suggested for updates.

```kotlin
includeKeys("excluded1", "excluded2")
```

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

### Apply Caupain Gradle Plugin

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Apply the plugin in your root `build.gradle.kts` file using the alias defined in `libs.versions.toml`.

```kotlin
plugins {
    alias(libs.plugins.caupain)
}
```

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

### Caupain CLI Configuration File (`caupain.toml`)

Source: https://context7.com/deezer/caupain/llms.txt

Configure Caupain's behavior using a TOML file. CLI flags override file settings.

```toml
# Repositories for dependencies (default: google + mavenCentral)
repositories = [
    "mavenCentral",
    { url = "https://my.private.repo/maven" },
    { url = "https://secure.repo/maven", user = "ci-user", password = "secret" },
    { url = "https://header.repo/maven", authHeaderName = "X-Api-Key", authHeaderValue = "token123" }
]

# Repositories for plugins (default: gradlePluginPortal + mavenCentral + google)
pluginRepositories = [ "gradlePluginPortal", "mavenCentral" ]

# Single catalog path (default: gradle/libs.versions.toml)
versionCatalogPath = "gradle/libs.versions.toml"

# Or multiple catalogs (overrides versionCatalogPath)
versionCatalogPaths = [ "gradle/libs.versions.toml", "gradle/test-libs.versions.toml" ]

# Update policies (default: stability-level)
policies = [ "stability-level" ]

# Output format(s): console, html, markdown, json
outputTypes = [ "console", "markdown", "html" ]

# Output file path (single output type only)
outputPath = "build/reports/dependency-updates.html"

# Output directory (multiple output types)
outputDir  = "build/reports"
outputBaseName = "dependency-updates"

# Show versions-block summary in report
showVersionReferences = true

# Only check static versions like 1.0.0 (default: true)
onlyCheckStaticVersions = true

# Gradle stability level: stable, rc, milestone, releaseNightly, nightly
gradleStabilityLevel = "stable"

# Show ignored dependencies in report
checkIgnored = false

# Cache directory (default: system user cache dir)
cacheDir = "build/caupain-cache"

# GitHub token for release note lookup
githubToken = "ghp_..."
searchReleaseNotes = true

# Verify .pom availability before accepting a version (slower)
verifyExistence = false

```

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

### Repository Configuration with Includes and Excludes

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Define custom repositories with specific inclusion and exclusion rules for components. Supports group, name, and glob patterns for matching.

```toml
includes = [
    { group = "com.example", name = "example-lib" }, # You can specify a group and name
    { group = "com.example" }, # You can also only specify a group...
    { group = "com.example2.**" } # ...or use globs
]
excludes = [
    { group = "com.other" }
]
[[ repositories ]]
# This can also be done for custom repositories
url = "http://www.example.com/repo"
# The credentials can be specified in the same way as for the repositories key
user = "my-user"
password = "my-password"
authHeaderName = "my-header-name"
authHeaderValue = "my-header-value"
includes = [
    { group = "com.example", name = "example-lib" },
    { group = "com.example2.**" }
]
excludes = [
    { group = "com.other" }
]
```

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

### Caupain CLI Usage

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Displays the available command-line options for the caupain tool. Use this to understand how to customize its behavior via flags and arguments.

```bash
Usage: caupain [<options>]

Options:
  -i, --version-catalog=<path>  Version catalog path. Use multiple times to use
                                multiple version catalogs (default:
                                gradle/libs.versions.toml)
  --gradle-wrapper-properties=<path>
                                Gradle wrapper properties path (default: 
gradle/wrapper/gradle-wrapper.properties)
  -e, --excluded=<text>         Excluded keys
  -c, --config=<path>           Configuration file (default: caupain.toml)
  --policy-plugin-dir=<path>    Custom policies plugin dir
  -p, --policy=<text>           Update policy (default: stability-level).
                                Multiple policies can be specified by using a
                                comma-separated list, and will be combined (a
                                version must satisfy all policies to be
                                accepted).
  --list-policies               List available policies
  --gradle-stability-level=(stable|rc|milestone|release-nightly|nightly)
                                Gradle stability level (default: stable)
  -t, --output-type=(console|html|markdown|json)
                                Output type (default: console)
  -o, --output=<file>           Report output path (or - if you want to ouput
                                to standard output). If a file is specified,
                                only used if a single output type is specified
                                (default:
                                build/reports/dependencies-update.(html|md|json))
  --output-dir=<path>           Report output dir. Only used if multiple output
                                types are specified, and output is not set to
                                standard output (default: build/reports)
  --output-base-name=<text>     Report output base name, without extension.
                                Only used if multiple output types are
                                specified, and output is not set to standard
                                output (default: dependencies-update)
  --show-version-references     Show versions references update summary in the
                                report
  --in-place                    Replace versions in version catalog in place
  --search-release-notes        Search for release notes for updated versions
                                on GitHub
  --github-token=<text>         GitHub token for searching release notes. Taken
                                from CAUPAIN_GITHUB_TOKEN environment variable
                                if not set
  --cache-dir=<path>            Cache directory. This is not used if --no-cache
                                is set (default: user cache dir)
  --no-cache                    Disable HTTP cache
  --clean-cache                 Clean the cache before running
  -q, --quiet                   Suppress all output
  -v, --verbose                 Verbose output
  -d, --debug                   Debug output
  --debug-http-calls            Enable debugging for HTTP calls
  --verify-existence            Verify that .pom file exists before accepting
                                version updates (warning: may slow down checks)
  --version                     Show the version and exit
  -h, --help                    Show this message and exit
```

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

### Basic Caupain CLI Usage

Source: https://context7.com/deezer/caupain/llms.txt

Run Caupain from your Gradle project's root for a basic console report. Use flags to customize output and behavior.

```bash
# Basic check — console output
caupain
```

```bash
# Generate HTML and Markdown reports
caupain -t html -t markdown
```

```bash
# Use a custom version catalog path
caupain -i path/to/my-catalog.versions.toml
```

```bash
# Output to a specific file
caupain -t html -o build/reports/updates.html
```

```bash
# Output formatted report to stdout
caupain -t markdown -o -
```

```bash
# Use a specific update policy
caupain -p stability-level
```

```bash
# Combine policies (version must satisfy ALL)
caupain -p stability-level,guava-android
```

```bash
# List available policies
caupain --list-policies
```

```bash
# Update version catalog in-place (replaces versions automatically)
caupain --in-place
```

```bash
# Search for GitHub release notes (requires token)
caupain --search-release-notes --github-token "$GITHUB_TOKEN"
```

```bash
# Show updates for ignored dependencies too
caupain --show-version-references
```

```bash
# Clean HTTP cache before running
caupain --clean-cache
```

```bash
# Debug HTTP calls
caupain --debug --debug-http-calls
```

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

### Set Multiple Policy Names

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Configure multiple policy names for version checks. Refer to the documentation for available policies.

```toml
policies = [ "stability-level" ]
```

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

### Full Gradle Plugin Configuration

Source: https://context7.com/deezer/caupain/llms.txt

Configure dependency exclusions, inclusions, version filters, repositories, and output formats for the Caupain Gradle plugin. Set various options like showing version references, checking static versions, stability level, and GitHub token.

```kotlin
// build.gradle.kts
import com.deezer.caupain.gradle.DependenciesUpdateTask
import com.deezer.caupain.model.DefaultRepositories
import com.deezer.caupain.model.GradleStabilityLevel
import com.deezer.caupain.model.LibraryExclusion
import com.deezer.caupain.model.LibraryInclusion
import com.deezer.caupain.policies.StabilityLevelPolicy

caupain {
    // --- Dependency selection ---
    excludeKeys("legacy-module", "unused-dep")
    excludeLibrary(group = "com.google.guava")
    excludeLibrary(group = "com.old.**")
    excludeLibrary(group = "com.example", name = "specific-artifact")
    excludeLibraries(
        LibraryExclusion(group = "com.deprecated"),
        LibraryExclusion(group = "com.internal", name = "secret-lib")
    )
    excludePluginIds("com.android.application")

    includeKeys("kotlin", "ktor")
    includeLibrary(group = "org.jetbrains.kotlinx")
    includeLibraries(
        LibraryInclusion(group = "io.ktor")
    )
    includePluginIds("org.jetbrains.kotlin.multiplatform")

    // --- Version filters ---
    addFilter(group = "com.google.guava", name = "guava", versionFilter = "1.+")
    addFilter(group = "com.google.**", versionFilter = "31.+")
    addFilter(pluginId = "com.android.application", versionFilter = "8.+")

    // --- Repository overrides ---
    repositories {
        libraries {
            repository(DefaultRepositories.google) {
                include(group = "com.google.**")
                exclude(group = "com.google.guava")
            }
            repository(DefaultRepositories.mavenCentral)
            repository("https://my.private.repo/maven", "user", "password")
            repository("https://header.repo/maven") {
                headerCredentials {
                    name  = "X-Api-Key"
                    value = "mytoken"
                }
            }
        }
        plugins {
            repository(DefaultRepositories.gradlePlugins)
        }
    }

    // --- Output configuration ---
    outputs {
        console { enabled = true }
        html {
            enabled = true
            outputFile = file("build/reports/dep-updates.html")
        }
        markdown {
            enabled = true
            outputFile = file("build/reports/dep-updates.md")
        }
        json {
            enabled = false
        }
    }

    // --- Misc options ---
    showVersionsReferences    = true
    onlyCheckStaticVersions   = true
    gradleStabilityLevel      = GradleStabilityLevel.STABLE
    checkIgnored              = true
    githubToken               = System.getenv("GITHUB_TOKEN")
    searchReleaseNotes        = true
    verifyExistence           = false
    versionCatalogFile        = file("gradle/libs.versions.toml")
    // Multiple catalogs:
    // versionCatalogFiles.from("gradle/libs.versions.toml", "gradle/bom.versions.toml")
}

// --- Policy configuration on the task ---
tasks.withType<DependenciesUpdateTask> {
    // Use a predefined policy
    selectIf(StabilityLevelPolicy)

    // Or write a lambda policy inline
    selectIf {
        // "this" exposes: dependency, currentVersion, updatedVersion
        !updatedVersion.exactVersion.text.contains("eap", ignoreCase = true)
    }

    // Attach a custom formatter
    customFormatter {
        println("Found ${result.updateInfos.values.sumOf { it.size }} updates")
    }
}
```

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

### Caupain CLI Usage

Source: https://github.com/deezer/caupain/blob/main/cli/chocolatey/description.md

This is the base usage command for Caupain. Launch it in your project's root directory to automatically detect the version catalog and generate a console report.

```bash
Usage: caupain [<options>]

Options:
  -i, --version-catalog=<path>  Version catalog path (default:
                                gradle/libs.versions.toml)
  --gradle-wrapper-properties=<path>
                                Gradle wrapper properties path (default:
                                gradle/wrapper/gradle-wrapper.properties)
  -e, --excluded=<text>         Excluded keys
  -c, --config=<path>           Configuration file (default: caupain.toml)
  --policy-plugin-dir=<path>    Custom policies plugin dir
  -p, --policy=<text>           Update policy
  -t, --output-type=(console|html|markdown)
                                Output type (default: console)
  -o, --output=<path>           Report output path
  --cache-dir=<path>            Cache directory. This is not used if --no-cache
                                is set (default: user cache dir)
  --no--cache                   Disable HTTP cache
  -q, --quiet                   Suppress all output
  -v, --verbose                 Verbose output
  -d, --debug                   Debug output
  --debug-http-calls            Enable debugging for HTTP calls
  --version                     Print version and exit
  -h, --help                    Show this message and exit
```

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

### Configure GitHub Token

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Provide a GitHub token for searching and displaying release notes on GitHub.

```toml
githubToken = "your-token"
```

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

### Enable POM Existence Verification

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Verify that .pom files exist in repositories before considering a version valid. This ensures that suggested versions are downloadable but may increase checking time due to extra network requests.

```toml
verifyExistence = true
```

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

### Enable Release Notes Search

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Automatically search for and display links to GitHub release notes. This is enabled by default if a GitHub token is provided.

```toml
searchReleaseNotes = true
```

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

### Set Output Path

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Specify the file path for HTML, Markdown, or JSON output. Defaults to 'build/reports/dependencies-update.(html|md|json)'.

```toml
outputPath = "path/to/output/file.html"
```

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

### Configure Snapshot Repository in settings.gradle.kts

Source: https://github.com/deezer/caupain/blob/main/core/README.md

Add the Sonatype snapshot repository to your Gradle settings file to resolve snapshot versions of the Caupain core library. Ensure snapshotsOnly() is configured for the repository.

```kotlin
dependencyResolutionManagement {
    repositories {
        maven("https://central.sonatype.com/repository/maven-snapshots/") {
            mavenContent {
                snapshotsOnly()
            }
        }
        // ... your other repositories
    }
}
```

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

### Include Libraries by Group and Name

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Include specific libraries or entire groups for update suggestions. Supports glob patterns for group names and exact matching for group/name combinations.

```kotlin
includeLibrary(group = "com.example")
includeLibrary(group = "com.example.**")
includeLibrary(group = "com.example.*.sub")
includeLibrary(group = "com.example", name = "example")
```

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

### Configure Gradle Wrapper Properties Path

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Set the path to the Gradle wrapper properties file to check for Gradle wrapper updates. The default path is 'gradle/wrapper/gradle-wrapper.properties'.

```toml
gradleWrapperPropertiesPath = "/path/to/properties/file"
```

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

### Configure Policy Plugin Directory

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Set the directory for custom policy plugins. This setting is applicable only to JVM projects.

```toml
policyPluginDir = "path/to/policy/plugin/dir"
```

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

### Run Gradle Update Check

Source: https://context7.com/deezer/caupain/llms.txt

Execute the Gradle update check task using `./gradlew checkDependencyUpdates`. Use `--no-configuration-cache` for cleaner runs.

```bash
# Run the update check
./gradlew checkDependencyUpdates --no-configuration-cache
```

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

### Repository Component Filtering in CLI Config

Source: https://context7.com/deezer/caupain/llms.txt

Define repository configurations, including default repositories, includes, and excludes. This TOML syntax is required at the end of the file.

```toml
# TOML array-of-tables syntax required; must be at end of file
[[ repositories ]]
default = "mavenCentral"
includes = [
    { group = "org.jetbrains.kotlinx" },
    { group = "com.example.**" }
]
excludes = [
    { group = "com.other" }
]

[[ repositories ]]
url = "https://private.repo/maven"
user = "user"
password = "pass"
includes = [
    { group = "com.mycompany", name = "internal-lib" }
]
```

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

### Customize Plugin Outputs

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Configure the output formats for the dependency update reports. By default, console and HTML outputs are enabled.

```kotlin
outputs {
    // Console output. Enabled by default
    console {
        enabled = true
    }
    // HTML output. Enabled by default. Default output file is "build/reports/dependency-updates.html"
    html {
        enabled = true
        outputFile = file("path/to/output.html")
    }
    // Markdown output. Disabled by default. Default output file is "build/reports/dependency-updates.md"
    markdown {
        enabled = true
        outputFile = file("path/to/output.md")
    }
    // JSON output. Disabled by default. Default output file is "build/reports/dependency-updates.json"
    json {
        enabled = true
        outputFile = file("path/to/output.json")
    }
}
```

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

### Run Dependency Update Check

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Execute the dependency update check task from your terminal. The `--no-configuration-cache` flag is recommended for this task.

```bash
./gradlew checkDependencyUpdates --no-configuration-cache
```

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

### Implement Custom Formatter

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Provide a custom implementation for the formatter to define the output structure of the dependency update results.

```kotlin
tasks.withType<DependenciesUpdateTask> {
    customFormatter { result ->
        // output whatever you want here
    }
}
```

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

### Update Selection Configuration

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Configure which dependency updates are suggested by defining exclusions and inclusions. Supports exclusion/inclusion by key, group, name, and plugin ID.

```toml
# You can exclude by key. The key matches the name used in the version catalog.
excludedKeys = [ "excluded1", "excluded2" ]
# You can also exclude by group and optionally by name. If name is not specified, all dependencies 
in the group are excluded. Furthermore, if name is not specified, then group is interpreted as a glob.
excludedLibraries = [
    { group = "com.google.guava" }, # Exclude all dependencies in the group
    { group = "com.google.guava", name = "guava" }, # Exclude only the guava dependency
    { group = "com.google.**" }, # Exclude all dependencies with group starting with com.google
    { group = "com.google.*.sub" }, # Exclude all dependencies like com.google.something.sub
]
# You can exclude plugins by their id
excludedPlugins = [
    { id = "excluded.plugin.id" }
]
# You can include by key. The key matches the name used in the version catalog.
includedKeys = [ "excluded1", "excluded2" ]
# You can also include by group and optionally by name. If name is not specified, all dependencies 
in the group are included. Furthermore, if name is not specified, then group is interpreted as a glob.
includedLibraries = [
    { group = "com.google.guava" }, # Include all dependencies in the group
    { group = "com.google.guava", name = "guava" }, # Include only the guava dependency
    { group = "com.google.**" }, # Include all dependencies with group starting with com.google
    { group = "com.google.*.sub" }, # Include all dependencies like com.google.something.sub
]
# You can include plugins by their id
includedPlugins = [
    { id = "included.plugin.id" }
]
```

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

### Replace Outdated Dependencies with Gradle

Source: https://context7.com/deezer/caupain/llms.txt

Use the `./gradlew replaceOutdatedDependencies` command to automatically replace outdated dependencies in your project.

```bash
# Replace versions in-place
./gradlew replaceOutdatedDependencies
```

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

### Configure Maven Repositories for Dependencies and Plugins

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Define custom Maven repositories for both project dependencies and plugins. Supports default repositories, custom URLs, and credentials.

```kotlin
repositories {
    // Defines the repositories for the dependencies
    libraries {
        // Default repositories "google", "mavenCentral" and "gradlePluginPortal" are provided as shortcuts
        repository(DefaultRepositories.google)
        // You can also specify a custom repository
        repository("https://www.example.com/maven2")
        // With optional password credentials
        repository("https://www.example.com/maven2", "user", "password")
        // Or with header credentials
        repository("https://www.example.com/maven2") {
            headerCredentials {
                name = "headerName"
                value = "headerValue"
            }
        }
    }
    // Defines the repositories for the plugins
    plugins {
        repository("https://www.example.com/maven2")
        repository("https://www.example.com/maven2", "user", "password")
    }
}
```

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

### Run Dependency Update Checks with DependencyUpdateChecker

Source: https://context7.com/deezer/caupain/llms.txt

Execute update checks using a configured `Configuration`. This class queries repositories in parallel and applies policies to return a structured result. It also provides progress updates.

```kotlin
import com.deezer.caupain.DependencyUpdateChecker
import com.deezer.caupain.model.Configuration
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

runBlocking {
    val checker = DependencyUpdateChecker(
        configuration = config,
        currentGradleVersion = "8.7",   // pass null to skip Gradle update check
        logger = object : com.deezer.caupain.model.Logger {
            override fun info(message: String)  { println("[INFO] $message") }
            override fun debug(message: String) { /* suppress */ }
            override fun warn(message: String)  { println("[WARN] $message") }
        }
    )

    // Optionally collect progress updates
    val progressJob = launch {
        checker.progress.collect {
            when (progress) {
                is DependencyUpdateChecker.Progress.Indeterminate ->
                    println(">> ${progress.taskName}…")
                is DependencyUpdateChecker.Progress.Determinate ->
                    println(">> ${progress.taskName} ${progress.percentage}%")
                null -> {}
            }
        }
    }

    val result = checker.checkForUpdates()
    progressJob.cancel()

    // Inspect results
    result.gradleUpdateInfo?.let {
        println("Gradle: ${it.currentVersion} -> ${it.updatedVersion}")
    }
    result.updateInfos.forEach { (type, updates) ->
        println("=== ${type.name} ===")
        updates.forEach { info ->
            println("  ${info.dependencyId}: ${info.currentVersion} -> ${info.updatedVersion}")
            info.releaseNoteUrl?.let { println("    Release notes: $it") }
        }
    }
    if (result.isEmpty()) println("Everything is up to date!")
}
```

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

### Configure Cache Directory

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Specify a custom directory for storing the HTTP cache. Defaults to the user's cache directory.

```toml
cacheDir = "path/to/cache/dir"
```

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

### Configure Dependency Update Checks with Configuration

Source: https://context7.com/deezer/caupain/llms.txt

Define repositories, exclusions, policies, and cache settings for update checks. Supports private repositories with credentials and custom stability levels.

```kotlin
import com.deezer.caupain.model.Configuration
import com.deezer.caupain.model.DefaultRepositories
import com.deezer.caupain.model.GradleStabilityLevel
import com.deezer.caupain.model.HeaderCredentials
import com.deezer.caupain.model.LibraryExclusion
import com.deezer.caupain.model.Repository
import com.deezer.caupain.policies.StabilityLevelPolicy
import okio.Path.Companion.toPath

val config = Configuration(
    repositories = listOf(
        DefaultRepositories.mavenCentral,
        DefaultRepositories.google,
        Repository(
            url = "https://private.repo/maven",
            credentials = HeaderCredentials("X-Api-Key", System.getenv("REPO_TOKEN"))
        )
    ),
    pluginRepositories = listOf(DefaultRepositories.gradlePlugins),
    versionCatalogPaths = listOf("gradle/libs.versions.toml".toPath()),
    excludedLibraries = listOf(
        LibraryExclusion(group = "com.google.guava"),
        LibraryExclusion(group = "com.internal.**")
    ),
    policies = listOf(StabilityLevelPolicy.name),   // "stability-level"
    cacheDir  = "build/caupain-cache".toPath(),
    gradleStabilityLevel = GradleStabilityLevel.STABLE,
    onlyCheckStaticVersions = true,
    checkIgnored = false,
    githubToken  = System.getenv("GITHUB_TOKEN"),
    searchReleaseNote = true,
    verifyExistence = false
)
```

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

### Using Caupain Output Formatters

Source: https://context7.com/deezer/caupain/llms.txt

This snippet shows how to format dependency update results for console, Markdown, HTML, and JSON outputs. For file outputs (Markdown, HTML, JSON), ensure you are within a coroutine scope.

```kotlin
import com.deezer.caupain.formatting.console.ConsoleFormatter
import com.deezer.caupain.formatting.console.ConsolePrinter
import com.deezer.caupain.formatting.markdown.MarkdownFormatter
import com.deezer.caupain.formatting.html.HtmlFormatter
import com.deezer.caupain.formatting.json.JsonFormatter
import com.deezer.caupain.formatting.model.Input
import okio.FileSystem
import okio.Path.Companion.toPath
import kotlinx.coroutines.runBlocking

val result = checker.checkForUpdates()
val formatterInput = Input(result, showVersionReferences = true)

// Console output
val console = ConsoleFormatter(ConsolePrinter { println(it) })
console.format(formatterInput)

// Markdown output to file
runBlocking {
    val markdownFormatter = MarkdownFormatter()
    markdownFormatter.format(
        sink = FileSystem.SYSTEM.sink("build/reports/updates.md".toPath()),
        input = formatterInput
    )
    // HTML output
    val htmlFormatter = HtmlFormatter()
    htmlFormatter.format(
        sink = FileSystem.SYSTEM.sink("build/reports/updates.html".toPath()),
        input = formatterInput
    )
    // JSON output
    val jsonFormatter = JsonFormatter()
    jsonFormatter.format(
        sink = FileSystem.SYSTEM.sink("build/reports/updates.json".toPath()),
        input = formatterInput
    )
}
```

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

### Dependency Selection in CLI Config

Source: https://context7.com/deezer/caupain/llms.txt

Configure which dependencies and plugins Caupain should exclude from checks within the TOML configuration file.

```toml
# Exclude by version catalog key
excludedKeys = [ "some-internal-lib" ]

# Exclude all libraries in a group (glob supported)
excludedLibraries = [
    { group = "com.google.guava" },
    { group = "com.google.**" },
    { group = "com.example", name = "legacy-module" }
]

# Exclude plugins
excludedPlugins = [
    { id = "com.android.application" }
]

```

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

### Caupain Plugin Configuration Block

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Use this block in your root `build.gradle.kts` to configure the Caupain plugin's behavior.

```kotlin
caupain {
    // Your configuration here
}
```

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

### Add Caupain Core Dependency to libs.versions.toml

Source: https://github.com/deezer/caupain/blob/main/core/README.md

Configure the Caupain core library version and dependency in your Gradle libs.versions.toml file. This sets up the library for use in your project.

```toml
[versions]
caupain = "1.0.1"
# ...your other versions

[libraries]
caupain-core = { module = "com.deezer.caupain:core", version.ref = "caupain" }
# ... The rest of your file
```

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

### Perform In-Place Version Updates with DependencyVersionsReplacer

Source: https://context7.com/deezer/caupain/llms.txt

Atomically rewrite the version catalog file with updated versions based on the `DependenciesUpdateResult`. Preserves original formatting and comments.

```kotlin
import com.deezer.caupain.DependencyVersionsReplacer
import okio.Path.Companion.toPath
import kotlinx.coroutines.runBlocking

runBlocking {
    val result = checker.checkForUpdates()   // from DependencyUpdateChecker above

    if (!result.isEmpty()) {
        val replacer = DependencyVersionsReplacer()
        replacer.replaceVersions(
            versionCatalogPath = "gradle/libs.versions.toml".toPath(),
            updateResult = result
        )
        println("Version catalog updated in place.")
    } else {
        println("Nothing to update.")
    }
}
```

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

### Set Output Type

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Define the output format for the dependency update report. Supported types are 'console', 'html', 'markdown', and 'json'.

```toml
outputType = "html"
```

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

### Include Plugins by ID

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Suggest updates only for specific plugins by their unique IDs.

```kotlin
includePluginIds("included.plugin.id")
```

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

### Configure Other Plugin Options

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Set various other options for the Caupain plugin, including cache usage, static version checking, stability levels, and GitHub integration.

```kotlin
// Whether to store HTTP cache for the Maven requests
useCache = true
```

```kotlin
// By default, Caupain only checks updates for static versions in the version catalog (versions like 
// 1.0.0 or 1.0.0-SNAPSHOT).
// The rationale behind this is that dynamic versions or rich versions indicate that the version range
// is already specified, and that an update isn't needed. If this value is passed to false, Caupain 
// will try to find the latest version for all dependencies, even if they are dynamic or rich versions.
// This is where the result may not be exactly what you want, because Caupain will not use Gradle to
// try to resolve the exact dependency that is used.
// Default is true.
onlyCheckStaticVersions = true
```

```kotlin
// The stability level to use for Gradle version checks. Default is STABLE.
gradleStabilityLevel = GradleStabilityLevel.STABLE
```

```kotlin
// Whether to show a section in the report about the ignored available updates.
checkIgnored = true
```

```kotlin
// GitHub token, used to search for release notes on GitHub.
githubToken = "your-token"
```

```kotlin
// Whether to search for release notes on GitHub and display the link to them in the results.
// If a GitHub token is provided, this will be true by default.
searchReleaseNotes = true
```

```kotlin
// Whether to verify that .pom files exist in the repository before accepting a version as valid.
// When enabled, only versions with available POM metadata will be considered for updates.
// This helps ensure that suggested versions are actually downloadable.
// Note: This may slow down the checking process as it adds extra network requests.
// Default is false.
verifyExistence = true
```

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

### Configure Dependency Update Policies

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Define custom update policies for dependency updates using task configuration. Allows for predefined policies like StabilityLevelPolicy or custom logic.

```kotlin
tasks.withType<DependenciesUpdateTask> {
    // You can use one of the predefined policies
    selectIf(StabilityLevelPolicy)
    // Or define your own. In the "selectIf" block, "this" will have properties "dependency", "currentVersion" and
    // "updatedVersion" which are the dependency, current and updated versions of the dependency.
    selectIf {
        updatedVersion.text == "1.0.0"
    }
}
```

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

### Include Libraries using LibraryInclusion Objects

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Use `LibraryInclusion` objects for more structured inclusion of libraries by group and name.

```kotlin
includeLibraries(
  LibraryInclusion(group = "com.example"),
  LibraryInclusion(group = "com.example", name = "example")
)
```

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

### Set Policy Name

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Specify a policy name for version checks. Refer to the documentation for available policies.

```toml
policy = "stability-level"
```

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

### Define Custom Repositories and Filters in Kotlin

Source: https://context7.com/deezer/caupain/llms.txt

Configure custom Maven repositories with authentication and apply component filters to restrict dependency resolution. This allows fine-grained control over where and which dependencies are fetched.

```kotlin
import com.deezer.caupain.model.DefaultRepositories
import com.deezer.caupain.model.HeaderCredentials
import com.deezer.caupain.model.PasswordCredentials
import com.deezer.caupain.model.Repository
import com.deezer.caupain.model.buildComponentFilter
import com.deezer.caupain.model.withComponentFilter

// Public repository (no auth)
val central: Repository = DefaultRepositories.mavenCentral

// Password-protected repository
val privateRepo: Repository = Repository(
    url = "https://nexus.corp/maven",
    credentials = PasswordCredentials("ci-bot", System.getenv("NEXUS_PASSWORD"))
)

// Header-authenticated repository
val headerRepo: Repository = Repository(
    url = "https://artifactory.corp/maven",
    credentials = HeaderCredentials("X-JFrog-Art-Api", System.getenv("JFROG_TOKEN"))
)

// Repository restricted to a specific group
val googleFiltered: Repository = DefaultRepositories.google.withComponentFilter {
    include(group = "com.google.**")
    exclude(group = "com.google.guava")
}

// Repository that handles only one artifact
val internalRepo: Repository = Repository(
    url = "https://internal.corp/maven"
).withComponentFilter {
    include(group = "com.mycompany", name = "proprietary-sdk")
}

val config = Configuration(
    repositories = listOf(googleFiltered, privateRepo, central),
    pluginRepositories = listOf(DefaultRepositories.gradlePlugins)
)
```

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

### Use Caupain Core Dependency in Gradle

Source: https://github.com/deezer/caupain/blob/main/core/README.md

Include the Caupain core library in your project's dependencies using the 'implementation' keyword in your Gradle build file.

```kotlin
implementation(libs.caupain.core)
```

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

### Configure Repository Component Filtering

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Apply component filtering to repositories to specify which dependencies or plugins can be searched for. Supports inclusions and exclusions based on group, name, or globs.

```kotlin
repositories {
    libraries {
        // You can add filtering on default repositories
        repository(DefaultRepositories.google) {
            // If only exclusions are defined, then all components except those excluded will be searched
            // for in the repository. If only inclusions are defined, then only those components will be searched
            // for in the repository. If both are defined, then only the components that are included and not excluded
            // will be searched for in the repository.
            include(group = "com.example", name = "example") // You can specify a group and name
            include(group = "com.example") // You can also only specify a group...
            include(group = "com.example.**") // ...or use globs
            exclude(group = "com.example")
        }
        // This can also be done for custom repositories
        repository("https://www.example.com/maven2") {
            //include(...)
            //exclude(...)
        }
    }
    // The same can be done for plugins
    plugins {
        //...
    }
}
```

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

### Add Caupain Core Library Dependency

Source: https://context7.com/deezer/caupain/llms.txt

Define the Caupain core library version and add it as an implementation dependency in your Gradle build file.

```toml
# gradle/libs.versions.toml
[versions]
caupain = "1.9.1"

[libraries]
caupain-core = { module = "com.deezer.caupain:core", version.ref = "caupain" }
```

```kotlin
// build.gradle.kts
dependencies {
    implementation(libs.caupain.core)
}
```

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

### Exclude Dependencies by Key

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Configure exclusions in your Gradle build script by specifying dependency keys. This prevents updates for dependencies matching these keys.

```kotlin
excludeKeys("excluded1", "excluded2")
```

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

### IntelliJ Compatible Inline Exclusion

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Use `#noinspection NewerVersionAvailable` comments in TOML files to mark ignored updates, compatible with IntelliJ IDEA's inspection system.

```toml
#noinspection NewerVersionAvailable
```

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

### Implement Custom Update Policy in Kotlin

Source: https://context7.com/deezer/caupain/llms.txt

Define a custom `Policy` to reject specific version patterns like 'eap', 'dev', or 'preview'. This policy can be directly used when initializing `DependencyUpdateChecker`.

```kotlin
import com.deezer.caupain.model.Dependency
import com.deezer.caupain.model.GradleDependencyVersion
import com.deezer.caupain.model.Policy
import com.deezer.caupain.model.versionCatalog.Version

// Custom policy: reject any version containing "eap" or "dev"
object NoPreviewPolicy : Policy {
    override val name        = "no-preview"
    override val description = "Rejects EAP, dev, and preview releases."

    override fun select(
        dependency: Dependency,
        currentVersion: Version.Resolved,
        updatedVersion: GradleDependencyVersion.Static
    ): Boolean {
        val versionText = updatedVersion.exactVersion.text.lowercase()
        return !versionText.contains("eap")
            && !versionText.contains("dev")
            && !versionText.contains("preview")
    }
}

// Use directly when building the checker
val checker = DependencyUpdateChecker(
    configuration = config,
    currentGradleVersion = null,
    policies = listOf(NoPreviewPolicy)
)
```

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

### Enable Check for Ignored Updates

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

Display a section in the report detailing ignored available updates. Defaults to false.

```toml
checkIgnored = true
```

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

### Configure Dependency Filters

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Define filters to restrict which dependency updates are suggested. Supports prefix and range version filters, and can apply to groups or plugins.

```kotlin
addFilter(group = "com.google.guava", name = "guava", versionFilter = "1.+")
```

```kotlin
addFilter(group = "com.google.guava", name = "guava", versionFilter = "(1.2, 1.5]")
```

```kotlin
addFilter(group = "com.google.**", versionFilter = "1.+")
```

```kotlin
addFilter(pluginId = "filtered.plugin.id", versionFilter = "1.+")
```

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

### Disable Static Version Check

Source: https://github.com/deezer/caupain/blob/main/cli/README.md

When set to false, Caupain will attempt to find the latest version for all dependencies, including dynamic or rich versions. This may lead to unexpected results as Gradle's resolution is not fully utilized.

```toml
onlyCheckStaticVersions = false
```

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

### Exclude Libraries by Group and Name

Source: https://github.com/deezer/caupain/blob/main/gradle-plugin/README.md

Exclude specific libraries or entire groups from update suggestions. Supports glob patterns for group names and exact matching for group/name combinations.

```kotlin
excludeLibrary(group = "com.example")
excludeLibrary(group = "com.example.**")
excludeLibrary(group = "com.example.*.sub")
excludeLibrary(group = "com.example", name = "example")
```