Soda CLI reference

Manage your entire data quality lifecycle from the terminal or your pipeline.

Soda CLI (sodacli) is a single command-line tool for managing Soda Cloud. From your terminal or a CI/CD pipeline, you can connect data sources, onboard datasets, generate and verify contracts, configure monitors, review results, and manage runners, secrets, and access. All through one interface.

Soda CLI is a single Go binary with no dependencies. Every command is built to work the same way for a person typing in a terminal and for an AI agent or automation calling it programmatically: flags, exit codes and outputs are all machine- and human-readable.

Core CLI and Soda CLI are not the same.

Looking for local contract authoring and verification with Soda Core? See the Core CLI reference for the soda 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

Install

macOS/Linux

Homebrew

brew tap sodadata/tap
brew install sodacli

Install script

curl -sSL https://raw.githubusercontent.com/sodadata/soda-cli/main/install.sh | sh

Windows

From source

Verify the installation:

sodacli version
sodacli --help

Quickstart

1

Authenticate

# Interactive: prompts for host, API key ID, and secret
sodacli auth login

# Confirm the connection
sodacli auth status

Generate API keys in Soda Cloud.

2

Onboard a datasource

# Create the datasource, discover datasets, and enable monitoring,
# profiling, contract generation, and verification in one command
sodacli datasource onboard warehouse.yml --monitoring --profiling --contracts copilot

3

Verify a contract

# Run checks via a Soda Cloud Runner
sodacli contract verify orders.yml

# Or run locally via Soda Core
sodacli contract verify orders.yml --local --datasource datasource.yml

# Review results
sodacli results list --status failing
sodacli job logs <scan-id> 

Global flags

These flags work on every command.

Flag	Short	Description
--output table|json|csv	-o	Output format. Auto-detects: a table in an interactive terminal, JSON when piped.
--profile <name>		Override the active auth profile.
--no-color		Disable color output.
--quiet	-q	Suppress non-essential output.
--verbose	-v	Show detailed output.
--no-interactive		Never prompt; fail with a clear error if required input is missing. Use in CI/CD and for AI agents.

Output formats

The CLI picks a format automatically: a human-readable, colored table in an interactive terminal, and JSON when output is piped. Override the format on any command with --output.

sodacli dataset list                    # colored table
sodacli dataset list --output json      # JSON
sodacli dataset list --output csv       # CSV
sodacli dataset list | jq '.[] | .id'   # auto-JSON when piped

Essential Commands

This section covers the most common commands. For the complete command surface, see the soda-cli repository, or run sodacli <command> --help.

soda-cli/command_tree.txt at main · sodadata/soda-cliGitHub

Soda CLI command tree on GitHub

Authentication

Credentials are stored in ~/.soda/credentials. login runs an interactive wizard unless --no-interactive is set, in which case --api-key-id and --api-key-secret are required.

Command	Description
sodacli auth login	Authenticate with Soda Cloud. Add --host cloud.us.soda.io for the US region.
sodacli auth status	Check connection health for the active profile.
sodacli auth switch <profile>	Switch between saved profiles.

Datasources

Manage warehouse connections. Aliased to ds.

Command	Description
sodacli datasource list	List datasources.
sodacli datasource get <id>	Show a datasource's configuration.
sodacli datasource create <config.yml>	Register a datasource from a YAML config; returns its ID.
sodacli datasource onboard <config-or-id>	Guided end-to-end setup. Supports --monitoring, --profiling, and --contracts copilot|skeleton|none.
sodacli datasource update <id>	Update label, runner, or connection.
sodacli datasource test-connection <config.yml>	Async connection test via a Runner.
sodacli datasource diagnostics <id>	View or configure the diagnostics warehouse.
sodacli datasource delete <id>	Delete a datasource and its resources.

Datasets

Manage datasets, their configuration, and access.

Command	Description
sodacli dataset list	List datasets. Supports --datasource, --status, --limit.
sodacli dataset get <id>	Show dataset details.
sodacli dataset update <id>	Update tags or owner.
sodacli dataset attributes <id>	List a dataset's attributes.
sodacli dataset profiling <id>	View or configure profiling, e.g. --enable --schedule "0 6 * * *".
sodacli dataset time-partition <id>	Set or view the time-partition column.
sodacli dataset diagnostics <id>	View or configure dataset-level diagnostics.
sodacli dataset permissions list <id>	List role assignments on a dataset.
sodacli dataset permissions assign <id>	Assign a role to a user or group.

