From 10b07d73478274ca6890f13297877fd1b0292e25 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 17:33:45 +0000
Subject: [PATCH 01/11] =?UTF-8?q?=E2=9C=A8=20Add=20optional=20command-line?=
 =?UTF-8?q?=20interface?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .pre-commit-config.yaml                    |   4 +-
 README.md                                  |  37 +++
 examples/example.py                        |   2 +-
 poetry.lock                                |  33 +-
 pyproject.toml                             |   9 +-
 src/twentemilieu/cli/__init__.py           | 268 ++++++++++++++++
 src/twentemilieu/cli/async_typer.py        | 191 +++++++++++
 src/twentemilieu/cli/ruff.toml             |   9 +
 tests/__snapshots__/test_twentemilieu.ambr |  21 ++
 tests/cli/__init__.py                      |   1 +
 tests/cli/__snapshots__/test_cli.ambr      | 216 +++++++++++++
 tests/cli/test_cli.py                      | 348 +++++++++++++++++++++
 tests/conftest.py                          |  53 ++++
 tests/fixtures/calendar_response.json      |  28 ++
 tests/fixtures/empty_pickups.json          |   7 +
 tests/fixtures/sample_pickups.json         |   7 +
 tests/test_twentemilieu.py                 | 234 ++++++--------
 17 files changed, 1314 insertions(+), 154 deletions(-)
 create mode 100644 src/twentemilieu/cli/__init__.py
 create mode 100644 src/twentemilieu/cli/async_typer.py
 create mode 100644 src/twentemilieu/cli/ruff.toml
 create mode 100644 tests/__snapshots__/test_twentemilieu.ambr
 create mode 100644 tests/cli/__init__.py
 create mode 100644 tests/cli/__snapshots__/test_cli.ambr
 create mode 100644 tests/cli/test_cli.py
 create mode 100644 tests/conftest.py
 create mode 100644 tests/fixtures/calendar_response.json
 create mode 100644 tests/fixtures/empty_pickups.json
 create mode 100644 tests/fixtures/sample_pickups.json

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4db286ea..805d886d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -81,6 +81,7 @@ repos:
         name: ⮐  Fix End of Files
         language: system
         types: [text]
+        exclude: ^tests/.*/__snapshots__/
         entry: poetry run end-of-file-fixer
         stages: [commit, push, manual]
       - id: ty
@@ -118,12 +119,13 @@ repos:
         name: 🧪 Running tests and test coverage with pytest
         language: system
         types: [python]
-        entry: poetry run pytest
+        entry: poetry run pytest --cov twentemilieu tests
         pass_filenames: false
       - id: trailing-whitespace
         name: ✄  Trim Trailing Whitespace
         language: system
         types: [text]
+        exclude: ^tests/.*/__snapshots__/
         entry: poetry run trailing-whitespace-fixer
         stages: [commit, push, manual]
       - id: yamllint
