feat: add CRUD and schema discovery commands to infrahubctl

.vale/styles/spelling-exceptions.txt

@@ -133,6 +133,7 @@ validators
 Version Control
 Vitest
 VLANs
+yaml
 Yaml
 yamllint
 YouTube

docs/docs/infrahubctl/infrahubctl-create.mdx

@@ -0,0 +1,31 @@
+# `infrahubctl create`
+
+Create a new object in Infrahub.
+
+Provide field values with repeatable --set flags or supply a
+JSON/YAML object file via --file. The two modes are mutually exclusive.
+
+Examples:
+  infrahubctl create InfraDevice --set name=spine01 --set status=active
+  infrahubctl create InfraDevice --set name=spine01 --set location=DC1
+  infrahubctl create InfraDevice --file devices.yml
+
+**Usage**:
+
+```console
+$ infrahubctl create [OPTIONS] KIND
+```
+
+**Arguments**:
+
+* `KIND`: Infrahub schema kind to create  [required]
+
+**Options**:
+
+* `--set TEXT`: Field value in key=value format
+* `-f, --file PATH`: JSON or YAML file with object data
+* `-b, --branch TEXT`: Target branch
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

docs/docs/infrahubctl/infrahubctl-delete.mdx

@@ -0,0 +1,30 @@
+# `infrahubctl delete`
+
+Delete an Infrahub object.
+
+Fetches the object by KIND and IDENTIFIER, then deletes it.
+Unless --yes is provided, a confirmation prompt is shown first.
+
+Examples:
+  infrahubctl delete InfraDevice spine01
+  infrahubctl delete InfraDevice spine01 --yes
+
+**Usage**:
+
+```console
+$ infrahubctl delete [OPTIONS] KIND IDENTIFIER
+```
+
+**Arguments**:
+
+* `KIND`: Infrahub schema kind  [required]
+* `IDENTIFIER`: UUID, name, or HFID (use / for multi-part, for example: Cisco/NX-OS)  [required]
+
+**Options**:
+
+* `-y, --yes`: Skip confirmation prompt
+* `-b, --branch TEXT`: Target branch
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

docs/docs/infrahubctl/infrahubctl-get.mdx

@@ -0,0 +1,41 @@
+# `infrahubctl get`
+
+Query and display Infrahub objects.
+
+When IDENTIFIER is omitted the command lists all objects of the given
+KIND. When IDENTIFIER is provided it displays a single object in
+detail view. Empty columns are hidden by default (use --all-columns).
+
+Examples:
+  infrahubctl get InfraDevice
+  infrahubctl get InfraDevice spine01
+  infrahubctl get InfraDevice --filter name__value=spine01
+  infrahubctl get InfraDevice --output json
+  infrahubctl get InfraDevice --output yaml > backup.yml
+
+Exit codes: 0 = results found, 1 = error (including not found in detail
+mode), 80 = list query succeeded but returned zero objects.
+
+**Usage**:
+
+```console
+$ infrahubctl get [OPTIONS] KIND [IDENTIFIER]
+```
+
+**Arguments**:
+
+* `KIND`: Infrahub schema kind to query  [required]
+* `[IDENTIFIER]`: UUID, name, or HFID (use / for multi-part, for example: Cisco/NX-OS)
+
+**Options**:
+
+* `--filter TEXT`: Filter in attr__value=x format
+* `-o, --output [table|json|csv|yaml]`: Output format
+* `-b, --branch TEXT`: Target branch
+* `--limit INTEGER`: Maximum results
+* `--offset INTEGER`: Skip first N results
+* `--all-columns`: Show all columns including empty ones
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

docs/docs/infrahubctl/infrahubctl-schema.mdx

@@ -18,7 +18,9 @@ $ infrahubctl schema [OPTIONS] COMMAND [ARGS]...
 
 * `check`: Check if schema files are valid and what...
 * `export`: Export the schema from Infrahub as YAML...
+* `list`: List all available schema kinds.
 * `load`: Load one or multiple schema files into...
+* `show`: Show details for a specific schema kind.
 
 ## `infrahubctl schema check`
 
