Skip to main content
This page is generated from the synq-scout command tree, so it always matches the released binary. For what Scout does and how to deploy it, see Scout AI; for using its tools from an MCP client, see Scout MCP.
Scout investigates your data: it triages issues, works out what changed and suggests tests, using your warehouse and your Coalesce Quality workspace. It runs three ways, and the same tools back all of them:
Scout only ever connects outward, so it can sit inside your network with nothing exposed. Run synq-scout health after configuring it, and synq-scout auth login to authenticate as yourself rather than with a client secret. With no subcommand, Scout runs the agent.

​
Global flags

These apply to every command.

​
Commands

​
synq-scout agent

Run the Scout agent, working tasks from Coalesce Quality
Run Scout as a long-lived agent. It connects out to Coalesce Quality, picks up tasks as they are created, and works them against your warehouse — nothing needs to reach in from outside your network. This is the mode the container runs by default, and the mode an on-premise deployment uses. Database connections are validated on startup so a bad credential fails here rather than midway through a task; —require-valid-connections turns a partial failure into a refusal to start.

​
synq-scout 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 —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:

​
synq-scout 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 the permissions synq-scout’s tools need, not everything your account could grant — a tool whose permission is not granted is left out of the MCP tool list rather than failing when called. 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-scout its own credential instead. Pass —coalesce to sign in with your Coalesce account instead. The credential then carries your Coalesce Quality roles in the organization’s workspace rather than the permissions synq-scout asks for. —organization picks the Coalesce organization; without it the login asks you to choose one. Examples:

​
synq-scout 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-scout 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 —endpoint to show one deployment instead of all of them.

​
synq-scout 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-scout auth use

Show or set the deployment commands use by default
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:

​
synq-scout auth whoami

Show who you are authenticated as and which permissions are granted
Call the Coalesce Quality IAM API and print the current identity, workspace and granted permissions. Uses the standard credential resolution (client credentials, then a pre-issued token, then the browser login).

​
synq-scout health

Check that Scout can reach everything it needs
Verify this deployment’s configuration. Loads the config, fetches this deployment’s settings from the Scout control plane (which confirms both credentials and reachability, and reports the workspace it resolved to), and sends a trial prompt to every configured model. Warehouse connections are listed as discovered, not connected to. Exits non-zero if the control plane or any model is unreachable, so use it after a configuration change, or as a container health check, and a bad deployment fails visibly rather than on its first task.

​
synq-scout issue

Triage one or more issues by their IDs. Multiple issues can be specified using —issue-id flag multiple times.

​
synq-scout mcp

Serve Scout’s tools to an MCP client over stdio
Run Scout as an MCP server, speaking the protocol on stdin and stdout. Point any MCP client at it — Claude Code, Claude Desktop, Cursor — and Scout’s tools become available in that client, running against your own warehouse and Coalesce Quality workspace. The same tools are individually invocable from a shell with synq-scout tools. Because stdout carries protocol frames, all logging goes to stderr.

​
synq-scout sre

Triage open issues once, now
Run one triage pass over open issues and exit. This is the same work the agent does continuously, invoked on demand — useful to try Scout against your data before deploying it, or to re-run triage after changing configuration. Narrow it to particular issues with —issue-ids; with none, every open issue is considered. Triage normally skips an issue whose status says it has been handled already; —ignore-status-check triages it regardless. Note —dry-run defaults to true here, so nothing is written back until you pass —dry-run=false. To triage specific issues by id, synq-scout issue is the narrower command.

​
synq-scout tester

Suggest data quality tests for tables
Run one pass of test suggestion and exit. Scout inspects the tables you name, and proposes tests appropriate to what it finds in them. Restrict it to particular tables with —table-fqn, repeated per table; a table is identified by its fully-qualified name. Note —dry-run defaults to true here, so suggestions are reported without being created until you pass —dry-run=false.

​
synq-scout tools

Inspect and invoke Coalesce Quality Scout MCP tools directly from the CLI
Expose the same tools the MCP server serves as one-shot CLI commands.
Arguments can be supplied either as individual —<arg> flags (derived from the tool’s input schema) or as a single —json object, but not both at once.

​
synq-scout tools add_comment

Adds a Markdown comment to an issue or an incident, as the calling user. Use it to record context, hand-off notes or your reasoning for other readers.

​
synq-scout tools apply_service_account_changes

Writes a planned change set, all of it or nothing. The call is gated. Without confirmed=true it writes nothing and returns the plan. Show the plan to the user. Call again with confirmed=true only after the user approves. If the service accounts changed after the plan, the call is refused: plan again. A retry is safe: a change set that is already in place returns applied.

​
synq-scout tools batch_entity_annotations

Returns the annotations of the given entities. Annotations are name and value labels. Filters and ResolverQL selections match on them: with_annotation(“<name>”) selects the entities with a name, and with_annotation(“<name>”, values=[“<value>”]) the entities with a value. Put all the entities in one call. One call for a hundred entities costs the same as one call for one entity. If you do not know the annotation names yet, call list_annotations first. get_entity_details and batch_entity_details do not return annotations.

​
synq-scout tools batch_entity_details

Returns the details of many entities in one call. Use it in place of many get_entity_details calls. Each entity has table_metrics and table_info when they are available. Read the size and freshness of a table there before you query it.

​
synq-scout tools batch_executions

​
synq-scout tools batch_urls

