CLI Reference

Relevant source files

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

• infrahub_sync/cli.py
• AGENTS.md
• README.md
• dev/knowledge/sync-architecture.md
• dev/constitution.md
• tasks/docs.py

The infrahub-sync Command Line Interface (CLI) provides the primary entry point for managing data synchronization between infrastructure systems. It manages project discovery, difference calculation, code generation, and data application. The CLI adheres to a "Safe by Default" principle where non-mutating commands like list and diff require no confirmation, while the sync and apply commands perform live data modifications.

Sources: infrahub_sync/cli.py:53-58, dev/constitution.md:18-24

Command Execution Flow

The CLI interacts with the Potenda engine to orchestrate sync operations. It uses a structured workflow to ensure that changes are calculated and reviewed before application.

The diagram shows how the CLI processes different command types, branching between safe discovery and active synchronization logic. Sources: infrahub_sync/cli.py:78-316, dev/knowledge/sync-architecture.md:30-43

Global Options

Global options apply to the base infrahub-sync command and control output behavior.

Option	Type	Default	Description
--verbosity	Enum	default	Log levels: quiet (WARNING), default (INFO), verbose (DEBUG).
--verbose / -v	Flag	False	Shorthand for --verbosity verbose.
--quiet / -q	Flag	False	Shorthand for --verbosity quiet.

Sources: infrahub_sync/cli.py:38-51

Core Commands

list

The list command searches for and displays all available synchronization projects. It lists the project name, the source adapter, the destination adapter, and the configuration directory.

Sources: infrahub_sync/cli.py:78-83

diff

The diff command calculates the differences between the source and destination systems without applying changes. It populates a local cache with the calculated plan.

• Logic: It initializes a Potenda instance, loads data from both adapters (concurrently by default), and computes a diff object.
• Caching: It generates a unique run_id and saves the result as a JSON run file and a Parquet plan.

Sources: infrahub_sync/cli.py:86-146, dev/knowledge/sync-architecture.md:46-55

generate

The generate command produces the Python model files required for a sync based on the YAML configuration and the destination system's schema.

• Validation: It connects to the Infrahub instance to verify that all models defined in the configuration exist in the server schema.
• Output: It renders Jinja2 templates into Python classes that represent the DiffSync models.

Sources: infrahub_sync/cli.py:277-316, dev/knowledge/sync-architecture.md:46-55

sync

The sync command reconciles the destination system to match the source.

• Safety: It performs a diff first and displays the changes unless suppressed.
• Guardrails: It includes a row-count drop guardrail to prevent massive accidental deletions unless --allow-rowcount-drop is specified.
• Modes: Supports serial execution or parallel execution via --parallel (if order is not manually set in the config).

Sources: infrahub_sync/cli.py:149-231, dev/constitution.md:27-35

Command Arguments Reference

Command	Option	Description
diff, sync, gen	--name	The name of the sync project defined in YAML.
diff, sync, gen	--config-file	Direct path to a sync configuration YAML.
diff, sync, gen	--directory	Base directory to search for configurations.
diff, sync	--branch	The Infrahub branch to use for the operation.
diff, sync	--full-extract	Whether to re-extract all resources (default) or use cursors.
sync	--parallel	Sync tier-by-tier using an auto-computed dependency graph.
sync	--allow-rowcount-drop	Bypasses the safety check for large resource deletions.

Sources: infrahub_sync/cli.py:86-104, infrahub_sync/cli.py:149-183

Cache Management

The CLI utilizes a local cache directory to store run history and diff plans. The apply command specifically requires a run_id from a previous diff operation.

This diagram illustrates the relationship between the cached diff plans and the eventual application of data to the destination. Sources: infrahub_sync/cli.py:137-146, infrahub_sync/cli.py:234-274

Error Handling

The CLI uses specific exception handling to maintain system safety:

1. Pipeline Lock: Commands that mutate or extensively read data utilize a pipeline_lock based on the sync project name to prevent concurrent execution collisions.
2. Schema Validation: The generate command fails if the YAML configuration references models missing from the Infrahub schema.
3. Authentication: The CLI explicitly handles ServerNotResponsiveError and provides user-facing error messages via print_error_and_abort.

Sources: infrahub_sync/cli.py:73-75, infrahub_sync/cli.py:112, infrahub_sync/cli.py:308-312

The CLI serves as the orchestration layer for the infrahub-sync ecosystem, ensuring that data synchronization is predictable, idempotent, and safe through mandatory diffing and robust caching mechanisms.

Sources: README.md:91-96, dev/constitution.md:12-16