@@ -60,6 +62,30 @@ $ infrahubctl schema export [OPTIONS]
 * `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
 * `--help`: Show this message and exit.
 
+## `infrahubctl schema list`
+
+List all available schema kinds.
+
+Displays a table of all node schema entries. Use --filter to narrow
+results by a case-insensitive match on the kind name.
+
+Examples:
+  infrahubctl schema list
+  infrahubctl schema list --filter Device
+
+**Usage**:
+
+```console
+$ infrahubctl schema list [OPTIONS]
+```
+
+**Options**:
+
+* `--filter TEXT`: Filter kinds by name
+* `-b, --branch TEXT`: Target branch
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.
+
 ## `infrahubctl schema load`
 
 Load one or multiple schema files into Infrahub.
@@ -81,3 +107,29 @@ $ infrahubctl schema load [OPTIONS] SCHEMAS...
 * `--wait INTEGER`: Time in seconds to wait until the schema has converged across all workers  [default: 0]
 * `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
 * `--help`: Show this message and exit.
+
+## `infrahubctl schema show`
+
+Show details for a specific schema kind.
+
+Displays metadata, attributes, and relationships for the requested
+schema kind in a human-readable format.
+
+Examples:
+  infrahubctl schema show InfraDevice
+
+**Usage**:
+
+```console
+$ infrahubctl schema show [OPTIONS] KIND
+```
+
+**Arguments**:
+
+* `KIND`: Schema kind to display  [required]
+
+**Options**:
+
+* `-b, --branch TEXT`: Target branch
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.

docs/docs/infrahubctl/infrahubctl-update.mdx

@@ -0,0 +1,32 @@
+# `infrahubctl update`
+
+Update an existing object in Infrahub.
+
+Fetches the object by KIND and IDENTIFIER, applies the requested
+changes, and saves back to the server. Use --set or --file.
+
+Examples:
+  infrahubctl update InfraDevice spine01 --set status=active
+  infrahubctl update InfraDevice spine01 --set location=DC1
+  infrahubctl update InfraDevice spine01 --file updates.yml
+
+**Usage**:
+
+```console
+$ infrahubctl update [OPTIONS] KIND IDENTIFIER
+```
+
+**Arguments**:
+
+* `KIND`: Infrahub schema kind  [required]
+* `IDENTIFIER`: UUID, name, or HFID (use / for multi-part, for example: Cisco/NX-OS)  [required]
+
+**Options**:
+
+* `--set TEXT`: Field value in key=value format
+* `-f, --file PATH`: JSON or YAML file with update data
+* `-b, --branch TEXT`: Target branch
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

