Skip to main content

​
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
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
  3. Pulls each resource to disk as a YAML file under kodexa-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 2 task-templates, 1 assistant)
Writing manifest.yaml
Pulling 10 resources...
  ✓ data-definition/invoice-taxonomy
  ✓ data-definition/contract-taxonomy
  ✓ 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-taxonomy
    - contract-taxonomy
    - 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-taxonomy.yaml
Find the description field and update it: 
name: Invoice Taxonomy
description: "Updated taxonomy 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-taxonomy
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-taxonomy
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 taxonomy 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-taxonomy
    - contract-taxonomy
    # - claim-schema          # 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