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

# Monitors CLI reference

> Every synqcli command, argument and flag, generated from the CLI itself.

<Info>
  This page is generated from the `synqcli` command tree, so it always matches
  the released binary. For what the YAML declares and how to structure it, see
  [Defining monitors in code](/monitors/monitors-as-code); the field-by-field
  format is the [configuration reference](https://schemas.synq.io/synq-monitors/v1/config.html).
</Info>

Manage Coalesce Quality monitors, SQL tests and deployment rules as code.

A YAML configuration declares which monitors and tests belong on which assets.
The deploy command reconciles a workspace with that configuration, export writes
what a workspace already has back out as YAML, and advisor proposes tests for an
asset. The schema command writes the JSON schema out for editor completion.

## Global flags

These apply to every command.

| Flag              | Type     | Default | Description                                                                                                              |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--client-id`     | `string` | —       | Coalesce Quality API client ID (overrides .env and environment variables)                                                |
| `--client-secret` | `string` | —       | Coalesce Quality API client secret (overrides .env and environment variables)                                            |
| `--endpoint`      | `string` | —       | Coalesce Quality API endpoint, for staging or a self-hosted deployment; overrides --region (or \$QUALITY\_API\_ENDPOINT) |
| `--region`        | `region` | —       | Coalesce Quality deployment to use: au, eu, us (or \$QUALITY\_REGION)                                                    |

## Commands

### `synqcli advisor`

Suggest data quality tests for one or more entities

```bash theme={null}
synqcli advisor [flags]
```

The advisor command uses AI to suggest appropriate data quality tests and monitors
for one or more entities (tables) based on provided instructions.

Example (single entity, JSON output):

```bash theme={null}
synqcli advisor \
  --entity-id "postgres::public::users" \
  --instructions "Suggest basic data quality tests"
```

Example (single entity with YAML file output):

```bash theme={null}
synqcli advisor \
  --entity-id "postgres::public::users" \
  --instructions "Suggest basic data quality tests" \
  --output ./tests
```

Example (multiple entities):

```bash theme={null}
synqcli advisor \
  --entity-id "postgres::public::users" \
  --entity-id "postgres::public::orders" \
  --entity-id "postgres::public::products" \
  --instructions "Suggest basic data quality tests" \
  --output ./tests
```

Example (with DWH connection for data profiling):

```bash theme={null}
synqcli advisor \
  --entity-id "postgres::public::users" \
  --instructions "Suggest accepted_values tests for enum columns" \
  --connections ./connections.yaml
```

Example (filter to specific columns):

```bash theme={null}
synqcli advisor \
  --entity-id "postgres::public::users" \
  --columns "status,email,role" \
  --instructions "Suggest tests for these columns"
```

This will create separate YAML files for each entity in the output directory.
When --deploy is specified, all YAML files in the output directory will be deployed.

DWH CONNECTIONS:
When --connections is specified, the advisor can profile columns to:

* Discover actual values for accepted\_values tests
* Determine min/max bounds for range tests
* Check null rates and distinct counts

Connection file format (connections.yaml):

```bash theme={null}
- id: my-postgres
  type: postgres
  host: localhost
  port: 5432
  database: mydb
  username: user
  password: pass
```

Alternatively, configure a single connection via environment variables:

```bash theme={null}
DWH_TYPE, DWH_HOST, DWH_PORT, DWH_DATABASE, DWH_USERNAME, DWH_PASSWORD
```

Supported types: postgres, mysql, bigquery, snowflake, clickhouse, redshift, databricks

| Flag                        | Type          | Default | Description                                                                                      |
| --------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `--auto-confirm`            | `bool`        | —       | Automatically confirm deployment prompts (only used with --deploy)                               |
| `-C`, `--columns`           | `stringSlice` | —       | Filter test suggestions to specific columns (can be comma-separated or specified multiple times) |
| `-c`, `--connections`       | `string`      | —       | Path to DWH connections YAML file for data profiling                                             |
| `--deploy`                  | `bool`        | —       | Deploy generated YAML files after creation (requires --output)                                   |
| `-e`, `--entity-id`         | `stringSlice` | —       | Entity ID(s) (table FQN) to suggest tests for (can be specified multiple times, required)        |
| `-f`, `--force`             | `bool`        | —       | Force overwrite existing YAML files (default: skip if exists)                                    |
| `-i`, `--instructions`      | `string`      | —       | Instructions for what tests/monitors to suggest (required if --instructions-file not provided)   |
| `-I`, `--instructions-file` | `string`      | —       | Path to file containing instructions (required if --instructions not provided)                   |
| `-n`, `--namespace`         | `string`      | —       | Namespace for generated YAML (default: synq-advisor)                                             |
| `-o`, `--output`            | `string`      | —       | Output directory path for YAML files (required if --deploy is used)                              |
| `-p`, `--print-protobuf`    | `bool`        | —       | Print protobuf messages in JSON format during deployment                                         |
| `-s`, `--severity`          | `string`      | —       | Default severity for tests/monitors (INFO, WARNING, ERROR)                                       |
| `-v`, `--verbose`           | `bool`        | —       | Show verbose output including loaded schema and LLM interactions                                 |

### `synqcli auth`

Manage Coalesce Quality API authentication

```bash theme={null}
synqcli auth [flags]
```

Manage authentication for the Coalesce Quality API.

synqcli can authenticate as a human in a browser, not only with client
credentials. Credentials are cached under \~/.synq/oauth/, partitioned by region,
and shared with the other Coalesce Quality CLIs by default.

Client credentials (--client-id / --client-secret or QUALITY\_CLIENT\_ID /
QUALITY\_CLIENT\_SECRET) and a pre-issued QUALITY\_TOKEN still take precedence over
a browser login, so CI is unaffected.

Pick a deployment with --region, or point at a staging or self-hosted deployment
with --endpoint. Both work on every command, and a successful login is
remembered — so after logging in to one deployment, later commands need neither
flag.

Examples:

```bash theme={null}
synqcli auth login
synqcli auth login --region us
synqcli auth status
synqcli auth use au
synqcli auth logout --region us
```

| Flag             | Type     | Default | Description                                                       |
| ---------------- | -------- | ------- | ----------------------------------------------------------------- |
| `--auth-profile` | `string` | —       | Credential profile to read or write (default: the shared profile) |

#### `synqcli auth login`

Authenticate with Coalesce Quality in a browser

```bash theme={null}
synqcli 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 synqcli needs — managing monitors, SQL tests
and query-based deployment rules, plus the reads required to resolve the assets a
check targets.

By default the credential goes to the shared slot, so one login serves every
Coalesce Quality CLI on this machine. Pass --isolated to keep it to synqcli.

| Flag         | Type   | Default | Description                                                    |
| ------------ | ------ | ------- | -------------------------------------------------------------- |
| `--isolated` | `bool` | —       | Store a credential for synqcli alone instead of the shared one |

#### `synqcli auth logout`

Remove the stored credential for a region

```bash theme={null}
synqcli 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.

#### `synqcli auth status`

Show every stored credential, for every region

```bash theme={null}
synqcli 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.

#### `synqcli auth token`

Print the access token, refreshing it if needed

```bash theme={null}
synqcli 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 $(synqcli auth token)" ...
```

#### `synqcli auth use`

Show or set the deployment commands use by default

```bash theme={null}
synqcli 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}
synqcli auth use
synqcli auth use au
synqcli auth use developer.synq.dev:443
synqcli auth use --clear
```

| Flag      | Type   | Default | Description                                                        |
| --------- | ------ | ------- | ------------------------------------------------------------------ |
| `--clear` | `bool` | —       | Forget the recorded deployment and fall back to the default region |

### `synqcli deploy`

Deploy custom monitors from YAML configuration

```bash theme={null}
synqcli deploy [FILES...] [flags]
```

Deploy custom monitors by parsing YAML configuration files.

Before deploying, it prints what changes will be made and prompts for confirmation,
unless --auto-confirm is set.

If no files are provided, it will recursively search for YAML files from the working directory.

| Flag                     | Type          | Default | Description                                                                          |
| ------------------------ | ------------- | ------- | ------------------------------------------------------------------------------------ |
| `--auto-confirm`         | `bool`        | —       | Automatically confirm all prompts (skip interactive confirmations)                   |
| `--dry-run`              | `bool`        | —       | Show what would be deployed without actually deploying                               |
| `--log-file`             | `string`      | —       | Path to write execution log in JSONL format (or \$QUALITY\_LOG\_FILE)                |
| `--namespace`            | `stringSlice` | —       | If set, will only make changes to the included namespaces                            |
| `-p`, `--print-protobuf` | `bool`        | —       | Print protobuf messages in JSON format                                               |
| `--verbose`              | `bool`        | —       | List every affected asset in the deployment-rule preview instead of capping the list |

### `synqcli export`

Export custom monitors, SQL tests, and deployment rules to YAML

```bash theme={null}
synqcli export [output-file] [flags]
```

Export custom monitors, SQL tests, and deployment rules as YAML.

By default all three resource types are exported. Use --type to narrow:

```bash theme={null}
synqcli export out.yaml                          # everything
synqcli export out.yaml --type=sql-tests         # only SQL tests
synqcli export out.yaml --sql-test=<uuid>        # auto-narrows to that one test
synqcli export out.yaml --type=monitors --sql-test=<uuid>   # all monitors + that test
```

ID-scoped flags (--monitor, --sql-test, --deployment-rule) implicitly add
their owning type to the selection, so you rarely need --type explicitly.

| Flag                | Type          | Default | Description                                                                                                                                               |
| ------------------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--deployment-rule` | `stringArray` | —       | Limit exported deployment rules by rule IDs. AND'ed with other scopes.                                                                                    |
| `--integration`     | `stringArray` | —       | Limit exported monitors by integration IDs. AND'ed with other scopes.                                                                                     |
| `--monitor`         | `stringArray` | —       | Limit exported monitors by monitor IDs. AND'ed with other scopes.                                                                                         |
| `--monitored`       | `stringArray` | —       | Limit exported monitors by monitored asset paths. AND'ed with other scopes.                                                                               |
| `--namespace`       | `string`      | —       | Namespace for generated YAML config                                                                                                                       |
| `--source`          | `string`      | `app`   | Limit exported monitors by source. One of \[app api all]. Defaults to "app". AND'ed with other scopes.                                                    |
| `--sql-test`        | `stringArray` | —       | Limit exported SQL tests by test IDs. AND'ed with other scopes.                                                                                           |
| `--type`            | `stringArray` | —       | Limit exported resource types. Repeatable; accepted values: \[monitors sql-tests deployment-rules]. Unset = all. ID-scoped flags auto-include their type. |

### `synqcli schema`

```bash theme={null}
synqcli schema
```

Generate JSON schema.
The schema can be used in IDEs for autocomplete and validation.