diff --git a/pkgs/clan-cli/clan_cli/machines/list.py b/pkgs/clan-cli/clan_cli/machines/list.py
index e1153fb19..7035e23b0 100644
--- a/pkgs/clan-cli/clan_cli/machines/list.py
+++ b/pkgs/clan-cli/clan_cli/machines/list.py
@@ -2,7 +2,7 @@ import argparse
 import logging
 
 from clan_lib.flake import require_flake
-from clan_lib.machines.actions import list_machines
+from clan_lib.machines.actions import ListOptions, MachineFilter, list_machines
 
 from clan_cli.completions import add_dynamic_completer, complete_tags
 
@@ -12,7 +12,9 @@ log = logging.getLogger(__name__)
 def list_command(args: argparse.Namespace) -> None:
     flake = require_flake(args.flake)
 
-    for name in list_machines(flake, opts={"filter": {"tags": args.tags}}):
+    for name in list_machines(
+        flake, opts=ListOptions(filter=MachineFilter(tags=args.tags))
+    ):
         print(name)
 
 
diff --git a/pkgs/clan-cli/clan_cli/machines/update.py b/pkgs/clan-cli/clan_cli/machines/update.py
index 7a6cd552b..a3674c12c 100644
--- a/pkgs/clan-cli/clan_cli/machines/update.py
+++ b/pkgs/clan-cli/clan_cli/machines/update.py
@@ -7,7 +7,7 @@ from clan_lib.async_run import AsyncContext, AsyncOpts, AsyncRuntime
 from clan_lib.errors import ClanError
 from clan_lib.flake import require_flake
 from clan_lib.flake.flake import Flake
-from clan_lib.machines.actions import list_machines
+from clan_lib.machines.actions import ListOptions, MachineFilter, list_machines
 from clan_lib.machines.list import instantiate_inventory_to_machines
 from clan_lib.machines.machines import Machine
 from clan_lib.machines.suggestions import validate_machine_names
@@ -49,7 +49,9 @@ def get_machines_for_update(
     filter_tags: list[str],
 ) -> list[Machine]:
     all_machines = list_machines(flake)
-    machines_with_tags = list_machines(flake, {"filter": {"tags": filter_tags}})
+    machines_with_tags = list_machines(
+        flake, ListOptions(filter=MachineFilter(tags=filter_tags))
+    )
 
     if filter_tags and not machines_with_tags:
         msg = f"No machines found with tags: {' AND '.join(filter_tags)}"
diff --git a/pkgs/clan-cli/clan_lib/machines/actions.py b/pkgs/clan-cli/clan_lib/machines/actions.py
index c24c702f4..be95ba0fd 100644
--- a/pkgs/clan-cli/clan_lib/machines/actions.py
+++ b/pkgs/clan-cli/clan_lib/machines/actions.py
@@ -1,3 +1,4 @@
+from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import TypedDict
 
@@ -18,12 +19,14 @@ from clan_lib.persist.util import (
 )
 
 
-class MachineFilter(TypedDict):
-    tags: list[str]
+@dataclass
+class MachineFilter:
+    tags: list[str] | None = None
 
 
-class ListOptions(TypedDict):
-    filter: MachineFilter
+@dataclass
+class ListOptions:
+    filter: MachineFilter = field(default_factory=MachineFilter)
 
 
 class MachineStatus(StrEnum):
@@ -44,26 +47,18 @@ def list_machines(
 ) -> dict[str, InventoryMachine]:
     """
     List machines of a clan
-
-    Usage Example:
-
-    machines = list_machines(flake, {"filter": {"tags": ["foo" "bar"]}})
-
-    lists only machines that include both "foo" AND "bar"
-
     """
     inventory_store = InventoryStore(flake=flake)
     inventory = inventory_store.read()
 
     machines = inventory.get("machines", {})
 
-    if opts and opts.get("filter"):
+    if opts and opts.filter.tags is not None:
         filtered_machines = {}
-        filter_tags = opts.get("filter", {}).get("tags", [])
 
         for machine_name, machine in machines.items():
             machine_tags = machine.get("tags", [])
-            if all(ft in machine_tags for ft in filter_tags):
+            if all(ft in machine_tags for ft in opts.filter.tags):
                 filtered_machines[machine_name] = machine
 
         return filtered_machines