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

# Pull, Push & Deploy

> Use kdx sync pull, push, discover, and deploy commands to move Kodexa metadata between local YAML files and platform environments across targets.

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

```bash theme={null}
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:

```bash theme={null}
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

| 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

```bash theme={null}
# 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.

```bash theme={null}
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

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

```bash theme={null}
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.

```text theme={null}
CONFLICT activity-plan/invoice-intake:
server changeSequence is 18 but local sync state recorded 16
```

Resolve by pulling first:

```bash theme={null}
kdx sync pull --target finance --env prod --filter '^invoice-intake$'
git diff
```

Use `--force` only after review:

```bash theme={null}
kdx sync push --target finance --env prod --force
```

## Deploy

Deploy chooses targets and environments from branch or tag mappings, then runs the push workflow.

```bash theme={null}
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:

```bash theme={null}
kdx sync deploy --target finance --env prod --dry-run
```

Branch mapped deployment:

```yaml theme={null}
branch_mappings:
  - pattern: releases/.*
    target: finance
    environment: prod
```

```bash theme={null}
kdx sync deploy --branch releases/2026.4
```

JSON report:

```bash theme={null}
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:

```text theme={null}
<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

```bash theme={null}
# 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
```