soda-cli

Files (3)

• LICENSE
• SKILL.md
• command-reference.md

SKILL.md (first lines)

# Soda CLI Guide

The Soda CLI (`sodacli`) manages data quality from the command line. All commands follow `sodacli <resource> <action>`.

## Important: always use `--output json` when running commands

When calling `sodacli` from an agent, **always pass `--output json`** to get structured, parseable output. Without it, the CLI outputs human-readable tables that are harder to parse.

## Quick Reference — What Works

**Fully working (tested against live API):**
- `auth` — login, logout, status, switch profiles
- `datasource` — list, get, create, update, delete, onboard (full wizard), test-connection, diagnostics
- `dataset` — list (with filters), get, update, profiling, diagnostics, permissions, onboard
- `contract` — list, push, pull, diff, lint (JSON schema validation), create (skeleton/copilot), verify (cloud or local via soda-core)
- `monitor` — list, config, add (column/custom), update, delete
- `results` — list (with all filters, sorting, date ranges)
- `job` — status, logs
- `runner` — list, get, create (returns API keys for Kubernetes deployment), delete
- `iam` — user list, user invite, group CRUD, role list
- `secret` — list, get, create, update, delete (client-side encrypted with AES-256-GCM + RSA-OAEP)

**Not yet available (API blocked):**
- `incident` — list, get, update (documented in OpenAPI spec but still returns HTML on dev)
- `dataset attributes` — (documented in OpenAPI spec but still returns HTML on dev)
- `notification` — rules and integrations
- `job list`, `job cancel`
- `contract proposal` — list, pull, push, close
- `monitor add --type dataset` (dataset monitors exist by default, no write endpoint)

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success / all checks passed |
| `1` | One or more checks failed |
| `2` | Execution error |
| `3` | Authentication error — run `sodacli auth login` |

## Authentication

```bash
# Non-interactive (for agents and CI/CD)
sodacli auth login --host cloud.soda.io --api-key-id <id> --api-key-secret <secret>

# Check connection
sodacli auth status

# Named profiles
sodacli auth login --profile prod --host cloud.soda.io --api-key-id <id> --api-key-secret <secret>
sodacli auth switch prod
sodacli dataset list --profile prod    # any command accepts --profile
```

Credentials stored in `~/.soda/credentials`. Generate API keys at https://docs.soda.io/reference/generate-api-keys

## Core Workflows

### Discover what's there

```bash
# List datasources
sodacli datasource list --output json

# Get datasource details
sodacli datasource get <id> --output json

# List datasets (default limit: 10)
sodacli dataset list --output json
sodacli dataset list --datasource <name> --status onboarded --limit 50 --output json

# Filter datasets by name, date range, tag
sodacli dataset list --filter "orders" --from 2026-01-01 --until 2026-12-31 --output json

# Get dataset details
sodacli dataset get <dataset-id> --output json

# View profiling data (column stats, row count, missing %)
sodacli dataset profiling <dataset-id> --output json
```

### Onboard a datasource (end-to-end)

```bash
# Full onboard: create datasource + discover + monitoring + profiling + contracts + verify
sodacli datasource onboard warehouse.yml --monitoring --profiling --contracts skeleton

# Or step by step:
sodacli datasource create warehouse.yml
# ⚠ Discovery is async — datasets won't appear immediately.
# Use `sodacli job logs <scan-id>` (printed by create) to confirm completion,
# or wait ~10-15 seconds before listing datasets.
sodacli datasource onboard <datasource-id> --monitoring --profiling --contracts none
```

**Onboarding a single dataset from a new datasource:**
`dataset onboard` only works after `datasource onboard` has run at least once. If you only need one table, you must still run `datasource onboard` first (which onboards all discovered datasets), then manage individual datasets afterwards.

```bash
# This will NOT work right after `datasource create`, even if the dataset appears in `dataset list`:
# sodacli dataset onboard <dataset-id>   ← returns "dataset not found"

# Instead, onboard the datasource first, then work with individual datasets:
sodacli datasource onboard <datasource-id> --monitoring --profiling --contracts copilot
# Now `dataset onboard`, `dataset profiling`, `monitor add`, etc. work on individual datasets.
```

**Contract generation modes:**
- `skeleton` — schema structure + not-null checks only (fast, deterministic)
- `copilot` — AI analyzes your data and generates format, range, uniqueness, and business-logic checks (takes longer, may need manual fixes — see Troubleshooting below)

When `--contracts skeleton` or `--contracts copilot` is used, the onboard flow automatically verifies the generated contracts against your data and displays pass/fail results.

Datasource config file format:
```yaml
type: snowflake           # snowflake, postgres, bigquery, mysql, redshift, etc.
name: my_warehouse
connection:
  host: account.snowflakecomputing.com

From Kilo-Org/kilo-marketplace, Apache-2.0.

More from Kilo-Org/kilo-marketplace