Pull, Push & Deploy

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

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:

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`.

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

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

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

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`.

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:

--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/

Use these logs for CI diagnostics and release review. They include target, environment, URL, dry-run state, force state, filter, and per-resource outcomes.

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

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Overview

Pull

First Pull With Discover

Pull Flags

Filtering Pulls

Push

Push Flags

What Push Does

Dry Run First

Conflict Detection

Deploy

Deploy Flags

Endpoint Resolution

Push Order

Logs

Recommended Workflow

​Overview

​Pull

​First Pull With Discover

​Pull Flags

​Filtering Pulls

​Push

​Push Flags

​What Push Does

​Dry Run First

​Conflict Detection

​Deploy

​Deploy Flags

​Endpoint Resolution

​Push Order

​Logs

​Recommended Workflow

Overview

Pull

First Pull With Discover

Pull Flags

Filtering Pulls

Push

Push Flags

What Push Does

Dry Run First

Conflict Detection

Deploy

Deploy Flags

Endpoint Resolution

Push Order

Logs

Recommended Workflow