Getting Started with Sync

Prerequisites

Before you begin, ensure you have:

KDX CLI installed (installation guide)
An API key for your Kodexa environment (authentication guide)
Access to a Kodexa organization with existing resources (data definitions, knowledge sets, etc.)

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.

Step 1: Create Your Sync Directory

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

mkdir -p my-kodexa-config
cd my-kodexa-config

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

sync-config.yaml

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.

If you already have a kdx CLI profile configured, you can use profile: my-profile instead of api_key_env in the environment definition.

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:

export KODEXA_DEV_API_KEY="your-api-key-here"

Then run the discover pull:

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:

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

You should see output similar to:

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:

ls -la

You should see:

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:

cat manifest.yaml

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:

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:

# Open a resource file in your editor
vim kodexa-resources/data-definitions/invoice-data.yaml

Find the description field and update it:

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:

kdx sync push --target my-org --env dev --dry-run

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

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:

kdx sync push --target my-org --env dev

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.

git init
git add sync-config.yaml manifest.yaml kodexa-resources/ .sync-state/
git commit -m "Initial sync from dev"

Always commit the .sync-state/ directory. It contains changeSequence values that power conflict detection — without these, the CLI cannot detect when someone else has modified a resource on the server since your last pull.

From here, your typical workflow becomes:

# 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:

manifest.yaml

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.

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 for details.

What’s Next

Configuration

Set up multiple environments, targets, and branch-based automation

Manifests & Resource Types

Define exactly which resources to sync and how they are organized

Conflict Detection

Understand how changeSequence prevents accidental overwrites

CI/CD Integration

Automate sync with GitHub Actions for continuous deployment

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Prerequisites

Step 1: Create Your Sync Directory

Step 2: Discover Resources

Step 3: Review What Was Pulled

Step 4: Make a Local Change

Step 5: Push Changes

Step 6: Set Up Version Control

Step 7: Customize Your Manifest

What’s Next

Configuration

Manifests & Resource Types

Conflict Detection

CI/CD Integration

​Prerequisites

​Step 1: Create Your Sync Directory

​Step 2: Discover Resources

​Step 3: Review What Was Pulled

​Step 4: Make a Local Change

​Step 5: Push Changes

​Step 6: Set Up Version Control

​Step 7: Customize Your Manifest

​What’s Next

Configuration

Manifests & Resource Types

Conflict Detection

CI/CD Integration

Prerequisites

Step 1: Create Your Sync Directory

Step 2: Discover Resources

Step 3: Review What Was Pulled

Step 4: Make a Local Change

Step 5: Push Changes

Step 6: Set Up Version Control

Step 7: Customize Your Manifest

What’s Next