Output Formatters and Parsers

Relevant source files

The following files were used as context for generating this wiki page:

• infrahub_sdk/ctl/formatters/base.py
• infrahub_sdk/ctl/formatters/json.py
• infrahub_sdk/ctl/parsers.py
• specs/001-end-user-cli/tasks.md
• specs/001-end-user-cli/research.md

Output Formatters and Parsers provide the structural foundation for data transformation within the infrahubctl CLI. Formatters convert internal SDK node data into user-consumable representations such as JSON, Tables, CSV, and YAML. Parsers handle the reverse process by converting CLI input flags—specifically for filtering and setting attributes—into structured Python dictionaries usable by the SDK client.

This system ensures that users can interact with Infrahub infrastructure data as native Python objects while maintaining flexibility in how that data is displayed or updated.

Sources: specs/001-end-user-cli/research.md:4-8, specs/001-end-user-cli/tasks.md:38-50

CLI Input Parsers

Parsers interpret command-line arguments to build query filters and object data payloads. These tools allow users to interact with the SDK without manually constructing complex dictionaries.

Key Parser Functions

Function	Purpose	Implementation Details
--set Parser	Parses key=value strings	Converts CLI input into a dictionary for client.create() or node updates.
--filter Parser	Parses attr__value=x strings	Converts input into a kwargs dictionary for client.filters().

Sources: specs/001-end-user-cli/tasks.md:38-40, specs/001-end-user-cli/research.md:65-70

Logic Flow for Input Parsing

The following diagram illustrates how user-provided flags are processed into SDK-compatible structures.

The diagram shows the transition from raw CLI text to structured data used by the SDK.
Sources: specs/001-end-user-cli/research.md:65-75, specs/001-end-user-cli/tasks.md:38-40

Output Formatter Architecture

The formatting system follows a protocol-based design where every formatter must implement methods for both list and detail views. The system automatically detects the appropriate format based on whether the output is a TTY or a piped stream.

Formatter Interface

All formatters inherit from or implement the FormatBase protocol. This ensures consistent method signatures across different export types.

class FormatBase(Protocol):
    def format_list(self, data: list[InfrahubNode]) -> None:
        """Formats a list of nodes for output."""
        ...

    def format_detail(self, data: InfrahubNode) -> None:
        """Formats a single node for detailed output."""
        ...

Sources: infrahub_sdk/ctl/formatters/base.py:8-16, specs/001-end-user-cli/tasks.md:42-44

Supported Formats

Format	Implementation	Usage Context
Table	Rich-based	Default for interactive TTY sessions. Displays attribute/relationship columns.
JSON	Standard Library	Default when piped. Provides full structured data serialization.
CSV	Standard Library	Used for spreadsheet integration. Primarily for list views.
YAML	PyYAML / Ruamel	Used for Infrahub Object round-tripping via apiVersion/kind structure.

Sources: specs/001-end-user-cli/research.md:86-90, specs/001-end-user-cli/tasks.md:45-50

Formatter Class Hierarchy

The following diagram represents the relationship between the base protocol and concrete implementations.

The diagram illustrates the inheritance and implementation of the standard formatting interface.
Sources: infrahub_sdk/ctl/formatters/base.py:8-16, infrahub_sdk/ctl/formatters/json.py:10-15, specs/001-end-user-cli/tasks.md:45-50

Auto-Detection and Serialization

The CLI utilizes sys.stdout.isatty() to determine the default output format. If a user pipes the output to another tool, the JSONFormatter is selected to provide machine-readable data.

Serialization Logic

Formatters extract values from SDK nodes using the following patterns:

• node.display_label: Used for human-friendly table headers and labels.
• node.<attr>.value: Accessed for specific attribute data.
• schema.display_labels: Identifies which attributes constitute the display label.

Sources: specs/001-end-user-cli/research.md:27-35, specs/001-end-user-cli/research.md:88-90

Sequence: Query to Formatted Output

The sequence shows how the CLI coordinates between the SDK client and the selected formatter based on the execution environment.
Sources: specs/001-end-user-cli/research.md:21-25, specs/001-end-user-cli/tasks.md:41-43

Conclusion

The Output Formatters and Parsers module creates a predictable interface between the Infrahub SDK and the end user. By providing robust parsing of CLI flags into SDK calls and automated selection of output formats, the system enables efficient infrastructure management across both interactive and automated workflows.