Contracts

Generate, validate, publish, and verify data contracts.

Command	Description
sodacli contract list	List all contracts.
sodacli contract create --dataset <dqn>	Generate a contract from a dataset schema. --mode skeleton|copilot.
sodacli contract pull <dqn>	Download a contract from Soda Cloud.
sodacli contract push <file>	Upload a local contract to Soda Cloud.
sodacli contract diff <file>	Show a local-vs-cloud diff.
sodacli contract lint <file...>	Validate contract syntax offline. Supports globs.
sodacli contract verify <file|dqn>	Run checks via a cloud Runner, or locally with --local --datasource <config>.

Monitors

Configure ML-based metric monitors (anomaly detection).

Command	Description
sodacli monitor list --dataset <id>	List a dataset's monitors.
sodacli monitor config <dataset-id>	View or set the monitoring schedule, e.g. --enable --schedule "0 */6 * * *".
sodacli monitor add --dataset <id>	Add a monitor: --type column (with --column, --metric) or --type custom (with --name, --sql).
sodacli monitor update <monitor-id>	Update a monitor.
sodacli monitor delete <monitor-id>	Delete a monitor.

Results

Command	Description
sodacli results list	List check results. Supports --dataset-name, --status, --from, --limit.

Jobs

Observe scans. Aliased to scan.

Command	Description
sodacli job status <scan-id>	Show a scan's state and check summary.
sodacli job logs <scan-id>	Show a scan's logs.

IAM

Manage users, groups, and roles.

Command	Description
sodacli iam user list	List users.
sodacli iam user invite --email <email>	Invite users (repeatable, up to 10).
sodacli iam group create --name <name>	Create a group; add members with --member.
sodacli iam group update <id>	Update membership, e.g. --add-member <email>.
sodacli iam role list	List roles. Supports --scope global|dataset.

Runners

Command	Description
sodacli runner list	List registered runners.
sodacli runner get <id>	Show a runner's details.
sodacli runner create --name <name>	Create runner credentials (shown once).
sodacli runner delete <id>	Delete a runner.

Secrets

Encrypted credentials referenced from datasource configs as ${secret.NAME}. Values are encrypted client-side before they leave your machine.

Command	Description
sodacli secret list	List secrets.
sodacli secret get <id>	Show a secret's details.
sodacli secret create --name <name>	Create a secret via masked prompt, --value, or stdin.
sodacli secret update <id>	Update a secret's value.
sodacli secret delete <id>	Delete a secret.

CI/CD integration

Every command runs non-interactively with --no-interactive, emits machine-readable output with --output json, and returns structured exit codes.

sodacli auth login \
  --host cloud.soda.io \
  --api-key-id "$SODA_API_KEY_ID" \
  --api-key-secret "$SODA_API_KEY_SECRET" \
  --no-interactive

sodacli contract verify contracts/orders.yml --no-interactive --output json

contract verify exit codes:

Code	Meaning
0	All checks passed.
1	One or more checks failed — fail the pipeline.
2	Execution error — retry or alert.
3	Authentication error — check credentials.

GitHub Actions example

- name: Verify data contracts
  run: |
    sodacli auth login --host cloud.soda.io \
      --api-key-id ${{ secrets.SODA_KEY_ID }} \
      --api-key-secret ${{ secrets.SODA_KEY_SECRET }} \
      --no-interactive
    sodacli contract verify contracts/orders.yml --no-interactive

Telemetry

Soda CLI collects anonymous usage data (command names, exit codes, duration, OS/arch) to help improve the tool. No personal information, API keys, file contents, or query data is collected. Opt out by setting an environment variable:

export SODACLI_TELEMETRY=false

---

{% if (visitor.claims.plan === 'datasetStandard') %}

You are logged in to Soda and seeing the Dataset Standard license documentation. Learn more about Documentation access & licensing.

{% if (visitor.claims.plan === 'enterprise') %}

You are logged in to Soda and seeing the Team license documentation. Learn more about Documentation access & licensing.

{% if (visitor.claims.plan === 'enterpriseUserBased') %}

You are logged in to Soda and seeing the Enterprise license documentation. Learn more about Documentation access & licensing.

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard') %}

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

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