Skip to main content
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.
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:

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

​
Commands

​
synq-recon audit-logs

Inspect reconciliation run results (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
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)

​
synq-recon auth

Manage Coalesce Quality API authentication
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 —synq-endpoint. Examples:

​
synq-recon auth login

Authenticate with Coalesce Quality in a browser
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:

​
synq-recon auth logout

Remove the stored credential for a region
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
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 —synq-endpoint to show one deployment instead of all of them.

​
synq-recon auth token

Print the access token, refreshing it if needed
Print the current access token to stdout, refreshing it first if it has expired or is close to expiring. Useful for scripting:

​
synq-recon auth whoami

Show who you are authenticated as and what permissions you hold
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

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:

​
synq-recon connections

Work with reconciliation connections (data warehouses / databases)
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
synq-recon connections remote bootstrap
Print a .connections.yaml for selected cloud DWH connections
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:
synq-recon connections remote list
List DWH connections in the cloud workspace

​
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)
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.

​
synq-recon deployment history

Show the change history of a deployment
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.

​
synq-recon deployment list

List promoted deployments in the workspace

​
synq-recon deployment pause

Pause a deployment (suppress scheduled and API-triggered runs)
Pause a deployment so it stops running on its schedule and via the API. Without —until the pause is indefinite (until ‘deployment resume’).

​
synq-recon deployment resume

Resume a paused deployment

​
synq-recon deployment set-annotations

Replace a deployment’s annotations

​
synq-recon deployment update

Update a deployment’s schedule, API-triggering, drill, or execution-timeout setting
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.

​
synq-recon drill-deeper

Continue a previous run’s drill-down from where it stopped
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:

​
synq-recon dump-suite

Parse a YAML config and dump the proto Suite as JSON
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:

​
synq-recon promote

Promote a suite config to a scheduled/triggerable deployment
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.

​
synq-recon recheck

Re-run a previous run’s queries to check whether its differences still exist
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:

​
synq-recon run

Run check and optionally drill on mismatch
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:

​
synq-recon run-check

Quick check for differences (Stage 1)
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:

​
synq-recon run-drill

Bisection drill-down to locate differences (Stage 2)
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:

​
synq-recon run-remote

Run a suite on the Coalesce Quality backend (ad-hoc), not locally
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:
A client-generated invocation id makes submission idempotent: re-running with the same —invocation-id will not start a duplicate run.

​
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
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)

​
synq-recon suite

Manage reconciliation suite configs in the Coalesce Quality workspace
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)
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.

​
synq-recon suite delete

Delete a suite config (soft 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
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
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).

​
synq-recon suite versions

List the version history of a suite config

​
synq-recon suite yaml

Render a suite config as canonical recon 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:

​
synq-recon trigger

Trigger an on-demand run of a promoted deployment
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.

​
synq-recon unpromote

Deactivate a deployment (stop scheduling and API triggers)
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.

​
synq-recon upload-config

Upload reconciliation config to Coalesce Quality
Parse a YAML configuration file and upload the reconciliation suite to the Coalesce Quality cloud platform using the UpsertSuiteConfig API. Authentication (checked in order):
The endpoint is controlled by —synq-endpoint (default: developer.synq.io:443). Examples: