feat: support OIDC detector controls in config file + warn on misconfig

Address PR #311 review feedback:

- Allow oidc_detector_order and oidc_disabled_detectors to be set in
  config.ini (under [default] or a profile). The config disabled list is
  additive with the per-detector CLOUDSMITH_OIDC_<ID>_DISABLED env vars;
  the --oidc-detector-order flag / env var still override the config order.
- Surface a warning (in the CLI layer, where click lives) when
  --oidc-detector-order names unknown ids, or when the order/disable
  controls leave no detector enabled. Advisory only: the credential
  fallback chain is preserved rather than aborting with a UsageError, and
  the core detectors module stays click-free.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cloudsmith-iduffy

CHANGELOG.md

@@ -16,7 +16,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Added GitHub Actions to OIDC credential auto-discovery. When running in GitHub Actions (with `id-token: write` permission), the CLI fetches an OIDC token from the Actions runtime endpoint and exchanges it for a Cloudsmith access token. Works out of the box with no extra dependencies.
 - Added a generic fallback to OIDC credential auto-discovery. When no dedicated environment is detected, the CLI reads an OIDC token from the `CLOUDSMITH_OIDC_TOKEN` environment variable (useful for Jenkins or any custom CI/CD) and exchanges it for a Cloudsmith access token. Works out of the box with no extra dependencies.
 - Added GitLab CI to OIDC credential auto-discovery. When running in GitLab CI/CD, the CLI reads the OIDC token from the `CLOUDSMITH_OIDC_TOKEN` environment variable (configured via `id_tokens` in `.gitlab-ci.yml`) and exchanges it for a Cloudsmith access token. Works out of the box with no extra dependencies.
-- Added controls for OIDC detector selection. Set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip a specific detector (only the literal `true` disables), or use `--oidc-detector-order` (env var `CLOUDSMITH_OIDC_DETECTOR_ORDER`) with a comma-separated list of detector ids to override which detectors are considered and the order they are tried in. When both are set, disable flags take precedence over the order list. Detector ids: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
+- Added controls for OIDC detector selection. Set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip a specific detector (only the literal `true` disables), or use `--oidc-detector-order` (env var `CLOUDSMITH_OIDC_DETECTOR_ORDER`) with a comma-separated list of detector ids to override which detectors are considered and the order they are tried in. When both are set, disable flags take precedence over the order list. Both controls can also be set in `config.ini` via the `oidc_detector_order` and `oidc_disabled_detectors` keys (the latter additive with the `*_DISABLED` env vars). Unknown ids in the order, or controls that leave no detector enabled, are surfaced as a warning. Detector ids: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
 
 ## [1.18.0] - 2026-06-09
 

README.md

