> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Reconciliation CLI reference
> Every synq-recon command, argument and flag, generated from the CLI itself.
This page is generated from the `synq-recon` command tree, so it always matches
the released binary. The YAML suite format is documented separately in the
[configuration reference](https://schemas.synq.io/synq-recon/v1/config.html).
synq-recon is a database reconciliation tool that uses hierarchical
checksum bisection to efficiently detect data differences between
source and target databases.
It supports multiple database types including PostgreSQL, MySQL,
Snowflake, BigQuery, and DuckDB.
Example usage:
```bash theme={null}
# Check configuration (offline)
synq-recon check-config config.yaml
# Check configuration with live database validation
synq-recon check-config config.yaml --db
# Quick check for differences (Stage 1)
synq-recon run-check config.yaml
synq-recon run-check config.yaml --include orders-daily
# Drill down to locate differences (Stage 2)
synq-recon run-drill config.yaml --include orders-daily
# Combined check and optional drill
synq-recon run config.yaml --auto-drill
# Filter reconciliations with --include/--exclude
synq-recon run config.yaml --include orders-daily --include users-sync
synq-recon run config.yaml --exclude slow-check
```
## Global flags
These apply to every command.
`--output` defaults to `table` for a human terminal and to `toon` when an
AI-agent environment marker is present. Anything parsing the output should
pass `--output json` explicitly rather than relying on the default.
| Flag | Type | Default | Description |
| --------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--actor-email` | `string` | — | Email to attribute write operations to (or RECON\_ACTOR\_EMAIL) |
| `--audit-log` | `string` | — | Write audit log JSON to this path (file or directory) |
| `--client-id` | `string` | — | Coalesce Quality API client ID (overrides env/YAML) |
| `--client-secret` | `string` | — | Coalesce Quality API client secret (overrides env/YAML) |
| `--columns` | `stringSlice` | — | Comma-separated list of columns to display (table/tsv mode) |
| `--concurrency` | `int` | `1` | Max reconciliations to run in parallel (1 = sequential) |
| `--connections` | `string` | — | External connections file with credentials kept out of the suite (default: auto-discover .connections.yaml) |
| `--dbt-profiles` | `string` | — | Resolve connections from a dbt profiles.yml file (fallback after YAML config) |
| `--endpoint` | `string` | — | Coalesce Quality API endpoint, for staging or a self-hosted deployment; overrides --region (or \$QUALITY\_API\_ENDPOINT) |
| `--env-file` | `string` | — | Path to environments YAML file (auto-discovered if omitted) |
| `-e`, `--environment` | `string` | — | Apply named environment overrides from environment file |
| `--exclude` | `stringArray` | — | Exclude these reconciliations (can be repeated) |
| `--force` | `bool` | — | Force destructive actions, bypassing safety checks (implies --yes) |
| `--include` | `stringArray` | — | Include only these reconciliations (can be repeated) |
| `--jq` | `string` | — | jq expression to filter JSON output |
| `--max-table-bytes` | `int64` | — | Warn before running when a reconciliation's estimated scan exceeds this size in bytes, via dry-run/EXPLAIN (0 = disabled) |
| `--max-table-rows` | `int64` | — | Warn before running when a reconciliation's estimated scan exceeds this row count, via dry-run/EXPLAIN (0 = disabled; check-config --db always reports table sizes) |
| `--no-headers` | `bool` | — | Omit the header row (table/tsv mode) |
| `--no-report` | `bool` | — | Keep the run local: do not send its audit log to Coalesce Quality (or RECON\_NO\_REPORT) |
| `-o`, `--output` | `string` | `table` | Output format: table, json, yaml, toon, tsv, wide |
| `--region` | `region` | — | Coalesce Quality deployment to use: au, eu, us (or \$QUALITY\_REGION) |
| `--timeout` | `duration` | `5m0s` | Query timeout |
| `--var` | `stringArray` | — | Set or override a template variable (can be repeated): --var start\_date=2026-01-01 |
| `-v`, `--verbose` | `bool` | — | Verbose logging |
| `--wide` | `bool` | — | Show all columns in table mode |
| `-y`, `--yes` | `bool` | — | Assume yes to confirmation prompts (for non-interactive use) |
## Commands
### `synq-recon audit-logs`
Inspect reconciliation run results (audit logs)
```bash theme={null}
synq-recon audit-logs
```
Inspect reconciliation run results stored in the workspace. Each audit log is
the recorded outcome of one reconciliation run (counts, checksums, mismatches).
#### `synq-recon audit-logs get`
Get a single audit log by invocation id
```bash theme={null}
synq-recon audit-logs get
```
Fetch a single audit log by invocation id.
Use -o json or -o yaml to see the full run result including every
reconciliation's counts, checksums, and mismatches.
#### `synq-recon audit-logs list`
List audit logs (newest first)
```bash theme={null}
synq-recon audit-logs list [flags]
```
| Flag | Type | Default | Description |
| ---------- | ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `--limit` | `int` | — | Maximum number of audit logs to return (0 = all) |
| `--status` | `stringArray` | — | Filter by status: passed, mismatched, mismatched\_within\_threshold, failed (repeatable) |
| `--suite` | `string` | — | Filter by suite name |
### `synq-recon auth`
Manage Coalesce Quality API authentication
```bash theme={null}
synq-recon auth [flags]
```
Manage authentication for the Coalesce Quality API using OAuth2 authorization
code flow with PKCE. Credentials are cached under \~/.synq/oauth/, partitioned by
region, and shared with the other Coalesce Quality CLIs by default.
Pick a deployment with --region, or point at a staging or self-hosted deployment
with --endpoint. Both work on every command, not just under auth, and a
successful login is remembered — so after logging in to one deployment, later
commands need neither flag.
Examples:
```bash theme={null}
synq-recon auth login
synq-recon auth login --region us
synq-recon auth login --isolated
synq-recon auth status
synq-recon auth use au
synq-recon auth logout --region us
```
| Flag | Type | Default | Description |
| ---------------- | -------- | ------- | ----------------------------------------------------------------- |
| `--auth-profile` | `string` | — | Credential profile to read or write (default: the shared profile) |
#### `synq-recon auth login`
Authenticate with Coalesce Quality in a browser
```bash theme={null}
synq-recon auth login [flags]
```
Authenticate using the OAuth2 authorization code flow with PKCE.
Opens a browser, then caches the resulting credential under \~/.synq/oauth/. The
login asks for only the permissions synq-recon needs, not everything your
account could grant.
By default the credential goes to the shared slot, so one login serves every
Coalesce Quality CLI on this machine. Pass --isolated to give synq-recon its own
credential instead — useful when you want one tool to hold a read-only token
while another holds an ingest token.
Examples:
```bash theme={null}
synq-recon auth login
synq-recon auth login --region us
synq-recon auth login --endpoint developer.synq.dev:443
```
| Flag | Type | Default | Description |
| ------------ | ------ | ------- | ----------------------------------------------------------------- |
| `--isolated` | `bool` | — | Store a credential for synq-recon alone instead of the shared one |
#### `synq-recon auth logout`
Remove the stored credential for a region
```bash theme={null}
synq-recon auth logout
```
Delete the cached credential for one region, leaving credentials for other
regions in place. The OAuth client registration is kept, so logging back in does
not create another connected app.
#### `synq-recon auth status`
Show every stored credential, for every region
```bash theme={null}
synq-recon auth status
```
List the cached credentials across all regions, with the workspace, granted
permissions and expiry of each. Reads local files only — no network calls.
Pass --region or --endpoint to show one deployment instead of all of them.
#### `synq-recon auth token`
Print the access token, refreshing it if needed
```bash theme={null}
synq-recon auth token
```
Print the current access token to stdout, refreshing it first if it has
expired or is close to expiring.
Useful for scripting:
```bash theme={null}
curl -H "Authorization: Bearer $(synq-recon auth token)" ...
```
#### `synq-recon auth use`
Show or set the deployment commands use by default
```bash theme={null}
synq-recon auth use [region|endpoint] [flags]
```
Record which deployment a command talks to when it is given neither --region
nor --endpoint.
A successful login already records the deployment it authenticated against, so
this is only needed to switch between two deployments you are logged in to. An
explicit --region or --endpoint, QUALITY\_API\_ENDPOINT and QUALITY\_REGION all
still win over what is recorded here.
Called with no argument it prints the current setting.
Examples:
```bash theme={null}
synq-recon auth use
synq-recon auth use au
synq-recon auth use developer.synq.dev:443
synq-recon auth use --clear
```
| Flag | Type | Default | Description |
| --------- | ------ | ------- | ------------------------------------------------------------------ |
| `--clear` | `bool` | — | Forget the recorded deployment and fall back to the default region |
#### `synq-recon auth whoami`
Show who you are authenticated as and what permissions you hold
```bash theme={null}
synq-recon auth whoami
```
Call the Coalesce Quality IAM API and print the current identity, workspace
and granted permissions. Uses the same credential resolution as every other
command (client credentials, then a pre-issued token, then the browser login).
### `synq-recon check-config`
```bash theme={null}
synq-recon check-config [flags]
```
Check a configuration file for syntax and semantic correctness.
This command parses the YAML configuration, checks for required fields,
validates connection parameters, verifies reconciliation definitions,
and detects potential issues like time-dependent SQL references.
Use --db to also connect to databases and validate SQL queries.
Examples:
```bash theme={null}
synq-recon check-config config.yaml
synq-recon check-config config.yaml --db
```
| Flag | Type | Default | Description |
| ------ | ------ | ------- | --------------------------------------------- |
| `--db` | `bool` | — | Connect to databases and validate SQL queries |
### `synq-recon connections`
Work with reconciliation connections (data warehouses / databases)
```bash theme={null}
synq-recon connections
```
Work with reconciliation connections — the data warehouses / databases recon
runs against. A connection id is what a suite's source/target `connection:` refers
to. The `remote` subcommands operate on the connections defined in the cloud
workspace.
#### `synq-recon connections remote`
Inspect DWH connections defined in the cloud workspace
```bash theme={null}
synq-recon connections remote
```
##### `synq-recon connections remote bootstrap`
Print a .connections.yaml for selected cloud DWH connections
```bash theme={null}
synq-recon connections remote bootstrap [flags]
```
Print a .connections.yaml skeleton for the selected cloud DWH connections,
ready to redirect to a file. Credentials are left as \$\{ENV} placeholders —
nothing is written to disk and no secrets are fetched.
Select non-interactively with --connection (repeatable), --all, or
\--recon-deployable:
```bash theme={null}
synq-recon connections remote bootstrap --recon-deployable > .connections.yaml
```
| Flag | Type | Default | Description |
| -------------------- | ------------- | ------- | --------------------------------------------------------------- |
| `--all` | `bool` | — | Bootstrap all DWH connections |
| `--connection` | `stringArray` | — | Connection id to bootstrap (repeatable) |
| `--out` | `string` | — | Write to this file instead of stdout (use --force to overwrite) |
| `--recon-deployable` | `bool` | — | Bootstrap all recon-deployable connections |
##### `synq-recon connections remote list`
List DWH connections in the cloud workspace
```bash theme={null}
synq-recon connections remote list [flags]
```
| Flag | Type | Default | Description |
| -------------------- | ------ | ------- | -------------------------------------------------- |
| `--include-disabled` | `bool` | — | Include disabled connections |
| `--limit` | `int` | — | Maximum number of connections to return (0 = all) |
| `--recon-deployable` | `bool` | — | Only connections reconciliation can deploy against |
### `synq-recon deployment`
```bash theme={null}
synq-recon deployment
```
Inspect promoted reconciliation deployments (the operations side of recon):
the scheduled/triggerable instances of a suite running against workspace
integrations. Use the subcommands to list deployments, fetch one, and view
its append-only change history.
#### `synq-recon deployment get`
Get a single deployment by suite id (or --deployment-id)
```bash theme={null}
synq-recon deployment get [suite-id] [flags]
```
Fetch a single deployment. By default the positional argument is the
suite id; pass --deployment-id to look up by deployment id instead.
Use -o json or -o yaml to see the full deployment including schedule,
connection mappings, and case-failure impacts.
| Flag | Type | Default | Description |
| ----------------- | -------- | ------- | -------------------------------------------- |
| `--deployment-id` | `string` | — | Look up by deployment id instead of suite id |
#### `synq-recon deployment history`
Show the change history of a deployment
```bash theme={null}
synq-recon deployment history [suite-id] [flags]
```
Show the append-only change history of a deployment (promote, unpromote,
schedule/mapping/annotation changes, pause, resume). By default the positional
argument is the suite id; pass --deployment-id to look up by deployment id.
| Flag | Type | Default | Description |
| ----------------- | -------- | ------- | -------------------------------------------- |
| `--deployment-id` | `string` | — | Look up by deployment id instead of suite id |
#### `synq-recon deployment list`
List promoted deployments in the workspace
```bash theme={null}
synq-recon deployment list [flags]
```
| Flag | Type | Default | Description |
| ---------------------- | -------- | ------- | -------------------------------------------------- |
| `--active-only` | `bool` | — | Only currently-active deployments |
| `--include-paused` | `bool` | — | Include paused deployments |
| `--integration` | `string` | — | Filter to deployments bound to this integration id |
| `--limit` | `int` | — | Maximum number of deployments to return (0 = all) |
| `--triggerable-by-api` | `bool` | — | Only deployments that can be triggered via the API |
#### `synq-recon deployment pause`
Pause a deployment (suppress scheduled and API-triggered runs)
```bash theme={null}
synq-recon deployment pause [flags]
```
Pause a deployment so it stops running on its schedule and via the API.
Without --until the pause is indefinite (until 'deployment resume').
| Flag | Type | Default | Description |
| ---------- | -------- | ------- | ----------------------------------------------------- |
| `--reason` | `string` | — | Reason recorded in the deployment history |
| `--until` | `string` | — | Pause until this RFC3339 time (default: indefinitely) |
#### `synq-recon deployment resume`
Resume a paused deployment
```bash theme={null}
synq-recon deployment resume
```
#### `synq-recon deployment set-annotations`
Replace a deployment's annotations
```bash theme={null}
synq-recon deployment set-annotations [flags]
```
| Flag | Type | Default | Description |
| ------------------ | ------------- | ------- | ------------------------------------------------------------------- |
| `--annotation` | `stringArray` | — | Annotation: name=value\[,value...] (repeatable); pass none to clear |
| `--change-summary` | `string` | — | Audit log summary for this change |
#### `synq-recon deployment update`
Update a deployment's schedule, API-triggering, drill, or execution-timeout setting
```bash theme={null}
synq-recon deployment update [flags]
```
Partially update a deployment without re-promoting its config. Every flag
is independent: omit one and its current value is preserved. Pass --schedule
with a cron expression (or --ical with an RFC 5545 recurrence rule, optionally
anchored with --dtstart) to set it, --clear to remove it, --drill /
\--drill=false to toggle bisection drill-down, --triggerable-by-api / =false
to toggle on-demand API triggers, and --execution-timeout to set the per-run
wall-clock budget (e.g. 20m; the server clamps it to its supported range).
Use 'deployment set-annotations' to change a deployment's annotations.
| Flag | Type | Default | Description |
| ---------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `--change-summary` | `string` | — | Audit log summary for this change |
| `--clear` | `bool` | — | Clear the schedule |
| `--drill` | `bool` | — | Enable (--drill) or disable (=false) bisection drill-down on each run; omit to preserve |
| `--dtstart` | `string` | — | Anchor time for --ical (RFC3339, e.g. 2026-01-02T15:04:05Z) |
| `--execution-timeout` | `duration` | `0s` | Maximum wall-clock budget for a single run, e.g. 20m (server clamps to its supported range); omit to preserve |
| `--ical` | `string` | — | iCal RFC 5545 recurrence rule, e.g. 'FREQ=MONTHLY;BYDAY=TH;BYSETPOS=-1' (mutually exclusive with --schedule) |
| `--schedule` | `string` | — | Cron schedule, e.g. '0 \* \* \* \*' (mutually exclusive with --ical) |
| `--timezone` | `string` | — | Timezone for the schedule |
| `--triggerable-by-api` | `bool` | — | Allow (--triggerable-by-api) or disallow (=false) on-demand API triggers; omit to preserve |
### `synq-recon drill-deeper`
Continue a previous run's drill-down from where it stopped
```bash theme={null}
synq-recon drill-deeper [flags]
```
Resume a drill from where a previous run stopped, instead of re-drilling
the whole dataset. Bisection and aggregate reconciliations both resume, each
picking up where it left off.
Bisection resumes from the mismatch segments the previous run left open — the
ones it stopped at because it hit its row threshold or its depth limit. Segments
it could not split further, or that errored, are reported and skipped: drilling
deeper cannot narrow those. Lowering --threshold is the usual reason to resume;
\--depth is counted from the depth the resumed segments already reached, so it
means "this many more levels".
Aggregate resumes from the divergent groups the previous run found. An aggregate
drill already visits every configured group column, so resuming needs at least
one more via --add-group-column: each divergent group is then broken down by the
extra columns. Groups present on only one side are reported and skipped.
Queries are replayed from the audit log for the same reason as recheck: the
recorded ranges and group keys were computed against that data, so re-deriving
the queries would drill scopes that no longer line up.
Examples:
```bash theme={null}
# Narrow every open bisection mismatch to 100-row segments
synq-recon drill-deeper audit.json --threshold 100
# Two more levels of detail on one bisection reconciliation
synq-recon drill-deeper audit.json --include orders-daily --depth 2
# Break each divergent aggregate group down by region, then by product
synq-recon drill-deeper audit.json --add-group-column region --add-group-column product
# Have the backend drill a stored run deeper against workspace integrations
synq-recon drill-deeper 3f7c1e28-5a1b-4c9e-9f10-2b7d8e6a4c53 --remote --threshold 100
```
| Flag | Type | Default | Description |
| -------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `--add-group-column` | `stringArray` | — | Extra group column to break divergent aggregate groups down by (repeatable); required to resume an aggregate drill |
| `--depth` | `int` | — | Levels to drill below the resumed segments (0 = unlimited) |
| `--invocation-id` | `string` | — | Client-supplied invocation id for idempotency (with --remote; default: generated) |
| `--map` | `stringArray` | — | Map a connection the run recorded to an integration: connection=integration\_id (repeatable, with --remote) |
| `--remote` | `bool` | — | Run the replay on the Coalesce Quality backend against workspace integrations instead of locally |
| `--reresolve` | `bool` | — | Re-derive queries against current data instead of replaying the previous run's resolved SQL |
| `--threshold` | `int` | — | Row count at which to stop drilling (overrides the reconciliation's own) |
### `synq-recon dump-suite`
Parse a YAML config and dump the proto Suite as JSON
```bash theme={null}
synq-recon dump-suite
```
Parse a YAML configuration file and output the reconciliation suite
as a protojson-encoded message. This is useful for inspecting the
parsed configuration and for integration with other tools.
Examples:
```bash theme={null}
synq-recon dump-suite config.yaml
synq-recon dump-suite config.yaml | jq .
```
### `synq-recon promote`
Promote a suite config to a scheduled/triggerable deployment
```bash theme={null}
synq-recon promote [flags]
```
Promote a suite config to production: create (or update) a deployment that can
run on a schedule and/or be triggered via the API. Re-promoting the same suite
reuses its deployment id, so this is safe to repeat.
On a re-promote, omitted flags are preserved: leaving out --schedule,
\--triggerable-by-api, --drill or --execution-timeout keeps the existing
deployment's value rather than resetting it, so refreshing the suite snapshot
won't unschedule the deployment or disable API triggers. (A fresh promote
defaults to no schedule, not triggerable, bisection on, and the server-default
execution timeout.) Pass --clear-schedule to actively remove an existing
schedule on re-promote.
Wire the suite's connections to workspace integrations with --map; discover
integration ids with 'synq-recon connections list'.
The deployment id is part of every promoted reconciliation's asset path, so it
is worth keeping stable. Pass --deployment-id to promote under a specific id:
it is adopted when no deployment holds it yet, and is an idempotent retry when
the deployment already exists for this suite. Promoting a suite that already
has a deployment keeps that id whether or not the flag is passed.
| Flag | Type | Default | Description |
| ---------------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--annotation` | `stringArray` | — | Deployment annotation: name=value\[,value...] (repeatable) |
| `--change-summary` | `string` | — | Audit log summary describing this promotion |
| `--clear-schedule` | `bool` | — | Remove the existing schedule on re-promote (mutually exclusive with --schedule/--ical) |
| `--deployment-id` | `string` | — | Promote under a specific deployment id, adopting it if no deployment holds it yet (default: reuse the suite's deployment, or allocate a new id) |
| `--drill` | `bool` | — | Run hierarchical bisection drill-down on each run |
| `--dtstart` | `string` | — | Anchor time for --ical (RFC3339, e.g. 2026-01-02T15:04:05Z); wall-clock in --timezone |
| `--execution-timeout` | `duration` | `0s` | Maximum wall-clock budget for a single run, e.g. 20m (server clamps to its supported range; omit to preserve on re-promote / use the server default on a fresh promote) |
| `--ical` | `string` | — | iCal RFC 5545 recurrence rule, e.g. 'FREQ=MONTHLY;BYDAY=TH;BYSETPOS=-1' (mutually exclusive with --schedule) |
| `--map` | `stringArray` | — | Map a suite connection to an integration: connection=integration\_id (repeatable) |
| `--schedule` | `string` | — | Cron schedule for recurring runs, e.g. '0 \* \* \* \*' (mutually exclusive with --ical) |
| `--timezone` | `string` | — | Timezone for the schedule (e.g. UTC, Europe/Warsaw) |
| `--triggerable-by-api` | `bool` | — | Allow on-demand triggers via the API |
### `synq-recon recheck`
Re-run a previous run's queries to check whether its differences still exist
```bash theme={null}
synq-recon recheck [flags]
```
Re-execute the queries a previous run ran and report what changed.
The previous run is identified by an audit log file or, for a run stored in
Coalesce Quality, by its invocation id (fetched via the API).
Queries come from the audit log, not from a fresh config load, so the comparison
is against the same data the previous run compared: template variables keep the
values they resolved to, a cutoff keeps the watermark it derived, and a
time-travel snapshot keeps its timestamp. Use --reresolve to re-derive
everything against the current clock instead — necessary for a time-travel
snapshot, which can otherwise never turn green.
By default only the reconciliations that did not pass are re-run, since that is
what needs re-checking. Pass --all to re-run every one.
Credentials are not stored in an audit log. Connections are resolved by name
from --connections or an auto-discovered connections file, exactly as for a
normal run.
Exit code 1 means something still (or newly) mismatches; 0 means everything
re-validated clean.
Examples:
```bash theme={null}
# Re-check whatever the previous run found
synq-recon recheck audit-logs/audit-2026-07-25T10-30-00.json
# Re-check a run stored in Coalesce Quality
synq-recon recheck 3f7c1e28-5a1b-4c9e-9f10-2b7d8e6a4c53
# Re-check one reconciliation, drilling into whatever still differs
synq-recon recheck audit.json --include orders-daily --drill
# Re-run against current data rather than the previous run's window
synq-recon recheck audit.json --reresolve
# Have the backend re-check a stored run against workspace integrations
synq-recon recheck 3f7c1e28-5a1b-4c9e-9f10-2b7d8e6a4c53 --remote
```
| Flag | Type | Default | Description |
| ----------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `--all` | `bool` | — | Re-run every reconciliation, not only the ones that did not pass |
| `--drill` | `bool` | — | Drill into whatever still mismatches |
| `--invocation-id` | `string` | — | Client-supplied invocation id for idempotency (with --remote; default: generated) |
| `--map` | `stringArray` | — | Map a connection the run recorded to an integration: connection=integration\_id (repeatable, with --remote) |
| `--remote` | `bool` | — | Run the replay on the Coalesce Quality backend against workspace integrations instead of locally |
| `--reresolve` | `bool` | — | Re-derive queries against current data instead of replaying the previous run's resolved SQL |
### `synq-recon run`
Run check and optionally drill on mismatch
```bash theme={null}
synq-recon run [flags]
```
Run quick check and optionally perform bisection drill-down
when mismatches are detected.
This combines Stage 1 (run-check) and Stage 2 (run-drill) into a single command.
By default all reconciliations in the config are run.
Use --include/--exclude to filter which reconciliations to run.
Examples:
```bash theme={null}
# Run all reconciliations, auto-drill on mismatch
synq-recon run config.yaml --auto-drill
# Run only specific reconciliations
synq-recon run config.yaml --include orders-daily --auto-drill
# Run all except one
synq-recon run config.yaml --exclude slow-check --auto-drill
# Run without auto-drill (just check)
synq-recon run config.yaml
```
| Flag | Type | Default | Description |
| -------------- | ------ | ------- | ------------------------------------ |
| `--auto-drill` | `bool` | — | Automatically drill down on mismatch |
### `synq-recon run-check`
Quick check for differences (Stage 1)
```bash theme={null}
synq-recon run-check
```
Perform a quick check to detect differences between source and target.
This is Stage 1 of reconciliation, which compares row counts and checksums
to efficiently detect if any differences exist.
By default all reconciliations in the config are checked.
Use --include/--exclude to filter which reconciliations to run.
Examples:
```bash theme={null}
# Check all reconciliations
synq-recon run-check config.yaml
# Check only specific reconciliations
synq-recon run-check config.yaml --include orders-daily --include users-sync
# Check all except one
synq-recon run-check config.yaml --exclude slow-check
# JSON output
synq-recon run-check config.yaml --output json
```
### `synq-recon run-drill`
Bisection drill-down to locate differences (Stage 2)
```bash theme={null}
synq-recon run-drill [flags]
```
Perform bisection drill-down to locate the specific segments
where data differences exist.
This is Stage 2 of reconciliation, which recursively bisects the data
space to narrow down the location of mismatches.
Use --include/--exclude to filter which reconciliations to drill.
Examples:
```bash theme={null}
# Drill down on all reconciliations
synq-recon run-drill config.yaml
# Drill down on specific reconciliations
synq-recon run-drill config.yaml --include orders-daily
# Drill down on multiple reconciliations
synq-recon run-drill config.yaml --include orders-daily --include users-sync
# Limit the drill depth
synq-recon run-drill config.yaml --include orders-daily --depth 3
# JSON output
synq-recon run-drill config.yaml --include orders-daily --output json
```
| Flag | Type | Default | Description |
| ------------- | ----- | ------- | ------------------------------------------------------- |
| `--depth` | `int` | — | Maximum drill depth (0 for unlimited) |
| `--threshold` | `int` | — | Row count threshold to stop drilling (overrides config) |
### `synq-recon run-remote`
Run a suite on the Coalesce Quality backend (ad-hoc), not locally
```bash theme={null}
synq-recon run-remote [flags]
```
Submit an ad-hoc reconciliation run executed by the Coalesce Quality backend
against workspace integrations — as opposed to run/run-check/run-drill, which
execute locally against databases you can reach.
The run is asynchronous; poll its result with:
```bash theme={null}
synq-recon audit-logs get
```
A client-generated invocation id makes submission idempotent: re-running with
the same --invocation-id will not start a duplicate run.
| Flag | Type | Default | Description |
| --------------------- | ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--drill` | `bool` | — | Run hierarchical bisection drill-down to locate mismatches |
| `--execution-timeout` | `duration` | `0s` | Maximum wall-clock budget for this run, e.g. 20m (server clamps to its supported range); omit to use the server default |
| `--fail-on` | `stringArray` | `[mismatched,failed]` | Audit statuses that cause a non-zero exit: passed, within\_threshold, mismatched, failed (with --wait) |
| `--invocation-id` | `string` | — | Client-supplied invocation id for idempotency (default: generated) |
| `--map` | `stringArray` | — | Map a suite connection to an integration: connection=integration\_id (repeatable) |
| `--poll-interval` | `duration` | `5s` | How often to poll for the run result (with --wait) |
| `--wait` | `bool` | — | Block until the run completes and exit non-zero on mismatch (1) or failure (2) |
| `--wait-timeout` | `duration` | `30m0s` | Maximum time to wait for the run to complete (with --wait) |
### `synq-recon runs`
```bash theme={null}
synq-recon runs
```
Inspect reconciliation run state across the workspace: scheduled, in-progress,
and concluded runs, with their trigger, status, and timing.
#### `synq-recon runs cancel`
Cancel a scheduled or in-progress run
```bash theme={null}
synq-recon runs cancel
```
Cancel a stuck or unwanted run by marking it cancelled. An independent
execution job will skip the run when it next checks its state.
Requires confirmation; pass --yes (or --force) for non-interactive use.
#### `synq-recon runs list`
List reconciliation runs (newest first)
```bash theme={null}
synq-recon runs list [flags]
```
| Flag | Type | Default | Description |
| -------------- | ------------- | ------- | --------------------------------------------------------------------------------------------- |
| `--actor` | `stringArray` | — | Filter by actor identity, e.g. email:[user@example.com](mailto:user@example.com) (repeatable) |
| `--deployment` | `stringArray` | — | Filter by deployment id (repeatable) |
| `--limit` | `int` | — | Maximum number of runs to return (0 = all) |
| `--status` | `stringArray` | — | Filter by status: scheduled, in\_progress, succeeded, failed, cancelled (repeatable) |
| `--suite` | `stringArray` | — | Filter by suite id (repeatable) |
| `--trigger` | `stringArray` | — | Filter by trigger: adhoc, scheduled, api (repeatable) |
### `synq-recon suite`
Manage reconciliation suite configs in the Coalesce Quality workspace
```bash theme={null}
synq-recon suite
```
Inspect and manage reconciliation suite configurations stored in the
Coalesce Quality workspace (the authoring side of recon). Use the subcommands
to list suites, fetch a single suite, and view its version history.
#### `synq-recon suite bootstrap`
Print a new suite skeleton (generated id + connection references)
```bash theme={null}
synq-recon suite bootstrap [flags]
```
Print a new reconciliation suite skeleton to stdout, ready to redirect to a
file and edit. The suite gets a generated UUID name and one reconciliation
referencing source/target connections by id (discover ids with
'synq-recon connections remote list'). Nothing is written to disk.
```bash theme={null}
synq-recon suite bootstrap --source --target > my-suite.yaml
```
| Flag | Type | Default | Description |
| -------------- | -------- | --------- | ------------------------------------------------------------------------ |
| `--key-column` | `string` | `id` | Key column for the example reconciliation |
| `--name` | `string` | — | Suite name — the stable identifier (default: generated UUID) |
| `--out` | `string` | — | Write to this file instead of stdout (use --force to overwrite) |
| `--recon-key` | `string` | `example` | Reconciliation key in the generated suite |
| `--source` | `string` | — | Source connection id |
| `--target` | `string` | — | Target connection id |
| `--title` | `string` | — | Suite title — human-friendly label (default: "New Reconciliation Suite") |
#### `synq-recon suite delete`
Delete a suite config (soft delete)
```bash theme={null}
synq-recon suite delete
```
Delete a suite config from the workspace. This is a soft delete: the suite's
version history is preserved.
Requires confirmation; pass --yes (or --force) for non-interactive use.
#### `synq-recon suite get`
Get a single suite config by suite id
```bash theme={null}
synq-recon suite get
```
Fetch a single suite config by its suite id.
Use -o json or -o yaml to see the full suite definition including every
reconciliation, query, and threshold.
#### `synq-recon suite list`
List suite configs in the workspace
```bash theme={null}
synq-recon suite list [flags]
```
List reconciliation suite configs in the workspace.
By default only managed suites are returned. Pass --include-adhoc to also
include one-off ad-hoc submissions (e.g. local test runs uploaded to the API).
| Flag | Type | Default | Description |
| ----------------- | -------- | ------- | --------------------------------------------------------------- |
| `--connection` | `string` | — | Filter suites that use this connection name |
| `--include-adhoc` | `bool` | — | Include ad-hoc (one-off) suite configs, not just managed suites |
| `--limit` | `int` | — | Maximum number of suites to return (0 = all) |
#### `synq-recon suite versions`
List the version history of a suite config
```bash theme={null}
synq-recon suite versions
```
#### `synq-recon suite yaml`
Render a suite config as canonical recon YAML
```bash theme={null}
synq-recon suite yaml
```
Fetch a suite config and render it as canonical reconciliation YAML — the
same shape accepted by check-config and upload-config. Use this to pull a
remote suite down to a local file, edit it, and re-upload:
```bash theme={null}
synq-recon suite yaml my-suite > my-suite.yaml
# edit my-suite.yaml ...
synq-recon upload-config my-suite.yaml
```
### `synq-recon trigger`
Trigger an on-demand run of a promoted deployment
```bash theme={null}
synq-recon trigger [suite-id] [flags]
```
Trigger an immediate run of a promoted deployment. The deployment must be
active, triggerable by API, and not paused. By default the positional argument
is the suite id; pass --deployment-id to target by deployment id.
| Flag | Type | Default | Description |
| --------------------- | ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--deployment-id` | `string` | — | Target by deployment id instead of suite id |
| `--drill` | `bool` | — | Run drill-down for this run (--drill) or skip it (=false); omit to inherit the deployment default |
| `--execution-timeout` | `duration` | `0s` | Maximum wall-clock budget for this run, e.g. 20m (server clamps to its supported range); omit to inherit the deployment default |
| `--fail-on` | `stringArray` | `[mismatched,failed]` | Audit statuses that cause a non-zero exit: passed, within\_threshold, mismatched, failed (with --wait) |
| `--poll-interval` | `duration` | `5s` | How often to poll for the run result (with --wait) |
| `--wait` | `bool` | — | Block until the run completes and exit non-zero on mismatch (1) or failure (2) |
| `--wait-timeout` | `duration` | `30m0s` | Maximum time to wait for the run to complete (with --wait) |
### `synq-recon unpromote`
Deactivate a deployment (stop scheduling and API triggers)
```bash theme={null}
synq-recon unpromote [flags]
```
Unpromote a suite: deactivate its deployment so it no longer runs on a schedule
or via the API. The deployment record and its history are retained.
Requires confirmation; pass --yes (or --force) for non-interactive use.
| Flag | Type | Default | Description |
| ---------- | -------- | ------- | ----------------------------------------- |
| `--reason` | `string` | — | Reason recorded in the deployment history |
### `synq-recon upload-config`
Upload reconciliation config to Coalesce Quality
```bash theme={null}
synq-recon upload-config [flags]
```
Parse a YAML configuration file and upload the reconciliation suite
to the Coalesce Quality cloud platform using the UpsertSuiteConfig API.
Authentication (checked in order):
```bash theme={null}
1. Client credentials: --client-id/--client-secret, env vars, or YAML config
2. OAuth token: cached from 'synq-recon auth login' (auto-refreshes if expired)
```
The deployment is controlled by --region, or --endpoint for a staging or
self-hosted one (default: the deployment of the last login, else eu).
Examples:
```bash theme={null}
# Upload using client credentials
synq-recon upload-config config.yaml --client-id=... --client-secret=...
# Upload using OAuth token (after 'synq-recon auth login')
synq-recon upload-config config.yaml
# Upload with a change summary
synq-recon upload-config config.yaml --change-summary "Added new orders reconciliation"
# Upload to a different environment
synq-recon upload-config config.yaml --region us
```
| Flag | Type | Default | Description |
| ------------------ | -------- | ------- | -------------------------------------- |
| `--change-summary` | `string` | — | Human-readable summary of what changed |