infrahub-server 1.6.0b0__py3-none-any.whl → 1.6.2__py3-none-any.whl

infrahub/graphql/queries/search.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import ipaddress
 from typing import TYPE_CHECKING, Any
 
@@ -117,11 +118,9 @@ async def search_resolver(
         if matching:
             results.append(matching)
     else:
-        try:
+        with contextlib.suppress(ValueError, ipaddress.AddressValueError):
             # Convert any IPv6 address, network or partial address to collapsed format as it might be stored in db.
             q = _collapse_ipv6(q)
-        except (ValueError, ipaddress.AddressValueError):
-            pass
 
         for kind in [InfrahubKind.NODE, InfrahubKind.GENERICGROUP]:
             objs = await NodeManager.query(

infrahub/graphql/resolvers/ipam.py

@@ -4,6 +4,7 @@ import ipaddress
 from typing import TYPE_CHECKING, Any
 
 from graphql.type.definition import GraphQLNonNull
+from infrahub_sdk.utils import deep_merge_dict
 from netaddr import IPSet
 from opentelemetry import trace
 
@@ -233,6 +234,23 @@ async def _resolve_available_prefix_nodes(
     return available_nodes
 
 
+def _ensure_display_label_fields(
+    db: InfrahubDatabase, branch: Branch, schema: NodeSchema | GenericSchema, node_fields: dict[str, Any]
+) -> None:
+    """Ensure fields needed to compute display_label are included in node_fields.
+
+    This is mostly for virtual nodes (InternalIPPrefixAvailable, InternalIPRangeAvailable) that are not stored in the
+    database.
+    """
+    if "display_label" not in node_fields or schema.kind not in [InfrahubKind.IPPREFIX, InfrahubKind.IPADDRESS]:
+        return
+
+    schema_branch = db.schema.get_schema_branch(name=branch.name)
+    display_label_fields = schema_branch.generate_fields_for_display_label(name=schema.kind)
+    if display_label_fields:
+        deep_merge_dict(dicta=node_fields, dictb=display_label_fields)
+
+
 def _filter_kinds(nodes: list[Node], kinds: list[str], limit: int | None) -> list[Node]:
     filtered: list[Node] = []
     available_node_kinds = [InfrahubKind.IPPREFIXAVAILABLE, InfrahubKind.IPRANGEAVAILABLE]
@@ -324,6 +342,8 @@ async def ipam_paginated_list_resolver(  # noqa: PLR0915
         edges = fields.get("edges", {})
         node_fields = edges.get("node", {})
 
+        _ensure_display_label_fields(db=db, branch=graphql_context.branch, schema=schema, node_fields=node_fields)
+
         permission_set: dict[str, Any] | None = None
         permissions = (
             await get_permissions(schema=schema, graphql_context=graphql_context)

infrahub/graphql/resolvers/many_relationship.py

@@ -1,7 +1,6 @@
 from typing import TYPE_CHECKING, Any
 
 from graphql import GraphQLResolveInfo
-from infrahub_sdk.utils import deep_merge_dict
 
 from infrahub.core.branch.models import Branch
 from infrahub.core.constants import BranchSupportType, RelationshipHierarchyDirection
@@ -12,6 +11,7 @@ from infrahub.core.schema.relationship_schema import RelationshipSchema
 from infrahub.core.timestamp import Timestamp
 from infrahub.database import InfrahubDatabase
 from infrahub.graphql.field_extractor import extract_graphql_fields
+from infrahub.utils import has_any_key
 
 from ..loaders.peers import PeerRelationshipsDataLoader, QueryPeerParams
 from ..types import RELATIONS_PROPERTY_MAP, RELATIONS_PROPERTY_MAP_REVERSED
@@ -195,6 +195,9 @@ class ManyRelationshipResolver:
         offset: int | None = None,
         limit: int | None = None,
     ) -> list[dict[str, Any]] | None:
+        include_source = has_any_key(data=node_fields, keys=["_relation__source", "source"])
+        include_owner = has_any_key(data=node_fields, keys=["_relation__owner", "owner"])
+
         async with db.start_session(read_only=True) as dbs:
             objs = await NodeManager.query_peers(
                 db=dbs,
@@ -209,6 +212,8 @@ class ManyRelationshipResolver:
                 branch=branch,
                 branch_agnostic=rel_schema.branch is BranchSupportType.AGNOSTIC,
                 fetch_peers=True,
+                include_source=include_source,
+                include_owner=include_owner,
             )
             if not objs:
                 return None
@@ -226,17 +231,11 @@ class ManyRelationshipResolver:
         filters: dict[str, Any],
         node_fields: dict[str, Any],
     ) -> list[dict[str, Any]] | None:
-        if node_fields and "display_label" in node_fields:
-            schema_branch = db.schema.get_schema_branch(name=branch.name)
-            display_label_fields = schema_branch.generate_fields_for_display_label(name=rel_schema.peer)
-            if display_label_fields:
-                node_fields = deep_merge_dict(dicta=node_fields, dictb=display_label_fields)
-
         if node_fields and "hfid" in node_fields:
-            peer_schema = db.schema.get(name=rel_schema.peer, branch=branch, duplicate=False)
-            hfid_fields = peer_schema.generate_fields_for_hfid()
-            if hfid_fields:
-                node_fields = deep_merge_dict(dicta=node_fields, dictb=hfid_fields)
+            node_fields["human_friendly_id"] = None
+
+        include_source = has_any_key(data=node_fields, keys=["_relation__source", "source"])
+        include_owner = has_any_key(data=node_fields, keys=["_relation__owner", "owner"])
 
         query_params = QueryPeerParams(
             branch=branch,
@@ -246,6 +245,8 @@ class ManyRelationshipResolver:
             fields=node_fields,
             at=at,
             branch_agnostic=rel_schema.branch is BranchSupportType.AGNOSTIC,
+            include_source=include_source,
+            include_owner=include_owner,
         )
         if query_params in self._data_loader_instances:
             loader = self._data_loader_instances[query_params]

infrahub/graphql/resolvers/resolver.py

@@ -9,6 +9,7 @@ from infrahub.core.constants import BranchSupportType, InfrahubKind, Relationshi
 from infrahub.core.manager import NodeManager
 from infrahub.exceptions import NodeNotFoundError
 from infrahub.graphql.field_extractor import extract_graphql_fields
+from infrahub.utils import has_any_key
 
 from ..models import OrderModel
 from ..parser import extract_selection
@@ -185,6 +186,9 @@ async def default_paginated_list_resolver(
 
         objs = []
         if edges or "hfid" in filters:
+            include_source = has_any_key(data=node_fields, keys=["_relation__source", "source"])
+            include_owner = has_any_key(data=node_fields, keys=["_relation__owner", "owner"])
+
             objs = await NodeManager.query(
                 db=db,
                 schema=schema,
@@ -195,8 +199,8 @@ async def default_paginated_list_resolver(
                 limit=limit,
                 offset=offset,
                 account=graphql_context.account_session,
-                include_source=True,
-                include_owner=True,
+                include_source=include_source,
+                include_owner=include_owner,
                 partial_match=partial_match,
                 order=order,
             )

infrahub/graphql/resolvers/single_relationship.py

@@ -2,7 +2,6 @@ from typing import TYPE_CHECKING, Any
 
 from graphql import GraphQLResolveInfo
 from graphql.type.definition import GraphQLNonNull
-from infrahub_sdk.utils import deep_merge_dict
 
 from infrahub.core.branch.models import Branch
 from infrahub.core.constants import BranchSupportType
@@ -142,17 +141,8 @@ class SingleRelationshipResolver:
         except (KeyError, IndexError):
             return None
 
-        if node_fields and "display_label" in node_fields:
-            schema_branch = db.schema.get_schema_branch(name=branch.name)
-            display_label_fields = schema_branch.generate_fields_for_display_label(name=rel_schema.peer)
-            if display_label_fields:
-                node_fields = deep_merge_dict(dicta=node_fields, dictb=display_label_fields)
-
         if node_fields and "hfid" in node_fields:
-            peer_schema = db.schema.get(name=rel_schema.peer, branch=branch, duplicate=False)
-            hfid_fields = peer_schema.generate_fields_for_hfid()
-            if hfid_fields:
-                node_fields = deep_merge_dict(dicta=node_fields, dictb=hfid_fields)
+            node_fields["human_friendly_id"] = None
 
         query_params = GetManyParams(
             fields=node_fields,

infrahub/log.py

@@ -10,7 +10,7 @@ from structlog.dev import plain_traceback
 if TYPE_CHECKING:
     from structlog.types import Processor
 
-INFRAHUB_PRODUCTION = TypeAdapter(bool).validate_python(os.environ.get("INFRAHUB_PRODUCTION", True))
+INFRAHUB_PRODUCTION = TypeAdapter(bool).validate_python(os.environ.get("INFRAHUB_PRODUCTION", "true"))
 INFRAHUB_LOG_LEVEL = os.environ.get("INFRAHUB_LOG_LEVEL", "INFO")
 
 

infrahub/message_bus/messages/__init__.py

@@ -22,20 +22,8 @@ RESPONSE_MAP: dict[str, type[InfrahubResponse]] = {
 }
 
 PRIORITY_MAP = {
-    "check.artifact.create": 2,
-    "check.repository.check_definition": 2,
-    "check.repository.merge_conflicts": 2,
     "send.echo.request": 5,  # Currently only for testing purposes, will be removed once all message bus have been migrated to prefect
-    "event.branch.delete": 5,
-    "event.branch.merge": 5,
-    "event.schema.update": 5,
-    "git.diff.names_only": 4,
     "git.file.get": 4,
-    "request.artifact.generate": 2,
-    "request.git.sync": 4,
-    "request.proposed_change.pipeline": 5,
-    "transform.jinja.template": 4,
-    "transform.python.data": 4,
 }
 
 

infrahub/profiles/node_applier.py

@@ -9,6 +9,15 @@ from .queries.get_profile_data import GetProfileDataQuery, ProfileData
 
 
 class NodeProfilesApplier:
+    """Applies profile values to nodes and templates.
+
+    Profile values take precedence over both default values and template-sourced values.
+    When a template has profiles assigned:
+    1. Profile values are applied to the template itself
+    2. Nodes created from that template inherit the profile values (not the template's own values)
+    3. Profile priority determines which profile wins when multiple profiles set the same attribute
+    """
+
     def __init__(self, db: InfrahubDatabase, branch: Branch):
         self.db = db
         self.branch = branch

infrahub/proposed_change/branch_diff.py

@@ -64,4 +64,4 @@ async def get_diff_summary_cache(pipeline_id: UUID) -> list[NodeDiff]:
     if not summary_payload:
         raise ResourceNotFoundError(message=f"Diff summary for pipeline {pipeline_id} was not found in the cache")
 
-    return cast(list["NodeDiff"], json.loads(summary_payload))
+    return cast("list[NodeDiff]", json.loads(summary_payload))

infrahub/proposed_change/tasks.py

@@ -480,7 +480,7 @@ async def _get_proposed_change_schema_integrity_constraints(
                 DiffElementType.RELATIONSHIP_ONE.value.lower(),
             ):
                 field_summary.relationship_names.add(element_name)
-            elif element_type.lower() in (DiffElementType.ATTRIBUTE.value.lower(),):
+            elif element_type.lower() == DiffElementType.ATTRIBUTE.value.lower():
                 field_summary.attribute_names.add(element_name)
 
     determiner = ConstraintValidatorDeterminer(schema_branch=schema)

infrahub/repositories/create_repository.py

@@ -4,7 +4,6 @@ from typing import TYPE_CHECKING, cast
 
 from infrahub.core.constants import RepositoryInternalStatus
 from infrahub.core.constants.infrahubkind import READONLYREPOSITORY, REPOSITORY
-from infrahub.core.protocols import CoreGenericRepository, CoreReadOnlyRepository, CoreRepository
 from infrahub.exceptions import ValidationError
 from infrahub.git.models import GitRepositoryAdd, GitRepositoryAddReadOnly
 from infrahub.log import get_logger
@@ -16,6 +15,7 @@ if TYPE_CHECKING:
     from infrahub.auth import AccountSession
     from infrahub.context import InfrahubContext
     from infrahub.core.branch import Branch
+    from infrahub.core.protocols import CoreGenericRepository, CoreReadOnlyRepository, CoreRepository
     from infrahub.database import InfrahubDatabase
     from infrahub.services import InfrahubServices
 
@@ -74,7 +74,7 @@ class RepositoryFinalizer:
             authenticated_user = self.account_session.account_id
 
         if obj.get_kind() == READONLYREPOSITORY:
-            obj = cast(CoreReadOnlyRepository, obj)
+            obj = cast("CoreReadOnlyRepository", obj)
             model = GitRepositoryAddReadOnly(
                 repository_id=obj.id,
                 repository_name=obj.name.value,
@@ -92,7 +92,7 @@ class RepositoryFinalizer:
             )
 
         elif obj.get_kind() == REPOSITORY:
-            obj = cast(CoreRepository, obj)
+            obj = cast("CoreRepository", obj)
             git_repo_add_model = GitRepositoryAdd(
                 repository_id=obj.id,
                 repository_name=obj.name.value,

infrahub/task_manager/models.py

@@ -74,7 +74,7 @@ class FlowLogs(BaseModel):
                 "node": {
                     "message": log.message,
                     "severity": LOG_LEVEL_MAPPING.get(log.level, "error"),
-                    "timestamp": log.timestamp.to_iso8601_string(),
+                    "timestamp": log.timestamp.isoformat(),
                 }
             }
             for log in self.logs[flow_id]

infrahub/task_manager/task.py

@@ -151,7 +151,7 @@ class PrefectTask:
             remaining -= nb_fetched
 
         for flow_log in all_logs:
-            if flow_log.flow_run_id and flow_log.message not in ["Finished in state Completed()"]:
+            if flow_log.flow_run_id and flow_log.message != "Finished in state Completed()":
                 logs_flow.logs[flow_log.flow_run_id].append(flow_log)
 
         return logs_flow
@@ -325,13 +325,13 @@ class PrefectTask:
                                 "parameters": flow.parameters,
                                 "branch": await cls._extract_branch_name(flow=flow),
                                 "tags": flow.tags,
-                                "workflow": workflow_names.get(flow.flow_id, None),
+                                "workflow": workflow_names.get(flow.flow_id),
                                 "related_node": related_node.id if related_node else None,
                                 "related_node_kind": related_node.kind if related_node else None,
                                 "related_nodes": related_nodes_info.get_related_nodes_as_dict(flow_id=flow.id),
-                                "created_at": flow.created.to_iso8601_string(),  # type: ignore
-                                "updated_at": flow.updated.to_iso8601_string(),  # type: ignore
-                                "start_time": flow.start_time.to_iso8601_string() if flow.start_time else None,
+                                "created_at": flow.created.isoformat() if flow.created else None,
+                                "updated_at": flow.updated.isoformat() if flow.updated else None,
+                                "start_time": flow.start_time.isoformat() if flow.start_time else None,
                                 "id": flow.id,
                                 "logs": {"edges": logs, "count": len(logs)},
                             }

infrahub/trigger/setup.py

@@ -122,7 +122,7 @@ async def setup_triggers(
             actions=[action.get_prefect(mapping=deployments_mapping) for action in trigger.actions],
         )
 
-        existing_automation = existing_automations.get(trigger.generate_name(), None)
+        existing_automation = existing_automations.get(trigger.generate_name())
 
         if existing_automation:
             trigger_comparison = compare_automations(
@@ -171,19 +171,16 @@ async def gather_all_automations(client: PrefectClient) -> list[Automation]:
     retrieves them all by paginating through the results. The default within Prefect is 200 items,
     and client.read_automations() doesn't support pagination parameters.
     """
-    automation_count_response = await client.request("POST", "/automations/count")
-    automation_count_response.raise_for_status()
-    automation_count: int = automation_count_response.json()
     offset = 0
     limit = 200
-    missing_automations = True
     automations: list[Automation] = []
-    while missing_automations:
+    while True:
         response = await client.request("POST", "/automations/filter", json={"limit": limit, "offset": offset})
         response.raise_for_status()
-        automations.extend(Automation.model_validate_list(response.json()))
-        if len(automations) >= automation_count:
-            missing_automations = False
+        batch = Automation.model_validate_list(response.json())
+        automations.extend(batch)
+        if len(batch) < limit:
+            break
         offset += limit
 
     return automations

infrahub/utils.py

@@ -83,3 +83,21 @@ def get_all_subclasses[AnyClass: type](cls: AnyClass) -> list[AnyClass]:
         subclasses.append(subclass)
         subclasses.extend(get_all_subclasses(subclass))
     return subclasses
+
+
+def has_any_key(data: dict[str, Any], keys: list[str]) -> bool:
+    """Recursively check if any of the specified keys exist in the dictionary at any level.
+
+    Args:
+        data: The dictionary to search through
+        keys: List of key names to search for
+
+    Returns:
+        True if any of the keys are found at any level of the dictionary, False otherwise
+    """
+    for key, value in data.items():
+        if key in keys:
+            return True
+        if isinstance(value, dict) and has_any_key(data=value, keys=keys):
+            return True
+    return False

infrahub/validators/tasks.py

@@ -26,7 +26,7 @@ async def start_validator[ValidatorType: CoreValidator](
         validator.started_at.value = ""
         validator.completed_at.value = ""
         await validator.save()
-        validator = cast(ValidatorType, validator)
+        validator = cast("ValidatorType", validator)
     else:
         data["proposed_change"] = proposed_change
         validator = await client.create(kind=validator_type, data=data)

infrahub/workers/infrahub_async.py

@@ -1,4 +1,5 @@
 import asyncio
+import contextlib
 import logging
 import os
 from pathlib import Path
@@ -107,7 +108,7 @@ class InfrahubWorkerAsync(BaseWorker):
 
         # Start metric endpoint
         if metric_port is None or metric_port != 0:
-            metric_port = metric_port or int(os.environ.get("INFRAHUB_METRICS_PORT", 8000))
+            metric_port = metric_port or int(os.environ.get("INFRAHUB_METRICS_PORT", "8000"))
             self._logger.info(f"Starting metric endpoint on port {metric_port}")
             start_http_server(metric_port)
 
@@ -212,18 +213,18 @@ class InfrahubWorkerAsync(BaseWorker):
         global_config_file = config.SETTINGS.git.global_config_file
         if not os.getenv("GIT_CONFIG_GLOBAL") and global_config_file:
             config_dir = Path(global_config_file).parent
-            try:
+            with contextlib.suppress(FileExistsError):
                 config_dir.mkdir(exist_ok=True, parents=True)
-            except FileExistsError:
-                pass
             os.environ["GIT_CONFIG_GLOBAL"] = global_config_file
             self._logger.info(f"Set git config file to {global_config_file}")
 
         await self._run_git_config_global(config.SETTINGS.git.user_name, setting_name="user.name")
         await self._run_git_config_global(config.SETTINGS.git.user_email, setting_name="user.email")
-        await self._run_git_config_global("'*'", "--replace-all", setting_name="safe.directory")
+        await self._run_git_config_global("*", "--replace-all", setting_name="safe.directory")
         await self._run_git_config_global("true", setting_name="credential.usehttppath")
-        await self._run_git_config_global(config.SETTINGS.dev.git_credential_helper, setting_name="credential.helper")
+        await self._run_git_config_global(
+            f"/usr/bin/env {config.SETTINGS.dev.git_credential_helper}", setting_name="credential.helper"
+        )
 
     async def _run_git_config_global(self, *args: str, setting_name: str) -> None:
         proc = await asyncio.create_subprocess_exec(

infrahub_sdk/client.py

@@ -34,7 +34,7 @@ from .config import Config
 from .constants import InfrahubClientMode
 from .convert_object_type import CONVERT_OBJECT_MUTATION, ConversionFieldInput
 from .data import RepositoryBranchInfo, RepositoryData
-from .diff import NodeDiff, diff_tree_node_to_node_diff, get_diff_summary_query
+from .diff import DiffTreeData, NodeDiff, diff_tree_node_to_node_diff, get_diff_summary_query, get_diff_tree_query
 from .exceptions import (
     AuthenticationError,
     Error,
@@ -1282,6 +1282,62 @@ class InfrahubClient(BaseClient):
 
         return node_diffs
 
+    async def get_diff_tree(
+        self,
+        branch: str,
+        name: str | None = None,
+        from_time: datetime | None = None,
+        to_time: datetime | None = None,
+        timeout: int | None = None,
+        tracker: str | None = None,
+    ) -> DiffTreeData | None:
+        """Get complete diff tree with metadata and nodes.
+
+        Returns None if no diff exists.
+        """
+        query = get_diff_tree_query()
+        input_data = {"branch_name": branch}
+        if name:
+            input_data["name"] = name
+        if from_time and to_time and from_time > to_time:
+            raise ValueError("from_time must be <= to_time")
+        if from_time:
+            input_data["from_time"] = from_time.isoformat()
+        if to_time:
+            input_data["to_time"] = to_time.isoformat()
+
+        response = await self.execute_graphql(
+            query=query.render(),
+            branch_name=branch,
+            timeout=timeout,
+            tracker=tracker,
+            variables=input_data,
+        )
+
+        diff_tree = response["DiffTree"]
+        if diff_tree is None:
+            return None
+
+        # Convert nodes to NodeDiff objects
+        node_diffs: list[NodeDiff] = []
+        if "nodes" in diff_tree:
+            for node_dict in diff_tree["nodes"]:
+                node_diff = diff_tree_node_to_node_diff(node_dict=node_dict, branch_name=branch)
+                node_diffs.append(node_diff)
+
+        return DiffTreeData(
+            num_added=diff_tree.get("num_added") or 0,
+            num_updated=diff_tree.get("num_updated") or 0,
+            num_removed=diff_tree.get("num_removed") or 0,
+            num_conflicts=diff_tree.get("num_conflicts") or 0,
+            to_time=diff_tree["to_time"],
+            from_time=diff_tree["from_time"],
+            base_branch=diff_tree["base_branch"],
+            diff_branch=diff_tree["diff_branch"],
+            name=diff_tree.get("name"),
+            nodes=node_diffs,
+        )
+
     @overload
     async def allocate_next_ip_address(
         self,
@@ -2520,6 +2576,62 @@ class InfrahubClientSync(BaseClient):
 
         return node_diffs
 
+    def get_diff_tree(
+        self,
+        branch: str,
+        name: str | None = None,
+        from_time: datetime | None = None,
+        to_time: datetime | None = None,
+        timeout: int | None = None,
+        tracker: str | None = None,
+    ) -> DiffTreeData | None:
+        """Get complete diff tree with metadata and nodes.
+
+        Returns None if no diff exists.
+        """
+        query = get_diff_tree_query()
+        input_data = {"branch_name": branch}
+        if name:
+            input_data["name"] = name
+        if from_time and to_time and from_time > to_time:
+            raise ValueError("from_time must be <= to_time")
+        if from_time:
+            input_data["from_time"] = from_time.isoformat()
+        if to_time:
+            input_data["to_time"] = to_time.isoformat()
+
+        response = self.execute_graphql(
+            query=query.render(),
+            branch_name=branch,
+            timeout=timeout,
+            tracker=tracker,
+            variables=input_data,
+        )
+
+        diff_tree = response["DiffTree"]
+        if diff_tree is None:
+            return None
+
+        # Convert nodes to NodeDiff objects
+        node_diffs: list[NodeDiff] = []
+        if "nodes" in diff_tree:
+            for node_dict in diff_tree["nodes"]:
+                node_diff = diff_tree_node_to_node_diff(node_dict=node_dict, branch_name=branch)
+                node_diffs.append(node_diff)
+
+        return DiffTreeData(
+            num_added=diff_tree.get("num_added") or 0,
+            num_updated=diff_tree.get("num_updated") or 0,
+            num_removed=diff_tree.get("num_removed") or 0,
+            num_conflicts=diff_tree.get("num_conflicts") or 0,
+            to_time=diff_tree["to_time"],
+            from_time=diff_tree["from_time"],
+            base_branch=diff_tree["base_branch"],
+            diff_branch=diff_tree["diff_branch"],
+            name=diff_tree.get("name"),
+            nodes=node_diffs,
+        )
+
     @overload
     def allocate_next_ip_address(
         self,

infrahub_sdk/ctl/AGENTS.md

@@ -0,0 +1,67 @@
+# infrahub_sdk/ctl/AGENTS.md
+
+CLI tool (`infrahubctl`) built with Typer/AsyncTyper.
+
+## Command Pattern
+
+```python
+from rich.console import Console
+from ..async_typer import AsyncTyper
+from ..ctl.client import initialize_client
+from ..ctl.utils import catch_exception
+from .parameters import CONFIG_PARAM
+
+console = Console()
+app = AsyncTyper()
+
+@app.command(name="my-command")
+@catch_exception(console=console)
+async def my_command(
+    path: str = typer.Option(".", help="Path to file"),
+    branch: Optional[str] = None,
+    _: str = CONFIG_PARAM,  # Always include, even if unused
+):
+    client = initialize_client(branch=branch)
+    # implementation using Rich for output
+    console.print(Panel("Result", title="Success"))
+```
+
+## File Organization
+
+```text
+infrahub_sdk/ctl/
+├── cli_commands.py    # Entry point, registers subcommands
+├── client.py          # initialize_client(), initialize_client_sync()
+├── utils.py           # catch_exception decorator, parse_cli_vars
+├── parameters.py      # CONFIG_PARAM and shared parameters
+├── branch.py          # Branch subcommands
+├── schema.py          # Schema subcommands
+└── object.py          # Object subcommands
+```
+
+## Registering Commands
+
+```python
+# In cli_commands.py
+from ..ctl.branch import app as branch_app
+app.add_typer(branch_app, name="branch")
+
+# Or for top-level commands
+from .exporter import dump
+app.command(name="dump")(dump)
+```
+
+## Boundaries
+
+✅ **Always**
+
+- Use `@catch_exception(console=console)` decorator
+- Include `CONFIG_PARAM` in all commands
+- Use `initialize_client()` for client creation
+- Use Rich for output (tables, panels, console.print)
+
+🚫 **Never**
+
+- Use plain `print()` statements
+- Instantiate `InfrahubClient` directly (use `initialize_client`)
+- Forget error handling decorator