Returns links to the app pages of entities, issues, incidents, data products and owners. You can set all id lists in one call.

​
synq-scout tools browse_folders

Returns one level of the folder hierarchy. Without parent_folder_entity_id, it returns the roots: the top-level integrations and containers. With it, it returns the direct sub-folders and the direct members of that folder. To go deeper, browse each returned sub-folder. To list the entities of a folder, call list_folder_members.

​
synq-scout tools create_incident

Creates an incident that groups related issues under one name. Use it when the user escalates a set of issues that need one coordinated response.

​
synq-scout tools create_monitors

Creates custom monitors. Give each new monitor a new random UUID as id. The id is the identity of the monitor and is used as given. The call never changes an existing check: an id that names one is refused, and the response names that check. To change it, read it, show the user the change, and call update_monitors after the user approves. When the whole call is refused this way, requires_user_confirmation is true. Do not retry a create blind: a second call with a new id makes a second monitor. After a timeout, call list_monitors for the asset to see if the first call created it. For a DWH table, use create_table_stats_monitor, which reads cheap warehouse metadata. Use the table_stats sub-type here for a view, or when a query on each run is intended. A table_stats monitor on a table is refused unless allow_custom_table_stats_on_table is true. If you are not sure which check type fits, call describe_check_types.

​
synq-scout tools create_sql_tests

Creates SQL tests. The id is the identity of the test. A UUID is used as given. Any other string is a slug, and the id comes from the slug, the asset and the test type. Use a descriptive slug: the same slug for the same test gives the same id. The call never changes an existing check: an id that names one is refused, and the response names that check. To change it, read it, show the user the change, and call update_sql_tests after the user approves. When the whole call is refused this way, requires_user_confirmation is true. Do not retry a create blind. After a timeout, the first call can hold the slug, and the refusal looks the same as for another check. Call list_sql_tests for the asset to see if the first call created the test. To put the same tests on many tables, use deploy_sql_test_deployment_rule. A rule keeps the tests in sync when tables and columns change. If you are not sure which check type fits, call describe_check_types.

​
synq-scout tools create_table_stats_monitor

Creates and deploys a table-stats monitor on one DWH table. It reads cheap warehouse metadata (row count, load delay). It works only on tables: a view has no such metadata. For a view, use create_monitors with the table_stats sub-type, which queries the view on each run. A call on an asset that is not a table is refused. If you are not sure which check type fits, call describe_check_types. An asset has at most one table-stats monitor, and its id comes from the asset. If the asset already has one, the call is refused with requires_user_confirmation and names that monitor. No field confirms it. To change that monitor, read it, show the user the change, and call update_table_stats_monitor after the user approves. That tool replaces all of the metrics.

​
synq-scout tools decide_recommendation

Dismisses, ignores or restores one recommendation for the whole workspace. Decide only if the user asks or agrees. Coalesce Quality reads the reason to improve its recommendations.

​
synq-scout tools delete_alert

Deletes an alert by id or fqn. The call is gated. Without confirmed=true it deletes nothing and returns the alert it would delete. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_check_categorisation_rule

Deletes a categorisation rule of the workspace. Its checks fall back to the next rule that matches them, or become uncategorised. A delete of an unknown or deleted rule succeeds. The call is gated. Without confirmed=true it deletes nothing and returns the number of checks the rule categorises now. Show it to the user. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_data_product

Deletes a data product. It is a soft delete unless purge is true. A delete of an unknown or deleted product succeeds. The call is gated. Without confirmed=true it changes nothing. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_deployment_rule

Deletes a deployment rule and the monitors it owns. The call is gated. Without confirmed=true it changes nothing and returns the monitors it would delete. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_domain

Deletes a domain. It is a soft delete unless purge is true. A soft delete keeps the sub-domains, under a deleted parent. The backend refuses a purge while the domain has sub-domains. A delete of an unknown or deleted domain succeeds. The call is gated. Without confirmed=true it changes nothing and returns the number of sub-domains. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_monitors

Deletes custom monitors by id. A monitor that the app or another config owns is gated: the call deletes nothing and lists it in ownership_conflicts. Call again with its id in overwrite_confirmed_ids only after the user approves.

​
synq-scout tools delete_owner

Deletes an owner and all of its ownerships. If ownership_id is set, it deletes only that ownership. The owner is soft-deleted unless purge is true. A delete of an unknown or deleted owner succeeds. The call is gated. Without confirmed=true it changes nothing and returns the number of ownerships it would delete. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_saved_view

Deletes a saved view. A delete of an unknown or deleted view succeeds. The call is gated. Without confirmed=true it changes nothing. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_sql_test_deployment_rule

Deletes a SQL test deployment rule and all of its tests, with their run history. The call is gated. Without confirmed=true it changes nothing and returns the tests it would delete. Call again with confirmed=true only after the user approves.

​
synq-scout tools delete_sql_tests

Deletes SQL tests by id. A test that the app or another config owns is gated: the call deletes nothing and lists it in ownership_conflicts. Call again with its id in overwrite_confirmed_ids only after the user approves. A test from a SQL test deployment rule is refused with FailedPrecondition. Make the selection of the rule smaller, or delete the rule with delete_sql_test_deployment_rule, which deletes all of its tests.

​
synq-scout tools deploy_deployment_rule

