Deploy Command
The deploy command automatically determines what to deploy based on your current git branch or tag:
# Auto-deploy based on current git branch
kdx sync deploy
# Preview without making changes
kdx sync deploy --dry-run
# Ask for confirmation before deploying
kdx sync deploy --confirm-all
# Ask before each target deployment
kdx sync deploy --confirm-each
- Detects current git branch (or tag if specified with
--tag)
- Matches branch against
branch_mappings or tag against tag_mappings patterns
- Deploys all specified targets to their environments
- Reports results for each target
Manual branch override:
# Deploy using specific branch pattern (without switching branches)
kdx sync deploy --branch main
# Test feature branch deployment without creating branch
kdx sync deploy --branch feature/test --dry-run
# Deploy using tag pattern
kdx sync deploy --tag v1.5.0
# Preview tag deployment
kdx sync deploy --tag rc-1 --dry-run
# Deploy specific target to specific environment
kdx sync deploy --target shared --env prod
# Deploy using a specific branch mapping (override auto-detection)
kdx sync deploy --branch release/v1.0
# Deploy using a specific tag mapping
kdx sync deploy --tag v1.0.0
# Deploy multiple targets
kdx sync deploy --target division-a --env dev
kdx sync deploy --target division-b --env dev
Advanced Deployment Options
Parallel Execution (Threads)
Speed up deployments by processing multiple resources in parallel:
# Deploy with 8 parallel threads (recommended for large deployments)
kdx sync deploy --threads 8
# Default is 1 (sequential) for backwards compatibility
kdx sync deploy --threads 1
Using --threads 8 can significantly reduce deployment time for repositories with many resources. The optimal number depends on your system and network conditions.
JSON Reporting
Generate structured JSON reports for CI/CD integration:
# Generate a JSON report of deployment actions
kdx sync deploy --output-json ./deploy-report.json
# Combine with other options
kdx sync deploy --threads 8 --output-json ./results/deploy-$(date +%Y%m%d).json
- Timestamp and duration
- Success/failure status
- Detailed summary of resources and modules processed
- Error details for failed operations
Example JSON output:
{
"timestamp": "2025-12-03T10:30:00Z",
"duration_seconds": 45,
"success": true,
"targets": [
{
"name": "production",
"environment": "prod",
"resources_created": 3,
"resources_updated": 12,
"resources_skipped": 5,
"modules_deployed": 2
}
],
"errors": []
}
Resource Filtering
Deploy only specific resources matching a pattern:
# Deploy only resources matching "invoice-*"
kdx sync deploy --filter "invoice-*"
# Filter with dry-run to preview what would be deployed
kdx sync deploy --filter "prod-*" --dry-run
# Combine filter with parallel execution
kdx sync deploy --filter "division-a-*" --threads 4
The filter applies to resource slugs. If your filter doesn’t match any resources, the deploy will complete with no changes. Use --dry-run to verify your filter pattern first.
Pull Command
Download resources from an environment to local files:
# Pull resources defined in a target from an environment
kdx sync pull --target shared --env dev
# Pull from different environment
kdx sync pull --target division-a --env prod
# Auto-discover all resources in the organization and pull them
kdx sync pull --target shared --env dev --discover
# Skip resources that don't exist on the server instead of failing
kdx sync pull --target shared --env dev --skip-missing
# Pull with parallel threads for faster downloads
kdx sync pull --target shared --env dev --threads 8
| Flag | Description |
|---|
--target | The sync target to pull (as defined in sync-config.yaml) |
--env | The environment to pull from (must match a profile in the target) |
--discover | Query the server for all resources and generate/update the manifest before pulling |
--skip-missing | Skip resources listed in the manifest but not found on the server, instead of failing |
--threads | Number of parallel threads for downloading resources (default: 1) |
- Reads target’s manifests to determine what resources to fetch (or discovers them with
--discover)
- Connects to source environment
- Downloads each resource from the API
- Writes YAML files to local filesystem (default:
kodexa-resources/)
- Pulls project-scoped children (task templates, assistants, task statuses, assistant connections, project resource links)
- Updates the sync state file (
.sync-state/<env>.yaml) with the changeSequence of each pulled resource — used for conflict detection on subsequent pushes
Discover Mode
The --discover flag queries the server for all resources in the organization and generates (or updates) the manifest before pulling:
# First time: creates manifest.yaml from scratch
kdx sync pull --target my-org --env dev --discover
# Subsequent runs: merges new resources into existing manifest
kdx sync pull --target my-org --env dev --discover
Smart Merge Behavior
When a manifest already exists, --discover intelligently merges rather than overwriting:
- Existing resources are preserved (not duplicated)
- New server resources are appended to the manifest
- Commented-out resources are treated as intentional exclusions and not re-added
- Stale entries (in manifest but not on server) trigger a warning
For example, if your manifest contains:
resources:
knowledge-set:
- active-ks
# - excluded-ks # intentionally disabled
--discover will add any new knowledge sets found on the server, but will never re-add excluded-ks because it’s commented out.
Discover Output
Discovering resources in organization "my-org"...
knowledge-set: 5 on server, 3 in manifest, 1 excluded → 1 new added
data-definition: 3 on server, 3 in manifest → up to date
prompt-template: 2 on server, 0 in manifest → 2 new added
⚠ knowledge-set/old-ks: in manifest but not found on server
Manifest updated: 3 resources added (1 excluded)
Use --discover when onboarding an existing environment into a sync repository for the first time. After the initial discovery, you can comment out resources you do not want to sync and subsequent --discover runs will respect those exclusions.
Push Command
Upload local resources to an environment:
# Push resources to environment
kdx sync push --target shared --env prod
# Dry run (validate without pushing)
kdx sync push --target division-a --env dev --dry-run
# Force push even when conflicts are detected
kdx sync push --target shared --env prod --force
# Push with parallel threads
kdx sync push --target shared --env prod --threads 8
| Flag | Description |
|---|
--target | The sync target to push (as defined in sync-config.yaml) |
--env | The environment to push to (must match a profile in the target) |
--dry-run | Validate and report what would be pushed without making changes |
--force | Push even when conflicts are detected (overwrites server state) |
--threads | Number of parallel threads for uploading resources (default: 1) |
- Reads target’s manifests to determine what to upload
- Validates all resources exist locally
- Connects to destination environment
- Checks each resource for conflicts against the sync state
- Uploads each resource (creates or updates), skipping conflicted resources
- Updates the sync state file with new
changeSequence values
- Reports status for each resource
Resources are pushed in dependency order — labels and exception types first, then definitions/forms/stores/modules, then knowledge resources, then projects, and finally project-scoped resources. This ensures references resolve correctly during push.
Use --force with caution. It overrides conflict detection and will overwrite any changes made on the server since your last pull. See Conflict Detection for details on how conflicts are detected and resolved. 