CLI Commands Guide
Relevant source files
The following files were used as context for generating this wiki page:
The infrahubctl CLI provides a set of commands for interacting with the Infrahub database. It allows users to perform CRUD (Create, Read, Update, Delete) operations on infrastructure objects, manage branches, and discover schema definitions.
This tool acts as a thin layer over the Infrahub Python SDK, handling argument parsing, input validation, and result presentation.
Sources: dev/constitution.md:46-51, AGENTS.md:12-16
Architecture and Design Principles
The CLI follows a layered architecture where reusable logic resides in the SDK (infrahub_sdk/), and the CLI (infrahub_sdk/ctl/) is limited to presentation and user interaction. All commands use AsyncTyper to handle asynchronous SDK client calls.
Sources: dev/constitution.md:44-51, dev/specs/001-end-user-cli/research.md:16-19
Core Architecture Flow
The following diagram illustrates how a user request flows through the CLI to the Infrahub server.
Command Categories
Object Management (CRUD)
These commands allow users to manipulate data instances (Nodes) within Infrahub.
| Command | Description | Key Arguments |
|---|---|---|
get | Retrieves one or more objects. Supports list and detail views. | <kind>, [identifier], --filter, --output |
create | Adds new infrastructure objects to a branch. | <kind>, --set, --file |
update | Modifies attributes or relationships of existing objects. | <kind>, <identifier>, --set, --file |
delete | Removes objects from the database. | <kind>, <identifier>, --yes |
Sources: specs/001-end-user-cli/tasks.md:65-115, dev/specs/001-end-user-cli/spec.md:21-76
Schema Discovery
Schema commands enable users to explore the data model definitions stored in Infrahub.
schema list: Displays all available kinds, namespaces, and descriptions.schema show <kind>: Displays detailed metadata, attributes, and relationships for a specific kind.
Sources: specs/001-end-user-cli/tasks.md:120-130, dev/specs/001-end-user-cli/spec.md:80-92
Input and Output Handling
Parameter Parsing
The CLI uses specific parsers for complex flags:
--set: Parseskey=valuestrings into a dictionary for object creation or updates. It supports JSON syntax for many-to-many relationships, such as--set tags=[["blue"], ["red"]].--filter: Parsesattribute__value=xstrings into keyword arguments for query filtering.
Sources: specs/001-end-user-cli/tasks.md:45-48, dev/specs/001-end-user-cli/spec.md:105-108
Output Formatters
The CLI supports multiple output formats to accommodate both human interaction and tool integration.
Documentation and Validation
The documentation for all infrahubctl commands is automatically generated from the source code. The tasks.py file defines the docs-generate task, which uses typer-cli to produce MDX files for the documentation website.
Sources: tasks.py:65-92, dev/knowledge/doc-generation.md:1-20
Document Generation Workflow
Implementation Details
Initialization
All commands must use initialize_client() rather than instantiating InfrahubClient directly. This ensures that the CLI respects the shared configuration from infrahubctl.toml or environment variables.
Sources: dev/constitution.md:46-51, dev/specs/001-end-user-cli/research.md:47-50
Error Handling
The CLI wraps SDK exceptions to provide actionable feedback. For example, if a user queries an invalid kind, the CLI suggests similar kind names based on the available schema.
Sources: specs/001-end-user-cli/tasks.md:80-82, dev/specs/001-end-user-cli/spec.md:127-129
The CLI tools are registered in pyproject.toml as an entry point:
[project.scripts]
infrahubctl = "infrahub_sdk.ctl.cli:app"
Sources: pyproject.toml:35-36