Creates or updates a deployment rule and deploys its monitors. A title that names an existing rule updates that rule. The call is gated. Without confirmed=true it changes nothing and returns the impact: the monitors it would delete, the monitors whose settings would change, and the counts. Show the impact to the user. Call again with confirmed=true only after the user approves. Never confirm on your own: the impact is how you see that an update deletes monitors.

​
synq-scout tools deploy_sql_test_deployment_rule

Creates or updates a SQL test deployment rule and deploys its tests on every table and view it selects. Use it, not create_sql_tests, to put the same tests on many tables. A title that names an existing rule updates that rule. The tests of a rule cannot be changed with update_sql_tests or delete_sql_tests; change the rule. The call is gated. Without confirmed=true it changes nothing and returns the tests it would create, update and delete. Show them to the user. Call again with confirmed=true only after the user approves. Never confirm on your own: a changed selection deletes the tests of tables it no longer selects, with their run history.

​
synq-scout tools describe

Show a tool’s description, scopes and input/output schemas

​
synq-scout tools describe_check_categorisation

Explains how check categorisation works: the two dimensions, the three sources of a category and their precedence, the order of the rules, the matcher grammar and the steps to write a rule. Call it before you create or edit a rule.

​
synq-scout tools describe_check_types

Returns the check types this server can create (custom monitors, SQL tests, table-stats monitors), their sub-types, and which one fits which goal. Call it before you create a check when you are not sure which type fits.

​
synq-scout tools describe_resolver_ql

Returns the reference for ResolverQL selection queries: syntax, functions, asset type names, recipes, and the metric, sensitivity and severity values. Call it before you write a selection that you are not sure how to express.

​
synq-scout tools exclude_from_monitoring

Stops automatic monitoring of the given assets. Use this tool, not an edit of a broad rule’s selection: a rule edit replaces a definition that can own hundreds of monitors. Each asset gets its own exclusion, so the call does not read or change the exclusions that already exist. You can call it again with the same assets. The backend keeps no exclusion for an asset that no rule selects. Such assets are in not_selected_entity_ids. If a rule selects them later, exclude them again. The call is gated. Without confirmed=true it changes nothing and returns the monitors that would stop. Call again with confirmed=true only after the user approves.

​
synq-scout tools execute_monitor

Runs the query of an existing monitor and returns its data from the database. To find the root cause, you can segment the data by more columns than the monitor has. Read table_metrics.num_rows of the monitored table first. If the table is large, set a narrow time_partition_from and time_partition_to window.

​
synq-scout tools folder_of

Returns the folders of each given entity. The folders table has every ancestor with its own id, so you can browse or list any level directly. To find the siblings of an entity, find its parent handle in folders. Then pass the folder_entity_id of that entry to list_folder_members.

​
synq-scout tools get_alert

Returns alerts by id or fqn with their full configuration: the asset selection, the targets and the kind settings. An unknown id or fqn is left out of the response and is not an error.

​
synq-scout tools get_code

Returns the source code of an entity: SQL definitions, dbt and SQLMesh models, Python scripts and other transformation code. The call also reads the linked identities of the entity, for example a dbt model and the warehouse table it materializes. Do not call it again with a related entity id. If the response is empty, no linked identity has code. An entity can have several pieces of code, for example the CREATE statement and the body of a routine, or the source and the compiled SQL of a dbt model. All pieces are in codes, the most useful first. If one piece is enough, read codes[0]. Bodies are cut to a size budget, so the default call is safe on any entity. To read more, select pieces with code_types or piece_ids, raise max_content_bytes, or page one body with content_offset. If the entity can hold repository files, call first with detail_level=DETAIL_LEVEL_METADATA_ONLY to see the pieces and their sizes. To know if the response is complete, read these fields:
  • total_pieces larger than the length of codes: a filter or the listing cap
  • content_hint on a piece: what part of the body is missing, and the call
  • stored_partial: the body was cut at ingestion, and no offset reaches the
  • unavailable_sources not empty: a source could not be read, so there can be
tool_usage_guidance tells which of these applies. It is absent if the response holds all the code of the entity.

​
synq-scout tools get_commit_diff

​
synq-scout tools get_common_upstream_dependencies

Returns the upstream dependencies that two entities share, directly or transitively.

​
synq-scout tools get_coverage_summary

Counts data product and owner coverage for up to 20 named selections in one call. It lists no assets. Use this tool first for any coverage question. Give one selection for each bucket of the report, for example each type, platform, folder or domain. Each comes back as a row with its key. Selections can overlap, so do not add rows to get a workspace total. For a workspace total, add a selection for it.

​
synq-scout tools get_data_product

Returns data products by id, in full, with the membership definition as ResolverQL. Unknown and deleted ids are left out of the response, with no error.

​
synq-scout tools get_database_change_details

Returns the full diffs of database changes, in input order. Call it only for changes with has_details=true. Pass all change ids in one call.

​
synq-scout tools get_database_coordinates_from_entity

Returns the database coordinates of a table entity: dialect, connection, instance, database, schema and object name.

​
synq-scout tools get_deployment_rule

​
synq-scout tools get_domain

Returns domains by id, in full, with the membership definition (query parts as ResolverQL). Unknown and deleted ids are left out of the response, with no error.

​
synq-scout tools get_downstream_dependencies

Returns the downstream dependencies of the given entities, up to max_distance hops.

​
synq-scout tools get_entity_access

