v1.22.0

1.22.0 - 2026-06-23

Added

• Added query_name parameter to all(), filters(), count() and get() methods in InfrahubClient and InfrahubClientSync to be used as meaningful GraphQL operation name for observability (#923)
• Add infrahubctl graphql query-report to analyze a GraphQL query and report whether it targets unique nodes, which controls whether Infrahub limits artifact regeneration to changed nodes or regenerates all artifacts on any relevant node change. Supports --online to fetch the query from the server by name.
• Added OrderByEntry and an Order.by field so query results can be ordered by attributes, related-node attributes, or node metadata, e.g. Order(by=[OrderByEntry(field="name__value", direction=OrderDirection.DESC)]). The Order.node_metadata field is deprecated; use by with the node_metadata__created_at / node_metadata__updated_at fields instead.
• Added graph traversal support for Infrahub 1.10: InfrahubClient.traverse_paths() (shortest path(s) between two nodes), InfrahubClient.reachable_nodes() (nodes of given kinds reachable from a source), and InfrahubClient.path_exists() (boolean convenience for checks) — all with sync equivalents. Source and destination accept either a node id or an InfrahubNode; kind filters accept kind strings or protocol classes; each PathNode in the result exposes .fetch() to resolve the full node (store-backed). Calling these against a pre-1.10 server raises a clear VersionNotSupportedError.

Fixed

• Calling .save(allow_upsert=True) on a node whose human-friendly identifier contains a CoreNumberPool-sourced attribute now raises a clear ValidationError instead of crashing with an opaque backend error. (#339)

• RelatedNode, RelatedNodeSync, RelationshipManager and RelationshipManagerSync are now generic over their peer type, and infrahubctl protocols parameterises generated relationships accordingly (e.g. device: RelatedNode[NetworkDevice], interfaces: RelationshipManager[NetworkInterface]).

  Traversing a relationship via .peer, .peers or indexing now preserves the peer's type instead of collapsing to the dynamic InfrahubNode, so chains such as device.rack.peer.name.value type-check under mypy/ty without casts. Existing un-parameterised RelatedNode / RelationshipManager usage is unaffected — the peer type defaults to InfrahubNode / InfrahubNodeSync, preserving current behaviour. (#1063) (#1063)

• Cardinality-one relationships in generated protocols are now typed with a RelationshipAttribute[...] descriptor. It still reads back as a typed RelatedNode[Peer] (so .peer keeps the peer type), but it accepts assignment of an id string, an HFID, a peer node, or None — mirroring the runtime InfrahubNode.__setattr__, which wraps the assigned value in a RelatedNode.

  Previously relationships were typed read-only as RelatedNode, so the documented way of setting a relationship (node.rel = "<id>" or node.rel = peer_node) failed under mypy/ty with an assignment error. The descriptor only appears in generated protocols and is never instantiated at runtime.

  Because the new typing lives in the generated protocols, existing projects must regenerate them with infrahubctl protocols to pick up the change — it does not take effect for already-generated protocol files. (#1064) (#1064)

• Calling .save(allow_upsert=True) on a node hydrated by from_graphql no longer silently clears optional one-cardinality relationships that the GraphQL response didn't fetch. Explicitly assigning node.rel = None still clears the relationship. (#1080)

• Send the GraphQL operation name as operationName in the request payload so tracing and observability tools can identify each query.

v1.21.1

Changed

• infrahubctl marketplace get --collection now downloads each member schema individually into a <output_dir>/<collection name>/<schema name>.yml layout (for example schemas/base-schemas/dcim.yml), instead of dumping version-suffixed files flat into the output directory. Filenames no longer carry the version, matching single-schema downloads, so re-downloading a collection overwrites cleanly rather than accumulating stale versions. If two members share a schema name across namespaces, those members are written to <output_dir>/<collection name>/<namespace>/<schema name>.yml instead of overwriting each other. (#1057)

Fixed

• Fix infrahubctl printing a spurious Error: 1 and Python traceback after the human-readable error message when a command exits with typer.Exit. The CLI now exits cleanly with only the intended error output. (#1047)****

v1.21.0

1.21.0 - 2026-05-29

Added

• Add infrahubctl marketplace get for fetching schemas and collections from the Infrahub Marketplace. Auto-detects schemas vs collections by namespace/name, supports --version for pinning, --collection to force the collection path, --stdout to stream content for piping (status messages on stderr), and --marketplace-url / INFRAHUB_MARKETPLACE_URL to point at staging or local instances. (#952)

Changed

• Change default value of sync_with_git parameter in branch.create() from True to False to match UI behavior. (#224)

Fixed

• Improve error message when a single node is passed to a cardinality-many relationship. (#174)

v1.20.1

1.20.1 - 2026-05-20

Added

• Added SHA-1 idempotency primitives for CoreFileObject nodes:

  • InfrahubNode.matches_local_checksum(source) / sync variant — compare a local bytes | Path | BinaryIO source against the node's server-stored checksum without invoking a transfer.
  • InfrahubNode.upload_if_changed(source, name=None) / sync variant — stage + save only when the local source differs from the server, returning an UploadResult(was_uploaded, checksum) dataclass.
  • download_file(..., skip_if_unchanged=True) — short-circuit the download when dest already exists on disk with a matching SHA-1. Returns 0 bytes written when skipped.

  A shared sha1_of_source helper (streaming, 64 KiB chunks) centralises the hashing convention in infrahub_sdk.file_handler.

Fixed

• Skip mandatory field validation during object loading when object_profile is specified. (#908)
• Render schema rejections originating in an extensions: block as a readable one-line message in infrahubctl schema load, instead of crashing with ValueError: invalid literal for int(). (#1007)
• Add MERGING branch status so that a merging branch can still be correctly retrieved. (#1037)

v1.20.0

1.20.0 - 2026-04-24

Removed

• Removed the deprecated raise_for_error argument from execute_graphql, query_gql_query, get_diff_summary, allocate_next_ip_address, and allocate_next_ip_prefix client methods. HTTP errors are now always raised via resp.raise_for_status().

Added

• Add infrahubctl schema export command to export schemas from Infrahub. (#151)
• Add artifact_content, file_object_content, from_json, and from_yaml Jinja2 filters for artifact content composition in templates.

Changed

• Replace FilterDefinition.trusted: bool with flag-based ExecutionContext model (CORE, WORKER, LOCAL) for context-aware template validation. validate() now accepts an optional context parameter. Backward compatible.

Fixed

• Allow direct assignment of authentication method to the configuration to override settings from environment variables. (#654)
• Corrected protocol typing for IPHost.value IPAddress -> IPInterface (#891)
• Generate protocols so that optional attributes with a default value are rendered as required (not nullable). (#894)
• Fixed ObjectStore.get() and ObjectStore.upload() silently swallowing non-2xx HTTP errors instead of raising them. (#958)
• Skip mandatory field validation during object loading when object_template is specified.

v1.19.0

Added

• Added support for FileObject nodes with file upload and download capabilities. New methods upload_from_path(path) and upload_from_bytes(content, name) allow setting file content before saving, while download_file(dest) enables downloading files to memory or streaming to disk for large files. (#ihs193)
• Python SDK API documentation is now generated directly from the docstrings of the classes, functions, and methods contained in the code. (#201)
• Added a 'py.typed' file to the project. This is to enable type checking when the Infrahub SDK is imported from other projects. The addition of this file could cause new typing issues in external projects until all typing issues have been resolved. Adding it to the project now to better highlight remaining issues.

Changed

• Updated branch report command to use node metadata for proposed change creator information instead of the deprecated relationship-based approach. Requires Infrahub 1.7 or above.

Fixed

• Allow SDK tracking feature to continue after encountering delete errors due to impacted nodes having already been deleted by cascade delete. (#265)
• Fixed Python SDK query generation regarding from_pool generated attribute value (#497)

Full changelog

• Merge stable into develop by @infrahub-github-bot-app[bot] in #741
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #743
• Re-implement casting of HFIDs to a list if the rel peer schema has hf… by @FragmentedPacket in #746
• IHS-183: Fix typing errors for protocols by @solababs in #749
• Fix test annotations by @ogenstad in #751
• Add annotations to unit tests by @ogenstad in #750
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #752
• Fix ANN001 violations by @ogenstad in #753
• Merge stable into develop by @infrahub-github-bot-app[bot] in #754
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #755
• Avoid nested chained if statements by @ogenstad in #757
• Revert "IHS-183: Fix typing errors for protocols" by @solababs in #760
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #762
• Combine if statements by @ogenstad in #758
• Typing corrections by @ogenstad in #759
• Add CODEOWNERS by @ogenstad in #767
• Fix extracting value from dictionary without calling .items() by @ogenstad in #764
• Suppress try/except/pass by @ogenstad in #768
• Favor .extend instead of chaining .append by @ogenstad in #769
• Merge stable into develop by @infrahub-github-bot-app[bot] in #761
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #770
• Replace ternary if expression with or operator by @ogenstad in #772
• Prefer variables in lowercase by @ogenstad in #771
• Simplify for-loop with any() by @ogenstad in #777
• Prevent cascade delete from causing SDK tracking delete to fail by @ogenstad in #776
• Merge stable into develop by @infrahub-github-bot-app[bot] in #775
• Use a list comprehension to create a transformed list by @ogenstad in #774
• Add missing init.py files by @ogenstad in #778
• Fix ruff Jinja2 violations and move the remaining warning by @ogenstad in #781
• Add hash method to object that already has eq by @ogenstad in #780
• Move rules for too many branches by @ogenstad in #779
• Update packages: urllib3, filelock & virtualenv by @ogenstad in #783
• Fix flake8 raise linting violations by @ogenstad in #784
• Split apart pytest rule violations by @ogenstad in #785
• Avoid shadowing builtin list by @ogenstad in #786
• Merge stable into develop by @infrahub-github-bot-app[bot] in #782
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #787
• Add task to generate JSON schema for .infrahub.yml files by @ogenstad in #788
• add libstdc++ to flake.nix to support Python dependencies that depend on compiled libraries by @wvandeun in #790
• Upgrade infrahub-testcontainers to 1.7 by @gmazoyer in #793
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #796
• Upgrade ty by @ogenstad in #797
• add str method to JinjaTemplateError by @ajtmccarty in #795
• Merge stable into develop by @infrahub-github-bot-app[bot] in #791
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #800
• Update ruff==0.15.0 by @ogenstad in #799
• Raise SDK specific Jinja errors on syntax error by @ogenstad in #798
• IHS-193 Add support for file upload/download for CoreFileObject by @gmazoyer in #792
• fix(dependabot): update infrahub-testcontainers by @fatih-acar in #801
• Fix infrahubctl proposed change table generation by @gmazoyer in #805
• IFC-2184: Add MERGED to branch status by @solababs in #794
• Bump infrahub-testcontainers from 1.5.1 to 1.7.4 by @dependabot[bot] in #804
• migrate from pre-commit to prek by @solababs in #789
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #808
• Merge stable into develop with resolved conflicts by @ogenstad in #809
• Add integration tests for file objects by @gmazoyer in #802
• Merge 'develop' into 'infrahub-develop' with resolved conflicts by @ogenstad in #813
• Add pull request template by @ogenstad in #812
• Add invoke command specifically for code linting by @ogenstad in #815
• Use ternary operator instead of if-else-block by @ogenstad in #814
• Merge stable into develop by @infrahub-github-bot-app[bot] in #816
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #817
• Linting: Incorrect import of pytest; use import pytest instead by @ogenstad in #824
• Fix dulwich checkout_branch deprecation warning in testing utilities by @Copilot in #819
• Add Spec Kit by @ogenstad in #827
• Merge stable into develop by @infrahub-github-bot-app[bot] in #825
• Fix pytest plugin for integration tests and empty YAML files by @FragmentedPacket in #744
• Avoid + operator to concatenate collections by @ogenstad in #826
• Break apart ty violations into smaller components by @ogenstad in #828
• Merge develop into infrahub-develop by @infrahub-github-bot-app[bot] in #830
• Add py.typed by @ogenstad in https://github...

v1.19.0 (Release Candidate 0)

Added

• Added support for FileObject nodes with file upload and download capabilities. New methods upload_from_path(path) and upload_from_bytes(content, name) allow setting file content before saving, while download_file(dest) enables downloading files to memory or streaming to disk for large files. (#ihs193)
• Python SDK API documentation is now generated directly from the docstrings of the classes, functions, and methods contained in the code. (#201)
• Added a 'py.typed' file to the project. This is to enable type checking when the Infrahub SDK is imported from other projects. The addition of this file could cause new typing issues in external projects until all typing issues have been resolved. Adding it to the project now to better highlight remaining issues.

Changed

• Updated branch report command to use node metadata for proposed change creator information instead of the deprecated relationship-based approach. Requires Infrahub 1.7 or above.

Fixed

• Allow SDK tracking feature to continue after encountering delete errors due to impacted nodes having already been deleted by cascade delete. (#265)
• Fixed Python SDK query generation regarding from_pool generated attribute value (#497)

Version 1.19.0 (beta 0)

Added

• Added support for FileObject nodes with file upload and download capabilities. New methods upload_from_path(path) and upload_from_bytes(content, name) allow setting file content before saving, while download_file(dest) enables downloading files to memory or streaming to disk for large files. (#ihs193)
• Added a 'py.typed' file to the project. This is to enable type checking when the Infrahub SDK is imported from other projects. The addition of this file could cause new typing issues in external projects until all typing issues have been resolved. Adding it to the project now to better highlight remaining issues.

Changed

• Updated branch report command to use node metadata for proposed change creator information instead of the deprecated relationship-based approach. Requires Infrahub 1.7 or above.

Fixed

• Allow SDK tracking feature to continue after encountering delete errors due to impacted nodes having already been deleted by cascade delete. (#265)

v1.18.1

1.18.1 - 2026-01-08

Fixed

• Reverted #723 (Fix code for HFID casting of strings that aren't UUIDs)

Version 1.18.0

Added

• Add ability to query for metadata on nodes to include information such as creation and update timestamps, creator and last user to update an object.
• Added ability to order nodes by metadata created_at or updated_at fields

Removed

• The previously deprecated 'background_execution' parameter under client.branch.create() was removed.

Fixed

• Rewrite and re-enable integration tests (#187)
• Fixed SDK including explicit null values for uninitialized optional relationships when creating nodes with object templates, which prevented the backend from applying template defaults. (#630)

Housekeeping

• Fixed Python 3.14 compatibility warnings. Testing now requires pytest>=9.

Full changelog

• IHS-173 Detect if a relationship is set from a profile by @gmazoyer in #686
• Bump astral-sh/setup-uv from 4 to 7 by @dependabot[bot] in #681
• Bump actions/checkout from 5 to 6 by @dependabot[bot] in #682
• Bump DavidAnson/markdownlint-cli2-action from 21 to 22 by @dependabot[bot] in #695
• Bump actions/cache from 4 to 5 by @dependabot[bot] in #694
• fix: python 3.14 deprecation warnings by @fatih-acar in #692
• Remove deprecated 'background_execution' param from client.branch.create() by @ogenstad in #696
• fix(analyzer): allowing passing a parsed query by @fatih-acar in #701
• Add ty as a type checker by @ogenstad in #702
• Add ability to query for node metadata by @ogenstad in #700
• Upgrade ty and cleanup rules by @ogenstad in #706
• Fix invalid return types by @ogenstad in #705
• Fix optional relationships preventing object template defaults from applying by @Copilot in #634
• Fixes for test annotations and split up rules by @ogenstad in #707
• Add annotations for clients and client_type by @ogenstad in #708
• Fix issue #713 and #712 by @BaptisteGi in #714
• Fix annotations on CTL tests by @ogenstad in #718
• Upgrade ruff=0.14.10 and fix new violation by @ogenstad in #724
• Use pathlib instead of os for Path operations by @ogenstad in #722
• Fix unsupported operator on MainSchemaTypes by @ogenstad in #721
• Upgrade ty=0.0.8 by @ogenstad in #723
• Fix test annotations on unit tests by @ogenstad in #720
• Convert and enable integration tests by @gmazoyer in #730
• Add ability to order results by metadata created_at or updated_at by @ogenstad in #698
• Fix code for HFID casting of strings that aren't UUIDs by @FragmentedPacket in #732
• Add docs for metadata and ordering by @minitriga in #735

Full Changelog: v1.17.0...v1.18.0