# amfelt sync

Execute a pipeline job defined in amfelt.yaml.

Executes the pipeline job identified by `--job`. The job definition in amfelt.yaml
names the source and target, sets the default layer and write mode, and selects
which objects to move using glob include/exclude patterns resolved against the
source's data contract. Selected objects can override the history mode, write
mode, table type, cursor, and column handling individually.

Use `--dry-run` to validate the job configuration and print the resolved job
summary without executing any data movement.

Use `--run-report` to save the engine's run metadata and structured report as
JSON, including run and task IDs, bytes, row counts, and history counters. The
file uses schema version 1 and permissions 0600. Completed failed runs also save
their available evidence; setup failures leave an existing file unchanged. A
write failure fails the command. This flag cannot be combined with `--dry-run`. It
can be used alongside `--target-contract` with separate destinations.

Use `--target-contract` to write a data contract (ODCS) of what the warehouse
holds once the run succeeds: every table and view in the job's layer schemas,
read back from the warehouse itself, with the layer each one belongs to, and for
each table and view this job creates, the source object it came from. The
staging tables and current-record views this job creates can also carry primary
keys and foreign keys from the source's data contract. An object gets a key only
if it holds every column of the key. A foreign key links these objects only
within one layer, and only if the object it points to has the key it references;
the object it starts from needs no key of its own. In the history and bridge
layers, a foreign key links two objects only if the job gives both the same
history mode. In the bridge layer, a key or foreign key is included only when
the views pass every column it involves through unchanged, with no transform or
rename. A layer built from a SQL template you have customized gets no keys or
foreign keys, and neither does any layer built on top of it. The file is
replaced only when the run succeeds and the warehouse could be read back;
otherwise the command fails and the file is left as it was.

## Usage

```text
amfelt sync [flags]
```

## Examples

```text
amfelt sync --job sync-dwh
Validates and executes the 'sync-dwh' job defined in amfelt.yaml.

amfelt sync --job sync-dwh --dry-run
Prints the resolved job configuration without executing anything.
```

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--dry-run` | `bool` | `false` | generate DDL without executing against the database |
| `--force` | `bool` | `false` | ignore warnings and errors |
| `--job` | `string` | — | name of the job to execute (required) |
| `--path` | `string` | `amfelt.yaml` | path of the Amfelt project file |
| `--run-report` | `string` | — | write the engine run metadata and report as JSON to this file, including failed runs |
| `--source-url` | `string` | — | connection URL for the source database plugin (e.g. postgres://user:pass@host:5432/db) |
| `--strict` | `bool` | `true` | use strict validation |
| `--target-contract` | `string` | — | after a successful run, write a data contract (ODCS) of what the warehouse holds to this file: every table and view in the job's layer schemas with its layer, and for each one this job creates, the source object it came from and, where they apply, keys and foreign keys from the source's data contract |
{.clidoc-flags-table}

## Global flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--amfelt-dir` | `string` | `.amfelt` | directory for workspace files (such as plugins); does not move agent identity (controlled by AMFELT_DIR) |
| `--config` | `string` | — | directory or filename of the application configuration |
| `-f`, `--format` | `string` | `default` | log format to use; either default, pretty, or json |
| `-l`, `--level` | `string` | `info` | minimum log level to display; either error, warn, info, or debug |
| `-v`, `--verbose` | `bool` | `false` | trigger to use verbose logging |
{.clidoc-flags-table}

---

Generated from `amfelt` v5.6.3.