Returns how one entity is used over the window: what loads, runs, builds and reads it (usage), how popular it is, who reads and writes it, and when in the day and week. Times are in the user’s time zone. Use it for “how is this table used” and “what runs this table or model”. For what a job runs, use get_query_activity(issuer_entity_id=…).

​
synq-scout tools get_entity_details

Returns the details of one entity: its properties, metadata and current state. For a warehouse table or view, the response has table_metrics, the latest row count and freshness. Read it before an unbounded query on the table. It also has table_info: the owner, creation time and size that the warehouse reports.

​
synq-scout tools get_entity_from_database_coordinates

Returns the entity ids of the warehouse tables that match a SQL table name. A partial name can match more than one table, for example the same table name in two schemas. The tool returns all matches.

​
synq-scout tools get_entity_impact

Returns the entities and systems that a problem on the entity affects. Use it for incident response and to assess the impact of a change.

​
synq-scout tools get_entity_knowledge

Returns the knowledge the team keeps about entities: the description people wrote, and the pinned knowledge pages (runbooks, glossaries, metric definitions, imported Confluence or Notion pages). Use it to learn what an entity is for and how the team works with it. The description from the source (a warehouse comment, a dbt description) is in get_entity_details. Send all entities in one call. Read the pages with get_knowledge_pages. An entity in without_knowledge_entity_ids has no knowledge. That is a final answer, not a reason to retry, and it tells nothing about entity health.

​
synq-scout tools get_entity_metrics

Returns raw metric time series (row counts, last load times) for an entity. For a logical asset such as a dbt model, it reads the physical table that the asset builds.

​
synq-scout tools get_entity_overlays

Returns the owners and data products that claim each entity id. The response has one entry for each requested id, in request order. Use it on ids from get_entity_details, search_entities, get_lineage, an issue or an alert. To find the assets that nothing claims, use list_entity_coverage.

​
synq-scout tools get_immediate_downstream_dependencies

​
synq-scout tools get_immediate_upstream_dependencies

Returns only the direct upstream dependencies of the given entities. It is faster than get_upstream_dependencies.

​
synq-scout tools get_incident_details

Returns one incident with its state, its attached issues and its comment thread. If you have an incident id, use this tool, not list_open_incidents.

​
synq-scout tools get_issue

​
synq-scout tools get_issue_comments

​
synq-scout tools get_issue_details

Returns one issue with its comments, its trigger monitor and the schema of its main entity.

​
synq-scout tools get_issue_impact

​
synq-scout tools get_join_patterns

Shows how to join a table to other tables. Use it before you write a join. The data comes from the SQL that builds the tables, views and models of the workspace, and from the queries in the warehouse’s query history. Each pattern is one join key, with each join type it is joined with in join_types. evidence says where it was seen. The patterns that SQL definitions make come first, the ones that the most entities use first. Then come the patterns that only queries make, the ones that the most users run first. query_history says how many queries made the join and who ran them: kind says if it was a tool, people or service accounts. For a tool, tool names it, like looker, and entity_id the dashboard, model or task when the query names it. A join that people make often is a strong hint, as no SQL definition shows it. A join that only a few queries by one user make is left out. The queries of Coalesce Quality itself are never counted. query_history_left_out counts them, and the queries of service accounts when exclude_service_accounts is set. How to read a pattern:
  • Each part of key compares column of the requested table with
  • Put all parts of key in the ON clause. More than one part is a
  • join_types lists how the key is joined, the most used first. keeps
  • If unique_match is true, each row matches one row or none.
  • If unique_match is false, the join can return more rows than the
Counts are per pattern, for the join of the requested table with that pattern’s other table. Do not add up the counts of patterns with different other tables to count one join. same_table_entity_ids lists the other ids of the same table, like the Coalesce node or the dbt model that builds it. Their joins are already in the patterns, so do not call again with one of them. tables gives the SQL name, the row count and the unique keys of each table. You do not need get_database_coordinates_from_entity or get_schema for them. To get the join between two tables, set other_entity_id. To get the joins on one column, set column. The list shows only joins whose two sides are known columns of known tables. The response is in pages. If next_offset is set, call again with offset set to it. If no SQL makes such a join, tool_usage_guidance says so.

​
synq-scout tools get_knowledge_pages

Returns knowledge pages: the content as Markdown, the place in the page tree, the owners, and the pinned entities and pages. The content has a size limit and is filled in request order. tool_usage_guidance gives the call that reads the rest.

​
synq-scout tools get_latest_executions

Returns the latest execution of each given entity. It returns only executions where the entity is in executed_entity_ids: runs of a model, monitor, task or test. A table does not execute, so it gets no result.

​
synq-scout tools get_lineage

Returns the lineage of the given entities as upstream and downstream entity pairs. Upstream entities feed the given entities. Downstream entities depend on them.

​
synq-scout tools get_monitor

Returns the full configuration of one monitor: type, metrics, sensitivity, severity, schedule, segmentation, filters and state. Use it before you edit a monitor, or to explain why it did or did not fire. Get the monitor_entity_id from list_checks or from an issue.

​
synq-scout tools get_monitor_predictions

Returns recent model predictions for a monitor: actual values, expected values, confidence bands and anomaly patterns for each time bucket. Use it to see if the anomaly model is calibrated, for example if it predicts negative row counts.

​
synq-scout tools get_owner