docs/docs_generation/pages/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -39,12 +40,22 @@ class MDXDocPage:
         mdx.to_mdx()
     """
 
+    _CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
     def __init__(self, page: DocPage, output_path: Path) -> None:
         self.page = page
         self.output_path = output_path
 
     def to_mdx(self) -> None:
         rendered = self.page.content()
+        rendered = self._sanitize(rendered)
         self.output_path.parent.mkdir(parents=True, exist_ok=True)
         self.output_path.write_text(rendered, encoding="utf-8")
         print(f"Docs saved to: {self.output_path}")
+
+    @classmethod
+    def _sanitize(cls, text: str) -> str:
+        """Normalize line endings, strip control characters and collapse blank lines."""
+        text = text.replace("\r\n", "\n")
+        text = cls._CONTROL_CHAR_RE.sub("", text)
+        return re.sub(r"\n{3,}", "\n\n", text)

infrahub_sdk/ctl/cli_commands.py

@@ -11,14 +11,14 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-import typer
-import ujson
-from rich.console import Console
-from rich.layout import Layout
-from rich.logging import RichHandler
-from rich.panel import Panel
-from rich.pretty import Pretty
-from rich.table import Table
+import typer  # pyright: ignore[reportMissingImports]
+import ujson  # pyright: ignore[reportMissingModuleSource]
+from rich.console import Console  # pyright: ignore[reportMissingImports]
+from rich.layout import Layout  # pyright: ignore[reportMissingImports]
+from rich.logging import RichHandler  # pyright: ignore[reportMissingImports]
+from rich.panel import Panel  # pyright: ignore[reportMissingImports]
+from rich.pretty import Pretty  # pyright: ignore[reportMissingImports]
+from rich.table import Table  # pyright: ignore[reportMissingImports]
 
 from .. import __version__ as sdk_version
 from ..async_typer import AsyncTyper
@@ -51,6 +51,10 @@
 from ..template.exceptions import JinjaTemplateError
 from ..utils import write_to_file
 from ..yaml import SchemaFile
+from .commands.create import create_command
+from .commands.delete import delete_command
+from .commands.get import get_command
+from .commands.update import update_command
 from .exporter import dump
 from .importer import load
 from .parameters import CONFIG_PARAM
@@ -71,6 +75,17 @@
 
 app.command(name="dump")(dump)
 app.command(name="load")(load)
+app.command(name="get")(get_command)
+app.command(name="create")(create_command)
+app.command(name="update")(update_command)
+app.command(name="delete")(delete_command)
+
+# Expose command functions under their command names for typer doc generation
+# (typer --func <name> looks up module-level names)
+get = get_command
+create = create_command
+update = update_command
+delete = delete_command
 
 console = Console()
 

infrahub_sdk/ctl/commands/__init__.py

@@ -0,0 +1,3 @@
+"""Command modules for the ``infrahub`` end-user CLI."""
+
+from __future__ import annotations

infrahub_sdk/ctl/commands/create.py

@@ -0,0 +1,89 @@
+"""Command implementation for ``infrahub create``.
+
+Creates a new object in Infrahub either from inline ``--set`` key=value
+arguments or from a JSON/YAML object file specified via ``--file``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from infrahub_sdk.ctl.client import initialize_client
+from infrahub_sdk.ctl.commands.utils import derive_identifier, prepare_relationship_data, resolve_node
+from infrahub_sdk.ctl.parameters import CONFIG_PARAM
+from infrahub_sdk.ctl.parsers import parse_set_args, validate_set_fields
+from infrahub_sdk.ctl.utils import catch_exception
+from infrahub_sdk.exceptions import NodeNotFoundError
+from infrahub_sdk.spec.object import ObjectFile
+
+console = Console()
+
+
+@catch_exception(console=console)
+async def create_command(
+    kind: str = typer.Argument(..., help="Infrahub schema kind to create"),
+    set_args: list[str] | None = typer.Option(None, "--set", help="Field value in key=value format"),
+    file: Path | None = typer.Option(None, "--file", "-f", help="JSON or YAML file with object data"),
+    branch: str | None = typer.Option(None, "--branch", "-b", help="Target branch"),
+    _: str = CONFIG_PARAM,
+) -> None:
+    """Create a new object in Infrahub.
+
+    Provide field values with repeatable --set flags or supply a
+    JSON/YAML object file via --file. The two modes are mutually exclusive.
+
+    \b
+    Examples:
+      infrahubctl create InfraDevice --set name=spine01 --set status=active
+      infrahubctl create InfraDevice --set name=spine01 --set location=DC1
+      infrahubctl create InfraDevice --file devices.yml
+    """
+    if set_args and file:
+        console.print("[red]Error: --set and --file are mutually exclusive.")
+        raise typer.Exit(code=1)
+    if not set_args and not file:
+        console.print("[red]Error: provide --set key=value or --file <path>.")
+        console.print("Example: infrahubctl create MyKind --set name=foo --set status=active")
+        raise typer.Exit(code=1)
+
+    client = initialize_client(branch=branch)
+
+    if file:
+        files = ObjectFile.load_from_disk(paths=[file])
+
+        # Validate all files before processing any to avoid partial application
+        for obj_file in files:
+            if obj_file.spec.kind != kind:
+                console.print(f"[red]Error: file kind '{obj_file.spec.kind}' does not match positional kind '{kind}'.")
+                raise typer.Exit(code=1)
+            await obj_file.validate_format(client=client, branch=branch)
+
+        for obj_file in files:
+            await obj_file.process(client=client, branch=branch)
+            object_count = len(obj_file.spec.data)
+            console.print(f"[green]Created {object_count} objects of kind {obj_file.spec.kind}")
+    else:
+        data = parse_set_args(set_args)  # type: ignore[arg-type]
+        schema = await client.schema.get(kind=kind, branch=branch)
+        validate_set_fields(data, schema.attribute_names, schema.relationship_names)
+        data = prepare_relationship_data(data, schema)
+
+        # Check if node already exists to distinguish create from upsert
+        existing = None
+        identifier_value = derive_identifier(data, schema)
+        if identifier_value is not None:
+            with contextlib.suppress(NodeNotFoundError):
+                existing = await resolve_node(client, kind, identifier_value, schema=schema, branch=branch)
+
+        node = await client.create(kind=kind, data=data, branch=branch)
+        await node.save(allow_upsert=True)
+        label = node.display_label or identifier_value or node.id
+
+        if existing:
+            console.print(f"[yellow]Updated {kind} '{label}' (id: {node.id}) — already existed")
+        else:
+            console.print(f"[green]Created {kind} '{label}' (id: {node.id})")