> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/reference/soda-cli-reference.md).

# Soda CLI reference

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](/reference/cli-reference.md) for the `soda` command.
>
> <details>
>
> <summary><strong>Soda CLI vs Core CLI</strong></summary>
>
> {% hint style="info" %}
> **Which CLI should I use?**
>
> Soda has two command-line tools:
>
> * [**Core CLI**](/reference/cli-reference.md) **(`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.
> {% endhint %}
>
> |                         | **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                              |
>
> </details>

## Install

{% tabs %}
{% tab title=" macOS/Linux" %}

#### Homebrew

```bash
brew tap sodadata/tap
brew install sodacli
```

#### Install script

{% code overflow="wrap" %}

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

{% endcode %}
{% endtab %}

{% tab title="Windows" %}
Download the latest `.zip` for your architecture from [GitHub Releases](https://github.com/sodadata/soda-cli/releases), extract `sodacli.exe`, and add it to your `PATH`.
{% endtab %}

{% tab title="From source" %}

* Requires Go 1.22+.

```bash
git clone https://github.com/sodadata/soda-cli.git
cd soda-cli/go
go build -o sodacli .
sudo mv sodacli /usr/local/bin/
```

{% endtab %}
{% endtabs %}

Verify the installation:

```bash
sodacli version
sodacli --help
```

## Quickstart

{% stepper %}
{% step %}

### Authenticate

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

# Confirm the connection
sodacli auth status
```

[Generate API keys](broken://pages/H6Piqnv5lUFCAv1Cvm75) in Soda Cloud.
{% endstep %}

{% step %}

### Onboard a datasource

```bash
# 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
```

{% endstep %}

{% step %}

### Verify a contract

```bash
# 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> 
```

{% endstep %}
{% endstepper %}

## Global flags

These flags work on every command.

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

## 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`.

```bash
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

{% hint style="info" %}
This section covers the most common commands. For the complete command surface, see the `soda-cli` repository, or run `sodacli <command> --help`.

{% embed url="<http://github.com/sodadata/soda-cli/blob/main/command_tree.txt>" %}
Soda CLI command tree on GitHub
{% endembed %}
{% endhint %}

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

```bash
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:

<table><thead><tr><th width="120">Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>0</code></td><td>All checks passed.</td></tr><tr><td><code>1</code></td><td>One or more checks failed — fail the pipeline.</td></tr><tr><td><code>2</code></td><td>Execution error — retry or alert.</td></tr><tr><td><code>3</code></td><td>Authentication error — check credentials.</td></tr></tbody></table>

### GitHub Actions example

```yaml
- 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:

```bash
export SODACLI_TELEMETRY=false
```

<br>

***

{% if (visitor.claims.plan === 'datasetStandard')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Dataset Standard license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if (visitor.claims.plan === 'enterprise')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if (visitor.claims.plan === 'enterpriseUserBased')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard')
%}
{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).

If you do have a Soda license, make sure to **log in to Soda Cloud in this same browser**.
{% endhint %}
{% endif %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.soda.io/reference/soda-cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.