Returns owners by id, in full: the contacts and, by default, the ownerships with their assets and alert configuration. Unknown and deleted ids are left out, with no error.

​
synq-scout tools get_query_activity

Returns what one data platform login, job, tool, service account or person read, built and wrote over the window, what its queries cost per compute, and when it works. Name at most one of them. If you name none, it returns where the queries and compute of the workspace go, per group of logins, and the most read entities.

​
synq-scout tools get_saved_view

Returns saved views by id, in full: the selection as ResolverQL, the display configuration, sharing, grants, the permissions of the calling user and the pin state. Ids that the calling user cannot see are left out.

​
synq-scout tools get_schema

Returns the schema of a table: column names, types and constraints. To find how other tables join this table, use get_join_patterns.

​
synq-scout tools get_sql_test_deployment_rule

Returns one SQL test deployment rule with its tests, schedule, severity and selection.

​
synq-scout tools get_upstream_dependencies

Returns the upstream dependencies of the given entities, up to max_distance hops, with the closest first.

​
synq-scout tools get_upstream_sources

Traces lineage to the roots and returns the original data sources: dbt sources, SQLMesh external models, or the furthest upstream entities found.

​
synq-scout tools iam

Returns the authenticated caller: workspace, granted scopes, token subject, and the user and integration of the token. Use it if the user asks who they are or what they can do, or if an authorization error is not clear.

​
synq-scout tools list

List available MCP tools

​
synq-scout tools list_access_signals

Lists the entities that one access signal names over the window, such as the tables nobody reads. Use it for cleanup and cost questions about the workspace or a selection. It names entities and tools, never a login.

​
synq-scout tools list_alerts

Lists the alerts of the workspace as short rows. Filter by kind, owner, name or config namespace. The response also tells if the incident-owner alert of the workspace is on. That alert notifies the owner of each incident and has no other configuration.

​
synq-scout tools list_annotations

Lists the annotation names and values that the workspace uses, with the number of entities that have each.

​
synq-scout tools list_categorised_checks

Lists the checks of the workspace with their category on both dimensions. The filters combine. For example, one call finds the checks with no governance category, the checks that a rule categorised, or the checks with a pinned category. Get the entity_id for set_check_category here. annotation_keys in the response gives the annotation keys of the checks on the page. A rule’s annotation_matches uses these keys. Set include_check_details to also get the annotation values.

​
synq-scout tools list_check_categories

Returns the category vocabulary of the workspace. Per dimension, it gives the category names in use, the number of checks with each name, and if a workspace or platform rule produces the name. It also gives the number of uncategorised checks per dimension. Use a name from this list. Do not make a new spelling for a concept that has a name.

​
synq-scout tools list_check_categorisation_rules

Lists the categorisation rules of the workspace, its own and the platform rules, in the order they are tried. Each row gives the number of checks the rule categorises now. Pass ids, or set include_matcher, to also get the matcher and etag. The response also gives the state of the recategorisation sweep, so you can see if a recent change is complete.

​
synq-scout tools list_checks

Lists the data quality checks on an entity: the checks set on it and the checks it inherits from upstream entities. It also returns how downstream queries use its columns.

​
synq-scout tools list_commits

Lists the git commits that change an entity or its upstream dependencies, the most recent first.

​
synq-scout tools list_data_product_members

Lists the entity ids of the assets that belong to a data product now, paginated.

​
synq-scout tools list_data_products

Lists the data products in the workspace, paginated. Definitions are left out unless include_definition is true. For one product in full, call get_data_product.

​
synq-scout tools list_database_changes

Lists the schema and SQL definition changes that Coalesce Quality detected on a warehouse entity, the most recent first. A schema change is a column that is added, removed or changed. A SQL change is a new view or materialized view definition. For changes in git, use list_commits. Monitor changes are not included.

​
synq-scout tools list_deployment_rules

Lists the query, exclusive-query and product deployment rules. Use it to find the id of a rule to read, preview or delete.

​
synq-scout tools list_domain_members

Lists the entity ids of the assets that belong to a domain now, paginated. It includes the assets of the data products and domains that the definition references, and of the sub-domains.

​
synq-scout tools list_domains

Lists the domains in the workspace, paginated. Use parent_id to walk the hierarchy. Definitions are never included. For the definition of one domain, call get_domain.

​
synq-scout tools list_entity_coverage

Lists the assets of a selection by coverage state: for example the assets in no data product, or the assets with no owner. Call get_coverage_summary first. Use this tool only to name assets. total_count gives the number without paging. If the list is very large, narrow the selection with ResolverQL (with_type, in_folder, in_domain) and do not page through it. A selection of more than 100,000 assets is rejected.

​
synq-scout tools list_executions

Lists the executions of the given entities, newest first. Use it to see when an entity ran, with what status, and the error messages.

​
synq-scout tools list_folder_members

Lists the entity ids in a folder, in pages. By default it returns only the direct members. Set deep=true to include the members of all sub-folders. Use a large limit, not many small pages: each deep page repeats work on the server.

​
synq-scout tools list_history

Lists past incidents and issues related to an issue. Use it to find patterns and problems that occur again.

​
synq-scout tools list_integration_health

Lists the enabled integrations that are not healthy, the worst first, with the status, time and message of the last run and the time of the last success. For changes that improve a working integration, use list_recommendations.

​
synq-scout tools list_knowledge_pages

