# datadog/datadog-sync-cli architecture

> Architecture diagram of the GitHub repository datadog/datadog-sync-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datadog/datadog-sync-cli
- Repository: https://github.com/datadog/datadog-sync-cli

## Overview

datadog-sync-cli copies Datadog configuration resources between organizations, using persisted resource state as the handoff between import and sync. The main workflow is import from the source organization, review diffs, then apply to the destination; migrate combines import and sync. Reset, prune, schema discovery, metadata, completions, filtering, and machine-readable events are supporting product capabilities. The tree and excerpts establish the resource, client, storage, and worker layers; command-to-handler wiring is represented only where documented, since command implementations were not sampled.

Main entry points: [`datadog_sync/cli.py`](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/cli.py) (Command interface), [`datadog_sync/utils/resources_handler.py`](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/resources_handler.py) (Resource orchestration), [`datadog_sync/commands/_import.py`](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/_import.py) (Import), [`datadog_sync/commands/sync.py`](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/sync.py) (Sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_cli["Command interface<br/>[cli.py]"]
  node_import["Import<br/>[_import.py]"]
  node_sync["Sync<br/>[sync.py]"]
  node_migrate["Migrate<br/>[migrate.py]"]
  node_diffs["Diff preview<br/>[diffs.py]"]
  node_reset["Reset<br/>[reset.py]"]
  node_prune["Prune state<br/>[prune.py]"]
  node_metadata["Schema and metadata<br/>[metadata.py]"]
  node_completions["Shell completions<br/>[completions.py]"]
end

subgraph group_engine["Sync engine"]
  node_config["Configuration<br/>[configuration.py]"]
  node_handler["Resource orchestration"]
  node_workers["Async workers<br/>[workers.py]"]
  node_models["Resource models"]
  node_client["HTTP client<br/>[custom_client.py]"]
end

subgraph group_state["Resource state"]
  node_state["State handling<br/>[state.py]"]
  node_storage["Storage backends"]
  node_sourcefiles[("Source resource files")]
  node_destinationfiles[("Destination resource files")]
end

subgraph group_integrations["Datadog APIs"]
  node_sourceorg(("Source organization"))
  node_destinationorg(("Destination organization"))
end

node_user(("Operator"))
node_events["Structured events<br/>[cli_events.py]"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_import
node_cli -->|"dispatches"| node_sync
node_cli -->|"dispatches"| node_migrate
node_cli -->|"dispatches"| node_diffs
node_cli -->|"dispatches"| node_reset
node_cli -->|"dispatches"| node_prune
node_cli -->|"dispatches"| node_metadata
node_cli -->|"dispatches"| node_completions
node_import -->|"configures"| node_config
node_sync -->|"configures"| node_config
node_migrate -->|"runs"| node_import
node_migrate -->|"runs"| node_sync
node_import -->|"imports resources"| node_handler
node_sync -->|"applies resources"| node_handler
node_diffs -->|"compares state"| node_handler
node_reset -->|"deletes resources"| node_handler
node_prune -->|"deletes stale files"| node_storage
node_handler -->|"schedules work"| node_workers
node_handler -->|"dispatches actions"| node_models
node_models -->|"calls API"| node_client
node_client -->|"reads"| node_sourceorg
node_client -->|"reads and writes"| node_destinationorg
node_handler -->|"loads and compares"| node_state
node_state -->|"loads and saves"| node_storage
node_storage -->|"stores source"| node_sourcefiles
node_storage -->|"stores destination"| node_destinationfiles
node_import -->|"emits events"| node_events
node_sync -->|"emits events"| node_events

click node_cli "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/cli.py"
click node_import "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/_import.py"
click node_sync "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/sync.py"
click node_migrate "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/migrate.py"
click node_diffs "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/diffs.py"
click node_reset "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/reset.py"
click node_prune "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/prune.py"
click node_metadata "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/metadata.py"
click node_completions "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/completions.py"
click node_config "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/configuration.py"
click node_handler "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/resources_handler.py"
click node_workers "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/workers.py"
click node_models "https://github.com/datadog/datadog-sync-cli/tree/main/datadog_sync/model"
click node_client "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/custom_client.py"
click node_state "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/state.py"
click node_storage "https://github.com/datadog/datadog-sync-cli/tree/main/datadog_sync/utils/storage"
click node_events "https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/cli_events.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_import,node_sync,node_migrate,node_diffs,node_reset,node_prune,node_metadata,node_completions toneBlue
class node_config,node_handler,node_workers,node_models,node_client toneAmber
class node_state,node_storage,node_sourcefiles,node_destinationfiles toneMint
class node_sourceorg,node_destinationorg toneRose
class node_user toneIndigo
class node_events toneTeal
```

## Components

### CLI commands

- [Command interface](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/cli.py): `datadog_sync/cli.py`
- [Import](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/_import.py): `datadog_sync/commands/_import.py`
- [Sync](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/sync.py): `datadog_sync/commands/sync.py`
- [Migrate](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/migrate.py): `datadog_sync/commands/migrate.py`
- [Diff preview](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/diffs.py): `datadog_sync/commands/diffs.py`
- [Reset](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/reset.py): `datadog_sync/commands/reset.py`
- [Prune state](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/prune.py): `datadog_sync/commands/prune.py`
- [Schema and metadata](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/metadata.py): `datadog_sync/commands/metadata.py`
- [Shell completions](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/commands/completions.py): `datadog_sync/commands/completions.py`

### Sync engine

- [Configuration](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/configuration.py): `datadog_sync/utils/configuration.py`
- [Resource orchestration](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/resources_handler.py): `datadog_sync/utils/resources_handler.py`
- [Async workers](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/workers.py): `datadog_sync/utils/workers.py`
- [Resource models](https://github.com/datadog/datadog-sync-cli/tree/main/datadog_sync/model): `datadog_sync/model`
- [HTTP client](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/custom_client.py): `datadog_sync/utils/custom_client.py`

### Resource state

- [State handling](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/utils/state.py): `datadog_sync/utils/state.py`
- [Storage backends](https://github.com/datadog/datadog-sync-cli/tree/main/datadog_sync/utils/storage): `datadog_sync/utils/storage`
- **Source resource files**
- **Destination resource files**

### Datadog APIs

- **Source organization**
- **Destination organization**

### Other components

- **Operator**
- [Structured events](https://github.com/datadog/datadog-sync-cli/blob/main/datadog_sync/cli_events.py): `datadog_sync/cli_events.py`

## Connections

- Operator → Command interface: invokes
- Command interface → Import: dispatches
- Command interface → Sync: dispatches
- Command interface → Migrate: dispatches
- Command interface → Diff preview: dispatches
- Command interface → Reset: dispatches
- Command interface → Prune state: dispatches
- Command interface → Schema and metadata: dispatches
- Command interface → Shell completions: dispatches
- Import → Configuration: configures
- Sync → Configuration: configures
- Migrate → Import: runs
- Migrate → Sync: runs
- Import → Resource orchestration: imports resources
- Sync → Resource orchestration: applies resources
- Diff preview → Resource orchestration: compares state
- Reset → Resource orchestration: deletes resources
- Prune state → Storage backends: deletes stale files
- Resource orchestration → Async workers: schedules work
- Resource orchestration → Resource models: dispatches actions
- Resource models → HTTP client: calls API
- HTTP client → Source organization: reads
- HTTP client → Destination organization: reads and writes
- Resource orchestration → State handling: loads and compares
- State handling → Storage backends: loads and saves
- Storage backends → Source resource files: stores source
- Storage backends → Destination resource files: stores destination
- Import → Structured events: emits events
- Sync → Structured events: emits events