Skip to main content

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.

Claude Code edits files. KDX sync moves those files between Git and Kodexa. This page shows the operational loop for taking Claude Code-authored metadata through validation, review, and deployment.

​
Pull Before You Edit

Start every session by pulling the latest platform state and Git state: 
git pull
kdx sync pull --target my-org --env dev
Then inspect the diff: 
git status --short
git diff
If kdx sync pull changed files, commit or intentionally review those changes before asking Claude Code to make new edits. A clean baseline makes conflicts easier to reason about.

​
Validate Local Files

Validate changed resource files before sync: 
kdx validate -f kodexa-resources/activity-plans/invoice-intake.yaml
kdx validate -f kodexa-resources/data-definitions/invoice.yaml
kdx validate -f kodexa-resources/data-forms/invoice-review.yaml
For a broad pass: 
find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
kdx validate checks YAML against the platform OpenAPI schema without sending the resource to the server.

​
Dry-Run The Sync

Always preview before pushing: 
kdx sync push --target my-org --env dev --dry-run
Review:
  • created resources
  • updated resources
  • deleted resources
  • dependency ordering
  • unresolved references
  • target organization and environment
If the dry run is not clean, ask Claude Code to inspect the output and the relevant files: 
Review this kdx sync dry-run output. Identify which local files caused the errors,
which references are unresolved, and what edits are required before deployment.

​
Push To A Development Environment

Once the dry run is correct: 
kdx sync push --target my-org --env dev
Commit the deployed change and sync state: 
git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Add invoice intake Activity configuration"
Commit .sync-state/ after pull and push operations. It records server change sequences used for conflict detection.

​
Use Deploy For GitOps Promotion

Use sync deploy when your repository has branch or tag mappings in sync-config.yaml: 
kdx sync deploy --branch main --dry-run
kdx sync deploy --branch main
For release-driven promotion: 
kdx sync deploy --tag v2026.05.03 --dry-run
kdx sync deploy --tag v2026.05.03
For GitHub Actions, prefer the official kdx-sync-action. See CI/CD Integration.

​
Handling Conflicts

If KDX reports stale server state: 
kdx sync pull --target my-org --env dev
git diff
Then decide whether to keep the server change, keep your local change, or merge both. Do not use --force until you understand which server-side change would be overwritten. Ask Claude Code to help with the merge, not to blindly force it: 
kdx sync push detected a conflict. Review the pulled server changes and my local
changes. Propose a merged version that preserves the intended Activity behavior
and avoids overwriting unrelated platform edits.

​
A Safe Claude Code + KDX Loop

# 1. Refresh local state
git pull
kdx sync pull --target my-org --env dev

# 2. Let Claude Code edit files
claude

# 3. Review and validate
git diff
find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
kdx sync push --target my-org --env dev --dry-run

# 4. Push only after the dry run is expected
kdx sync push --target my-org --env dev

# 5. Commit the files and sync state
git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Update Kodexa metadata"

​
Next Steps

Sync Overview

Understand the sync repository model.

Pull, Push & Deploy

Learn command flags and operational behavior.

Conflict Detection

See how .sync-state/ protects against stale writes.

Resource Validation

Validate YAML against the platform schema before deployment.