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-postgresReplace 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.ymlParameters
--f
Yes
Output file path for the config
Test Connection
soda cloud test -sc sc.yml--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--f
Yes
Output file path for the config file
Test Data Source Connection
soda data-source test -ds ds.yml--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--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--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--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--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
--data-source, -ds
Yes
Path to local data source config
With Soda Agent
--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
--contract
Yes (if verifying local file)
Path to contract YAML file
With a Soda Cloud Data Contract
--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--set
No
Define variable key-value pairs for substitution
Last updated
Was this helpful?