Lists the knowledge pages of the workspace by name: glossaries, metric definitions, runbooks, onboarding notes. Most pages are not pinned to an entity. Read the pages you need with get_knowledge_pages.

​
synq-scout tools list_monitor_segments

Lists the segments of a monitor, with the raw value and the label of each. Use it to see what the monitor is split by, which segments have no label, and which segment to pass to get_monitor_predictions. A segment appears only after the monitor observes data for it. A monitor that has not run yet has no segments.

​
synq-scout tools list_monitoring_exclusions

Tells which assets have no automatic monitoring and which rule turned it off. The rule tools cannot tell this: the counts on an exclusion rule give the size of its own selection. With entity_ids, you get an exact verdict per asset. This is the check to do after an exclusion. Without entity_ids, you get the workspace inventory. In the inventory, an exclusion that is a selection is shown as that selection, not as a list of assets.

​
synq-scout tools list_monitors

Lists custom monitors. Use it to find the id of a monitor to change or delete.

​
synq-scout tools list_open_incidents

​
synq-scout tools list_open_issues

​
synq-scout tools list_owners

Lists the owners in the workspace, paginated, with the contact count of each. Set include_ownership_counts to also get the ownership count of each owner.

​
synq-scout tools list_ownerships

Lists ownerships, with the asset selection and the alert configuration of each. Give owner_id for all ownerships of one owner, or ownership_ids for a set across owners.

​
synq-scout tools list_platform_users

Lists the data platform logins of the workspace, the largest share of activity first: the classification of each, its service accounts and the evidence. The first page has a summary of how much activity is classified. Set full for each slice and the cost per platform.

​
synq-scout tools list_recommendations

Lists the open recommendations of the workspace: changes that improve a working setup, with what to change and where. For integrations that fail, use list_integration_health.

​
synq-scout tools list_saved_views

Lists the saved views that the calling user can see: their own views, the views shared with the workspace and the views granted to them. Narrow with relationships, context and only_pinned.

​
synq-scout tools list_service_account_suggestions

Suggests service accounts for the logins that the evidence shows are not a person. Each suggestion is a change set to pass to plan_service_account_changes unchanged. It writes nothing.

​
synq-scout tools list_service_accounts

Lists the service accounts of the workspace with their matchers, then the built-in accounts, in the order they apply, and the person links. For a built-in account, the matchers are not listed. Only whether its reads count can change.

​
synq-scout tools list_sql_test_deployment_rules

Lists SQL test deployment rules with the number of tests each one deploys. Use it to find the id of a rule to read, preview or delete.

​
synq-scout tools list_sql_tests

Lists SQL tests. A test with deployment_rule_id comes from a SQL test deployment rule. update_sql_tests and delete_sql_tests refuse such a test. Change the rule instead: read it with get_sql_test_deployment_rule. A rule change applies to every table the rule selects.

​
synq-scout tools list_table_stats_monitors

​
synq-scout tools list_users

Lists the users of the workspace, sorted by email. Call it before you set owner_email in update_incident, so that the email is a workspace user.

​
synq-scout tools plan_service_account_changes

Shows what a change set would change, and writes nothing: each login slice whose classification changes, the counted reads it adds or removes, and the entities whose rank changes most. A change to an existing account or person link is a patch: only the fields set change, and matchers are added and removed by id. A new item with no id gets one here. Pass the returned changes and plan_token to apply_service_account_changes unchanged.

​
synq-scout tools preview_check_categorisation_rule

Returns what a candidate rule would change, without saving it. The call resolves the candidate against the live rules of the workspace, so scope, priority, pins and producer categories all apply. matched_count is what the candidate matches, affected_count is what it really changes. Always preview before you save: a broad matcher can recategorise a large part of a workspace. The call also validates the candidate. A matcher that does not compile is refused, not returned as a preview with zero matches. An unknown attribute value is refused with its name. A bad CEL expression or annotation regex returns an invalid-argument error with the compiler message. Fix the matcher from that message, do not send it again unchanged. save_check_categorisation_rule refuses it for the same reasons.

​
synq-scout tools preview_deployment_rule

Shows what a deploy of the rule would do now: the monitors it would create, delete and keep, and the assets it would skip. It writes nothing. It also validates the query: a malformed resolver_ql returns an invalid-argument error with the parse message.

​
synq-scout tools preview_sql_test_deployment_rule

Shows what a deploy of the rule would do now: the tests it would create, update, delete and keep, and the tables it would skip. It writes nothing. It also validates the query: a malformed resolver_ql returns an invalid-argument error with the parse message.

​
synq-scout tools profile_columns

Returns statistics of the values in the given columns. Only string, numeric and time columns get a profile. The tool ignores other columns. Read table_metrics.num_rows from get_entity_details first. If the table is large, set a narrow time_partition_from and time_partition_to window.

​
synq-scout tools resolve_query

Evaluates a ResolverQL selection and returns the matched entity ids, in pages. Use it to see which entities a selection matches before you deploy monitors on it, or to find entities. If the selection is not valid, the tool returns an invalid-argument error with the parse message. Correct the selection and call again.

​
synq-scout tools run_sql_test_again

Runs a SQL test again with the time values of an earlier execution, and returns the result of the new run. Use it after a data fix, or to triage a failure, so the run checks the same rows as the earlier execution. The run uses the current SQL of the test. {{ executed_at }}, {{ last_executed_at }} and {{ last_passed_at }} get the values the earlier execution used, so a test without these placeholders simply runs again. Later scheduled runs do not take their time values from this run. The run queries the warehouse, so ask the user before you call it.