@@ -216,10 +216,20 @@ As a fallback for environments without a dedicated detector (for example Jenkins
 By default the CLI tries each detector in a fixed priority order and uses the first that matches. Two controls let you override this when a detector matches an environment you don't want it to (for example, the AWS detector matching ambient instance credentials):
 
 - **Disable a detector** — set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip it entirely. Only the literal value `true` (case-insensitive) disables; anything else leaves the detector enabled. For example, `CLOUDSMITH_OIDC_AWS_DISABLED=true` skips the AWS detector so an explicitly-set `CLOUDSMITH_OIDC_TOKEN` is picked up by the generic detector instead.
-- **Reorder evaluation** — use `--oidc-detector-order` (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) with a comma-separated list of detector ids to control both which detectors are considered and the order they are tried in (first match wins). Ids not listed are skipped; unrecognised ids are ignored. For example, `--oidc-detector-order=generic,aws` tries the generic detector first and considers only those two.
+- **Reorder evaluation** — use `--oidc-detector-order` (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) with a comma-separated list of detector ids to control both which detectors are considered and the order they are tried in (first match wins). Ids not listed are skipped; unrecognised ids are ignored with a warning. For example, `--oidc-detector-order=generic,aws` tries the generic detector first and considers only those two.
 
 When both are set, the order list defines the candidate set and sequence, then the `*_DISABLED` flags are applied on top — so a disabled detector is always skipped even if it appears in the order list. Detector ids are: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
 
+Both controls can also be set in `config.ini`, under `[default]` or a profile section:
+
+```ini
+[default]
+oidc_detector_order = github, aws
+oidc_disabled_detectors = aws, gitlab
+```
+
+The `--oidc-detector-order` flag (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) overrides the `oidc_detector_order` config value. The `oidc_disabled_detectors` config key is additive with the per-detector `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED` environment variables — a detector disabled by either is skipped.
+
 ## Configuration
 
 There are two configuration files used by the CLI:

cloudsmith_cli/cli/config.py

@@ -69,6 +69,8 @@ class Default(SectionSchema):
         oidc_audience = ConfigParam(name="oidc_audience", type=str)
         oidc_org = ConfigParam(name="oidc_org", type=str)
         oidc_service_slug = ConfigParam(name="oidc_service_slug", type=str)
+        oidc_detector_order = ConfigParam(name="oidc_detector_order", type=str)
+        oidc_disabled_detectors = ConfigParam(name="oidc_disabled_detectors", type=str)
         metadata_failure_mode = ConfigParam(name="metadata_failure_mode", type=str)
 
     @matches_section("profile:*")
@@ -499,6 +501,16 @@ def oidc_detector_order(self, value):
         """Set value for the OIDC detector evaluation order."""
         self._set_option("oidc_detector_order", value)
 
+    @property
+    def oidc_disabled_detectors(self):
+        """Get the comma-separated OIDC detector ids disabled via config."""
+        return self._get_option("oidc_disabled_detectors")
+
+    @oidc_disabled_detectors.setter
+    def oidc_disabled_detectors(self, value):
+        """Set the comma-separated OIDC detector ids disabled via config."""
+        self._set_option("oidc_disabled_detectors", value)
+
     @property
     def metadata_failure_mode(self):
         """Get value for push-time metadata failure mode."""

cloudsmith_cli/cli/decorators.py

@@ -11,7 +11,10 @@
 from ..core.api.init import initialise_api as _initialise_api
 from ..core.credentials.chain import CredentialProviderChain
 from ..core.credentials.models import CredentialContext
-from ..core.credentials.oidc.detectors import disabled_detectors_from_env
+from ..core.credentials.oidc.detectors import (
+    disabled_detectors_from_env,
+    registered_detectors,
+)
 from ..core.mcp import server
 from ..core.rest import create_requests_session as _create_session
 from . import config, utils
@@ -309,6 +312,50 @@ def wrapper(ctx, *args, **kwargs):
     return wrapper
 
 
+def _parse_detector_ids(value):
+    """Split a comma-separated detector id string into stripped, lowercased ids."""
+    return [
+        token.strip().lower() for token in (value or "").split(",") if token.strip()
+    ]
+
+
+def _config_disabled_detectors(value):
+    """Detector ids disabled via the config-file ``oidc_disabled_detectors`` key."""
+    return frozenset(_parse_detector_ids(value))
+
+
+def _warn_on_oidc_detector_controls(order, disabled):
+    """Warn when the OIDC detector order/disable controls look misconfigured.
+
+    Advisory only — detection itself is resolved in the core detectors module;
+    these warnings surface user-facing mistakes (a typo'd id, or controls that
+    leave nothing enabled) without aborting the credential fallback chain.
+    """
+    valid_ids = [detector_cls.id for detector_cls in registered_detectors()]
+    order_ids = _parse_detector_ids(order)
+
+    unknown_ids = [
+        identifier for identifier in order_ids if identifier not in valid_ids
+    ]
+    if unknown_ids:
+        click.secho(
+            "OIDC: ignoring unknown detector id(s) in --oidc-detector-order: "
+            f"{', '.join(unknown_ids)}. Valid ids: {', '.join(valid_ids)}.",
+            fg="yellow",
+            err=True,
+        )
+
+    candidate_ids = [i for i in order_ids if i in valid_ids] if order_ids else valid_ids
+    enabled_ids = [i for i in candidate_ids if i not in disabled]
+    if (order_ids or disabled) and not enabled_ids:
+        click.secho(
+            "OIDC: no detectors are enabled after applying the detector "
+            "order/disable controls; OIDC auto-discovery will be skipped.",
+            fg="yellow",
+            err=True,
+        )
+
+
 def resolve_credentials(f):
     """Resolve credentials via the provider chain. Depends on initialise_session."""
 
@@ -363,6 +410,13 @@ def wrapper(ctx, *args, **kwargs):
         if oidc_detector_order:
             opts.oidc_detector_order = oidc_detector_order
 
+        oidc_disabled_detectors = disabled_detectors_from_env(
+            os.environ
+        ) | _config_disabled_detectors(opts.oidc_disabled_detectors)
+        _warn_on_oidc_detector_controls(
+            opts.oidc_detector_order, oidc_disabled_detectors
+        )
+
         context = CredentialContext(
             session=opts.session,
             api_key_from_flag=opts.api_key_from_flag,
@@ -377,7 +431,7 @@ def wrapper(ctx, *args, **kwargs):
             oidc_service_slug=opts.oidc_service_slug,
             oidc_discovery_disabled=opts.oidc_discovery_disabled,
             oidc_detector_order=opts.oidc_detector_order,
-            oidc_disabled_detectors=disabled_detectors_from_env(os.environ),
+            oidc_disabled_detectors=oidc_disabled_detectors,
         )
 
         chain = CredentialProviderChain()

cloudsmith_cli/cli/tests/test_oidc_detector_config.py

@@ -0,0 +1,77 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Tests for config-file + CLI-layer OIDC detector controls."""
+
+import pytest
+
+from ..config import ConfigReader, Options
+from ..decorators import _config_disabled_detectors, _warn_on_oidc_detector_controls
+
+
+@pytest.fixture
+def config_file(tmp_path):
+    """Yield a writer for a temporary config.ini, restoring reader state."""
+    original_files = list(ConfigReader.config_files)
+
+    def write(body):
+        path = tmp_path / "config.ini"
+        path.write_text(body)
+        return str(path)
+
+    yield write
+    ConfigReader.config_files = original_files
+
+
+class TestConfigFileControls:
+    def test_detector_order_is_read_from_config(self, config_file):
+        path = config_file("[default]\noidc_detector_order = github, aws\n")
+        opts = Options()
+        opts.load_config_file(path)
+        assert opts.oidc_detector_order == "github, aws"
+
+    def test_disabled_detectors_is_read_from_config(self, config_file):
+        path = config_file("[default]\noidc_disabled_detectors = aws,gitlab\n")
+        opts = Options()
+        opts.load_config_file(path)
+        assert opts.oidc_disabled_detectors == "aws,gitlab"
+
+
+class TestConfigDisabledDetectors:
+    def test_parses_comma_separated_ids(self):
+        assert _config_disabled_detectors("aws, gitlab") == frozenset({"aws", "gitlab"})
+
+    def test_lowercases_and_strips(self):
+        assert _config_disabled_detectors("  AWS , GitLab ") == frozenset(
+            {"aws", "gitlab"}
+        )
+
+    def test_empty_or_none_is_empty_set(self):
+        assert _config_disabled_detectors(None) == frozenset()
+        assert _config_disabled_detectors("  ") == frozenset()
+
+
+class TestDetectorControlWarnings:
+    def test_unknown_id_warns(self, capsys):
+        _warn_on_oidc_detector_controls("github,nope", frozenset())
+        err = capsys.readouterr().err
+        assert "nope" in err
+        assert "github" not in err.split("Valid ids", 1)[0]
+
+    def test_no_warning_when_all_ids_known(self, capsys):
+        _warn_on_oidc_detector_controls("github,aws", frozenset())
+        assert capsys.readouterr().err == ""
+
+    def test_no_warning_without_controls(self, capsys):
+        _warn_on_oidc_detector_controls(None, frozenset())
+        assert capsys.readouterr().err == ""
+
+    def test_warns_when_no_detectors_enabled_via_order(self, capsys):
+        _warn_on_oidc_detector_controls("nope", frozenset())
+        assert "no detectors are enabled" in capsys.readouterr().err.lower()
+
+    def test_warns_when_order_fully_disabled(self, capsys):
+        _warn_on_oidc_detector_controls("aws", frozenset({"aws"}))
+        assert "no detectors are enabled" in capsys.readouterr().err.lower()
+
+    def test_no_enabled_warning_in_normal_case(self, capsys):
+        _warn_on_oidc_detector_controls("github,aws", frozenset())
+        assert "no detectors are enabled" not in capsys.readouterr().err.lower()