infrahubctl CLI Overview
Relevant source files
The following files were used as context for generating this wiki page:
The infrahubctl CLI is a command-line interface providing end users with tools to query, create, and modify infrastructure data within the Infrahub database. It acts as a thin presentation layer over the Infrahub Python SDK, handling argument parsing, local validation, and output formatting while delegating core domain logic to the underlying SDK.
infrahubctl supports standard CRUD (Create, Read, Update, Delete) operations and schema discovery. It integrates with the project's async/sync dual API architecture, utilizing AsyncTyper to execute asynchronous SDK commands within a synchronous CLI environment.
Sources: dev/specs/001-end-user-cli/spec.md:5-7, dev/constitution.md:65-72, dev/specs/001-end-user-cli/research.md:16-20
Architecture and Design Principles
The CLI follows a layered architecture where all reusable logic resides in the infrahub_sdk/ core. The CLI components in infrahub_sdk/ctl/ focus exclusively on user interaction and presentation.
Core Principles
- SDK-First Logic: The CLI must not duplicate logic found in the SDK. If a non-CLI consumer needs the same behavior, the logic belongs in the SDK.
- Async Execution: The CLI uses
AsyncTyperto wrapasyncio.run()around command functions, enabling the use of the asyncInfrahubClient. - Presentation: Interactive output utilizes the
Richlibrary for tables and formatting, while programmatic output supports JSON, CSV, and YAML. - Error Handling: Exceptions are caught using the
@catch_exceptiondecorator to translate SDK errors into appropriate exit codes.
Sources: dev/constitution.md:65-76, dev/specs/001-end-user-cli/research.md:16-20, dev/specs/001-end-user-cli/research.md:63-66
Component Relationship
The following diagram illustrates the relationship between the CLI entry point, the command implementation, and the SDK client.
Command Structure and Operations
infrahubctl organizes functionality into top-level commands and subgroups. CRUD operations are implemented as top-level commands, while schema-related discovery is grouped under schema.
CRUD Operations
| Command | Operation | Key SDK Method | Description |
|---|---|---|---|
get | Read | client.all(), client.get() | Retrieves object lists or single object details. |
create | Create | client.create() | Creates new objects via --set flags or file input. |
update | Update | node.save() | Modifies existing objects by identifier (HFID or UUID). |
delete | Delete | node.delete() | Removes objects with a confirmation prompt. |
Sources: dev/specs/001-end-user-cli/research.md:7-12, dev/specs/001-end-user-cli/research.md:47-51
Schema Discovery
Schema commands allow users to explore the available data model:
schema list: Returns a table of all available kinds including their namespace and description.schema show <kind>: Displays detailed attributes, relationships, and constraints for a specific kind.
Sources: dev/specs/001-end-user-cli/spec.md:58-64, dev/specs/001-end-user-cli/research.md:42-45
Data Interaction and Formatting
Input Handling
The CLI provides two primary methods for data entry:
- Inline Flags: The
--setflag parseskey=valuepairs. For relationships, users provide Human-Friendly IDs (HFID) or UUIDs. - File Input: The
--fileflag loads JSON or YAML files using theInfrahubObjectFileDatamodel.
Sources: dev/specs/001-end-user-cli/spec.md:85-92, dev/specs/001-end-user-cli/research.md:31-36
Output Formats
infrahubctl supports four output formatters. It automatically detects the environment to choose between interactive and programmatic modes.
| Format | Auto-Detection Trigger | Use Case |
|---|---|---|
| Table | Standard TTY (Terminal) | Human-readable interactive display using Rich. |
| JSON | Piped Output | Scripting and integration with other tools. |
| CSV | Explicit Flag | Spreadsheet import and data analysis. |
| YAML | Explicit Flag | Round-tripping data back into Infrahub via --file. |
Sources: dev/specs/001-end-user-cli/research.md:63-66, dev/specs/001-end-user-cli/spec.md:113-116
Query Flow and Filtering
When executing a get command, the CLI translates user input into SDK filter arguments.
Configuration and Environment
The CLI reuses the standard SDK configuration mechanism. Settings are loaded from the infrahubctl.toml file or environment variables.
Key Configuration Parameters
server_address: The URL of the Infrahub instance.api_token: The authentication token for API access.default_branch: The target branch for operations (defaults tomainif not specified).
Sources: dev/specs/001-end-user-cli/research.md:58-61, pyproject.toml:53-65
Implementation Details
AsyncTyper Integration
Because the Infrahub SDK is primarily asynchronous, infrahubctl utilizes a custom AsyncTyper class located in infrahub_sdk/async_typer.py. This wrapper ensures that async command functions are executed within an event loop.
# Example of async command registration in cli.py
from infrahub_sdk.async_typer import AsyncTyper
app = AsyncTyper()
@app.command()
async def get(kind: str):
client = await initialize_client()
nodes = await client.all(kind=kind)
# Presentation logic follows...
Sources: infrahub_sdk/async_typer.py:1-10, dev/specs/001-end-user-cli/research.md:16-20
Development Tasks
Documentation for the CLI is generated automatically using typer-cli and mdxify. The tasks.py file includes an invoke task specifically for this purpose.
@task(name="generate-infrahubctl")
def generate_infrahubctl(context: Context) -> None:
"""Generate documentation for the infrahubctl cli."""
_generate_infrahubctl_documentation(context=context)
Sources: tasks.py:58-62, tasks.py:307-310
Summary: The infrahubctl CLI provides a powerful yet simple interface for managing Infrahub data. By strictly adhering to the Infrahub SDK's core logic and utilizing modern Python CLI libraries, it ensures a consistent and performant experience for network automation engineers.