​
synq-scout tools sample_column_values

Returns the frequency of values in the given columns. Read table_metrics.num_rows from get_entity_details first. If the table is large, set a narrow time_partition_from and time_partition_to window.

​
synq-scout tools sample_entities

Returns the approximate number of entities per type that match a search query. Use it to see which kinds of entities exist before you call search_entities. It costs much less than search_entities.

​
synq-scout tools save_alert

Creates or updates an alert. With id, the alert must exist and the call updates it. Without id, fqn is the key: the call updates the alert with that fqn, or creates it. A repeated call never makes a second alert. To create, send name, fqn, targets and the settings of one kind. The issue_lifecycle and schema_change kinds also need resolver_ql. An update is a patch: send only what changes. Omitted fields, omitted settings fields and the stored targets stay. add_targets and remove_targets edit the target list, targets replaces it. The kind cannot change. If the alert changed after this call read it, the call writes nothing and fails. Call again to apply the patch to the new state. On a partial failure, alert is what was stored and message names the part that failed. The call is gated. Without confirmed=true it writes nothing and returns the plan. Show the plan to the user. Call again with confirmed=true only after the user approves. Never confirm on your own.

​
synq-scout tools save_check_categorisation_rule

Creates or updates a categorisation rule of the workspace. Omit id to create, give an existing id to update. The call then schedules the sweep that recategorises the existing checks. The call is gated. Without confirmed=true it changes nothing and returns the impact. Preview the rule first and show the impact to the user. Call again with confirmed=true and the id the gated call returned, only after the user approves. If the save reassigns checks that have a different category, it also needs overwrite_confirmed=true. Both are approvals from the user. Never set either on your own. You cannot edit a platform rule. To change what it does, create a workspace rule. Every workspace rule is tried before every platform rule, whatever the priorities. A matcher that does not compile is refused before the gate, with the compiler message. Do not send it again unchanged. To edit a rule whose stored matcher does not compile, send a new matcher with the edit. A concurrent edit is refused. The write uses the etag if you give one, or else the version the call read at its start. On a conflict, read the rule again and start again. The same call again does not fix the conflict.

​
synq-scout tools save_data_product

Creates or updates a data product. If a definition is given, it replaces the membership definition in the same call. To create, omit id or give a new UUID. To update, give an existing id. On update, an omitted field stays the same. The call is gated. Without confirmed=true it changes nothing and returns the impact. Show the impact to the user. Call again with confirmed=true only after the user approves. A product that an external source (for example Atlan) manages also needs overwrite_confirmed=true. Never confirm on your own.

​
synq-scout tools save_domain

Creates or updates a domain. If a definition is given, it replaces the membership definition in the same call. To create, omit id or give a new UUID. To update, give an existing id. On update, an omitted field stays the same. A parent or a reference that makes a loop is refused. The call is gated. Without confirmed=true it changes nothing and returns the impact. Show the impact to the user. Call again with confirmed=true only after the user approves. A domain that an external source (for example Atlan) manages also needs overwrite_confirmed=true. Never confirm on your own.

​
synq-scout tools save_owner

Creates or updates an owner, and creates or updates the ownerships listed under it, in one call. An owner is a team or a person with contacts. An ownership assigns assets to the owner and sets the alerts for them. An owner gets no alerts until an ownership assigns it assets. To create, omit id. To update, give an existing id. On update, an omitted field stays the same. If you assign a data product that another ownership covers, the data product moves to this ownership. The call is gated. Without confirmed=true it changes nothing and returns the impact. Show the impact to the user. Call again with confirmed=true only after the user approves. An owner that an external source (for example Atlan) manages also needs overwrite_confirmed=true. Never confirm on your own.

​
synq-scout tools save_saved_view

Creates or updates a saved view: a named ResolverQL selection with display configuration and sharing. To create, omit id. To update, give an existing id. On update, an omitted field stays the same. The call is gated. Without confirmed=true it changes nothing and returns the impact. Show the impact to the user. Call again with confirmed=true only after the user approves. To edit a view that the calling user does not own, or to change visibility or grants, also set overwrite_confirmed=true. Never confirm on your own.

​
synq-scout tools search_entities

Searches entities by name, description and other text, and returns the full entity details of each hit. Each hit has table_metrics when it is available. Use it to decide if a table is safe to query without a partition filter.

​
synq-scout tools send_test_alert

Sends a static test message to targets, or to the targets of a saved alert (id or fqn). Returns, per target, if the message was handed to the channel. Use it to find a wrong channel name or webhook before the alert is in use. The call stores nothing. The message does not use the template or the data of the alert. The call is gated, as it sends real messages. Without confirmed=true it sends nothing. Call again with confirmed=true only after the user approves.

​
synq-scout tools set_alert_enabled

Pauses or resumes an alert. With incident_owner_alert=true, it turns the incident-owner alert of the workspace on or off. The call is gated. Without confirmed=true it changes nothing. Call again with confirmed=true only after the user approves.

​
synq-scout tools set_check_category

