Skip to main content

Run a sync

The Infrahub Sync CLI is a synchronous client of the Sync API. The service owns configuration registration, run admission, durable plans, and worker execution. The CLI does not load adapters or execute a sync locally.

Connect to the Sync API​

Set the service URL and bearer token in the environment. You can override the URL with the root --api-url option. The token has no command-line option, so it does not enter shell history or process arguments.

export INFRAHUB_SYNC_API_URL=https://sync.example.com
export INFRAHUB_SYNC_API_TOKEN=<token>

Before its first protected request, the client checks the service's public compatibility resource. An incompatible service is refused before the bearer token is sent.

Register a configuration package​

Registration reads one JSON or YAML package and sends its object to the service. The file is preparation input only; later runs use the immutable (config_id, registry_version) returned by the registry.

infrahub-sync configs register path/to/package.yml \
  --reason "register inventory import"

infrahub-sync configs version <config-id> path/to/package.yml \
  --reason "update inventory mapping"

Each mutation accepts --idempotency-key. If you omit it, the CLI generates and prints a key before sending the request. Keep that key: if the connection fails after the service accepted the mutation, retry with the same key instead of creating another mutation.

Inspect and validate registered content with:

infrahub-sync configs list
infrahub-sync configs show <config-id>
infrahub-sync configs versions <config-id>
infrahub-sync configs show <config-id> --version <version>
infrahub-sync configs validate <config-id> <version>

Validation preserves the service's finding order and prints its offset, limit, total_findings, and next_offset fields. Use --offset and --limit to request another finding page.

Create and review a plan​

diff is the familiar command name for creating a service plan run. It sends only the registered configuration tuple, optional destination branch, reason, confirmation state, and idempotency key.

infrahub-sync diff \
  --config-id <config-id> \
  --version <version> \
  --reason "review scheduled changes"

The default --wait follows the accepted product run for at most 30 minutes, polling every 2 seconds. Override those positive finite durations with --wait-timeout and --poll-interval. When the plan succeeds, diff prints the saved plan summary and its service-issued checksum.

Use --no-wait to return immediately after admission. The output includes the service run ID and idempotency key. Review that run later through the same saved resource:

infrahub-sync runs plan <run-id>
infrahub-sync runs plan <run-id> --detail
infrahub-sync runs plan <run-id> --detail --kind <destination-kind>

The review prints checksum_source: Sync API saved plan. Detailed output includes every operation selected by the optional kind filter. Delete operations carry a (not executed) marker, and the summary states how many recorded deletes apply will skip. A kind that matches no operation is an input error instead of an empty successful review.

Apply a reviewed plan​

Copy the checksum from runs plan and bind the apply to it:

infrahub-sync apply <run-id> \
  --expected-checksum <checksum> \
  --reason "apply reviewed plan"

The service validates the expected checksum. The CLI never reads, reconstructs, or hashes a local plan. --branch, --idempotency-key, --wait/--no-wait, --wait-timeout, and --poll-interval have the same meanings as on run admission.

Run a confirmed sync​

sync creates a confirmed composed synchronization through the shipped run route:

infrahub-sync sync \
  --config-id <config-id> \
  --version <version> \
  --reason "scheduled synchronization"

It uses the same idempotency and bounded-wait behavior as diff. The service and worker own extraction, guardrails, ordering, and destination calls.

Wait outcomes​

  • A successful selected execution returns the latest product record.
  • A failed, cancelled, abandoned, or ambiguous selected execution exits nonzero and keeps the service run ID and terminal fields.
  • A failed waited apply also reports recorded failure evidence as apply failed: <ErrorClass> when the result is available. PlanSchemaChangedError adds a hint to create and review a new plan before applying again.
  • A timeout exits nonzero with the run ID and last product phase, outcome, and execution state. It does not cancel the remote run.
  • Ctrl-C stops local polling, prints the last observed product record, exits 130, and does not send a cancellation request.

The wait follows the execution accepted by that mutation. It does not infer completion from Prefect logs or from an earlier execution on the same product run.