Skip to main content
This page is the published copy of the operating guide that ships with the tool as AGENTS.md — in the release archive and in getsynq/synqcli. It is deliberately denser than the rest of this section. Start at Monitors as code for what the YAML declares, and see the CLI reference for every flag.
This is the operating guide for a coding agent using synqcli to declare data quality monitors, SQL tests and deployment rules as code: the loop to follow, the mistakes that cost real time, and what each command does to a workspace. It is written to be acted on top-down. synqcli reconciles a workspace with a YAML file. You declare which monitors and tests belong on which assets; deploy makes the workspace match. That means it creates, it updates, and it deletes — anything in the file’s namespace that is no longer declared goes away. Understanding that one sentence prevents most of the damage this tool can do.

​
1. The loop

1. See what already exists — export Never start from a blank file against a workspace that already has monitors. export writes the current state back out as YAML:
That gives you the real shape of what is deployed, in the format deploy accepts. Edit that rather than authoring from scratch, and you will not silently delete someone’s monitors. 2. Get the schema into your editor
Then put this at the top of every config file, which gives completion and validation as you type:
3. Preview — deploy --dry-run
Prints the create / update / delete plan and touches nothing. Read the delete list every time. This is the step that catches a wrong namespace, a mistyped asset path, or a file that is missing half of what the workspace has. 4. Deploy
Interactive by default: it shows the plan and asks. In CI, add --auto-confirm, but only once the same config has been through --dry-run at least once. 5. Iterate on the diff, not the file Re-run --dry-run after every edit. An empty plan is the goal — it means the workspace matches your file, so the config is now the source of truth.

​
2. Never do these

  • Never run deploy without --dry-run first on a workspace you did not author the config for. Deploy is a reconcile, so an incomplete file is a delete.
  • Never guess a namespace. It is the grouping key: everything under one namespace is reconciled together, and a typo means “this namespace has nothing declared, so delete everything in it”. Get it from export.
  • Never hand-assign monitor ids. They are derived deterministically from the monitor’s identity, which is what makes a re-deploy an update instead of a duplicate. Let the tool compute them.
  • Never edit the published docs or the schema by hand. Both are generated.
  • Never assume a rename is a rename. Changing something in a monitor’s identity produces a new monitor and deletes the old one — with its history. --dry-run shows that as a delete plus a create; look for it.
  • Never point a config at a workspace you have not confirmed. See below.

​
3. Confirm the target

Credentials resolve in this order:
  1. --client-id / --client-secret flags
  2. QUALITY_CLIENT_ID / QUALITY_CLIENT_SECRET
  3. A .env file in the working directory
  4. A browser login, cached and shared with the other Coalesce Quality CLIs
Deployments are named, not spelled out: --region eu|us|au, or --endpoint for a self-hosted deployment. auth login remembers the choice, so later commands need no flag. A wrong region is the most expensive mistake available here — it reconciles the wrong workspace, deleting what it does not find declared.

​
4. What goes in the YAML

One file declares monitors and tests per asset:
  • Monitors watch an asset over time: volume, freshness, field_stats, custom_numeric.
  • SQL tests assert something is true right now: not_null, unique, empty, accepted_values, rejected_values, min_max, min_value, max_value, freshness, relative_time, business_rule, business_query.
  • Deployment rules apply monitors by query rather than by listing assets, so new matching assets are covered without editing the file.
Asset paths can be written in a simplified form and are resolved against the workspace, so you do not need to spell out full warehouse coordinates. The field-by-field reference is the published schema, and it is authoritative in a way prose is not. Read it rather than inferring field names.

​
5. advisor — propose tests for an asset

advisor asks the model to suggest tests for an entity, and can write them straight into a config:
Useful flags: --columns to narrow the scope, --instructions-file for a long prompt, --severity for the default it assigns, --namespace for the group it writes into, and --deploy to deploy immediately. Review what it writes before deploying it. --output then read then deploy --dry-run is the safe order; --deploy skips your review, not the reconcile. Instructions steer it, and being specific pays. Some that work:

​
6. What each command costs

  • schema — free, offline. No credentials, no API call.
  • export — reads the workspace. Cheap.
  • deploy --dry-run — resolves asset paths and diffs against the workspace. Cheap, and always worth it.
  • deploy — writes. The cost is the blast radius, not the runtime: creates, updates and deletes in one pass.
  • advisor — a model call per entity, plus warehouse metadata reads. The only command here with a per-run cost worth thinking about; scope it with --entity-id and --columns rather than pointing it at everything.

​
7. When something fails

The full command and flag reference is generated from the CLI itself and published as the CLI reference. For what the YAML declares and why, start at Monitors as code.