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.
Overview
kdx sync has three operational commands:
| Command | Use it for |
|---|
kdx sync pull | Download resources from a platform environment into local YAML files |
kdx sync push | Upload local YAML resources to one environment |
kdx sync deploy | Select targets from branch or tag mappings and push them to mapped environments |
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
- Queries the organization for resources.
- Merges discovered resources into the target manifest.
- Preserves existing entries and commented-out exclusions.
- Pulls the resources selected by the manifest.
- Writes state to
.sync-state/<env>.yaml.
Pull Flags
| Flag | Description |
|---|
--target | Target from sync-config.yaml. Repeatable. |
--env | Source environment from sync-config.yaml. |
--from-profile | Source profile override. |
--from-url | Source URL override. |
--from-api-key | Source API key override. |
--filter, -f | Regex matched against resource slug or project slug. |
--discover | Discover organization resources and merge the manifest before pulling. |
--discover-dir | Set metadata_dir in a generated manifest. |
--skip-missing | Skip manifest entries that no longer exist on the server. |
--threads | Parallel workers. Default is 4. |
--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
| Flag | Description |
|---|
--target | Target from sync-config.yaml. Repeatable. |
--env | Destination environment from sync-config.yaml. |
--to-profile | Destination profile override. |
--to-url | Destination URL override. |
--to-api-key | Destination API key override. |
--filter, -f | Regex matched against resource slug. |
--dry-run | Validate, diff, and plan without server changes. |
--force | Overwrite resources even when conflict detection finds server drift. |
--threads | Parallel workers. Default is 4. |
What Push Does
- Reads target manifests.
- Resolves local resource files under each
metadata_dir.
- Resolves destination environment credentials.
- Compares
.sync-state/<env>.yaml against server changeSequence values.
- Skips unchanged resources.
- Pushes changed resources in dependency order.
- Uploads module implementation content when configured.
- Syncs knowledge-set content, items, features, and attachments.
- Updates
.sync-state/<env>.yaml.
- Writes a push log under
<metadata_dir>/sync-logs/push/.
Dry Run First
kdx sync push --target finance --env prod --dry-run
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
kdx sync pull --target finance --env prod --filter '^invoice-intake$'
git diff
--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
| Flag | Description |
|---|
--target | Explicit target. Repeatable. Requires --env. |
--env | Explicit or filtering environment. |
--branch | Branch name override for branch mapping. |
--tag | Tag name override for tag mapping. |
--dry-run | Plan without server changes. |
--force | Overwrite conflicts. |
--confirm-each | Confirm each target. |
--confirm-all | Confirm once before all targets. |
--filter, -f | Regex filter for resource slugs. |
--output-json | Write a deployment report for CI/CD. |
--threads | Parallel workers. Default is 4. |
kdx sync deploy --target finance --env prod --dry-run
branch_mappings:
- pattern: releases/.*
target: finance
environment: prod
kdx sync deploy --branch releases/2026.4
kdx sync deploy --branch releases/2026.4 --output-json deploy-report.json
Endpoint Resolution
For pull, source credentials resolve in this order:
--from-url plus --from-api-key--from-profile--env from sync-config.yaml
For push and deploy, destination credentials resolve in this order:
--to-url plus --to-api-key--to-profile--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:
- Labels and low-level shared resources
- Data definitions, data forms, stores, modules, prompts, and Service Bridges
- Knowledge type definitions and feature instances
- Intakes and Activity Plans
- Project templates and projects
- Task templates, task statuses, and knowledge sets
- Project-scoped knowledge items, triggers, and bindings
Logs
Every sync operation writes logs under:
<metadata_dir>/sync-logs/
Recommended Workflow
# 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
