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

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

---

Installation

Install the Soda Core package for your data source. This gives you access to all CLI functionality for working with contracts.

pip install -i https://pypi.dev.sodadata.io/simple -U soda-postgres

Replace soda-postgres with the appropriate package for your data source. See the Data source reference for Soda Corefor supported packages and configurations.

---

Connect to Soda Cloud

Used to create and test your Soda Cloud configuration file. This is required for publishing contracts or pushing verification results.

Don’t have an account? Sign up here to get started.

soda cloud create -f sc.yml

Parameters

Parameter	Required	Description
--f	Yes	Output file path for the config

---

Test Connection

soda cloud test -sc sc.yml

Parameter	Required	Description
--sc	Yes	Path to Soda Cloud config file

---

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

Parameter	Required	Description
--f	Yes	Output file path for the config file

Test Data Source Connection

soda data-source test -ds ds.yml

Parameter	Required	Description
--f	Yes	Output file path for the config file

---

Test a Contract (Dry Run)

Checks that a contract is syntactically valid and points to an existing dataset before publishing or running a verification.

soda contract test --data-source ds.yml --contract contract.yaml

Parameter	Required	Description
--data-source	Yes	Path to local data source config
--contract	Yes	Path to the contract YAML file

Publish a Contract

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

soda contract publish --contract contract.yaml --soda-cloud sc.yml

Parameter	Required	Description
--contract	Yes	Path to the contract YAML file
--soda-cloud	Yes	Path to Soda Cloud config file

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

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

Parameter	Required	Description
--dataset	yes	The dataset path
--file	yes	The path to the contract file to either update or create.
--soda-cloud, -sc	yes	Path to Soda config file

Verify a Contract

Executes a contract verification to check if the dataset complies with its expectations. You can run this locally (Soda Core) or remotely via a Soda Agent.

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

Parameter	Required	Description
--use-agent, -a	No	Use Soda Agent for execution
--publish	No	Push verification results 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
--soda-cloud, -sc	with --publish	Path to Soda Cloud config file
--set	No	Override contract variables at runtime (can be used multiple times)
--verbose, -u	No	Display detailed logs during execution

---

With Soda Core

Parameter	Required	Description
--data-source, -ds	Yes	Path to local data source config

With Soda Agent

Parameter	Required	Description
--use-agent, -a	Yes	Use Soda Agent for execution
--soda-cloud, -sc	Yes	Path to Soda Cloud config file

---

With a local Data Contract file

Parameter	Required	Description
--contract	Yes (if verifying local file)	Path to contract YAML file

With a Soda Cloud Data Contract

Parameter	Required	Description
--dataset, -d	Yes	Fully qualified dataset name

---

Override Variables

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

soda contract verify --data-source ds.yml --contract contract.yaml --set country=BE --set threshold=5

Parameter	Required	Description
--set	No	Define variable key-value pairs for substitution