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
Soda Python LibrariesConnect 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.ymlParameters
--file, -f
Yes
Path to a Soda Cloud YAML configuration file.
--verbose, -v
No
Display detailed logs during execution.
Test connection
soda cloud test -sc sc_config.yml--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--file, -f
Yes
Output file path for the data source YAML configuration file.
--verbose, -v
No
Display detailed logs during execution.
Test data source connection
soda data-source test -ds ds_config.yml--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 (Team or Entreprise license), unless you are using an agent.
Need access to the private PyPI? Please contact us.
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--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
No
Path to a data source YAML config file.
--soda-cloud, -sc
No
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
No
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--contract, -c
Yes
Path to a contract YAML file
--verbose, -v
No
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--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
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--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
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--use-agent, -a
No
Use Soda Agent 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-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
No
Override contract variables at runtime (can be used multiple times)
--verbose, -v
No
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--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-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"-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-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 Soda contract by providing one or more check paths using the --check-paths option.
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-cp, --check-paths
No
Provide a list of check paths to identify the checks that need to be verified (see next section CLI reference) to only execute those ones.
The --check-paths option is only available when running Soda Core locally.
It is not supported with Soda Agent and cannot be used together with the --use-agent option.
Check paths
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.5bb8b1orchecks.row_count.5bb8b1) .
Each segment of the path corresponds to a level in the YAML hierarchy, separated by dots (.).
Example:
dataset: datasource/schema/deatasets
dataset: datasource/schema/deatasets
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.
Behavior and results
Omitting check paths, skipping certain parts of the expressions, or including invalid information can lead to different outcomes.
One or more valid paths provided
Only those checks are executed.
Empty --check-paths
e.g. ... --check-paths --verbose ...
Ignored; all checks execute.
Non-matching check path
e.g. with ... --check-paths does.not.exist
No checks execute.
Partial non-matching check path
e.g. ... --check-paths checks.freshness does.not.exist
Only the valid check will execute (in this case, only the freshness check executes).
Results in Soda Cloud
When using the --check-paths (or -cp) option, only the checks specified by their paths are executed.
Checks not included in the provided paths 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 were not part of the specified --check-paths) are still present in the list of check results, but are marked with CheckResultsData.level: excluded.
Last updated
Was this helpful?