> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Sync

> Set up your first GitOps workflow for Kodexa metadata in 10 minutes using kdx sync, sync-config.yaml, and manifest files for repeatable deployments.

## Prerequisites

Before you begin, ensure you have:

* KDX CLI installed ([installation guide](/guides/kdx-cli/installation))
* An API key for your Kodexa environment ([authentication guide](/guides/kdx-cli/authentication))
* Access to a Kodexa organization with existing resources (data definitions, knowledge sets, etc.)

<Note>
  You can generate an API key from your Kodexa platform account settings. You will need the organization slug for your target organization -- you can find this in the URL when viewing your organization in the Kodexa UI.
</Note>

## Step 1: Create Your Sync Directory

Create a new directory for your sync configuration. This will become the root of your GitOps repository.

```bash theme={null}
mkdir -p my-kodexa-config
cd my-kodexa-config
```

Create a `sync-config.yaml` file that defines your environment and target:

```yaml sync-config.yaml theme={null}
schema_version: "2.0"

environments:
  dev:
    url: https://your-instance.kodexa-enterprise.com
    api_key_env: KODEXA_DEV_API_KEY

targets:
  my-org:
    organization: your-org-slug
    manifests:
      - manifest.yaml
```

Replace `your-instance.kodexa-enterprise.com` with your actual Kodexa platform URL, and `your-org-slug` with your organization's slug.

<Tip>
  If you already have a [kdx CLI profile](/guides/kdx-cli/profiles-configuration) configured, you can use `profile: my-profile` instead of `api_key_env` in the environment definition.
</Tip>

## Step 2: Discover Resources

The `--discover` flag queries your Kodexa environment, auto-generates a `manifest.yaml`, and pulls all resources to disk as YAML files.

First, set your API key as an environment variable:

```bash theme={null}
export KODEXA_DEV_API_KEY="your-api-key-here"
```

Then run the discover pull:

```bash theme={null}
kdx sync pull --target my-org --env dev --discover --discover-dir resources
```

The `--discover-dir resources` flag tells the CLI to store resource files under a `resources/` subdirectory and sets `metadata_dir: resources` in the generated manifest. You can omit it to store files next to the manifest.

This command does three things:

1. **Queries the API** for all resources in your organization
2. **Generates `manifest.yaml`** listing every discovered resource by slug (with `metadata_dir: resources`)
3. **Pulls each resource** to disk as a YAML file under `resources/`

You should see output similar to:

```text theme={null}
Discovering resources for organization your-org-slug...
  Found 3 data-definitions
  Found 2 knowledge-sets
  Found 1 prompt-template
  Found 1 project (with task templates, task statuses, triggers, and project links)
Writing manifest.yaml
Pulling 10 resources...
  ✓ data-definition/invoice-data
  ✓ data-definition/contract-data
  ✓ knowledge-set/extraction-rules
  ...
Pull complete: 10 resources written
```

## Step 3: Review What Was Pulled

Take a look at the files that were generated:

```bash theme={null}
ls -la
```

You should see:

```text theme={null}
sync-config.yaml       # Your configuration (created in Step 1)
manifest.yaml          # Auto-generated resource manifest
kodexa-resources/      # Directory containing all resource YAML files
.sync-state/           # Conflict detection state
```

Inspect the generated manifest to see which resources were discovered:

```bash theme={null}
cat manifest.yaml
```

```yaml theme={null}
manifest_version: "1.0"
metadata_dir: kodexa-resources

resources:
  data-definitions:
    - invoice-data
    - contract-data
    - claim-schema
  knowledge-sets:
    - extraction-rules
    - validation-rules
  prompt-templates:
    - invoice-analysis
  projects:
    - finance-automation
```

Browse the pulled resource files:

```bash theme={null}
ls kodexa-resources/data-definitions/
ls kodexa-resources/knowledge-sets/
```

Each file is a complete YAML representation of the resource as it exists on the server.

## Step 4: Make a Local Change

Open any resource YAML file and make a change. For example, update the description of a data definition:

```bash theme={null}
# Open a resource file in your editor
vim kodexa-resources/data-definitions/invoice-data.yaml
```

Find the `description` field and update it:

```yaml theme={null}
name: Invoice Data
description: "Updated data definition for invoice document processing with new field mappings"
# ... rest of the file
```

Save the file. The change exists only on disk -- it has not been pushed to the server yet.

## Step 5: Push Changes

Always preview your changes with `--dry-run` before pushing:

```bash theme={null}
kdx sync push --target my-org --env dev --dry-run
```

The dry run shows what would be updated without making any changes:

```text theme={null}
DRY RUN — no changes will be applied
  Would update data-definition/invoice-data
Push dry-run complete: 1 resource would be updated
```

When you are satisfied with the preview, push for real:

```bash theme={null}
kdx sync push --target my-org --env dev
```

```text theme={null}
Pushing to dev (https://your-instance.kodexa-enterprise.com)...
  ✓ Updated data-definition/invoice-data
Push complete: 1 resource updated
```

## Step 6: Set Up Version Control

Initialize a git repository to track your sync configuration. This enables team collaboration and provides a full audit trail of every change.

```bash theme={null}
git init
git add sync-config.yaml manifest.yaml kodexa-resources/ .sync-state/
git commit -m "Initial sync from dev"
```

<Warning>
  Always commit the `.sync-state/` directory. It contains `changeSequence` values that power [conflict detection](/guides/kdx-cli/sync/conflict-detection) -- without these, the CLI cannot detect when someone else has modified a resource on the server since your last pull.
</Warning>

From here, your typical workflow becomes:

```bash theme={null}
# Pull latest from the server
kdx sync pull --target my-org --env dev

# Review changes
git diff

# Commit the latest state
git add .
git commit -m "Sync from dev: $(date +%Y-%m-%d)"

# Make local edits, then push
kdx sync push --target my-org --env dev
git add .
git commit -m "Update invoice data definition description"
```

## Step 7: Customize Your Manifest

The auto-generated manifest includes every resource that was discovered. You can edit `manifest.yaml` to include only the resources you want to manage:

```yaml manifest.yaml theme={null}
manifest_version: "1.0"
metadata_dir: kodexa-resources

resources:
  data-definitions:
    - invoice-data
    - contract-data
    # - claim-data            # Excluded — managed by another team

  knowledge-sets:
    - extraction-rules
    # - validation-rules      # Excluded — still in development
```

Commented-out resources will not be pulled or pushed. If you run `--discover` again later, it will add newly created resources but will not re-add resources you have removed from the manifest.

<Tip>
  Split resources across multiple manifest files for larger organizations. A target can reference several manifests, and the same manifest can be shared across targets. See [Manifests & Resource Types](/guides/kdx-cli/sync/manifests) for details.
</Tip>

## What's Next

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/guides/kdx-cli/sync/configuration">
    Set up multiple environments, targets, and branch-based automation
  </Card>

  <Card title="Manifests & Resource Types" icon="list" href="/guides/kdx-cli/sync/manifests">
    Define exactly which resources to sync and how they are organized
  </Card>

  <Card title="Conflict Detection" icon="code-compare" href="/guides/kdx-cli/sync/conflict-detection">
    Understand how changeSequence prevents accidental overwrites
  </Card>

  <Card title="CI/CD Integration" icon="github" href="/guides/kdx-cli/sync/ci-cd">
    Automate sync with GitHub Actions for continuous deployment
  </Card>
</CardGroup>