diff --git a/README.md b/README.md
index b2b39001..317496f3 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,43 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## Command-line interface
+
+This package ships with an optional CLI that is handy for quickly
+inspecting the waste pickup schedule for an address. Install it with
+the `cli` extra:
+
+```bash
+pip install "twentemilieu[cli]"
+```
+
+The CLI exposes two commands: `upcoming` (a chronologically sorted list
+of the next pickups across all waste types) and `next` (the single next
+pickup, optionally filtered by waste type). Both commands accept
+`--post-code`, `--house-number`, and an optional `--house-letter`, and
+both support a `--json` flag for machine-readable output.
+
+```bash
+# Show the next 5 pickups across all waste types
+twentemilieu upcoming --post-code 7531AT --house-number 148
+
+# Limit to the next 3 pickups and emit JSON
+twentemilieu upcoming --post-code 7531AT --house-number 148 --limit 3 --json
+
+# Show the very next pickup (any waste type)
+twentemilieu next --post-code 7531AT --house-number 148
+
+# Show the next organic pickup only
+twentemilieu next --post-code 7531AT --house-number 148 --waste-type organic
+
+# Emit as JSON for use in scripts
+twentemilieu next --post-code 7531AT --house-number 148 --waste-type organic --json
+```
+
+Address options can also be supplied via the `TWENTEMILIEU_POST_CODE`,
+`TWENTEMILIEU_HOUSE_NUMBER`, and `TWENTEMILIEU_HOUSE_LETTER` environment
+variables. Run any command with `--help` for the full reference.
+
 ## Changelog & Releases
 
 This repository keeps a change log using [GitHub's releases][releases]
diff --git a/examples/example.py b/examples/example.py
index 4ac396f3..f8f81426 100644
--- a/examples/example.py
+++ b/examples/example.py
@@ -8,7 +8,7 @@
 
 async def main() -> None:
     """Show example on stats from Twente Milieu."""
-    async with TwenteMilieu(post_code="7531LA", house_number=16) as twente:
+    async with TwenteMilieu(post_code="7531AT", house_number=148) as twente:
         print(twente)
         unique_id = await twente.unique_id()
         print("Unique Address ID:", unique_id)
diff --git a/poetry.lock b/poetry.lock
index 0dd3e61f..e5d56688 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -176,11 +176,12 @@ version = "0.0.4"
 description = "Document parameters, class attributes, return types, and variables inline, with Annotated."
 optional = false
 python-versions = ">=3.8"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320"},
     {file = "annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [[package]]
 name = "annotated-types"
@@ -526,11 +527,12 @@ version = "8.3.2"
 description = "Composable command line interface toolkit"
 optional = false
 python-versions = ">=3.10"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d"},
     {file = "click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [package.dependencies]
 colorama = {version = "*", markers = "platform_system == \"Windows\""}
@@ -559,12 +561,12 @@ version = "0.4.6"
 description = "Cross-platform colored terminal text."
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
-groups = ["dev"]
-markers = "sys_platform == \"win32\" or platform_system == \"Windows\""
+groups = ["main", "dev"]
 files = [
     {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
 ]
+markers = {main = "extra == \"cli\" and platform_system == \"Windows\"", dev = "platform_system == \"Windows\" or sys_platform == \"win32\""}
 
 [[package]]
 name = "covdefaults"
@@ -1098,11 +1100,12 @@ version = "4.0.0"
 description = "Python port of markdown-it. Markdown parsing, done right!"
 optional = false
 python-versions = ">=3.10"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147"},
     {file = "markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [package.dependencies]
 mdurl = ">=0.1,<1.0"
@@ -1245,11 +1248,12 @@ version = "0.1.2"
 description = "Markdown URL utilities"
 optional = false
 python-versions = ">=3.7"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"},
     {file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [[package]]
 name = "multidict"
@@ -1839,11 +1843,12 @@ version = "2.20.0"
 description = "Pygments is a syntax highlighting package written in Python."
 optional = false
 python-versions = ">=3.9"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176"},
     {file = "pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [package.extras]
 windows-terminal = ["colorama (>=0.4.6)"]
@@ -2173,11 +2178,12 @@ version = "15.0.0"
 description = "Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal"
 optional = false
 python-versions = ">=3.9.0"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb"},
     {file = "rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [package.dependencies]
 markdown-it-py = ">=2.2.0"
@@ -2293,11 +2299,12 @@ version = "1.5.4"
 description = "Tool to Detect Surrounding Shell"
 optional = false
 python-versions = ">=3.7"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686"},
     {file = "shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [[package]]
 name = "syrupy"
@@ -2397,11 +2404,12 @@ version = "0.24.1"
 description = "Typer, build great CLIs. Easy to code. Based on Python type hints."
 optional = false
 python-versions = ">=3.10"
-groups = ["dev"]
+groups = ["main", "dev"]
 files = [
     {file = "typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e"},
     {file = "typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45"},
 ]
+markers = {main = "extra == \"cli\""}
 
 [package.dependencies]
 annotated-doc = ">=0.0.2"
@@ -2638,7 +2646,10 @@ files = [
     {file = "zizmor-1.24.1.tar.gz", hash = "sha256:54ebb7a7061ebaa3a373126dcbafe970c9228fe274cfc40776a9714d2095b5e6"},
 ]
 
+[extras]
+cli = ["typer"]
+
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.11"
-content-hash = "f235f9eaa4489777c4ffe56ee7675641f6ba17e94c49988cf5523dd1791a687f"
+content-hash = "3aff75b168e67514b6b568792793af4b5fe5bae57e0937cda54f75efba4d4d72"
diff --git a/pyproject.toml b/pyproject.toml
index 680a8acb..84f28861 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -24,6 +24,12 @@ dynamic = ["dependencies"]
 packages = [{ include = "twentemilieu", from = "src" }]
 dependencies = ['aiohttp (>=3.0.0)', 'yarl (>=1.6.0)']
 
+[project.optional-dependencies]
+cli = ["typer>=0.15.1"]
+
+[project.scripts]
+twentemilieu = "twentemilieu.cli:cli"
+
 [tool.poetry]
 requires-poetry = '>=2.0'
 
@@ -50,6 +56,7 @@ pytest-cov = "7.1.0"
 ruff = "0.15.10"
 safety = "3.7.0"
 syrupy = "5.1.0"
+typer = "0.24.1"
 yamllint = "1.38.0"
 zizmor = "1.24.1"
 
@@ -60,6 +67,7 @@ source = ["twentemilieu"]
 [tool.coverage.report]
 show_missing = true
 fail_under = 10
+omit = ["src/twentemilieu/cli/async_typer.py"]
 
 [tool.ty.environment]
 python-version = "3.11"
@@ -83,7 +91,6 @@ ignore-imports = true
 max-line-length = 88
 
 [tool.pytest.ini_options]
-addopts = "--cov"
 asyncio_mode = "auto"
 
 [tool.ruff.lint]
diff --git a/src/twentemilieu/cli/__init__.py b/src/twentemilieu/cli/__init__.py
new file mode 100644
index 00000000..4be613e9
--- /dev/null
+++ b/src/twentemilieu/cli/__init__.py
@@ -0,0 +1,268 @@
+"""Asynchronous Python client for the Twente Milieu API."""
+
+from __future__ import annotations
+
+import json
+import sys
+from enum import StrEnum
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from twentemilieu.exceptions import (
+    TwenteMilieuAddressError,
+    TwenteMilieuConnectionError,
+)
+from twentemilieu.twentemilieu import TwenteMilieu, WasteType
+
+from .async_typer import AsyncTyper
+
+if TYPE_CHECKING:
+    from datetime import date
+
+cli = AsyncTyper(
+    help="Twente Milieu CLI",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+
+WASTE_TYPE_LABELS: dict[WasteType, str] = {
+    WasteType.NON_RECYCLABLE: "Non-recyclable",
+    WasteType.ORGANIC: "Organic (GFT)",
+    WasteType.PAPER: "Paper",
+    WasteType.PACKAGES: "Packages (PMD)",
+    WasteType.TREE: "Christmas tree",
+}
+
+WASTE_TYPE_JSON_NAMES: dict[WasteType, str] = {
+    WasteType.NON_RECYCLABLE: "non_recyclable",
+    WasteType.ORGANIC: "organic",
+    WasteType.PAPER: "paper",
+    WasteType.PACKAGES: "packages",
+    WasteType.TREE: "tree",
+}
+
+
+class CliWasteType(StrEnum):
+    """Machine-friendly waste type names for CLI options."""
+
+    NON_RECYCLABLE = "non-recyclable"
+    ORGANIC = "organic"
+    PAPER = "paper"
+    PACKAGES = "packages"
+    TREE = "tree"
+
+
+CLI_TO_WASTE_TYPE: dict[CliWasteType, WasteType] = {
+    CliWasteType.NON_RECYCLABLE: WasteType.NON_RECYCLABLE,
+    CliWasteType.ORGANIC: WasteType.ORGANIC,
+    CliWasteType.PAPER: WasteType.PAPER,
+    CliWasteType.PACKAGES: WasteType.PACKAGES,
+    CliWasteType.TREE: WasteType.TREE,
+}
+
+PostCode = Annotated[
+    str,
+    typer.Option(
+        help="Postal code of the address",
+        prompt="Postal code",
+        show_default=False,
+        envvar="TWENTEMILIEU_POST_CODE",
+    ),
+]
+HouseNumber = Annotated[
+    int,
+    typer.Option(
+        help="House number of the address",
+        prompt="House number",
+        show_default=False,
+        envvar="TWENTEMILIEU_HOUSE_NUMBER",
+    ),
+]
+HouseLetter = Annotated[
+    str,
+    typer.Option(
+        help="Optional house letter of the address",
+        envvar="TWENTEMILIEU_HOUSE_LETTER",
+    ),
+]
+JsonFlag = Annotated[
+    bool,
+    typer.Option(
+        "--json",
+        help="Emit machine-readable JSON output",
+    ),
+]
+
+
+@cli.error_handler(TwenteMilieuAddressError)
+def address_error_handler(_: TwenteMilieuAddressError) -> None:
+    """Handle address errors."""
+    message = """
+    The provided address could not be found in the Twente Milieu service
+    area. Please double-check the postal code and house number (and
+    optional house letter) and try again.
+    """
+    panel = Panel(
+        message,
+        expand=False,
+        title="Address not found",
+        border_style="red bold",
+    )
+    console.print(panel)
+    sys.exit(1)
+
+
+@cli.error_handler(TwenteMilieuConnectionError)
+def connection_error_handler(_: TwenteMilieuConnectionError) -> None:
+    """Handle connection errors."""
+    message = """
+    Could not connect to the Twente Milieu API. Please check your
+    internet connection and try again.
+    """
+    panel = Panel(
+        message,
+        expand=False,
+        title="Connection error",
+        border_style="red bold",
+    )
+    console.print(panel)
+    sys.exit(1)
+
+
+async def fetch_pickups(
+    post_code: str,
+    house_number: int,
+    house_letter: str,
+) -> dict[WasteType, list[date]]:
+    """Fetch the pickup schedule for an address."""
+    async with TwenteMilieu(
+        post_code=post_code,
+        house_number=house_number,
+        house_letter=house_letter,
+    ) as twente:
+        return await twente.update()
+
+
+def format_address(post_code: str, house_number: int, house_letter: str) -> str:
+    """Format an address as a human-readable string."""
+    return f"{post_code} {house_number}{house_letter}".strip()
+
+
+def flatten_pickups(
+    pickups_by_type: dict[WasteType, list[date]],
+) -> list[tuple[date, WasteType]]:
+    """Flatten a per-type pickup schedule into a chronologically sorted list."""
+    events = [(d, wt) for wt, dates in pickups_by_type.items() for d in dates]
+    events.sort(key=lambda event: event[0])
+    return events
+
+
+def emit_json(payload: object) -> None:
+    """Emit a payload as indented JSON on stdout."""
+    typer.echo(json.dumps(payload, indent=2))
+
+
+@cli.command("upcoming")
+async def upcoming(
+    post_code: PostCode,
+    house_number: HouseNumber,
+    house_letter: HouseLetter = "",
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit",
+            "-n",
+            help="Maximum number of upcoming pickups to show",
+            min=1,
+        ),
+    ] = 5,
+    output_json: JsonFlag = False,
+) -> None:
+    """List the next pickups across all waste types in chronological order."""
+    pickups_by_type = await fetch_pickups(post_code, house_number, house_letter)
+    events = flatten_pickups(pickups_by_type)[:limit]
+
+    if output_json:
+        payload = [
+            {
+                "date": event_date.isoformat(),
+                "waste_type": WASTE_TYPE_JSON_NAMES[waste_type],
+            }
+            for event_date, waste_type in events
+        ]
+        emit_json(payload)
+        return
+
+    address = format_address(post_code, house_number, house_letter)
+    table = Table(title=f"Next {limit} pickups for {address}")
+    table.add_column("Date", style="cyan bold")
+    table.add_column("Waste type", style="cyan bold")
+
+    if not events:
+        table.add_row("—", "No upcoming pickups")
+    else:
+        for event_date, waste_type in events:
+            table.add_row(event_date.isoformat(), WASTE_TYPE_LABELS[waste_type])
+
+    console.print(table)
+
+
+@cli.command("next")
+async def next_pickup(
+    post_code: PostCode,
+    house_number: HouseNumber,
+    house_letter: HouseLetter = "",
+    waste_type: Annotated[
+        CliWasteType | None,
+        typer.Option(
+            "--waste-type",
+            "-t",
+            help="Limit the lookup to a single waste type",
+            case_sensitive=False,
+        ),
+    ] = None,
+    output_json: JsonFlag = False,
+) -> None:
+    """Show the very next pickup, optionally filtered to a specific waste type."""
+    pickups_by_type = await fetch_pickups(post_code, house_number, house_letter)
+
+    if waste_type is None:
+        events = flatten_pickups(pickups_by_type)
+        chosen = events[0] if events else None
+    else:
+        target = CLI_TO_WASTE_TYPE[waste_type]
+        dates = pickups_by_type.get(target, [])
+        chosen = (dates[0], target) if dates else None
+
+    if output_json:
+        payload = (
+            None
+            if chosen is None
+            else {
+                "date": chosen[0].isoformat(),
+                "waste_type": WASTE_TYPE_JSON_NAMES[chosen[1]],
+            }
+        )
+        emit_json(payload)
+        return
+
+    if chosen is None:
+        if waste_type is None:
+            console.print("[yellow]No upcoming pickups scheduled.[/yellow]")
+        else:
+            console.print(
+                f"[yellow]No upcoming {waste_type.value} pickup scheduled.[/yellow]"
+            )
+        return
+
+    event_date, event_type = chosen
+    label = WASTE_TYPE_LABELS[event_type]
+    console.print(
+        f"Next pickup: [cyan bold]{label}[/cyan bold] "
+        f"on [cyan bold]{event_date.isoformat()}[/cyan bold]",
+    )
diff --git a/src/twentemilieu/cli/async_typer.py b/src/twentemilieu/cli/async_typer.py
new file mode 100644
index 00000000..946796fe
--- /dev/null
+++ b/src/twentemilieu/cli/async_typer.py
@@ -0,0 +1,191 @@
+"""Asynchronous Python client for Peblar EV chargers.
+
+Adaptation of the snippet/code from:
+- https://github.com/tiangolo/typer/issues/88#issuecomment-1613013597
+- https://github.com/argilla-io/argilla/blob/e77ca86c629a492019f230ac55ebde207b280xc9c/src/argilla/cli/typer_ext.py
+"""
+
+#  Copyright 2021-present, the Recognai S.L. team.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable  # pylint: disable=import-error
+from functools import wraps
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ParamSpec,
+    TypeVar,
+)
+
+from typer import Exit
+from typer import Typer as SyncTyper
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+    from typer.core import TyperCommand, TyperGroup
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+HandleErrorFunc = Callable[[Any], None]
+
+
+class AsyncTyper(SyncTyper):
+    """A Typer subclass that supports async."""
+
+    error_handlers: dict[type[Exception], HandleErrorFunc]
+
+    # pylint: disable-next=too-many-arguments, too-many-locals
+    def callback(  # type: ignore[override] # ty: ignore[invalid-method-override] # noqa: PLR0913
+        self,
+        *,
+        cls: type[TyperGroup] | None = None,
+        invoke_without_command: bool = False,
+        no_args_is_help: bool = False,
+        subcommand_metavar: str | None = None,
+        chain: bool = False,
+        result_callback: Callable[..., Any] | None = None,
+        context_settings: dict[Any, Any] | None = None,
+        # pylint: disable-next=redefined-builtin
+        help: str | None = None,  # noqa: A002
+        epilog: str | None = None,
+        short_help: str | None = None,
+        options_metavar: str = "[OPTIONS]",
+        add_help_option: bool = True,
+        hidden: bool = False,
+        deprecated: bool = False,
+        rich_help_panel: str | None = None,
+    ) -> Callable[
+        [Callable[_P, Coroutine[Any, Any, _R]]],
+        Callable[_P, Coroutine[Any, Any, _R]],
+    ]:
+        """Create a new typer callback."""
+        super_callback = super().callback(
+            cls=cls,
+            invoke_without_command=invoke_without_command,
+            no_args_is_help=no_args_is_help,
+            subcommand_metavar=subcommand_metavar,
+            chain=chain,
+            result_callback=result_callback,
+            context_settings=context_settings,
+            help=help,
+            epilog=epilog,
+            short_help=short_help,
+            options_metavar=options_metavar,
+            add_help_option=add_help_option,
+            hidden=hidden,
+            deprecated=deprecated,
+            rich_help_panel=rich_help_panel,
+        )
+
+        def decorator(
+            func: Callable[_P, Coroutine[Any, Any, _R]],
+        ) -> Callable[_P, Coroutine[Any, Any, _R]]:
+            if asyncio.iscoroutinefunction(func):
+
+                @wraps(func)
+                def sync_func(*_args: _P.args, **_kwargs: _P.kwargs) -> _R:
+                    return asyncio.run(func(*_args, **_kwargs))
+
+                super_callback(sync_func)
+            else:
+                super_callback(func)
+
+            return func
+
+        return decorator
+
+    # pylint: disable-next=too-many-arguments
+    def command(  # type: ignore[override] # ty: ignore[invalid-method-override] # noqa: PLR0913
+        self,
+        name: str | None = None,
+        *,
+        cls: type[TyperCommand] | None = None,
+        context_settings: dict[Any, Any] | None = None,
+        # pylint: disable-next=redefined-builtin
+        help: str | None = None,  # noqa: A002
+        epilog: str | None = None,
+        short_help: str | None = None,
+        options_metavar: str = "[OPTIONS]",
+        add_help_option: bool = True,
+        no_args_is_help: bool = False,
+        hidden: bool = False,
+        deprecated: bool = False,
+        # Rich settings
+        rich_help_panel: str | None = None,
+    ) -> Callable[
+        [Callable[_P, Coroutine[Any, Any, _R]]],
+        Callable[_P, Coroutine[Any, Any, _R]],
+    ]:
+        """Create a new typer command."""
+        super_command = super().command(
+            name,
+            cls=cls,
+            context_settings=context_settings,
+            help=help,
+            epilog=epilog,
+            short_help=short_help,
+            options_metavar=options_metavar,
+            add_help_option=add_help_option,
+            no_args_is_help=no_args_is_help,
+            hidden=hidden,
+            deprecated=deprecated,
+            rich_help_panel=rich_help_panel,
+        )
+
+        def decorator(
+            func: Callable[_P, Coroutine[Any, Any, _R]],
+        ) -> Callable[_P, Coroutine[Any, Any, _R]]:
+            if asyncio.iscoroutinefunction(func):
+
+                @wraps(func)
+                def sync_func(*_args: _P.args, **_kwargs: _P.kwargs) -> _R:
+                    return asyncio.run(func(*_args, **_kwargs))
+
+                super_command(sync_func)
+            else:
+                super_command(func)
+
+            return func
+
+        return decorator
+
+    def error_handler(self, exc: type[Exception]) -> Callable[[HandleErrorFunc], None]:
+        """Register an error handler for a given exception."""
+        if not hasattr(self, "error_handlers"):
+            self.error_handlers = {}
+
+        def decorator(func: HandleErrorFunc) -> None:
+            self.error_handlers[exc] = func
+
+        return decorator
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the typer app."""
+        try:
+            return super().__call__(*args, **kwargs)
+        except Exit:
+            raise
+        # pylint: disable-next=broad-except
+        except Exception as e:
+            if (
+                not hasattr(self, "error_handlers")
+                or (handler := self.error_handlers.get(type(e))) is None
+            ):
+                raise
+            return handler(e)
diff --git a/src/twentemilieu/cli/ruff.toml b/src/twentemilieu/cli/ruff.toml
new file mode 100644
index 00000000..ac624159
--- /dev/null
+++ b/src/twentemilieu/cli/ruff.toml
@@ -0,0 +1,9 @@
+# This extend our general Ruff rules specifically for the examples
+extend = "../../../pyproject.toml"
+
+lint.extend-ignore = [
+  "FBT002",
+  "PLR0913",
+  "PLR0915",
+  "RUF100"
+]
diff --git a/tests/__snapshots__/test_twentemilieu.ambr b/tests/__snapshots__/test_twentemilieu.ambr
new file mode 100644
index 00000000..3cf1c28e
--- /dev/null
+++ b/tests/__snapshots__/test_twentemilieu.ambr
@@ -0,0 +1,21 @@
+# serializer version: 1
+# name: test_update
+  dict({
+    <WasteType.NON_RECYCLABLE: 0>: list([
+      datetime.date(2019, 7, 21),
+      datetime.date(2019, 8, 22),
+    ]),
+    <WasteType.ORGANIC: 1>: list([
+      datetime.date(2019, 7, 19),
+      datetime.date(2019, 7, 20),
+    ]),
+    <WasteType.PAPER: 2>: list([
+      datetime.date(2019, 7, 22),
+    ]),
+    <WasteType.TREE: 6>: list([
+    ]),
+    <WasteType.PACKAGES: 10>: list([
+      datetime.date(2019, 7, 23),
+    ]),
+  })
+# ---
diff --git a/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 00000000..d2b6cad9
--- /dev/null
+++ b/tests/cli/__init__.py
@@ -0,0 +1 @@
+"""Tests for the Twente Milieu CLI."""
diff --git a/tests/cli/__snapshots__/test_cli.ambr b/tests/cli/__snapshots__/test_cli.ambr
new file mode 100644
index 00000000..fc9e5573
--- /dev/null
+++ b/tests/cli/__snapshots__/test_cli.ambr
@@ -0,0 +1,216 @@
+# serializer version: 1
+# name: test_address_error_handler
+  '''
+  ╭─────────────────────────── Address not found ────────────────────────────╮
+  │                                                                          │
+  │     The provided address could not be found in the Twente Milieu service │
+  │     area. Please double-check the postal code and house number (and      │
+  │     optional house letter) and try again.                                │
+  │                                                                          │
+  ╰──────────────────────────────────────────────────────────────────────────╯
+  
+  '''
+# ---
+# name: test_connection_error_handler
+  '''
+  ╭──────────────────────── Connection error ─────────────────────────╮
+  │                                                                   │
+  │     Could not connect to the Twente Milieu API. Please check your │
+  │     internet connection and try again.                            │
+  │                                                                   │
+  ╰───────────────────────────────────────────────────────────────────╯
+  
+  '''
+# ---
+# name: test_help
+  '''
+                                                                                                      
+   Usage: root [OPTIONS] COMMAND [ARGS]...                                                            
+                                                                                                      
+   Twente Milieu CLI                                                                                  
+                                                                                                      
+  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
+  │ --help          Show this message and exit.                                                      │
+  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+  ╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
+  │ upcoming  List the next pickups across all waste types in chronological order.                   │
+  │ next      Show the very next pickup, optionally filtered to a specific waste type.               │
+  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+  
+  
+  '''
+# ---
+# name: test_next
+  '''
+  Next pickup: Organic (GFT) on 2026-04-17
+  
+  '''
+# ---
+# name: test_next_help
+  '''
+                                                                                                      
+   Usage: root next [OPTIONS]                                                                         
+                                                                                                      
+   Show the very next pickup, optionally filtered to a specific waste type.                           
+                                                                                                      
+  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
+  │ *  --post-code             TEXT                               Postal code of the address         │
+  │                                                               [env var: TWENTEMILIEU_POST_CODE]  │
+  │                                                               [required]                         │
+  │ *  --house-number          INTEGER                            House number of the address        │
+  │                                                               [env var:                          │
+  │                                                               TWENTEMILIEU_HOUSE_NUMBER]         │
+  │                                                               [required]                         │
+  │    --house-letter          TEXT                               Optional house letter of the       │
+  │                                                               address                            │
+  │                                                               [env var:                          │
+  │                                                               TWENTEMILIEU_HOUSE_LETTER]         │
+  │    --waste-type    -t      [non-recyclable|organic|paper|pac  Limit the lookup to a single waste │
+  │                            kages|tree]                        type                               │
+  │    --json                                                     Emit machine-readable JSON output  │
+  │    --help                                                     Show this message and exit.        │
+  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+  
+  
+  '''
+# ---
+# name: test_next_json
+  '''
+  {
+    "date": "2026-04-17",
+    "waste_type": "organic"
+  }
+  
+  '''
+# ---
+# name: test_next_none
+  '''
+  No upcoming pickups scheduled.
+  
+  '''
+# ---
+# name: test_next_none_json
+  '''
+  null
+  
+  '''
+# ---
+# name: test_next_waste_type_none
+  '''
+  No upcoming tree pickup scheduled.
+  
+  '''
+# ---
+# name: test_next_with_waste_type
+  '''
+  Next pickup: Organic (GFT) on 2026-04-17
+  
+  '''
+# ---
+# name: test_next_with_waste_type_json
+  '''
+  {
+    "date": "2026-04-28",
+    "waste_type": "paper"
+  }
+  
+  '''
+# ---
+# name: test_upcoming
+  '''
+   Next 5 pickups for 7531AT 148 
+  ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+  ┃ Date       ┃ Waste type     ┃
+  ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+  │ 2026-04-17 │ Organic (GFT)  │
+  │ 2026-04-20 │ Non-recyclable │
+  │ 2026-04-22 │ Packages (PMD) │
+  │ 2026-04-24 │ Organic (GFT)  │
+  │ 2026-04-28 │ Paper          │
+  └────────────┴────────────────┘
+  
+  '''
+# ---
+# name: test_upcoming_empty
+  '''
+  Next 5 pickups for 7531AT 148 
+  ┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+  ┃ Date ┃ Waste type          ┃
+  ┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+  │ —    │ No upcoming pickups │
+  └──────┴─────────────────────┘
+  
+  '''
+# ---
+# name: test_upcoming_help
+  '''
+                                                                                                      
+   Usage: root upcoming [OPTIONS]                                                                     
+                                                                                                      
+   List the next pickups across all waste types in chronological order.                               
+                                                                                                      
+  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
+  │ *  --post-code             TEXT                  Postal code of the address                      │
+  │                                                  [env var: TWENTEMILIEU_POST_CODE]               │
+  │                                                  [required]                                      │
+  │ *  --house-number          INTEGER               House number of the address                     │
+  │                                                  [env var: TWENTEMILIEU_HOUSE_NUMBER]            │
+  │                                                  [required]                                      │
+  │    --house-letter          TEXT                  Optional house letter of the address            │
+  │                                                  [env var: TWENTEMILIEU_HOUSE_LETTER]            │
+  │    --limit         -n      INTEGER RANGE [x>=1]  Maximum number of upcoming pickups to show      │
+  │                                                  [default: 5]                                    │
+  │    --json                                        Emit machine-readable JSON output               │
+  │    --help                                        Show this message and exit.                     │
+  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+  
+  
+  '''
+# ---
+# name: test_upcoming_json
+  '''
+  [
+    {
+      "date": "2026-04-17",
+      "waste_type": "organic"
+    },
+    {
+      "date": "2026-04-20",
+      "waste_type": "non_recyclable"
+    },
+    {
+      "date": "2026-04-22",
+      "waste_type": "packages"
+    }
+  ]
+  
+  '''
+# ---
+# name: test_upcoming_with_house_letter
+  '''
+  Next 5 pickups for 7531AT 148A 
+  ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+  ┃ Date       ┃ Waste type     ┃
+  ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+  │ 2026-04-17 │ Organic (GFT)  │
+  │ 2026-04-20 │ Non-recyclable │
+  │ 2026-04-22 │ Packages (PMD) │
+  │ 2026-04-24 │ Organic (GFT)  │
+  │ 2026-04-28 │ Paper          │
+  └────────────┴────────────────┘
+  
+  '''
+# ---
+# name: test_upcoming_with_limit
+  '''
+   Next 3 pickups for 7531AT 148 
+  ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+  ┃ Date       ┃ Waste type     ┃
+  ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+  │ 2026-04-17 │ Organic (GFT)  │
+  │ 2026-04-20 │ Non-recyclable │
+  │ 2026-04-22 │ Packages (PMD) │
+  └────────────┴────────────────┘
+  
+  '''
+# ---
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
new file mode 100644
index 00000000..2577fb0e
--- /dev/null
+++ b/tests/cli/test_cli.py
@@ -0,0 +1,348 @@
+"""Tests for the Twente Milieu CLI."""
+
+# pylint: disable=redefined-outer-name
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from twentemilieu.cli import cli
+from twentemilieu.exceptions import (
+    TwenteMilieuAddressError,
+    TwenteMilieuConnectionError,
+)
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from syrupy.assertion import SnapshotAssertion
+
+    from twentemilieu import WasteType
+
+
+@pytest.fixture(autouse=True)
+def stable_terminal(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Force deterministic Rich rendering for stable snapshots."""
+    monkeypatch.setenv("COLUMNS", "100")
+    monkeypatch.setenv("NO_COLOR", "1")
+    monkeypatch.setenv("TERM", "dumb")
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    """Return a CLI runner for invoking the Typer app."""
+    return CliRunner()
+
+
+def mock_twentemilieu_class(
+    pickups_data: dict[WasteType, list[date]],
+) -> MagicMock:
+    """Return a MagicMock that stands in for the TwenteMilieu class."""
+    client = AsyncMock()
+    client.update.return_value = pickups_data
+
+    instance = AsyncMock()
+    instance.__aenter__.return_value = client
+    instance.__aexit__.return_value = None
+
+    return MagicMock(return_value=instance)
+
+
+def invoke(
+    runner: CliRunner,
+    args: list[str],
+    pickups_data: dict[WasteType, list[date]],
+) -> tuple[int, str, MagicMock]:
+    """Invoke the CLI with a mocked TwenteMilieu class and return the result."""
+    mock_cls = mock_twentemilieu_class(pickups_data)
+    with patch("twentemilieu.cli.TwenteMilieu", mock_cls):
+        result = runner.invoke(cli, args)
+    return result.exit_code, result.stdout, mock_cls
+
+
+def test_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
+    """Top-level help lists all commands."""
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0
+    assert result.stdout == snapshot
+
+
+def test_upcoming_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
+    """Help for the upcoming command."""
+    result = runner.invoke(cli, ["upcoming", "--help"])
+    assert result.exit_code == 0
+    assert result.stdout == snapshot
+
+
+def test_next_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
+    """Help for the next command."""
+    result = runner.invoke(cli, ["next", "--help"])
+    assert result.exit_code == 0
+    assert result.stdout == snapshot
+
+
+def test_upcoming(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Upcoming command prints a chronologically sorted table."""
+    exit_code, output, mock_cls = invoke(
+        runner,
+        ["upcoming", "--post-code", "7531AT", "--house-number", "148"],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+    mock_cls.assert_called_once_with(
+        post_code="7531AT",
+        house_number=148,
+        house_letter="",
+    )
+
+
+def test_upcoming_with_house_letter(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Upcoming command accepts an optional house letter."""
+    exit_code, output, mock_cls = invoke(
+        runner,
+        [
+            "upcoming",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--house-letter",
+            "A",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+    mock_cls.assert_called_once_with(
+        post_code="7531AT",
+        house_number=148,
+        house_letter="A",
+    )
+
+
+def test_upcoming_with_limit(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Upcoming command honours the --limit option."""
+    exit_code, output, _ = invoke(
+        runner,
+        [
+            "upcoming",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--limit",
+            "3",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_upcoming_empty(
+    runner: CliRunner,
+    empty_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Upcoming command renders a placeholder when the schedule is empty."""
+    exit_code, output, _ = invoke(
+        runner,
+        ["upcoming", "--post-code", "7531AT", "--house-number", "148"],
+        empty_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_upcoming_json(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Upcoming command emits JSON when --json is given."""
+    exit_code, output, _ = invoke(
+        runner,
+        [
+            "upcoming",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--limit",
+            "3",
+            "--json",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command shows the single next pickup across all types."""
+    exit_code, output, _ = invoke(
+        runner,
+        ["next", "--post-code", "7531AT", "--house-number", "148"],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_json(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command emits JSON when --json is given."""
+    exit_code, output, _ = invoke(
+        runner,
+        ["next", "--post-code", "7531AT", "--house-number", "148", "--json"],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_with_waste_type(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command can be filtered to a specific waste type."""
+    exit_code, output, _ = invoke(
+        runner,
+        [
+            "next",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--waste-type",
+            "organic",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_with_waste_type_json(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command emits JSON for a specific waste type."""
+    exit_code, output, _ = invoke(
+        runner,
+        [
+            "next",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--waste-type",
+            "paper",
+            "--json",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_none(
+    runner: CliRunner,
+    empty_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command reports when there are no upcoming pickups."""
+    exit_code, output, _ = invoke(
+        runner,
+        ["next", "--post-code", "7531AT", "--house-number", "148"],
+        empty_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_none_json(
+    runner: CliRunner,
+    empty_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command returns null JSON when there are no upcoming pickups."""
+    exit_code, output, _ = invoke(
+        runner,
+        ["next", "--post-code", "7531AT", "--house-number", "148", "--json"],
+        empty_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_next_waste_type_none(
+    runner: CliRunner,
+    sample_pickups: dict[WasteType, list[date]],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Next command reports when a specific type has no upcoming pickup."""
+    exit_code, output, _ = invoke(
+        runner,
+        [
+            "next",
+            "--post-code",
+            "7531AT",
+            "--house-number",
+            "148",
+            "--waste-type",
+            "tree",
+        ],
+        sample_pickups,
+    )
+    assert exit_code == 0
+    assert output == snapshot
+
+
+def test_address_error_handler(
+    capsys: pytest.CaptureFixture[str],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Address error handler prints a panel and exits with 1."""
+    handler = cli.error_handlers[TwenteMilieuAddressError]
+    with pytest.raises(SystemExit) as exc_info:
+        handler(TwenteMilieuAddressError("unknown"))
+    assert exc_info.value.code == 1
+    assert capsys.readouterr().out == snapshot
+
+
+def test_connection_error_handler(
+    capsys: pytest.CaptureFixture[str],
+    snapshot: SnapshotAssertion,
+) -> None:
+    """Connection error handler prints a panel and exits with 1."""
+    handler = cli.error_handlers[TwenteMilieuConnectionError]
+    with pytest.raises(SystemExit) as exc_info:
+        handler(TwenteMilieuConnectionError("unreachable"))
+    assert exc_info.value.code == 1
+    assert capsys.readouterr().out == snapshot
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..c0d47a75
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,53 @@
+"""Shared fixtures and helpers for the test suite."""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from twentemilieu import WasteType
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+_PICKUP_KEY_TO_WASTE_TYPE: dict[str, WasteType] = {
+    "non_recyclable": WasteType.NON_RECYCLABLE,
+    "organic": WasteType.ORGANIC,
+    "paper": WasteType.PAPER,
+    "packages": WasteType.PACKAGES,
+    "tree": WasteType.TREE,
+}
+
+
+def load_fixture(filename: str) -> Any:
+    """Load a JSON fixture file from the tests/fixtures directory."""
+    return json.loads((FIXTURES_DIR / filename).read_text(encoding="utf-8"))
+
+
+def _parse_pickups(raw: dict[str, list[str]]) -> dict[WasteType, list[date]]:
+    """Parse a pickups fixture mapping keys to WasteType and ISO date strings."""
+    return {
+        _PICKUP_KEY_TO_WASTE_TYPE[key]: [date.fromisoformat(d) for d in dates]
+        for key, dates in raw.items()
+    }
+
+
+@pytest.fixture
+def calendar_response() -> Any:
+    """Return a sample GetCalendar API response payload."""
+    return load_fixture("calendar_response.json")
+
+
+@pytest.fixture
+def sample_pickups() -> dict[WasteType, list[date]]:
+    """Return a realistic pickup schedule used for CLI rendering tests."""
+    return _parse_pickups(load_fixture("sample_pickups.json"))
+
+
+@pytest.fixture
+def empty_pickups() -> dict[WasteType, list[date]]:
+    """Return a pickup schedule where every waste type has no upcoming dates."""
+    return _parse_pickups(load_fixture("empty_pickups.json"))
diff --git a/tests/fixtures/calendar_response.json b/tests/fixtures/calendar_response.json
new file mode 100644
index 00000000..6d244899
--- /dev/null
+++ b/tests/fixtures/calendar_response.json
@@ -0,0 +1,28 @@
+{
+  "dataList": [
+    {
+      "pickupDates": ["2019-07-20T00:00:00", "2019-07-19T00:00:00"],
+      "pickupType": 1
+    },
+    {
+      "pickupDates": ["2019-07-21T00:00:00"],
+      "pickupType": 0
+    },
+    {
+      "pickupDates": ["2019-08-22T00:00:00"],
+      "pickupType": 0
+    },
+    {
+      "pickupDates": ["2019-07-22T00:00:00"],
+      "pickupType": 2
+    },
+    {
+      "pickupDates": ["2019-07-23T00:00:00"],
+      "pickupType": 56
+    },
+    {
+      "pickupDates": [],
+      "pickupType": 10
+    }
+  ]
+}
diff --git a/tests/fixtures/empty_pickups.json b/tests/fixtures/empty_pickups.json
new file mode 100644
index 00000000..139b68d7
--- /dev/null
+++ b/tests/fixtures/empty_pickups.json
@@ -0,0 +1,7 @@
+{
+  "non_recyclable": [],
+  "organic": [],
+  "paper": [],
+  "packages": [],
+  "tree": []
+}
diff --git a/tests/fixtures/sample_pickups.json b/tests/fixtures/sample_pickups.json
new file mode 100644
index 00000000..48006593
--- /dev/null
+++ b/tests/fixtures/sample_pickups.json
@@ -0,0 +1,7 @@
+{
+  "non_recyclable": ["2026-04-20", "2026-05-04"],
+  "organic": ["2026-04-17", "2026-04-24", "2026-05-01"],
+  "paper": ["2026-04-28"],
+  "packages": ["2026-04-22", "2026-05-06"],
+  "tree": []
+}
diff --git a/tests/test_twentemilieu.py b/tests/test_twentemilieu.py
index 20a3e795..52a9d17f 100644
--- a/tests/test_twentemilieu.py
+++ b/tests/test_twentemilieu.py
@@ -1,10 +1,12 @@
 """Tests for `twentemilieu.twentemilieu`."""
 
-# pylint: disable=protected-access
+from __future__ import annotations
+
+# pylint: disable=protected-access,redefined-outer-name
 import asyncio
 import json
 import socket
-from datetime import date
+from typing import TYPE_CHECKING, Any
 from unittest.mock import patch
 
 import aiohttp
@@ -18,10 +20,31 @@
     TwenteMilieuError,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from syrupy.assertion import SnapshotAssertion
+
 API_HOST = "twentemilieuapi.ximmio.com"
 
 
-async def test_json_request(aresponses: ResponsesMockServer) -> None:
+@pytest.fixture
+async def twente() -> AsyncIterator[TwenteMilieu]:
+    """Return a TwenteMilieu client wired to a live aiohttp session."""
+    async with aiohttp.ClientSession() as session:
+        client = TwenteMilieu(
+            post_code="1234AB",
+            house_number=1,
+            session=session,
+        )
+        yield client
+        await client.close()
+
+
+async def test_json_request(
+    aresponses: ResponsesMockServer,
+    twente: TwenteMilieu,
+) -> None:
     """Test JSON response is handled correctly."""
     aresponses.add(
         API_HOST,
@@ -33,11 +56,8 @@ async def test_json_request(aresponses: ResponsesMockServer) -> None:
             text='{"status": "ok"}',
         ),
     )
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        response = await twente._request("")
-        assert response["status"] == "ok"
-        await twente.close()
+    response = await twente._request("")
+    assert response["status"] == "ok"
 
 
 async def test_wastetype_fallback() -> None:
@@ -51,7 +71,7 @@ async def test_wastetype_fallback() -> None:
 
 
 async def test_internal_session(aresponses: ResponsesMockServer) -> None:
-    """Test JSON response is handled correctly."""
+    """Test the TwenteMilieu client manages its own session as a context manager."""
     aresponses.add(
         API_HOST,
         "/api/",
@@ -62,25 +82,8 @@ async def test_internal_session(aresponses: ResponsesMockServer) -> None:
             text='{"status": "ok"}',
         ),
     )
-    async with TwenteMilieu(post_code="1234AB", house_number=1) as twente:
-        response = await twente._request("")
-        assert response["status"] == "ok"
-
-
-async def test_internal_eventloop(aresponses: ResponsesMockServer) -> None:
-    """Test JSON response is handled correctly."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(
-            status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"status": "ok"}',
-        ),
-    )
-    async with TwenteMilieu(post_code="1234AB", house_number=1) as twente:
-        response = await twente._request("")
+    async with TwenteMilieu(post_code="1234AB", house_number=1) as client:
+        response = await client._request("")
         assert response["status"] == "ok"
 
 
@@ -90,86 +93,71 @@ async def test_timeout(aresponses: ResponsesMockServer) -> None:
     # Faking a timeout by sleeping
     async def response_handler(_: aiohttp.ClientResponse) -> Response:
         await asyncio.sleep(2)
-        return aresponses.Response(body="Goodmorning!")
+        return aresponses.Response(body="Good morning!")
 
     aresponses.add(API_HOST, "/api/", "POST", response_handler)
 
     async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(
+        client = TwenteMilieu(
             post_code="1234AB",
             house_number=1,
             session=session,
             request_timeout=1,
         )
         with pytest.raises(TwenteMilieuConnectionError):
-            assert await twente._request("")
-
-
-async def test_http_error400(aresponses: ResponsesMockServer) -> None:
-    """Test HTTP 404 response handling."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(text="OMG PUPPIES!", status=404),
-    )
-
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        with pytest.raises(TwenteMilieuError):
-            assert await twente._request("")
+            assert await client._request("")
 
 
-async def test_http_error500(aresponses: ResponsesMockServer) -> None:
-    """Test HTTP 500 response handling."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(
-            body=b'{"status":"nok"}',
-            status=500,
-            headers={"Content-Type": "application/json"},
+@pytest.mark.parametrize(
+    "response_kwargs",
+    [
+        pytest.param(
+            {"text": "OMG PUPPIES!", "status": 404},
+            id="http_4xx_plaintext",
         ),
-    )
-
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        with pytest.raises(TwenteMilieuError):
-            assert await twente._request("")
-
-
-async def test_unexpected_response(aresponses: ResponsesMockServer) -> None:
-    """Test unexpected response handling."""
+        pytest.param(
+            {
+                "body": b'{"status":"nok"}',
+                "status": 500,
+                "headers": {"Content-Type": "application/json"},
+            },
+            id="http_5xx_json",
+        ),
+        pytest.param(
+            {"text": "OMG PUPPIES!", "status": 200},
+            id="200_unexpected_content_type",
+        ),
+    ],
+)
+async def test_request_errors(
+    aresponses: ResponsesMockServer,
+    twente: TwenteMilieu,
+    response_kwargs: dict[str, Any],
+) -> None:
+    """Test bad API responses raise TwenteMilieuError."""
     aresponses.add(
         API_HOST,
         "/api/",
         "POST",
-        aresponses.Response(text="OMG PUPPIES!", status=200),
+        aresponses.Response(**response_kwargs),
     )
-
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        with pytest.raises(TwenteMilieuError):
-            assert await twente._request("")
+    with pytest.raises(TwenteMilieuError):
+        await twente._request("")
 
 
-async def test_communication_error() -> None:
+async def test_communication_error(twente: TwenteMilieu) -> None:
     """Test communication error handling."""
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        with (
-            patch.object(
-                session,
-                "request",
-                side_effect=socket.gaierror,
-            ),
-            pytest.raises(TwenteMilieuConnectionError),
-        ):
-            assert await twente._request("")
-
-
-async def test_unique_id(aresponses: ResponsesMockServer) -> None:
+    with (
+        patch.object(twente.session, "request", side_effect=socket.gaierror),
+        pytest.raises(TwenteMilieuConnectionError),
+    ):
+        await twente._request("")
+
+
+async def test_unique_id(
+    aresponses: ResponsesMockServer,
+    twente: TwenteMilieu,
+) -> None:
     """Test request of a unique address identifier."""
     aresponses.add(
         API_HOST,
@@ -181,15 +169,16 @@ async def test_unique_id(aresponses: ResponsesMockServer) -> None:
             text='{"dataList": [{"UniqueId": "12345"}]}',
         ),
     )
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        unique_id = await twente.unique_id()
-        assert unique_id == "12345"
-        unique_id = await twente.unique_id()
-        assert unique_id == "12345"
+    unique_id = await twente.unique_id()
+    assert unique_id == "12345"
+    unique_id = await twente.unique_id()
+    assert unique_id == "12345"
 
 
-async def test_invalid_address(aresponses: ResponsesMockServer) -> None:
+async def test_invalid_address(
+    aresponses: ResponsesMockServer,
+    twente: TwenteMilieu,
+) -> None:
     """Test request of invalid address information."""
     aresponses.add(
         API_HOST,
@@ -201,13 +190,16 @@ async def test_invalid_address(aresponses: ResponsesMockServer) -> None:
             text='{"dataList": []}',
         ),
     )
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        with pytest.raises(TwenteMilieuAddressError):
-            assert await twente.unique_id()
+    with pytest.raises(TwenteMilieuAddressError):
+        await twente.unique_id()
 
 
-async def test_update(aresponses: ResponsesMockServer) -> None:
+async def test_update(
+    aresponses: ResponsesMockServer,
+    twente: TwenteMilieu,
+    calendar_response: Any,
+    snapshot: SnapshotAssertion,
+) -> None:
     """Test request for updating data from Twente Milieu."""
     aresponses.add(
         API_HOST,
@@ -226,47 +218,9 @@ async def test_update(aresponses: ResponsesMockServer) -> None:
         aresponses.Response(
             status=200,
             headers={"Content-Type": "application/json"},
-            text=json.dumps(
-                {
-                    "dataList": [
-                        {
-                            "pickupDates": [
-                                "2019-07-20T00:00:00",
-                                "2019-07-19T00:00:00",
-                            ],
-                            "pickupType": 1,
-                        },
-                        {
-                            "pickupDates": ["2019-07-21T00:00:00"],
-                            "pickupType": 0,
-                        },
-                        {
-                            "pickupDates": ["2019-08-22T00:00:00"],
-                            "pickupType": 0,
-                        },
-                        {
-                            "pickupDates": ["2019-07-22T00:00:00"],
-                            "pickupType": 2,
-                        },
-                        {
-                            "pickupDates": ["2019-07-23T00:00:00"],
-                            "pickupType": 56,
-                        },
-                        {"pickupDates": [], "pickupType": 10},
-                    ],
-                },
-            ),
+            text=json.dumps(calendar_response),
         ),
     )
 
-    async with aiohttp.ClientSession() as session:
-        twente = TwenteMilieu(post_code="1234AB", house_number=1, session=session)
-        pickups = await twente.update()
-
-        assert pickups[WasteType.NON_RECYCLABLE] == [
-            date(2019, 7, 21),
-            date(2019, 8, 22),
-        ]
-        assert pickups[WasteType.ORGANIC] == [date(2019, 7, 19), date(2019, 7, 20)]
-        assert pickups[WasteType.PAPER] == [date(2019, 7, 22)]
-        assert pickups[WasteType.PACKAGES] == [date(2019, 7, 23)]
+    pickups = await twente.update()
+    assert pickups == snapshot

From 8c6c0d1a74c5540030b9c45186374bbdb2436be9 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 17:44:17 +0000
Subject: [PATCH 02/11] =?UTF-8?q?=F0=9F=90=9B=20Force=20typer=20MAX=5FWIDT?=
 =?UTF-8?q?H=20in=20CLI=20tests=20for=20stable=20CI=20snapshots?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Typer caches TERMINAL_WIDTH into typer.rich_utils.MAX_WIDTH at module
import time, so setting the env var in a fixture is too late. Locally
it fell through to Rich's auto-detection which picked up COLUMNS from
the interactive shell, but on CI the fallback path produced an
80-column render instead of 100, breaking the help-output snapshots.

Patch the module attribute directly so the rich help renderer always
uses a 100-column Console regardless of the surrounding environment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 tests/cli/test_cli.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
index 2577fb0e..dd7404f0 100644
--- a/tests/cli/test_cli.py
+++ b/tests/cli/test_cli.py
@@ -29,6 +29,10 @@ def stable_terminal(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("COLUMNS", "100")
     monkeypatch.setenv("NO_COLOR", "1")
     monkeypatch.setenv("TERM", "dumb")
+    # Typer evaluates TERMINAL_WIDTH at import time and caches it in
+    # typer.rich_utils.MAX_WIDTH, so patching the env var at fixture time is
+    # too late; override the module attribute directly instead.
+    monkeypatch.setattr("typer.rich_utils.MAX_WIDTH", 100)
 
 
 @pytest.fixture

From 4d241c8dfb4d62f6a5dad24fe3b16c938d6dd00c Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 17:51:14 +0000
Subject: [PATCH 03/11] =?UTF-8?q?=F0=9F=90=9B=20Force=20typer=20TERMINAL?=
 =?UTF-8?q?=5FWIDTH=20in=20conftest=20before=20any=20import?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous fixture-level monkeypatch.setattr of typer.rich_utils.MAX_WIDTH
worked locally but still rendered at ~80 cols on CI. Typer caches
TERMINAL_WIDTH into MAX_WIDTH at module import time, so the only reliable
way to force a deterministic width across environments is to set the env
var in conftest.py before pytest imports any test module. Also explicitly
reassign typer.rich_utils.MAX_WIDTH after the import as belt-and-suspenders
in case typer was already imported by an earlier plugin.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 tests/conftest.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tests/conftest.py b/tests/conftest.py
index c0d47a75..b648b33a 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,16 +1,29 @@
 """Shared fixtures and helpers for the test suite."""
+# pylint: disable=wrong-import-position
 
 from __future__ import annotations
 
 import json
+import os
 from datetime import date
 from pathlib import Path
 from typing import Any
 
+# Typer caches TERMINAL_WIDTH into typer.rich_utils.MAX_WIDTH at import time,
+# so forcing a deterministic width for snapshot tests must happen before typer
+# is imported anywhere in the test suite. conftest.py is loaded before any
+# test module, so setting it here is guaranteed to run first. We also
+# explicitly import typer.rich_utils and overwrite MAX_WIDTH to cover any
+# edge case where typer might have been imported before this line runs.
+os.environ["TERMINAL_WIDTH"] = "100"
+
 import pytest
+import typer.rich_utils
 
 from twentemilieu import WasteType
 
+typer.rich_utils.MAX_WIDTH = 100
+
 FIXTURES_DIR = Path(__file__).parent / "fixtures"
 
 _PICKUP_KEY_TO_WASTE_TYPE: dict[str, WasteType] = {

From 1da6f04d935e85c2a8c2129168f17a8dc93db191 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 17:55:54 +0000
Subject: [PATCH 04/11] =?UTF-8?q?=F0=9F=90=9B=20Replace=20fragile=20help?=
 =?UTF-8?q?=20snapshot=20tests=20with=20structural=20introspection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The test_help / test_upcoming_help / test_next_help snapshot tests
captured rendered help output from typer's rich formatter, which is
impossible to stabilise across environments: typer caches
TERMINAL_WIDTH into typer.rich_utils.MAX_WIDTH at module import time
and the width fell through to 80 columns on CI regardless of env
variables or monkeypatching.

Replace them with a single test_cli_structure case that introspects
the click Command tree via typer.main.get_command(cli) and snapshots
the {command: [params]} mapping. This asserts exactly what the help
tests were trying to verify (commands and options exist) without
touching any rendered text, so it's environment-independent.

Also drop the now-unused conftest.py TERMINAL_WIDTH + MAX_WIDTH hacks
and the monkeypatch.setattr line from the stable_terminal fixture.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/scheduled_tasks.lock          |  1 +
 tests/cli/__snapshots__/test_cli.ambr | 89 ++++++---------------------
 tests/cli/test_cli.py                 | 39 +++++-------
 tests/conftest.py                     | 13 ----
 4 files changed, 35 insertions(+), 107 deletions(-)
 create mode 100644 .claude/scheduled_tasks.lock

diff --git a/.claude/scheduled_tasks.lock b/.claude/scheduled_tasks.lock
new file mode 100644
index 00000000..7badfb38
--- /dev/null
+++ b/.claude/scheduled_tasks.lock
@@ -0,0 +1 @@
+{"sessionId":"8e541af0-ea49-449e-8fc2-78c8aae9d794","pid":659367,"acquiredAt":1776275485863}
\ No newline at end of file
diff --git a/tests/cli/__snapshots__/test_cli.ambr b/tests/cli/__snapshots__/test_cli.ambr
index fc9e5573..cbe56779 100644
--- a/tests/cli/__snapshots__/test_cli.ambr
+++ b/tests/cli/__snapshots__/test_cli.ambr
@@ -11,6 +11,24 @@
   
   '''
 # ---
+# name: test_cli_structure
+  dict({
+    'next': list([
+      'house_letter',
+      'house_number',
+      'output_json',
+      'post_code',
+      'waste_type',
+    ]),
+    'upcoming': list([
+      'house_letter',
+      'house_number',
+      'limit',
+      'output_json',
+      'post_code',
+    ]),
+  })
+# ---
 # name: test_connection_error_handler
   '''
   ╭──────────────────────── Connection error ─────────────────────────╮
@@ -20,58 +38,12 @@
   │                                                                   │
   ╰───────────────────────────────────────────────────────────────────╯
   
-  '''
-# ---
-# name: test_help
-  '''
-                                                                                                      
-   Usage: root [OPTIONS] COMMAND [ARGS]...                                                            
-                                                                                                      
-   Twente Milieu CLI                                                                                  
-                                                                                                      
-  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
-  │ --help          Show this message and exit.                                                      │
-  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-  ╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
-  │ upcoming  List the next pickups across all waste types in chronological order.                   │
-  │ next      Show the very next pickup, optionally filtered to a specific waste type.               │
-  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-  
-  
   '''
 # ---
 # name: test_next
   '''
   Next pickup: Organic (GFT) on 2026-04-17
   
-  '''
-# ---
-# name: test_next_help
-  '''
-                                                                                                      
-   Usage: root next [OPTIONS]                                                                         
-                                                                                                      
-   Show the very next pickup, optionally filtered to a specific waste type.                           
-                                                                                                      
-  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
-  │ *  --post-code             TEXT                               Postal code of the address         │
-  │                                                               [env var: TWENTEMILIEU_POST_CODE]  │
-  │                                                               [required]                         │
-  │ *  --house-number          INTEGER                            House number of the address        │
-  │                                                               [env var:                          │
-  │                                                               TWENTEMILIEU_HOUSE_NUMBER]         │
-  │                                                               [required]                         │
-  │    --house-letter          TEXT                               Optional house letter of the       │
-  │                                                               address                            │
-  │                                                               [env var:                          │
-  │                                                               TWENTEMILIEU_HOUSE_LETTER]         │
-  │    --waste-type    -t      [non-recyclable|organic|paper|pac  Limit the lookup to a single waste │
-  │                            kages|tree]                        type                               │
-  │    --json                                                     Emit machine-readable JSON output  │
-  │    --help                                                     Show this message and exit.        │
-  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-  
-  
   '''
 # ---
 # name: test_next_json
@@ -140,31 +112,6 @@
   │ —    │ No upcoming pickups │
   └──────┴─────────────────────┘
   
-  '''
-# ---
-# name: test_upcoming_help
-  '''
-                                                                                                      
-   Usage: root upcoming [OPTIONS]                                                                     
-                                                                                                      
-   List the next pickups across all waste types in chronological order.                               
-                                                                                                      
-  ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
-  │ *  --post-code             TEXT                  Postal code of the address                      │
-  │                                                  [env var: TWENTEMILIEU_POST_CODE]               │
-  │                                                  [required]                                      │
-  │ *  --house-number          INTEGER               House number of the address                     │
-  │                                                  [env var: TWENTEMILIEU_HOUSE_NUMBER]            │
-  │                                                  [required]                                      │
-  │    --house-letter          TEXT                  Optional house letter of the address            │
-  │                                                  [env var: TWENTEMILIEU_HOUSE_LETTER]            │
-  │    --limit         -n      INTEGER RANGE [x>=1]  Maximum number of upcoming pickups to show      │
-  │                                                  [default: 5]                                    │
-  │    --json                                        Emit machine-readable JSON output               │
-  │    --help                                        Show this message and exit.                     │
-  ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-  
-  
   '''
 # ---
 # name: test_upcoming_json
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
index dd7404f0..a6ec5b72 100644
--- a/tests/cli/test_cli.py
+++ b/tests/cli/test_cli.py
@@ -6,7 +6,9 @@
 from typing import TYPE_CHECKING
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import click
 import pytest
+from typer.main import get_command
 from typer.testing import CliRunner
 
 from twentemilieu.cli import cli
@@ -29,10 +31,6 @@ def stable_terminal(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("COLUMNS", "100")
     monkeypatch.setenv("NO_COLOR", "1")
     monkeypatch.setenv("TERM", "dumb")
-    # Typer evaluates TERMINAL_WIDTH at import time and caches it in
-    # typer.rich_utils.MAX_WIDTH, so patching the env var at fixture time is
-    # too late; override the module attribute directly instead.
-    monkeypatch.setattr("typer.rich_utils.MAX_WIDTH", 100)
 
 
 @pytest.fixture
@@ -67,25 +65,20 @@ def invoke(
     return result.exit_code, result.stdout, mock_cls
 
 
-def test_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
-    """Top-level help lists all commands."""
-    result = runner.invoke(cli, ["--help"])
-    assert result.exit_code == 0
-    assert result.stdout == snapshot
-
-
-def test_upcoming_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
-    """Help for the upcoming command."""
-    result = runner.invoke(cli, ["upcoming", "--help"])
-    assert result.exit_code == 0
-    assert result.stdout == snapshot
-
-
-def test_next_help(runner: CliRunner, snapshot: SnapshotAssertion) -> None:
-    """Help for the next command."""
-    result = runner.invoke(cli, ["next", "--help"])
-    assert result.exit_code == 0
-    assert result.stdout == snapshot
+def test_cli_structure(snapshot: SnapshotAssertion) -> None:
+    """The CLI exposes the expected commands and options.
+
+    Inspects the click Command tree directly rather than snapshotting
+    rendered help output (which depends on Rich's terminal width
+    detection and is therefore environment-sensitive).
+    """
+    group = get_command(cli)
+    assert isinstance(group, click.Group)
+    structure = {
+        name: sorted(param.name for param in subcommand.params)
+        for name, subcommand in sorted(group.commands.items())
+    }
+    assert structure == snapshot
 
 
 def test_upcoming(
diff --git a/tests/conftest.py b/tests/conftest.py
index b648b33a..c0d47a75 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,29 +1,16 @@
 """Shared fixtures and helpers for the test suite."""
-# pylint: disable=wrong-import-position
 
 from __future__ import annotations
 
 import json
-import os
 from datetime import date
 from pathlib import Path
 from typing import Any
 
-# Typer caches TERMINAL_WIDTH into typer.rich_utils.MAX_WIDTH at import time,
-# so forcing a deterministic width for snapshot tests must happen before typer
-# is imported anywhere in the test suite. conftest.py is loaded before any
-# test module, so setting it here is guaranteed to run first. We also
-# explicitly import typer.rich_utils and overwrite MAX_WIDTH to cover any
-# edge case where typer might have been imported before this line runs.
-os.environ["TERMINAL_WIDTH"] = "100"
-
 import pytest
-import typer.rich_utils
 
 from twentemilieu import WasteType
 
-typer.rich_utils.MAX_WIDTH = 100
-
 FIXTURES_DIR = Path(__file__).parent / "fixtures"
 
 _PICKUP_KEY_TO_WASTE_TYPE: dict[str, WasteType] = {

From ffa5d75d7eda01c5e8ca0e4a657aea909d7657fa Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 17:56:11 +0000
Subject: [PATCH 05/11] =?UTF-8?q?=F0=9F=A7=B9=20Gitignore=20.claude/=20har?=
 =?UTF-8?q?ness=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit accidentally tracked a scheduled_tasks.lock file
written by the local Claude Code harness. Remove it from the index
and add .claude/ to .gitignore so it doesn't get picked up again.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/scheduled_tasks.lock | 1 -
 .gitignore                   | 1 +
 2 files changed, 1 insertion(+), 1 deletion(-)
 delete mode 100644 .claude/scheduled_tasks.lock

diff --git a/.claude/scheduled_tasks.lock b/.claude/scheduled_tasks.lock
deleted file mode 100644
index 7badfb38..00000000
--- a/.claude/scheduled_tasks.lock
+++ /dev/null
@@ -1 +0,0 @@
-{"sessionId":"8e541af0-ea49-449e-8fc2-78c8aae9d794","pid":659367,"acquiredAt":1776275485863}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index c7650d21..3212cd6c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -117,3 +117,4 @@ node_modules/
 
 # Deepcode AI
 .dccache
+.claude/

From 6eb503b3c07e17a7625e8ac55d1913653d569e69 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:33:10 +0000
Subject: [PATCH 06/11] =?UTF-8?q?=E2=9C=A8=20Tighten=20tooling,=20document?=
 =?UTF-8?q?=20behavior,=20fix=20WasteType=20edge=20case?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Several follow-up improvements on top of the CLI work:

Tooling & config:
- Bump pytest coverage gate from 10% to 95% so real regressions trip CI
- Drop dead VS Code settings (python.linting.*, python.formatting.provider)
  from .devcontainer/devcontainer.json; they were removed from the Python
  extension in favour of separate Pylint/Ruff extensions
- Expand pyproject keywords for PyPI discoverability
- Unquote "on": in scorecard.yml and add the yamllint disable comment so it
  matches the style of every other workflow
- Swap the unmaintained aresponses (last release 2021) for aioresponses,
  and rewrite tests/test_twentemilieu.py against it. test_timeout now uses
  exception=TimeoutError() instead of an async-sleep handler.

Documentation:
- Add a "Behavior & error handling" section to the README covering the
  per-call request_timeout (10 s default, configurable), the explicit lack
  of retries, asyncio cancellation behaviour, and the TwenteMilieuError
  exception taxonomy.

Source fix:
- WasteType._missing_ used to raise KeyError on any unknown integer value,
  which would crash update() mid-iteration on a newly introduced pickupType.
  It now returns None for unknown ints so the standard enum machinery
  raises ValueError, and update() catches that and skips the entry. Added
  a forward-compatibility entry with pickupType: 99 to the calendar fixture
  so the skip path is exercised on every run, and an explicit ValueError
  assertion in test_wastetype_fallback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .devcontainer/devcontainer.json       |   3 -
 .github/workflows/scorecard.yml       |   4 +-
 README.md                             |  31 ++++
 poetry.lock                           |  37 ++---
 pyproject.toml                        |  18 ++-
 src/twentemilieu/twentemilieu.py      |  32 ++--
 tests/fixtures/calendar_response.json |   4 +
 tests/test_twentemilieu.py            | 214 +++++++++++---------------
 8 files changed, 178 insertions(+), 165 deletions(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 39e36578..0eeb0a46 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -30,9 +30,6 @@
         "coverage-gutters.xmlname": "coverage.xml",
         "python.analysis.extraPaths": ["${workspaceFolder}/src"],
         "python.defaultInterpreterPath": ".venv/bin/python",
-        "python.formatting.provider": "ruff",
-        "python.linting.enabled": true,
-        "python.linting.pylintEnabled": true,
         "python.testing.cwd": "${workspaceFolder}",
         "python.testing.pytestArgs": ["--cov-report=xml"],
         "python.testing.pytestEnabled": true,
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
index 9c671463..d77330a5 100644
--- a/.github/workflows/scorecard.yml
+++ b/.github/workflows/scorecard.yml
@@ -4,7 +4,9 @@
 # policy, and support documentation.
 
 name: Scorecard supply-chain security
-"on":
+
+# yamllint disable-line rule:truthy
+on:
   # For Branch-Protection check. Only the default branch is supported. See
   # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
   branch_protection_rule:
diff --git a/README.md b/README.md
index 317496f3..55a1020a 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,36 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## Behavior & error handling
+
+Each API call is a single HTTP POST — the client does **not** retry on
+transient failures. If you need retries with backoff, wrap the calls in
+your own retry loop (or use something like [`backoff`][backoff]).
+
+Requests are bounded by a per-call timeout, which defaults to 10 seconds
+and can be overridden via the `request_timeout` constructor argument:
+
+```python
+async with TwenteMilieu(
+    post_code="1234AB",
+    house_number=1,
+    request_timeout=5,
+) as twente:
+    ...
+```
+
+Cancellation is plain `asyncio`: cancelling the task awaiting
+`unique_id()` or `update()` aborts the in-flight request, and the
+context manager still cleans up the internal session on exit.
+
+All exceptions inherit from `TwenteMilieuError`:
+
+| Exception                     | Raised when                                            |
+| ----------------------------- | ------------------------------------------------------ |
+| `TwenteMilieuConnectionError` | Request timed out or the network / API was unreachable |
+| `TwenteMilieuAddressError`    | The address could not be found in the service area     |
+| `TwenteMilieuError`           | Any other unexpected response from the API             |
+
 ## Command-line interface
 
 This package ships with an optional CLI that is handy for quickly
@@ -181,6 +211,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+[backoff]: https://github.com/litl/backoff
 [build-shield]: https://github.com/frenck/python-twentemilieu/actions/workflows/tests.yaml/badge.svg
 [build]: https://github.com/frenck/python-twentemilieu/actions/workflows/tests.yaml
 [codecov-shield]: https://codecov.io/gh/frenck/python-twentemilieu/branch/main/graph/badge.svg
diff --git a/poetry.lock b/poetry.lock
index e5d56688..a7d00600 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -154,6 +154,22 @@ yarl = ">=1.17.0,<2.0"
 [package.extras]
 speedups = ["Brotli (>=1.2) ; platform_python_implementation == \"CPython\"", "aiodns (>=3.3.0)", "backports.zstd ; platform_python_implementation == \"CPython\" and python_version < \"3.14\"", "brotlicffi (>=1.2) ; platform_python_implementation != \"CPython\""]
 
+[[package]]
+name = "aioresponses"
+version = "0.7.8"
+description = "Mock out requests made by ClientSession from aiohttp package"
+optional = false
+python-versions = "*"
+groups = ["dev"]
+files = [
+    {file = "aioresponses-0.7.8-py2.py3-none-any.whl", hash = "sha256:b73bd4400d978855e55004b23a3a84cb0f018183bcf066a85ad392800b5b9a94"},
+    {file = "aioresponses-0.7.8.tar.gz", hash = "sha256:b861cdfe5dc58f3b8afac7b0a6973d5d7b2cb608dd0f6253d16b8ee8eaf6df11"},
+]
+
+[package.dependencies]
+aiohttp = ">=3.3.0,<4.0.0"
+packaging = ">=22.0"
+
 [[package]]
 name = "aiosignal"
 version = "1.4.0"
@@ -214,25 +230,6 @@ typing_extensions = {version = ">=4.5", markers = "python_version < \"3.13\""}
 [package.extras]
 trio = ["trio (>=0.32.0)"]
 
-[[package]]
-name = "aresponses"
-version = "3.0.0"
-description = "Asyncio response mocking. Similar to the responses library used for 'requests'"
-optional = false
-python-versions = ">=3.7"
-groups = ["dev"]
-files = [
-    {file = "aresponses-3.0.0-py3-none-any.whl", hash = "sha256:8093ab4758eb4aba91c765a50295b269ecfc0a9e7c7158954760bc0c23503970"},
-    {file = "aresponses-3.0.0.tar.gz", hash = "sha256:8731d0609fe4c954e21f17753dc868dca9e2e002b020a33dc9212004599b11e7"},
-]
-
-[package.dependencies]
-aiohttp = [
-    {version = ">=3.7.0,<3.8.dev0 || >=3.9.dev0", markers = "python_version >= \"3.12\""},
-    {version = ">=3.7.0", markers = "python_version >= \"3.10\" and python_version < \"3.12\""},
-]
-pytest-asyncio = {version = ">=0.17.0", markers = "python_version >= \"3.7\""}
-
 [[package]]
 name = "astroid"
 version = "4.0.4"
@@ -2652,4 +2649,4 @@ cli = ["typer"]
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.11"
-content-hash = "3aff75b168e67514b6b568792793af4b5fe5bae57e0937cda54f75efba4d4d72"
+content-hash = "8b4d6d60615f95faa94e6e57ddca8e910e5a9c69b20d1d6dd58406c12afd8872"
diff --git a/pyproject.toml b/pyproject.toml
index 84f28861..d1be179e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,19 @@ maintainers = [{ name = "Franck Nijhof", email = "opensource@frenck.dev" }]
 license = "MIT"
 requires-python = ">=3.11"
 readme = "README.md"
-keywords = ["twente milieu", "afvalkalender", "api", "async", "client"]
+keywords = [
+  "afvalkalender",
+  "api",
+  "async",
+  "client",
+  "garbage",
+  "home-assistant",
+  "netherlands",
+  "pickup",
+  "twente",
+  "twente milieu",
+  "waste",
+]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Framework :: AsyncIO",
@@ -42,7 +54,7 @@ documentation = "https://github.com/frenck/python-twentemilieu"
 Changelog = "https://github.com/frenck/python-twentemilieu/releases"
 
 [tool.poetry.group.dev.dependencies]
-aresponses = "3.0.0"
+aioresponses = "0.7.8"
 codespell = "2.4.2"
 covdefaults = "2.3.0"
 coverage = { version = "7.13.5", extras = ["toml"] }
@@ -66,7 +78,7 @@ source = ["twentemilieu"]
 
 [tool.coverage.report]
 show_missing = true
-fail_under = 10
+fail_under = 95
 omit = ["src/twentemilieu/cli/async_typer.py"]
 
 [tool.ty.environment]
diff --git a/src/twentemilieu/twentemilieu.py b/src/twentemilieu/twentemilieu.py
index 2a498321..a0fd1304 100644
--- a/src/twentemilieu/twentemilieu.py
+++ b/src/twentemilieu/twentemilieu.py
@@ -34,25 +34,28 @@ class WasteType(IntEnum):
     PACKAGES = 10
 
     @classmethod
-    def _missing_(cls, value: object) -> WasteType:
+    def _missing_(cls, value: object) -> WasteType | None:
         """Fallback for unknown waste types.
 
-        Some waste types returned from the Twente Milieu API are semantically the same
-        as some types already defined in this enum. This maps the API value to the
-        correct enum value.
+        Some waste types returned from the Twente Milieu API are semantically
+        the same as types already defined in this enum. This maps those API
+        values to the correct enum member.
 
-        An example would be for packages. Some housing has a container for packages,
-        and high-density living may need to place their packages at a central point
-        for pick-up. Both is a pick-up for packages, but their waste type returned
-        from the API are different.
+        An example would be for packages. Some housing has a container for
+        packages, and high-density living may need to place their packages at
+        a central point for pick-up. Both are a pick-up for packages, but the
+        waste type values returned from the API are different.
+
+        For truly unknown integer values we return ``None`` so the standard
+        enum machinery raises ``ValueError``; callers can then skip the entry
+        instead of crashing on an unexpected API value.
 
         """
         if not isinstance(value, int):
             raise TypeError(value)
 
-        return {
-            56: WasteType.PACKAGES,
-        }[value]
+        aliases = {56: WasteType.PACKAGES}
+        return aliases.get(value)
 
 
 @dataclass
@@ -209,7 +212,12 @@ async def update(self) -> dict[WasteType, list[date]]:
         for pickup in response["dataList"]:
             if not pickup["pickupDates"]:
                 continue
-            waste_type = WasteType(pickup["pickupType"])
+            try:
+                waste_type = WasteType(pickup["pickupType"])
+            except ValueError:
+                # Skip waste types not (yet) known to this client so a
+                # newly-introduced API value doesn't crash the whole update.
+                continue
             for pickup_date_raw in pickup["pickupDates"]:
                 pickup_date = (
                     datetime.strptime(
diff --git a/tests/fixtures/calendar_response.json b/tests/fixtures/calendar_response.json
index 6d244899..52a374c1 100644
--- a/tests/fixtures/calendar_response.json
+++ b/tests/fixtures/calendar_response.json
@@ -23,6 +23,10 @@
     {
       "pickupDates": [],
       "pickupType": 10
+    },
+    {
+      "pickupDates": ["2019-09-01T00:00:00"],
+      "pickupType": 99
     }
   ]
 }
diff --git a/tests/test_twentemilieu.py b/tests/test_twentemilieu.py
index 52a9d17f..79bf19d0 100644
--- a/tests/test_twentemilieu.py
+++ b/tests/test_twentemilieu.py
@@ -3,15 +3,13 @@
 from __future__ import annotations
 
 # pylint: disable=protected-access,redefined-outer-name
-import asyncio
-import json
 import socket
 from typing import TYPE_CHECKING, Any
 from unittest.mock import patch
 
 import aiohttp
 import pytest
-from aresponses import Response, ResponsesMockServer
+from aioresponses import aioresponses
 
 from twentemilieu import TwenteMilieu, WasteType
 from twentemilieu.exceptions import (
@@ -21,11 +19,14 @@
 )
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator
+    from collections.abc import AsyncIterator, Callable
 
     from syrupy.assertion import SnapshotAssertion
 
-API_HOST = "twentemilieuapi.ximmio.com"
+API_BASE = "https://twentemilieuapi.ximmio.com/api/"
+API_URL = API_BASE
+API_FETCH_ADDRESS = API_BASE + "FetchAdress"
+API_GET_CALENDAR = API_BASE + "GetCalendar"
 
 
 @pytest.fixture
@@ -41,108 +42,94 @@ async def twente() -> AsyncIterator[TwenteMilieu]:
         await client.close()
 
 
-async def test_json_request(
-    aresponses: ResponsesMockServer,
-    twente: TwenteMilieu,
-) -> None:
+async def test_json_request(twente: TwenteMilieu) -> None:
     """Test JSON response is handled correctly."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(
+    with aioresponses() as mocked:
+        mocked.post(
+            API_URL,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"status": "ok"}',
-        ),
-    )
-    response = await twente._request("")
-    assert response["status"] == "ok"
+            payload={"status": "ok"},
+        )
+        response = await twente._request("")
+        assert response["status"] == "ok"
 
 
 async def test_wastetype_fallback() -> None:
     """Test the WasteType fallback is handled correctly."""
+    # Known alias for high-density packages pickup points.
     assert WasteType(56) == WasteType.PACKAGES, (
         "Fallback for high-density packages not handled!"
     )
 
+    # Unknown integer values must raise ValueError rather than KeyError
+    # so callers can catch and skip forward-compatibly.
+    with pytest.raises(ValueError, match="is not a valid WasteType"):
+        WasteType(999)
+
+    # Non-integer values still raise TypeError from the _missing_ hook.
     with pytest.raises(TypeError):
         WasteType._missing_("wrong_type")
 
 
-async def test_internal_session(aresponses: ResponsesMockServer) -> None:
+async def test_internal_session() -> None:
     """Test the TwenteMilieu client manages its own session as a context manager."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(
+    with aioresponses() as mocked:
+        mocked.post(
+            API_URL,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"status": "ok"}',
-        ),
-    )
-    async with TwenteMilieu(post_code="1234AB", house_number=1) as client:
-        response = await client._request("")
-        assert response["status"] == "ok"
+            payload={"status": "ok"},
+        )
+        async with TwenteMilieu(post_code="1234AB", house_number=1) as client:
+            response = await client._request("")
+            assert response["status"] == "ok"
 
 
-async def test_timeout(aresponses: ResponsesMockServer) -> None:
+async def test_timeout(twente: TwenteMilieu) -> None:
     """Test request timeout from Twente Milieu."""
+    twente.request_timeout = 1
+    with aioresponses() as mocked:
+        mocked.post(API_URL, exception=TimeoutError())
+        with pytest.raises(TwenteMilieuConnectionError):
+            await twente._request("")
 
-    # Faking a timeout by sleeping
-    async def response_handler(_: aiohttp.ClientResponse) -> Response:
-        await asyncio.sleep(2)
-        return aresponses.Response(body="Good morning!")
 
-    aresponses.add(API_HOST, "/api/", "POST", response_handler)
+def _mock_http_4xx_plaintext(mocked: aioresponses) -> None:
+    mocked.post(API_URL, status=404, body="OMG PUPPIES!", content_type="text/plain")
 
-    async with aiohttp.ClientSession() as session:
-        client = TwenteMilieu(
-            post_code="1234AB",
-            house_number=1,
-            session=session,
-            request_timeout=1,
-        )
-        with pytest.raises(TwenteMilieuConnectionError):
-            assert await client._request("")
+
+def _mock_http_5xx_json(mocked: aioresponses) -> None:
+    mocked.post(
+        API_URL,
+        status=500,
+        body=b'{"status":"nok"}',
+        content_type="application/json",
+    )
+
+
+def _mock_200_unexpected_content_type(mocked: aioresponses) -> None:
+    mocked.post(API_URL, status=200, body="OMG PUPPIES!", content_type="text/plain")
 
 
 @pytest.mark.parametrize(
-    "response_kwargs",
+    "setup_mock",
     [
+        pytest.param(_mock_http_4xx_plaintext, id="http_4xx_plaintext"),
+        pytest.param(_mock_http_5xx_json, id="http_5xx_json"),
         pytest.param(
-            {"text": "OMG PUPPIES!", "status": 404},
-            id="http_4xx_plaintext",
-        ),
-        pytest.param(
-            {
-                "body": b'{"status":"nok"}',
-                "status": 500,
-                "headers": {"Content-Type": "application/json"},
-            },
-            id="http_5xx_json",
-        ),
-        pytest.param(
-            {"text": "OMG PUPPIES!", "status": 200},
+            _mock_200_unexpected_content_type,
             id="200_unexpected_content_type",
         ),
     ],
 )
 async def test_request_errors(
-    aresponses: ResponsesMockServer,
     twente: TwenteMilieu,
-    response_kwargs: dict[str, Any],
+    setup_mock: Callable[[aioresponses], None],
 ) -> None:
     """Test bad API responses raise TwenteMilieuError."""
-    aresponses.add(
-        API_HOST,
-        "/api/",
-        "POST",
-        aresponses.Response(**response_kwargs),
-    )
-    with pytest.raises(TwenteMilieuError):
-        await twente._request("")
+    with aioresponses() as mocked:
+        setup_mock(mocked)
+        with pytest.raises(TwenteMilieuError):
+            await twente._request("")
 
 
 async def test_communication_error(twente: TwenteMilieu) -> None:
@@ -154,73 +141,48 @@ async def test_communication_error(twente: TwenteMilieu) -> None:
         await twente._request("")
 
 
-async def test_unique_id(
-    aresponses: ResponsesMockServer,
-    twente: TwenteMilieu,
-) -> None:
+async def test_unique_id(twente: TwenteMilieu) -> None:
     """Test request of a unique address identifier."""
-    aresponses.add(
-        API_HOST,
-        "/api/FetchAdress",
-        "POST",
-        aresponses.Response(
+    with aioresponses() as mocked:
+        mocked.post(
+            API_FETCH_ADDRESS,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"dataList": [{"UniqueId": "12345"}]}',
-        ),
-    )
-    unique_id = await twente.unique_id()
-    assert unique_id == "12345"
-    unique_id = await twente.unique_id()
-    assert unique_id == "12345"
+            payload={"dataList": [{"UniqueId": "12345"}]},
+        )
+        unique_id = await twente.unique_id()
+        assert unique_id == "12345"
+        unique_id = await twente.unique_id()
+        assert unique_id == "12345"
 
 
-async def test_invalid_address(
-    aresponses: ResponsesMockServer,
-    twente: TwenteMilieu,
-) -> None:
+async def test_invalid_address(twente: TwenteMilieu) -> None:
     """Test request of invalid address information."""
-    aresponses.add(
-        API_HOST,
-        "/api/FetchAdress",
-        "POST",
-        aresponses.Response(
+    with aioresponses() as mocked:
+        mocked.post(
+            API_FETCH_ADDRESS,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"dataList": []}',
-        ),
-    )
-    with pytest.raises(TwenteMilieuAddressError):
-        await twente.unique_id()
+            payload={"dataList": []},
+        )
+        with pytest.raises(TwenteMilieuAddressError):
+            await twente.unique_id()
 
 
 async def test_update(
-    aresponses: ResponsesMockServer,
     twente: TwenteMilieu,
     calendar_response: Any,
     snapshot: SnapshotAssertion,
 ) -> None:
     """Test request for updating data from Twente Milieu."""
-    aresponses.add(
-        API_HOST,
-        "/api/FetchAdress",
-        "POST",
-        aresponses.Response(
+    with aioresponses() as mocked:
+        mocked.post(
+            API_FETCH_ADDRESS,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text='{"dataList": [{"UniqueId": "12345"}]}',
-        ),
-    )
-    aresponses.add(
-        API_HOST,
-        "/api/GetCalendar",
-        "POST",
-        aresponses.Response(
+            payload={"dataList": [{"UniqueId": "12345"}]},
+        )
+        mocked.post(
+            API_GET_CALENDAR,
             status=200,
-            headers={"Content-Type": "application/json"},
-            text=json.dumps(calendar_response),
-        ),
-    )
-
-    pickups = await twente.update()
-    assert pickups == snapshot
+            payload=calendar_response,
+        )
+        pickups = await twente.update()
+        assert pickups == snapshot

From 457ed13dd67adeea1af814275f0e52d00f423e99 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:35:17 +0000
Subject: [PATCH 07/11] =?UTF-8?q?=F0=9F=94=90=20Attach=20SBOM=20attestatio?=
 =?UTF-8?q?n=20to=20release=20artifacts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generate a CycloneDX SBOM for the built wheel via anchore/sbom-action
and create a Sigstore-signed in-toto SBOM attestation covering dist/*
via actions/attest. The SBOM is kept in-workflow only (no release
asset, no workflow artifact) — the attestation is uploaded to GitHub's
attestations API and to Rekor.

Consumers can verify the provenance and SBOM attestations with:
  gh attestation verify twentemilieu-<version>-py3-none-any.whl \
      --owner frenck

Both new actions are pinned by SHA with # vX.Y.Z comments so Renovate
tracks them automatically.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index b294b959..4b5580f9 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -21,6 +21,7 @@ jobs:
       name: release
       url: https://pypi.org/p/twentemilieu
     permissions:
+      attestations: write
       contents: write
       id-token: write
     steps:
@@ -52,6 +53,23 @@ jobs:
           poetry version --no-interaction "${version}"
       - name: 🏗 Build package
         run: poetry build --no-interaction
+      - name: 🧭 Locate built wheel
+        run: |
+          WHEEL_PATH=$(ls dist/twentemilieu-*-py3-none-any.whl)
+          echo "WHEEL_PATH=${WHEEL_PATH}" >> "${GITHUB_ENV}"
+      - name: 📝 Generate CycloneDX SBOM
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        with:
+          file: ${{ env.WHEEL_PATH }}
+          format: cyclonedx-json
+          output-file: twentemilieu.cdx.json
+          upload-artifact: false
+          upload-release-assets: false
+      - name: 📝 Attest SBOM against built artifacts
+        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
+        with:
+          subject-path: "dist/*"
+          sbom-path: twentemilieu.cdx.json
       - name: 🚀 Publish to PyPi
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:

From 6986a3f9942147f2f0ccd9e3ac1b1caed2599283 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:40:34 +0000
Subject: [PATCH 08/11] =?UTF-8?q?=F0=9F=A9=B9=20Address=20Copilot=20review?=
 =?UTF-8?q?=20comments=20on=20PR=201769?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six fixes flagged by Copilot:

- Snapshot exclude regex in .pre-commit-config.yaml matched nested
  __snapshots__ dirs but missed the top-level tests/__snapshots__/
  used by test_twentemilieu. Widen to ^tests/(?:.*/)?__snapshots__/
  so both are protected by the end-of-file and trailing-whitespace
  hooks.

- The `twentemilieu` console script was registered unconditionally
  and would crash with ModuleNotFoundError when invoked after a plain
  `pip install twentemilieu` (no `cli` extra). Add a tiny
  twentemilieu._cli module that defers the import of twentemilieu.cli
  and raises SystemExit with an install hint if the extras are
  missing, and re-point the script entry at it.

- The `cli` extra only listed `typer>=0.15.1`, relying on typer's
  transitive dep on rich. Declare `rich>=13.0.0` explicitly so a
  future typer resolver can't surprise us at runtime.

- src/twentemilieu/cli/__init__.py docstring said "Asynchronous
  Python client for the Twente Milieu API"; this module is the CLI
  entry point, not the client. Fix the docstring.

- src/twentemilieu/cli/async_typer.py still had the Peblar copy/paste
  docstring mentioning "Peblar EV chargers". Replace with a
  project-accurate description.

- src/twentemilieu/cli/ruff.toml comment was grammatically wrong
  ("This extend") and referred to "examples". Fix both.

The `assert inside pytest.raises` comment was already addressed by
the earlier aioresponses migration and no longer applies.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .pre-commit-config.yaml             |  4 ++--
 poetry.lock                         |  4 ++--
 pyproject.toml                      |  9 ++++++---
 src/twentemilieu/_cli.py            | 25 +++++++++++++++++++++++++
 src/twentemilieu/cli/__init__.py    |  2 +-
 src/twentemilieu/cli/async_typer.py |  2 +-
 src/twentemilieu/cli/ruff.toml      |  2 +-
 7 files changed, 38 insertions(+), 10 deletions(-)
 create mode 100644 src/twentemilieu/_cli.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 805d886d..37a07e48 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -81,7 +81,7 @@ repos:
         name: ⮐  Fix End of Files
         language: system
         types: [text]
-        exclude: ^tests/.*/__snapshots__/
+        exclude: ^tests/(?:.*/)?__snapshots__/
         entry: poetry run end-of-file-fixer
         stages: [commit, push, manual]
       - id: ty
@@ -125,7 +125,7 @@ repos:
         name: ✄  Trim Trailing Whitespace
         language: system
         types: [text]
-        exclude: ^tests/.*/__snapshots__/
+        exclude: ^tests/(?:.*/)?__snapshots__/
         entry: poetry run trailing-whitespace-fixer
         stages: [commit, push, manual]
       - id: yamllint
diff --git a/poetry.lock b/poetry.lock
index a7d00600..408a1e3a 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -2644,9 +2644,9 @@ files = [
 ]
 
 [extras]
-cli = ["typer"]
+cli = ["rich", "typer"]
 
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.11"
-content-hash = "8b4d6d60615f95faa94e6e57ddca8e910e5a9c69b20d1d6dd58406c12afd8872"
+content-hash = "a8e174ba537c8d278541957359d5d01da7d7c4d7779bf7a911005d2ec534419b"
diff --git a/pyproject.toml b/pyproject.toml
index d1be179e..54d09b6a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -37,10 +37,10 @@ packages = [{ include = "twentemilieu", from = "src" }]
 dependencies = ['aiohttp (>=3.0.0)', 'yarl (>=1.6.0)']
 
 [project.optional-dependencies]
-cli = ["typer>=0.15.1"]
+cli = ["rich>=13.0.0", "typer>=0.15.1"]
 
 [project.scripts]
-twentemilieu = "twentemilieu.cli:cli"
+twentemilieu = "twentemilieu._cli:main"
 
 [tool.poetry]
 requires-poetry = '>=2.0'
@@ -79,7 +79,10 @@ source = ["twentemilieu"]
 [tool.coverage.report]
 show_missing = true
 fail_under = 95
-omit = ["src/twentemilieu/cli/async_typer.py"]
+omit = [
+  "src/twentemilieu/_cli.py",
+  "src/twentemilieu/cli/async_typer.py",
+]
 
 [tool.ty.environment]
 python-version = "3.11"
diff --git a/src/twentemilieu/_cli.py b/src/twentemilieu/_cli.py
new file mode 100644
index 00000000..db873331
--- /dev/null
+++ b/src/twentemilieu/_cli.py
@@ -0,0 +1,25 @@
+"""Entry point shim for the optional Twente Milieu CLI.
+
+Kept as a standalone module so the console script remains importable
+regardless of whether the ``cli`` extra is installed: if the CLI
+dependencies (``typer``, ``rich``) are missing we raise a friendly
+``SystemExit`` with an install hint instead of a bare ``ImportError``.
+"""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """Invoke the Typer CLI with a graceful error if extras are missing."""
+    try:
+        # Deferred import so the console script remains importable even
+        # when the optional ``cli`` extra is not installed.
+        # pylint: disable-next=import-outside-toplevel
+        from twentemilieu.cli import cli  # noqa: PLC0415
+    except ModuleNotFoundError as err:  # pragma: no cover
+        msg = (
+            "The Twente Milieu CLI requires the 'cli' extra. "
+            "Install it with: pip install 'twentemilieu[cli]'"
+        )
+        raise SystemExit(msg) from err
+    cli()
diff --git a/src/twentemilieu/cli/__init__.py b/src/twentemilieu/cli/__init__.py
index 4be613e9..ca65c0a7 100644
--- a/src/twentemilieu/cli/__init__.py
+++ b/src/twentemilieu/cli/__init__.py
@@ -1,4 +1,4 @@
-"""Asynchronous Python client for the Twente Milieu API."""
+"""Command-line interface for the Twente Milieu API."""
 
 from __future__ import annotations
 
diff --git a/src/twentemilieu/cli/async_typer.py b/src/twentemilieu/cli/async_typer.py
index 946796fe..f72739b3 100644
--- a/src/twentemilieu/cli/async_typer.py
+++ b/src/twentemilieu/cli/async_typer.py
@@ -1,4 +1,4 @@
-"""Asynchronous Python client for Peblar EV chargers.
+"""Async-capable Typer wrapper used by the Twente Milieu CLI.
 
 Adaptation of the snippet/code from:
 - https://github.com/tiangolo/typer/issues/88#issuecomment-1613013597
diff --git a/src/twentemilieu/cli/ruff.toml b/src/twentemilieu/cli/ruff.toml
index ac624159..5c78f814 100644
--- a/src/twentemilieu/cli/ruff.toml
+++ b/src/twentemilieu/cli/ruff.toml
@@ -1,4 +1,4 @@
-# This extend our general Ruff rules specifically for the examples
+# This extends our general Ruff rules specifically for the CLI.
 extend = "../../../pyproject.toml"
 
 lint.extend-ignore = [

From a2fb5fa7481bfc0565853aa6405b7ddabaf89554 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:49:55 +0000
Subject: [PATCH 09/11] =?UTF-8?q?=F0=9F=93=9D=20Add=20OpenSSF=20Scorecard?=
 =?UTF-8?q?=20badge=20to=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surfaces the supply-chain security score published by the scorecard
workflow next to the existing Build Status / Code Coverage / Dev
Containers badges, linking to the public Scorecard viewer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 55a1020a..10b9a8c6 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@
 
 [![Build Status][build-shield]][build]
 [![Code Coverage][codecov-shield]][codecov]
+[![OpenSSF Scorecard][scorecard-shield]][scorecard]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
 [![Sponsor Frenck via GitHub Sponsors][github-sponsors-shield]][github-sponsors]
@@ -235,4 +236,6 @@ SOFTWARE.
 [pypi]: https://pypi.org/project/twentemilieu
 [releases-shield]: https://img.shields.io/github/release/frenck/python-twentemilieu.svg
 [releases]: https://github.com/frenck/python-twentemilieu/releases
+[scorecard-shield]: https://api.scorecard.dev/projects/github.com/frenck/python-twentemilieu/badge
+[scorecard]: https://scorecard.dev/viewer/?uri=github.com/frenck/python-twentemilieu
 [semver]: http://semver.org/spec/v2.0.0.html

From 49f9f0c7fb2909936eca478e46d1452bac902cfb Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:54:53 +0000
Subject: [PATCH 10/11] =?UTF-8?q?=F0=9F=94=92=20Strengthen=20SECURITY.md?=
 =?UTF-8?q?=20and=20document=20npm=20pinning=20trade-off?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two Scorecard-related tweaks:

- SECURITY.md now contains explicit URLs — a direct link to GitHub's
  private advisories endpoint and a mailto: to opensource@frenck.dev.
  Scorecard's Security-Policy check was scoring 4/10 on "no linked
  content found" despite the policy being substantive; adding the
  links should bump it to 10/10.

- Document inline in linting.yaml why the npm install step stays at
  9/10 on Pinned-Dependencies. Versions are locked via
  package-lock.json but npm commands can't be hash-pinned the way
  GitHub Actions can, so the 9/10 score is an accepted trade-off.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/SECURITY.md            | 22 ++++++++++++++++------
 .github/workflows/linting.yaml |  4 ++++
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/.github/SECURITY.md b/.github/SECURITY.md
index 3cf65d4e..578dad0f 100644
--- a/.github/SECURITY.md
+++ b/.github/SECURITY.md
@@ -1,18 +1,28 @@
 # Security Policy
 
-We take the security of this project seriously. We appreciate your efforts to responsibly disclose your findings and will make every effort to acknowledge your contributions.
+We take the security of this project seriously. We appreciate your efforts to
+responsibly disclose your findings and will make every effort to acknowledge
+your contributions.
 
 ## Reporting a Vulnerability
 
 **Please do not report security vulnerabilities through public GitHub issues.**
 
-If you discover a security vulnerability, please report it via GitHub's private vulnerability reporting:
+If you discover a security vulnerability, please report it privately using
+GitHub's private vulnerability reporting at
+<https://github.com/frenck/python-twentemilieu/security/advisories/new>.
 
-1. Navigate to the Security tab of this repository
-2. Click "Report a vulnerability"
-3. Provide a description of the vulnerability and steps to reproduce
+Alternatively, you can email [opensource@frenck.dev](mailto:opensource@frenck.dev)
+directly.
 
-After the initial report, we will keep you informed of the progress towards a fix and may ask for additional information or guidance.
+When reporting, please include:
+
+1. A description of the vulnerability and its potential impact.
+2. Steps to reproduce the issue or a proof of concept.
+3. Any known mitigations or workarounds.
+
+After the initial report, we will keep you informed of the progress towards a
+fix and may ask for additional information or guidance.
 
 We aim to address reported vulnerabilities within 90 days.
 
diff --git a/.github/workflows/linting.yaml b/.github/workflows/linting.yaml
index 3bbac4e8..9b01de01 100644
--- a/.github/workflows/linting.yaml
+++ b/.github/workflows/linting.yaml
@@ -190,6 +190,10 @@ jobs:
           node-version-file: ".nvmrc"
           cache: "npm"
       - name: 🏗 Install NPM dependencies
+        # Versions are locked via package-lock.json; Scorecard's
+        # Pinned-Dependencies check still scores this 9/10 because npm
+        # commands can't be hash-pinned the way GitHub Actions can.
+        # Accepted trade-off.
         run: npm install
       - name: 🚀 Run prettier
         run: poetry run prek run prettier --all-files

From 02b93539bd9c88970f824e49dc7ddfdcbacc96ec Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Wed, 15 Apr 2026 18:59:40 +0000
Subject: [PATCH 11/11] =?UTF-8?q?=F0=9F=A9=B9=20Narrow=20CLI=20shim=20exce?=
 =?UTF-8?q?ption=20+=20harden=20wheel=20locate=20step?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more Copilot findings:

- The CLI entry shim's blanket `except ModuleNotFoundError` would turn a
  genuine internal-module bug (e.g. a renamed or missing private module
  inside twentemilieu.cli) into a misleading "install the cli extra"
  message. Narrow the catch to only the optional-dep roots (typer, rich)
  and re-raise anything else so real errors stay visible. Pylint's type
  inference is broken on ModuleNotFoundError.name, so the split() call
  carries an inline no-member disable with an explanatory comment.

- The release workflow's wheel-locate step used a bare
  `ls dist/twentemilieu-*-py3-none-any.whl` which silently takes the
  first match if the build ever produces more than one wheel, or fails
  opaquely on zero. Replace with a bash array + explicit count check,
  erroring out with a GitHub ::error:: annotation if anything other
  than exactly one pure wheel is present.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yaml |  9 +++++++--
 src/twentemilieu/_cli.py       | 11 +++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 4b5580f9..3628ab1e 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -55,8 +55,13 @@ jobs:
         run: poetry build --no-interaction
       - name: 🧭 Locate built wheel
         run: |
-          WHEEL_PATH=$(ls dist/twentemilieu-*-py3-none-any.whl)
-          echo "WHEEL_PATH=${WHEEL_PATH}" >> "${GITHUB_ENV}"
+          shopt -s failglob
+          wheels=(dist/twentemilieu-*-py3-none-any.whl)
+          if (( ${#wheels[@]} != 1 )); then
+            echo "::error::Expected exactly one wheel in dist/, found ${#wheels[@]}"
+            exit 1
+          fi
+          echo "WHEEL_PATH=${wheels[0]}" >> "${GITHUB_ENV}"
       - name: 📝 Generate CycloneDX SBOM
         uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
         with:
diff --git a/src/twentemilieu/_cli.py b/src/twentemilieu/_cli.py
index db873331..cb5c8c13 100644
--- a/src/twentemilieu/_cli.py
+++ b/src/twentemilieu/_cli.py
@@ -8,6 +8,8 @@
 
 from __future__ import annotations
 
+_CLI_EXTRA_MODULES = frozenset({"typer", "rich"})
+
 
 def main() -> None:
     """Invoke the Typer CLI with a graceful error if extras are missing."""
@@ -17,6 +19,15 @@ def main() -> None:
         # pylint: disable-next=import-outside-toplevel
         from twentemilieu.cli import cli  # noqa: PLC0415
     except ModuleNotFoundError as err:  # pragma: no cover
+        # Only convert to a friendly install hint when the *optional* deps
+        # are missing. Anything else (e.g. a renamed internal module) must
+        # still surface as a real error for debugging.
+        # pylint chokes on the type of ModuleNotFoundError.name, so silence
+        # the spurious no-member warning on the split() call below.
+        missing_module: str = err.name or ""
+        missing_root = missing_module.split(".", 1)[0]  # pylint: disable=no-member
+        if missing_root not in _CLI_EXTRA_MODULES:
+            raise
         msg = (
             "The Twente Milieu CLI requires the 'cli' extra. "
             "Install it with: pip install 'twentemilieu[cli]'"