Core CLI reference

This guide documents the Soda Core 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 Runner (remote execution).

Core CLI and Soda CLI are not the same.

Looking to manage your full Soda Cloud platform (datasources, datasets, monitors, runners, and more) from one tool? See the Soda CLI reference for the sodacli command.

Soda CLI vs Core CLI

Which CLI should I use?

Soda has two command-line tools:

• Core CLI (soda) — a Python tool focused on data contracts, run locally. Create, test, publish, and verify contracts, with fine-grained check selection.
• Soda CLI (sodacli) — a single Go binary that manages your entire Soda Cloud platform: datasources, datasets, contracts, monitors, results, incidents, IAM, runners, and secrets. Authenticate once and drive it from your terminal, CI/CD, or an AI agent.

Use sodacli to manage the full platform; use soda for local, contract-only work. They work together:sodacli contract verify --local runs soda under the hood.

	Soda CLI (sodacli)	Soda Core CLI (soda)
Language	Go single binary, no dependencies	Python (pip + data source connectors)
Execution	Cloud via Soda Runner, or local with --local	Local only
Scope	Full platform: datasources, datasets, contracts, monitors, results, runners, secrets, IAM, incidents	Contract verification and data source testing
Contract generation	contract create --mode copilot (AI) or skeleton	Manual authoring
CI/CD	--no-interactive, --output json, structured exit codes	Basic exit codes

Nomenclature change: "Agent" is now "Runner"

The Soda Agent has been renamed to Soda Runner across all Soda products and interfaces. This change affects terminology throughout the platform, including:

• Soda Cloud UI labels
• API permission names: MANAGE_DATASOURCES_AND_AGENTS → MANAGE_DATASOURCES_AND_RUNNERS
• CLI flags: --use-agent → --use-runner
• Python API methods: verify_contract_on_agent → verify_contract_on_runner

The underlying functionality is unchanged, and both runner/agent nomenclatures are backward compatible at present. If you are following older documentation or have existing scripts and automation that reference "agent", we recommend to gradually replace every occurrence of "agent" / "Agent" with "runner" / "Runner".

For full language reference, see: Contract Language reference

For supported data source configurations, see: Data source reference for Soda Core

---

Installation

Soda Python Libraries

Make sure you install the following packages:

• soda
• soda-<data_source>: the package relevant to the data source(s) you will use. E.g. soda-postgres, or soda-bigquery.

  Learn more about supported data sources.

---

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

soda cloud create -f sc_config.yml

Parameters

Parameter	Required	Description
--file, -f	Yes	Path to a Soda Cloud YAML configuration file.
--verbose, -v	No	Display detailed logs during execution.

The above command will create the sc_config.yml file, which will look like the following:

sc_config.yml

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

Required fields

Field	Required	Description
host	Yes	Soda Cloud region endpoint
api_key_id	Yes	Generated in Soda Cloud
api_key_secret	Yes	Generated in Soda Cloud

You can reference environment variables instead of hardcoding values:

sc_config.yml

soda_cloud:
  host: cloud.soda.io
  api_key_id: ${env.SODA_API_KEY_ID}
  api_key_secret: ${env.SODA_API_KEY_SECRET}

Set them in your environment:

export SODA_API_KEY_ID=your_key_id
export SODA_API_KEY_SECRET=your_key_secret

---

CLI usage

Pass the sc_config.yml file when running CLI commands:

soda scan -d my_datasource -c configuration.yml --soda-cloud sc_config.yml

The CLI uses this file to authenticate and send results to Soda Cloud.

Python API usage

Provide the file path when calling Soda Cloud operations:

verify_contracts_on_runner(
  dataset_identifiers=["my_dataset"],
  soda_cloud_file_path="sc_config.yml",
)

The Python API reads the file to authenticate and connect to Soda Cloud.

Without a valid sc_config.yml, the CLI and Python API cannot authenticate with Soda Cloud.

---

Test connection

soda cloud test -sc sc_config.yml

Parameter	Required	Description
--soda-cloud, -sc	Yes	Path to a Soda Cloud YAML configuration file
--verbose, -v	No	Display 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

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.

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.

Test data source connection

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

Creating a contract requires having installed the soda package using the Private PyPi installation flow available both for Team and Entreprise license, unless you are using a Runner.

Need access to the private PyPI? Please contact us.

Bootstraps a contract file from an existing dataset's schema. Runs either locally or on a Soda Runner; output is written to a local file, to Soda Cloud as a draft, or both.

Local execution:

soda contract create --dataset datasource/db/schema/table --data-source ds_config.yml --file contract.yaml

Runner execution:

soda contract create --dataset datasource/db/schema/table --soda-cloud sc_config.yml --file contract.yaml --use-runner

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-runner is set.
--soda-cloud, -sc	Conditional	Path to Soda Cloud YAML config file. Required when --use-runner is set, or when --file is omitted.
--use-runner, -a	No	Run introspection on Soda Runner 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.

---

Test a contract (dry run)

Checks that a contract is syntactically valid before publishing or running a verification.

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

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.

Publishes a local contract to Soda Cloud, making it the source of truth for verification.

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 & Responsibilities

Fetch a contract from Soda Cloud

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

You can fetch a contract from Soda Cloud to output it in a local file.

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

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

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

soda contract verify --data-source ds_config.yml --contract contract.yaml

Parameter	Required	Description
--use-runner, -r	No	Use Soda Runner for execution
--publish	No	Publish 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 & Responsibilities
--data-source, -ds	without --use-runner	Path to a data source YAML config file
--contract, -c	without --use-runner	Path to the contract YAML file
--soda-cloud, -sc	with --use-runner or with --publish	Path to a Soda Cloud YAML config file
--dataset, -d	with --use-runner	Soda Cloud dataset identifier
--set	No	Override contract variables at runtime (can be used multiple times)
--check-filter, -cf	No	Filter checks by field. Format: key=value. Can be repeated. Supported keys: type, name, column, relative_path (alias path), check_path, qualifier, attributes.<key>. Wildcards (*, ?) supported. See Run a subset of checks
--check-paths, -cp	No	One or more check paths to run. See Check paths
--verbose, -v	No	Display detailed logs during execution
--blocking-timeout-in-minutes, -btm	No	With --use-runner, the maximum time in minutes to wait for the remote verification to complete. Default: 60.

Exit codes

soda contract verify returns an exit code your pipeline can act on. The same codes apply with --use-runner.

Code	Meaning
0	All checks passed.
1	One or more checks failed.
2	One or more checks warned and none failed.
3	The verification could not run. Locally, a contract parse error or an engine error. On Soda Runner, a scan that errored, failed, was canceled, or timed out.
4	Results could not be sent to Soda Cloud. With --use-runner, this also covers a remote scan that could not be started and a wait longer than --blocking-timeout-in-minutes.

---

Override variables

Use the --set option to define or override variables in the contract when running a verification.

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

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.

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.

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.

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.

Check filters and check paths are only available when running Soda Core locally. They are not supported with Soda Runner and cannot be used together with the --use-runner option.

Check filters

Use --check-filter (or -cf) to select checks by their properties. Each filter is a key=value expression.

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
relative_path	YAML path to the check within its file. path is an alias.	relative_path=columns.id.checks.missing
check_path	Full check path, including the collection it comes from where the check is not from a contract (see #check-paths)	check_path=data-standard.pii_rules:columns.id.checks.missing
qualifier	Check qualifier	qualifier=c2
attributes.<key>	Custom attribute value (supports list-valued attributes)	attributes.severity=critical

Learn more about check names, qualifiers, and attributes in the Contract Language reference.

Every check belongs to a check collection — the file that defines it. A contract is one kind of check collection, a Data Standard is another. When a run covers more than one collection, two more fields select by collection:

Field	Description	Example
collection, standard	Name of the check collection the check comes from	collection=pii_rules
source	Kind of check collection: soda-contract or data-standard	source=data-standard

# Run every check that comes from one collection
soda data-standard verify -d datasource/db/schema/customers -ds ds_config.yml -sc sc_config.yml \
  -cf collection=pii_rules

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.

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

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

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

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

-cf "attributes.tags=[\"a,b\",hello world,unquoted]"

Values containing shell special characters ([, ], *, ?) must be quoted on the command line.

---

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.

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) (e.g. columns.last_updated_on.checks.invalid.5bb8b1or checks.row_count.5bb8b1 ) .

Each segment of the path corresponds to a level in the YAML hierarchy, separated by dots (.).

Example:

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.

Check paths outside a contract

Everything above describes contract check paths. A dataset can have other check collections applied to it at the same time, so a check from one of those is identified by a path that also names the collection it came from:

<collection kind>.<collection name>:<path within the collection>

Data Standards are the only other kind today, so their checks look like this:

soda data-standard verify -d datasource/db/schema/customers -ds ds_config.yml -sc sc_config.yml \
  -cp data-standard.pii_rules:columns.email.checks.missing

Because . and : separate the parts of a check path, a collection's name cannot contain either character. Contract check paths are unaffected — they stay exactly as shown above.

Internally, --check-paths values become check_path= check filters, so --check-filter check_path=checks.freshness is equivalent. To match a check's location while ignoring which collection it came from, filter on relative_path= instead.

---

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.

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

Scenario	Behavior
One or more valid filters or paths provided	Only 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.

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Licensing & documentation access.

If you do have a Soda license, make sure to log in to Soda Cloud in this same browser.