Sets or clears the category pinned on specific checks. A pin outranks the producer category and every rule, and stays when the rules change. Use a pin only for exceptions, and a rule for anything that applies to many checks. The dimensions are independent. Omit a field to keep that dimension. Send a category name to pin it. Send "" to clear the pin, so the check falls back to its producer or rule category. The call is gated. Without confirmed=true it changes nothing and returns the checks as they are now. Call again with confirmed=true only after the user approves. To replace or clear a pin that is already set, the call also needs overwrite_confirmed=true. Never set either on your own. The applied call returns the checks as they are after the change. Before you clear a pin, read computed on each dimension: it is the category the check falls back to. If computed is absent, the check becomes uncategorised.

​
synq-scout tools set_issue_status

Sets the status of issues. Use it after the user decides how to classify an issue. The note is added as a comment on each issue. Each issue and each note is applied separately, so the call can partly succeed. Always read applied_all before you report the result. If it is false, errors and comment_errors name the issues that failed. Tell the user what failed. Then call again with only the failed issue ids. Never report a partial result as a completed update.

​
synq-scout tools set_monitor_segment_labels

Sets labels on segments of one monitor. The check name, alerts and search then show the label instead of the raw value. Call list_monitor_segments first to get the segment values. The call changes only the segments in the request. A label for a segment with no label applies immediately. To replace or clear an existing label, the call needs overwrite_confirmed=true. Without it, those entries are not written and come back in pending_overwrites. Set overwrite_confirmed only after the user approves. Never confirm on your own.

​
synq-scout tools set_saved_view_pin

Pins or unpins a saved view on the main screen of the calling user. Any user who can see the view can pin it. The call is not gated: the pin applies only to the calling user and does not change the view.

​
synq-scout tools submit_feature_request

Sends a feature request to the Coalesce Quality product team. Use it only if no tool or combination of tools can do what the user asks, or if the user asks for a function that does not exist. If a tool can do part of the request, use that tool.

​
synq-scout tools summarise_executions

Returns execution counts by type and by status for the given entities. Use it to see execution patterns without the details of each execution.

​
synq-scout tools unexclude_from_monitoring

Removes the exclusions on the given assets, so that the rules that select them monitor them again. It does not create a monitor. An exclusion for one asset is deleted. An asset in the list of a shared exclusion rule is removed from that list, and the other entries stay. A rule with no entries left is deleted. An exclusion that is a selection (a folder, a name search) cannot lose one asset; the response names the rule to edit. Removing an entry writes the rule as ResolverQL, so the app then shows that rule in its ResolverQL editor, not in the filter builder. The call is gated. Without confirmed=true it changes nothing and returns what it would do. Call again with confirmed=true only after the user approves. An exclusion owned by the app or a YAML config also needs its rule id in overwrite_confirmed_ids.

​
synq-scout tools update_incident

Changes the name, state, owner or attached issues of an incident. It changes only the fields you set. Each field is applied separately, so the call can partly succeed. Always read applied_all before you report the result. If it is false, errors names the fields that failed. Tell the user what failed. Then call again with only the failed fields. Never report a partial result as a completed update.

​
synq-scout tools update_monitors

Replaces custom monitors by id. Each monitor replaces the stored one in full: a field you omit is cleared. Get the monitor from list_monitors, change it, and send all of it. Two changes are gated. Without approval the call changes nothing, sets requires_user_confirmation and lists them:
  1. A reset, from a change to the schedule, time partitioning, segmentation,
  1. A monitor that the app or another config owns (ownership_conflicts). Show the list to the user. Call again with the ids in reset_confirmed_ids or overwrite_confirmed_ids only after the user approves.

​
synq-scout tools update_sql_tests

Changes SQL tests by id. Each entry is a patch: the id and only the fields to change. A field you omit keeps its value, so you do not have to read the test first. A definition (template or raw_sql), evaluators or annotations that you send replaces that part in full. Two changes are gated. Without approval the call does not change those tests and lists them:
  1. A reset, from a change to the recurrence, severity, evaluators or
  1. A test that the app or another config owns (ownership_conflicts). Show the list to the user. Call again with the ids in reset_confirmed_ids or overwrite_confirmed_ids only after the user approves.
A test from a SQL test deployment rule is refused. Change the rule with deploy_sql_test_deployment_rule. Read applied_all for the result: applied has the tests that changed, and errors tells why each other test did not.

​
synq-scout tools update_table_stats_monitor

Replaces a table-stats monitor by id and deploys it again. The metrics you send replace all metrics: a metric you omit is removed. Get the monitor from list_table_stats_monitors first. A monitor that the app or another config owns is gated: the call changes nothing and lists it in ownership_conflicts. Call again with its id in overwrite_confirmed_ids only after the user approves.

​
synq-scout upgrade

Upgrade synq-scout to the latest release
Download the latest synq-scout release and replace this binary with it. The archive for this platform is verified against the release’s checksums.txt and the new binary is run once, before anything is replaced, to prove it works on this machine. If the directory holding the binary is not writable — /usr/local/bin usually is not — nothing is downloaded and the reason is printed. —check reports what an upgrade would do and changes nothing. Coalesce Quality CLIs also mention a newer release once a day, on stderr, when one exists. That check resolves a tag from a public GitHub URL, never blocks the command it runs beside, and never reports its own failures — so an air-gapped or offline machine behaves exactly like an up-to-date one. Set QUALITY_NO_UPDATE_CHECK=1 (or DO_NOT_TRACK=1) to switch it off entirely; it is already silent in CI, when output is not a terminal, and inside a container. Examples: