Skip to main content

​
Overview

kdx sync has three operational commands:
CommandUse it for
kdx sync pullDownload resources from a platform environment into local YAML files
kdx sync pushUpload local YAML resources to one environment
kdx sync deploySelect targets from branch or tag mappings and push them to mapped environments
All three use sync-config.yaml and one or more manifest files.

​
Pull

Pull is read-only with respect to the server. It creates or overwrites local files and updates .sync-state/. 
kdx sync pull --target finance --env dev
kdx sync pull --target finance --env dev --threads 8

​
First Pull With Discover

Use --discover when onboarding an existing organization: 
kdx sync pull --target finance --env dev --discover --discover-dir kodexa-resources
Discover mode:
  1. Queries the organization for resources.
  2. Merges discovered resources into the target manifest.
  3. Preserves existing entries and commented-out exclusions.
  4. Pulls the resources selected by the manifest.
  5. Writes state to .sync-state/<env>.yaml.

​
Pull Flags

FlagDescription
--targetTarget from sync-config.yaml. Repeatable.
--envSource environment from sync-config.yaml.
--from-profileSource profile override.
--from-urlSource URL override.
--from-api-keySource API key override.
--filter, -fRegex matched against resource slug or project slug.
--discoverDiscover organization resources and merge the manifest before pulling.
--discover-dirSet metadata_dir in a generated manifest.
--skip-missingSkip manifest entries that no longer exist on the server.
--threadsParallel workers. Default is 4.
Older --organization and --project flags are accepted for compatibility, but new workflows should use --target.

​
Filtering Pulls

# Pull one project and its project-scoped resources
kdx sync pull --target finance --env dev --filter '^invoice-processing$'

# Pull one data definition
kdx sync pull --target finance --env dev --filter '^invoice-data$'

# Pull a project and its core dependencies
kdx sync pull --target finance --env dev \
  --filter '^(invoice-processing|invoice-data|invoice-review|invoice-intake)$'
--filter does not follow references automatically. If a project references a data definition or Activity Plan, include those slugs in the filter when you need them refreshed too.

​
Push

Push reads local YAML and creates or updates resources on the destination environment. 
kdx sync push --target finance --env dev
kdx sync push --target finance --env prod --dry-run

​
Push Flags

FlagDescription
--targetTarget from sync-config.yaml. Repeatable.
--envDestination environment from sync-config.yaml.
--to-profileDestination profile override.
--to-urlDestination URL override.
--to-api-keyDestination API key override.
--filter, -fRegex matched against resource slug.
--dry-runValidate, diff, and plan without server changes.
--forceOverwrite resources even when conflict detection finds server drift.
--threadsParallel workers. Default is 4.

​
What Push Does

  1. Reads target manifests.
  2. Resolves local resource files under each metadata_dir.
  3. Resolves destination environment credentials.
  4. Compares .sync-state/<env>.yaml against server changeSequence values.
  5. Skips unchanged resources.
  6. Pushes changed resources in dependency order.
  7. Uploads module implementation content when configured.
  8. Syncs knowledge-set content, items, features, and attachments.
  9. Updates .sync-state/<env>.yaml.
  10. Writes a push log under <metadata_dir>/sync-logs/push/.

​
Dry Run First

kdx sync push --target finance --env prod --dry-run
Dry run is the default review step for production. It exercises validation, conflict detection, diffing, and push ordering without changing the server.

​
Conflict Detection

Push compares local sync state to server state. If the server changed since the last pull, the resource is treated as conflicted and skipped. 
CONFLICT activity-plan/invoice-intake:
server changeSequence is 18 but local sync state recorded 16
Resolve by pulling first: 
kdx sync pull --target finance --env prod --filter '^invoice-intake$'
git diff
Use --force only after review: 
kdx sync push --target finance --env prod --force

​
Deploy

Deploy chooses targets and environments from branch or tag mappings, then runs the push workflow. 
kdx sync deploy
kdx sync deploy --dry-run
kdx sync deploy --branch releases/2026.4 --dry-run
kdx sync deploy --tag v2026.4.0

​
Deploy Flags

FlagDescription
--targetExplicit target. Repeatable. Requires --env.
--envExplicit or filtering environment.
--branchBranch name override for branch mapping.
--tagTag name override for tag mapping.
--dry-runPlan without server changes.
--forceOverwrite conflicts.
--confirm-eachConfirm each target.
--confirm-allConfirm once before all targets.
--filter, -fRegex filter for resource slugs.
--output-jsonWrite a deployment report for CI/CD.
--threadsParallel workers. Default is 4.
Manual target deployment: 
kdx sync deploy --target finance --env prod --dry-run
Branch mapped deployment: 
branch_mappings:
  - pattern: releases/.*
    target: finance
    environment: prod

kdx sync deploy --branch releases/2026.4
JSON report: 
kdx sync deploy --branch releases/2026.4 --output-json deploy-report.json

​
Endpoint Resolution

For pull, source credentials resolve in this order:
  1. --from-url plus --from-api-key
  2. --from-profile
  3. --env from sync-config.yaml
For push and deploy, destination credentials resolve in this order:
  1. --to-url plus --to-api-key
  2. --to-profile
  3. --env from sync-config.yaml
For most repositories, use --env and let sync-config.yaml define the URL and API key environment variable.

​
Push Order

The CLI pushes dependencies before dependents. The important Activity-era ordering is:
  1. Labels and low-level shared resources
  2. Data definitions, data forms, stores, modules, prompts, and Service Bridges
  3. Knowledge type definitions and feature instances
  4. Intakes and Activity Plans
  5. Project templates and projects
  6. Task templates, task statuses, and knowledge sets
  7. Project-scoped knowledge items, triggers, and bindings

​
Logs

Every sync operation writes logs under: 
<metadata_dir>/sync-logs/
Use these logs for CI diagnostics and release review. They include target, environment, URL, dry-run state, force state, filter, and per-resource outcomes. 
# 1. Refresh local state
kdx sync pull --target finance --env dev

# 2. Edit metadata
$EDITOR kodexa-resources/activity-plans/invoice-intake.yaml

# 3. Validate with dry run
kdx sync push --target finance --env dev --dry-run

# 4. Push to development
kdx sync push --target finance --env dev

# 5. Commit files and sync state
git add kodexa-resources manifests sync-config.yaml .sync-state
git commit -m "Update invoice intake Activity Plan"

# 6. Promote through deploy mappings
kdx sync deploy --branch releases/2026.4 --dry-run