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

Requirements

To use Soda, you must have installed the following on your system.

Python 3.8, 3.9, 3.10 or 3.11.

To check your existing version, use the CLI command: python --version or python3 --version. If you have not already installed Python, consider using pyenv to manage multiple versions of Python in your environment.

Pip 21.0 or greater.

To check your existing version, use the CLI command: pip --version

A Soda Cloud account; see how to Quickstart #Sign up.

Best practice dictates that you install the Soda CLI using a virtual environment. If you haven't yet, in your command-line interface tool, create a virtual environment in the .venv directory using the commands below. Depending on your version of Python, you may need to replace python with python3 in the first command.

python -m venv .venv
source .venv/bin/activate

Public PyPI installation flow

This CLI installation flow applies to Soda’s public PyPI index (https://pypi.dev.sodadata.io/simple), which is used for open or evaluation environments. It is useful to install Soda Core CLI and connect to Soda Cloud.

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.

Now you can #Connect to Soda Cloud.

Private PyPI installation flow

The private PyPI installation process adds an authentication layer and region-based repositories for Team and Enterprise customers. It is useful to install Soda CLI and extensions from private, region-specific repositories with license-based access control.

Upgrade pip inside your new virtual environment.

pip install --upgrade pip

Choose the correct repository based on your license and region.

License

Soda Region

Repository URL

Team¹

team.pypi.cloud.soda.io/

Team

team.pypi.us.soda.io

Enterprise²

enterprise.pypi.cloud.soda.io

Enterprise

enterprise.pypi.us.soda.io/

¹Team: Any license except "Trial" or "Enterprise" (see below) ²Enterprise: one of enterprise , enterprise_user_based , dataset_standard , premier licenses.

Set your credentials. See how to generate your own API key values.

export SODA_API_KEY_ID="your_key_id"
export SODA_API_KEY_SECRET="your_key_secret"

Execute the following command, replacing soda with the install package that matches the type of data source you use to store data.

# For bash interactive shell
pip install -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.cloud.soda.io"  --extra-index-url=https://pypi.cloud.soda.io soda
# For zsh interactive shell
pip install -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.cloud.soda.io"  --extra-index-url=https://pypi.cloud.soda.io "soda"

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

Parameters

Parameter

Required

Description

--file, -f

Yes

Path to a Soda Cloud YAML configuration file.

--verbose, -v

Display detailed logs during execution.

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

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

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

Display detailed logs during execution.

Create a contract

Available soon

Creates a new contract file for a given dataset. This is useful for bootstrapping a contract definition from an existing dataset schema.

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

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

Yes

Path to a contract YAML file to be created. Directories will be created if needed.

--data-source, -ds

Path to a data source YAML config file.

--soda-cloud, -sc

Path to Soda Cloud YAML config file. Required if using Soda Agent.

--use-agent, -a

Yes

Use Soda Agent for execution. Currently, contract creation only works with --use-agent.

--verbose, -v

Display detailed logs during execution.

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

Parameter

Required

Description

--contract, -c

Yes

Path to a contract YAML file

--verbose, -v

Display detailed logs during execution.

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

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

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

Display detailed logs during execution.

Verify a contract

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.

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

Parameter

Required

Description

--use-agent, -a

Use Soda Agent for execution

--publish

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

Path to a data source YAML config file

--contract, -c

without --use-agent

Path to the contract YAML file

--soda-cloud, -sc

with --use-agent or with --publish

Path to a Soda Cloud YAML config file

--dataset, -d

with --use-agent

Soda Cloud dataset identifier

--set

Override contract variables at runtime (can be used multiple times)

--verbose, -v

Display detailed logs during execution

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

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

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

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

PreviousSoda Agent basic concepts NextContract Language reference

Last updated 4 days ago

Was this helpful?