# CLI reference This guide documents the CLI commands for working with Soda Data Contracts. You can use the CLI to generate, test, publish, and verify contracts using either Soda Core (local execution) or Soda Agent (remote execution). > For full language reference, see: [contract-language-reference](https://docs.soda.io/reference/contract-language-reference "mention") > For supported data source configurations, see: [data-source-reference-for-soda-core](https://docs.soda.io/reference/data-source-reference-for-soda-core "mention") *** ## Installation {% content-ref url="../deployment-options/soda-python-libraries" %} [soda-python-libraries](https://docs.soda.io/deployment-options/soda-python-libraries) {% endcontent-ref %} Make sure you install the following packages: * `soda` * `soda-`: the package relevant to the data source(s) you will use. E.g. `soda-postgres`, or `soda-bigquery`. > Learn more about [supported data sources](https://docs.soda.io/reference/data-source-reference-for-soda-core). *** ## Connect to Soda Cloud The connection to Soda Cloud is made via a config file (`sc_config.yml`), used to create and test your Soda Cloud configuration. This is required for publishing contracts or pushing verification results. > Don’t have an account? [Book a demo](https://soda.io/demo?utm_source=documentation\&utm_medium=cloud_docs\&utm_campaign=demo_request\&utm_content=connect_soda_cloud) to get started. ### Create Soda Cloud config To connect the CLI or Python API to Soda Cloud, **you must provide an `sc_config.yml` file for authentication**, which will be necessary to run scans that send results to Soda Cloud, to publish or verify contracts via CLI, and to use the Python API. ```bash soda cloud create -f sc_config.yml ``` #### Parameters
ParameterRequiredDescription
--file, -fYesPath to a Soda Cloud YAML configuration file.
--verbose, -vNoDisplay detailed logs during execution.
The above command will create the `sc_config.yml` file, which will look like the following: {% code title="sc\_config.yml" %} ```yaml soda_cloud: host: cloud.soda.io # Use cloud.us.soda.io for US region api_key_id: YOUR_API_KEY_ID api_key_secret: YOUR_API_KEY_SECRET ``` {% endcode %} **Required fields** | Field | Required | Description | | ---------------- | -------- | --------------------------------------------------------------------------- | | `host` | Yes | Soda Cloud region endpoint | | `api_key_id` | Yes | [Generated in Soda Cloud](https://docs.soda.io/reference/generate-api-keys) | | `api_key_secret` | Yes | [Generated in Soda Cloud](https://docs.soda.io/reference/generate-api-keys) | You can reference environment variables instead of hardcoding values: {% code title="sc\_config.yml" %} ```yaml soda_cloud: host: cloud.soda.io api_key_id: ${env.SODA_API_KEY_ID} api_key_secret: ${env.SODA_API_KEY_SECRET} ``` {% endcode %} Set them in your environment: ```bash export SODA_API_KEY_ID=your_key_id export SODA_API_KEY_SECRET=your_key_secret ``` *** {% columns %} {% column %} **CLI usage** Pass the `sc_config.yml` file when running CLI commands: {% code overflow="wrap" %} ```shellscript soda scan -d my_datasource -c configuration.yml --soda-cloud sc_config.yml ``` {% endcode %} The CLI uses this file to authenticate and send results to Soda Cloud. {% endcolumn %} {% column %} **Python API usage** Provide the file path when calling Soda Cloud operations: 
verify_contracts_on_agent(
  dataset_identifiers=["my_dataset"],
  soda_cloud_file_path="sc_config.yml",
)
The Python API reads the file to authenticate and connect to Soda Cloud. {% endcolumn %} {% endcolumns %} {% hint style="warning" %} Without a valid `sc_config.yml`, the CLI and Python API cannot authenticate with Soda Cloud. {% endhint %} *** ### Test connection ```bash soda cloud test -sc sc_config.yml ```
ParameterRequiredDescription
--soda-cloud, -scYesPath to a Soda Cloud YAML configuration file
--verbose, -vNoDisplay detailed logs during execution.
*** ## Configure a data source These commands help you define a local configuration for your data source (used by Soda Core) and validate the connection. ### Create data source config ```bash soda data-source create -f ds_config.yml ``` | Parameter | Required | Description | | --------------- | -------- | ------------------------------------------------------------- | | `--file, -f` | Yes | Output file path for the data source YAML configuration file. | | `--verbose, -v` | No | Display detailed logs during execution. | {% hint style="info" %} By default, the YAML file generated as `ds_config.yml` is a template for **PostgreSQL connections**. To see how to modify it to connect to other data sources, head to [data-source-reference-for-soda-core](https://docs.soda.io/reference/data-source-reference-for-soda-core "mention"). {% endhint %} ### Test data source connection ```bash soda data-source test -ds ds_config.yml ``` | Parameter | Required | Description | | -------------------- | -------- | ---------------------------------------------- | | `--data-source, -ds` | Yes | Path to a data source YAML configuration file. | | `--verbose, -v` | No | Display detailed logs during execution. | *** ## Create a contract {% hint style="warning" %} Creating a contract requires having installed the `soda` package using **the** [**Private PyPi installation flow**](https://docs.soda.io/deployment-options/soda-python-libraries#private-pypi-installation-flow) available both for Team and Entreprise license, unless you are using an Agent. Need access to the private PyPI? Please [contact us](mailto:support@soda.io). {% endhint %} Bootstraps a contract file from an existing dataset's schema. Runs either locally or on a Soda Agent; output is written to a local file, to Soda Cloud as a draft, or both. **Local execution:** {% code overflow="wrap" %} ```bash soda contract create --dataset datasource/db/schema/table --data-source ds_config.yml --file contract.yaml ``` {% endcode %} **Agent execution:** {% code overflow="wrap" %} ```bash soda contract create --dataset datasource/db/schema/table --soda-cloud sc_config.yml --file contract.yaml --use-agent ``` {% endcode %} | Parameter | Required | Description | | ---------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--dataset, -d` | Yes | Fully qualified dataset name (data\_source\_name/database\_name/schema\_name/table\_name) aka Soda Cloud dataset identifier. | | `--file, -f` | Conditional | Path to a contract YAML file to be created. Directories will be created if needed. Required unless `--soda-cloud` is set. | | `--data-source, -ds` | Conditional | Path to a data source YAML config file. Required for local execution; ignored when `--use-agent` is set. | | `--soda-cloud, -sc` | Conditional | Path to Soda Cloud YAML config file. Required when `--use-agent` is set, or when `--file` is omitted. | | `--use-agent, -a` | No | Run introspection on Soda Agent instead of locally. Default: `false`. | | `--no-type-parameters, -ntp` | No | Omit data type parameters (precision, scale, length) from generated columns. | | `--verbose, -v` | No | Display detailed logs during execution. | > For a full walkthrough including what the generated skeleton contains and common errors, see [create-and-edit-contracts](https://docs.soda.io/data-testing/git-managed-data-contracts/create-and-edit-contracts "mention"). *** ## Test a contract (dry run) Checks that a contract is syntactically valid before publishing or running a verification. ```bash soda contract test --contract contract.yaml ``` | Parameter | Required | Description | | ---------------- | -------- | --------------------------------------- | | `--contract, -c` | Yes | Path to a contract YAML file | | `--verbose, -v` | No | Display detailed logs during execution. | ## Publish a contract {% hint style="warning" %} Publishing a new version of a contract to Soda Cloud requires additional permissions in Soda Cloud. * If you are publishing a new version for an **existing dataset**, you must have the **Manage contract** permission for that dataset. * If you are publishing a **new dataset**, you must have the global permission **Create new datasets and data sources with Soda Library**. Learn more about permissions in Soda Cloud: [Global and Dataset Roles](https://docs.soda.io/organization-and-admin-settings/global-and-dataset-roles). {% endhint %} Publishes a local contract to Soda Cloud, making it the source of truth for verification. ```bash soda contract publish --contract contract.yaml --soda-cloud sc_config.yml ``` | Parameter | Required | Description | | ------------------- | -------- | --------------------------------------- | | `--contract, -c` | Yes | Path to a contract YAML file. | | `--soda-cloud, -sc` | Yes | Path to Soda Cloud YAML config file. | | `--verbose, -v` | No | Display detailed logs during execution. | This action requires the "Manage contract" permission on the dataset; the user is identified based on the API key provided in the Soda Cloud configuration. > Learn more about permissions here: [dataset-attributes-and-responsibilities](https://docs.soda.io/dataset-attributes-and-responsibilities "mention") ## Fetch a contract from Soda Cloud {% hint style="warning" %} To fetch a contract from Soda Cloud, you must have the **View** permission for that dataset. Learn more about permissions in Soda Cloud [global-and-dataset-roles](https://docs.soda.io/organization-and-admin-settings/global-and-dataset-roles "mention") {% endhint %} You can fetch a contract from Soda Cloud to output it in a local file. ```bash soda contract fetch --dataset datasource/db/schema/table --file contract.yaml --soda-cloud sc_config.yml ``` | Parameter | Required | Description | | ------------------- | -------- | ----------------------------------------------------- | | `--dataset, -d` | Yes | Soda Cloud dataset identifier. | | `--file, -f` | Yes | The path to a contract YAML file to update or create. | | `--soda-cloud, -sc` | Yes | Path to Soda Cloud YAML config file. | | `--verbose, -v` | no | Display detailed logs during execution. | ## Verify a contract {% hint style="warning" %} Publishing verification results to Soda Cloud with `--publish` requires additional permissions in Soda Cloud. * If you are publishing to an **existing dataset**, you must have the **Manage contract** permission for that dataset. * If you are publishing a **new dataset**, you must have the global permission **Create new datasets and data sources with Soda Library**. Learn more about permissions in Soda Cloud [global-and-dataset-roles](https://docs.soda.io/organization-and-admin-settings/global-and-dataset-roles "mention") {% endhint %} Executes a contract verification to check if the dataset complies with its expectations. You can verify a local contract file or a Soda Cloud contract either locally (in your Python environment) or remotely with a Soda Agent. ```bash soda contract verify --data-source ds_config.yml --contract contract.yaml ```
ParameterRequiredDescription
--use-agent, -aNoUse Soda Agent for execution
--publishNoPublish results and contract to Soda Cloud. This action requires the "Manage contract" permission on the dataset; the user is identified based on the API key provided in the Soda Cloud configuration. Learn more about permissions here: dataset-attributes-and-responsibilities
--data-source, -dswithout --use-agentPath to a data source YAML config file
--contract, -cwithout --use-agentPath to the contract YAML file
--soda-cloud, -scwith --use-agent or with --publishPath to a Soda Cloud YAML config file
--dataset, -dwith --use-agentSoda Cloud dataset identifier
--setNoOverride contract variables at runtime (can be used multiple times)
--check-filter, -cfNoFilter checks by field. Format: key=value. Can be repeated. Supported keys: type, name, column, path, qualifier, attributes.<key>. Wildcards (*, ?) supported. See #run-a-subset-of-checks
--check-paths, -cpNoOne or more check paths to run. See #check-paths
--verbose, -vNoDisplay detailed logs during execution
*** ### Override variables Use the `--set` option to define or override variables in the contract when running a verification. ```bash soda contract verify --data-source ds_config.yml --contract contract.yaml --set country=BE --set threshold=5 ``` | Parameter | Required | Description | | --------- | -------- | ------------------------------------------------ | | `--set` | No | Define variable key-value pairs for substitution | *** ## Contract Collaboration Soda enables collaboration on data contracts through **requests** and **proposals**. Data consumers can request changes, propose updates, and iterate with dataset owners until alignment is reached. From the CLI, you can fetch, review, and publish proposals, ensuring contract changes are tracked and versioned in Git. > Read more about [contract-collaboration](https://docs.soda.io/data-testing/contract-collaboration "mention") ### Fetch a proposal Fetches the content of a proposal from Soda Cloud and saves it as a contract file, which can then be published to Git. This allows dataset owners to incorporate approved changes into version-controlled data contracts. ```bash soda request fetch -r 7 -p 1 -sc soda-cloud.yaml --f ./contracts/ecommerce_orders.yaml ``` | Parameter | Required | Description | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-r` | Yes | The request number. Identifies the request to fetch. Request numbers can be found when reviewing a proposal. See screenshot below. | | `-p` | No | The proposal number. Defaults to the latest proposal if not specified. Proposal numbers are shown as the decimal part when reviewing a proposal. See screenshot below. | | `--soda-cloud, -sc` | Yes | Path to the Soda Cloud config file (e.g., `soda-cloud.yaml`). | | `--f` | Yes | Path to the output file where the contract will be written. | ### Push a proposal to Soda Cloud Uploads a contract file to Soda Cloud as a proposal for a specific request. This allows dataset consumers or owners to share updates directly from the CLI and provide context with an accompanying message. ```bash soda request push -sc soda-cloud.yaml -f ./contracts/ecommerce_orders.yaml -r 7 -m "Added new field for order_status" ``` | Parameter | Required | Description | | ------------------- | -------- | -------------------------------------------------------------- | | `-sc, --soda-cloud` | Yes | Path to the Soda Cloud configuration file. | | `-f, --file` | Yes | Path to the contract file to be pushed to Soda Cloud. | | `-r, --request` | Yes | The **Contract Request number** to which the proposal belongs. | | `-m, --message` | No | A descriptive message about the changes being proposed. | *** ### Transition a request Updates the status of a contract request in Soda Cloud. This is useful for marking a request as open, resolved, or closed when no action will be taken. ```bash soda request transition -sc soda-cloud.yaml -r 7 -s done ``` | Parameter | Required | Description | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-sc, --soda-cloud` | Yes | Path to the Soda Cloud configuration file. | | `-r, --request` | Yes | The **Contract Request number** to be transitioned. | | `-s, --status` | Yes |

• open → Reopen or keep the request active
• done → Mark the request as completed.
• wontDo → Mark the request as closed without changes (“won’t do”).

| *** ## Run a subset of checks You can choose to run only specific checks from your contract using **check filters** (`--check-filter`) or **check paths** (`--check-paths`). Both options can be combined. {% hint style="warning" %} Check filters and check paths are **only available when running Soda Core locally**.\ They are **not supported with Soda Agent** and **cannot be used together with the `--use-agent` option**. {% endhint %} ### Check filters Use `--check-filter` (or `-cf`) to select checks by their properties. Each filter is a `key=value` expression. ```bash soda contract verify \ --data-source ds_config.yml \ --contract contract.yaml \ -cf type=missing ``` #### Supported fields | Field | Description | Example | | ------------------ | ----------------------------------------------------------------------------------- | -------------------------------- | | `type` | Check type | `type=missing`, `type=schema` | | `name` | Check name (custom or default) | `name=Email format` | | `column` | Column name (column-level checks only) | `column=customer_email` | | `path` | Full YAML path to the check | `path=columns.id.checks.missing` | | `qualifier` | Check qualifier | `qualifier=c2` | | `attributes.` | Custom attribute value (supports [list-valued attributes](#list-valued-attributes)) | `attributes.severity=critical` | > Learn more about check names, qualifiers, and attributes in the [contract-language-reference](https://docs.soda.io/reference/contract-language-reference "mention"). #### Combining multiple filters Repeat `-cf` to add multiple filters. Filters follow AND/OR grouping logic: * **Same field** (OR): at least one value must match. * **Different fields** (AND): all field groups must match. ```bash # OR within same field — type is missing OR invalid soda contract verify -ds ds_config.yml -c contract.yaml \ -cf type=missing -cf type=invalid # AND across fields — type is missing AND column is id soda contract verify -ds ds_config.yml -c contract.yaml \ -cf type=missing -cf column=id # Combined — (type is missing OR invalid) AND column is id soda contract verify -ds ds_config.yml -c contract.yaml \ -cf type=missing -cf type=invalid -cf column=id # Filter by custom attribute soda contract verify -ds ds_config.yml -c contract.yaml \ -cf attributes.severity=critical ``` #### Wildcards Filter values support wildcards using `*` (matches any sequence of characters) and `?` (matches any single character). Matching is case-sensitive. ```bash # All check types starting with "miss" soda contract verify -ds ds_config.yml -c contract.yaml \ -cf type=miss* # All columns starting with "user_" soda contract verify -ds ds_config.yml -c contract.yaml \ -cf column=user_* ``` #### List-valued attributes When filtering by an attribute that contains a list (e.g., `tags: [prod, critical]`), check filters support two matching modes: **Member match** — use a plain value to match if *any* element in the list matches. Wildcards are supported. ```bash # Matches any check where tags contains "prod" soda contract verify -ds ds_config.yml -c contract.yaml \ -cf attributes.tags=prod # Wildcard member match soda contract verify -ds ds_config.yml -c contract.yaml \ -cf "attributes.tags=prod*" ``` **Full list match** — use `[a,b]` syntax to match only if the list equals that exact set of values. Order does not matter. Wildcards are **not** supported in full list match mode. ```bash # Matches only checks where tags is exactly [prod, critical] (in any order) soda contract verify -ds ds_config.yml -c contract.yaml \ -cf "attributes.tags=[prod,critical]" ``` For list elements that contain commas or spaces, use double quotes inside the brackets: ```bash -cf "attributes.tags=[\"a,b\",hello world,unquoted]" ``` {% hint style="info" %} Values containing shell special characters (`[`, `]`, `*`, `?`) must be quoted on the command line. {% endhint %} *** ### Check paths Use `--check-paths` (or `-cp`) to select checks by their hierarchical location in the contract YAML. A **check path** is the hierarchical location of a check within your YAML contract file. It follows the contract's structure and identifies the exact check(s) to run. ```bash soda contract verify \ --data-source ds_config.yml \ --contract contract.yaml \ --check-paths checks.freshness columns.Order_Date.checks.invalid_format ``` A check path is composed of the keys that define where the check is located in the YAML.\ It can reference: * a **check at the dataset level** (e.g. `checks.freshness`), * a **column-level check** (e.g. `columns.last_updated_on.checks.invalid`) * a check with a qualifier (see [#check-qualifiers](https://docs.soda.io/contract-language-reference#check-qualifiers "mention")) (e.g. `columns.last_updated_on.checks.invalid.5bb8b1`or `checks.row_count.5bb8b1` ) . Each segment of the path corresponds to a level in the YAML hierarchy, separated by dots (`.`). **Example**: ```yaml dataset: datasource/schema/dataset checks: # Check path: checks.freshness - freshness: column: last_updated_on threshold: must_be_less_than: 1 unit: day # Check path: checks.row_count - row_count: columns: - name: last_updated_on checks: # Check path: columns.last_updated_on.checks.invalid - invalid: invalid_format: regex: ^(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])/\d{4}$ name: MM/DD/YYYY # Check path: columns.last_updated_on.checks.invalid.5bb8b1 - invalid: qualifier: 5bb8b1 invalid_format: regex: ^(0[1-9]|[12]\d|3[01])/(0[1-9]|1[0-2])/\d{4}$ name: DD/MM/YYYY filter: region = 'EU' ``` **On Soda Cloud**, the check path of a given check can be found on the check page in the check info panel.
{% if visitor.claims.plan === %} {% hint style="info" %} Internally, `--check-paths` values are converted to `path=` check filters. You can achieve the same result with `--check-filter path=checks.freshness`. {% endhint %} {% endif %} *** ### Combining check filters and check paths You can use `--check-filter` and `--check-paths` together. The path selectors from `--check-paths` are combined with any other check filters using AND logic across different fields. ```bash # Run only the missing check on the id column that has severity=critical soda contract verify -ds ds_config.yml -c contract.yaml \ -cp columns.id.checks.missing \ -cf attributes.severity=critical ``` *** ### Behavior and results The behavior below applies to both `--check-filter` and `--check-paths`.
ScenarioBehavior
One or more valid filters or paths providedOnly matching checks are executed.

Empty --check-paths

e.g. ... --check-paths --verbose ...

Ignored; all checks execute.

No checks match the filters

e.g. ... -cf type=nonexistent

No checks execute.

Partial match

e.g. ... -cf type=freshness -cf type=nonexistent

Only matching checks execute (in this case, only the freshness check).
#### Results in Soda Cloud When using `--check-filter` or `--check-paths`, only the checks matching the selection are executed. * Checks **not matching** the filters are **not executed** and therefore **remain unchanged** in **Soda Cloud**. * Their status, metrics, and results are **not updated;** they are effectively **untouched** during this run. However, in the **Reporting API**, the response will include **all checks defined in the contract**, representing, for each scan, the **outcomes of all checks**.\ Checks that were **skipped** (because they did not match the filters) are still present in the list of check results, but are **marked with** `CheckResultsData.level: excluded`.
*** {% if (visitor.claims.plan === 'datasetStandard') %} {% hint style="success" %} You are **logged in to Soda** and seeing the **Free license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention"). {% endhint %} {% endif %} {% if (visitor.claims.plan === 'enterprise') %} {% hint style="success" %} You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention"). {% endhint %} {% endif %} {% if (visitor.claims.plan === 'enterpriseUserBased') %} {% hint style="success" %} You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention"). {% endhint %} {% endif %} {% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard') %} {% hint style="info" %} You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention"). {% endhint %} {% endif %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.soda.io/reference/cli-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.