document new commands

Author: santiviquez

command_tree.txt

@@ -54,33 +54,34 @@ sodacli
   │   │   # returns datasource ID + discovery scan ID
   │   │   # after success, suggests next steps: sodacli datasource onboard <id> or sodacli dataset onboard <dataset-id>
   │   │
-  │   ├── test-connection  <config-file>                # test connection via Soda Runner (async poll)  🔌 [CLI wired, API returns HTML]
+  │   ├── test-connection  <config-file>                # test connection via Soda Runner (async poll)  ✅
   │   │   [--runner <runner-id>]                      # route through a specific runner (auto-detects if only one)
   │   │
   │   ├── list                                          # list datasources  ✅
   │   │
   │   ├── get  <id>                                     # show datasource details  ✅
   │   │
-  │   ├── update  <id>                                  # update a datasource  🔌 [CLI wired, API returns 404]
+  │   ├── update  <id>                                  # update a datasource  ✅
   │   │   [--label <text>]                             # new label
   │   │   [--runner <runner-id>]                       # change runner
   │   │   [--config <file>]                            # update connection config
   │   │
-  │   ├── diagnostics  <id>                             # view or configure diagnostics warehouse  ❌
+  │   ├── diagnostics  <id>                             # view or configure diagnostics warehouse  ✅
   │       [--enable|--disable]                          # toggle diagnostics warehouse on/off
   │       [--warehouse same|<config-file>]              # reuse datasource connection or provide a separate config
-  │       [--schema <name>]                             # schema for diagnostic tables (default: soda_diagnostics)
-  │       [--collect-results]                            # store check results and scan history
-  │       [--no-collect-results]
-  │       [--collect-failed-rows]                       # store failed rows
-  │       [--no-collect-failed-rows]
-  │       [--table-prefix <prefix>]                     # prefix for diagnostic table names
-  │       [--table-suffix <suffix>]                     # suffix for diagnostic table names
-  │       [--failed-rows-description <text>]            # description shown in Cloud for failed rows storage context
-  │       [--expose-failed-rows-query]                  # expose the failed rows SQL query in Cloud
-  │       [--no-expose-failed-rows-query]
-  │       [--failed-rows-cta]                           # show a call-to-action link to where failed rows can be found
-  │       [--no-failed-rows-cta]
+  │       [--table-template <tpl>]                      # table name template (e.g. {dataset_name})
+  │       [--collect-results|--no-collect-results]      # store check results and scan history
+  │       [--collect-failed-rows|--no-collect-failed-rows]  # store failed rows
+  │       [--expose-failed-rows-query|--no-expose-failed-rows-query]
+  │       [--max-failed-rows <n>]                       # max failed rows to store
+  │       [--failed-rows-location <text>]               # message about where failed rows can be found
+  │       [--failed-rows-cta|--no-failed-rows-cta]      # enable/disable CTA button in Cloud
+  │       [--failed-rows-cta-title <text>]              # CTA button title
+  │       [--failed-rows-cta-url <url>]                 # CTA button URL
+  │       [--failed-rows-strategy <type>]               # useDefaultMaxRowCount|absolute|percentage
+  │       [--failed-rows-threshold <n>]                # threshold value (required for absolute|percentage, >= 1)
+  │       [--failed-rows-threshold-condition <cond>]   # greaterThan|lessThan (default: greaterThan)
+  │       # uses read-modify-write: fetches current config, applies changes, posts back
   │       └── test-connection   <id>                    # test the diagnostics warehouse connection  ❌
   │
   │   └── delete  <id>  ✅
@@ -135,6 +136,7 @@ sodacli
   │   │   # sc_abc123   pg_prod       orders      contract  ✗ failing  2026-03-05 08:12
   │   │   # sc_def456   pg_prod       users       monitor   ✓ passing  2026-03-05 06:45
   │   │
+  │   ├── status  <id>              # show scan/job status, checks, timing  ✅
   │   ├── logs    <id>  [--follow]  ✅
   │   └── cancel  <id>              # cancel a running scan  🔌 [CLI wired, API returns 404]
   │
@@ -166,6 +168,8 @@ sodacli
   │   │   # --owner takes a user ID (use `sodacli iam user list` to find it)
   │   ├── delete  <id>  ✅
   │   │
+  │   ├── attributes  <id>                              # list dataset attributes  🔌 [CLI wired, API documented but returns HTML on dev]
+  │   │
   │   ├── time-partition  <id>  --column <col>  ✅
   │   │   # affects both profiling and metric monitoring (anomaly detection window)
   │   │   # no --column → view current partition column (via GET /datasets/{id})
@@ -180,13 +184,6 @@ sodacli
   │   │   # no flags → show current settings (GET /api/v1/datasets/{id}/diagnosticsWarehouse)
   │   │   [--collect-results|--no-collect-results]      # store check results and scan history  ✅
   │   │   [--collect-failed-rows|--no-collect-failed-rows]  ✅
-  │   │   # flags below accepted but not yet in public API (silently ignored):
-  │   │   [--schema <name>]  ❌
-  │   │   [--table-prefix <prefix>]  ❌
-  │   │   [--table-suffix <suffix>]  ❌
-  │   │   [--failed-rows-description <text>]  ❌
-  │   │   [--expose-failed-rows-query|--no-expose-failed-rows-query]  ❌
-  │   │   [--failed-rows-cta|--no-failed-rows-cta]  ❌
   │   │
   │   ├── onboard  <id>                                  # guided setup for an existing dataset  ✅
   │   │   [--monitoring]                                # enable default metric monitors  ✅
@@ -246,9 +243,9 @@ sodacli
   │       # looks up monitor type from dataset config, then calls appropriate DELETE
   │
   ├── incident
-  │   ├── list    [--status reported|investigating|fixing|resolved]  [--dataset <id>]  🔌 [CLI wired, API returns HTML]
-  │   ├── get     <id>  🔌 [CLI wired, API returns HTML]
-  │   └── update  <id>  🔌 [CLI wired, API returns HTML]
+  │   ├── list    [--status reported|investigating|fixing|resolved]  [--dataset <id>]  🔌 [CLI wired, API documented but returns HTML on dev]
+  │   ├── get     <id>  🔌
+  │   └── update  <id>  🔌
   │       [--title <text>]
   │       [--severity minor|major|critical]
   │       [--description <text>]
@@ -299,7 +296,7 @@ sodacli
   │   │
   │   ├── user
   │   │   ├── list  ✅
-  │   │   ├── invite  --email <email>                    # invite user to org  ❌
+  │   │   ├── invite  --email <email>                    # invite user to org (repeatable, max 10)  ✅
   │   │   ├── remove  <user-id>                          # remove user from org  ❌
   │   │   ├── assign  <user-id>  --role <role-id>  ❌
   │   │   └── revoke  <user-id>  --role <role-id>  ❌
@@ -326,8 +323,14 @@ sodacli
   │   └── delete  <runner-id>  ✅
   │
   ├── secret
-  │   ├── create  --name <n>  --value <v>  ❌ [NOT YET IMPLEMENTABLE - API work required]
-  │   ├── update  <id>        --value <v>  ❌
-  │   └── delete  <id>  ❌
+  │   ├── list                             # list all secrets  ✅
+  │   ├── get     <id>                     # show secret details  ✅
+  │   ├── create  --name <n>  [--value <v>]  ✅
+  │   │   # value encrypted client-side (AES-256-GCM + RSA-OAEP) before sending
+  │   │   # --value omitted → masked interactive prompt (or pipe via stdin)
+  │   │   # reference in configs: ${secret.NAME}
+  │   ├── update  <id>  [--value <v>]  ✅
+  │   │   # same input methods as create: --value flag, stdin pipe, or masked prompt
+  │   └── delete  <id>  ✅
   │
   └── completion  bash|zsh|fish  🏠

skills/soda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: soda-cli
-description: How to use the Soda CLI for data quality management — authentication, datasources, datasets, contracts, monitors, results, permissions, and CI/CD integration. Use when working with Soda, data quality, or the sodacli command.
+description: How to use the Soda CLI for data quality management — authentication, datasources, datasets, contracts, monitors, results, secrets, permissions, and CI/CD integration. Use when working with Soda, data quality, or the sodacli command.
 allowed-tools: Read, Bash(sodacli *), Bash(cat *), Glob, Grep
 ---
 
@@ -16,22 +16,21 @@ When calling `sodacli` from an agent, **always pass `--output json`** to get str
 
 **Fully working (tested against live API):**
 - `auth` — login, logout, status, switch profiles
-- `datasource` — list, get, create, delete, onboard (full wizard)
-- `dataset` — list (with filters), update, profiling, diagnostics, permissions, onboard
+- `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` — logs
-- `runner` — list, create (returns API keys for Kubernetes deployment)
-- `iam` — user list, group CRUD, role list
+- `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 (API returns HTML)
+- `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
-- `secret` — CRUD
 - `job list`, `job cancel`
-- `dataset get` (API returns HTML instead of JSON)
-- `datasource update`, `datasource test-connection`
 - `contract proposal` — list, pull, push, close
 - `monitor add --type dataset` (dataset monitors exist by default, no write endpoint)
 
@@ -69,18 +68,21 @@ Credentials stored in `~/.soda/credentials`. Generate API keys at https://docs.s
 # 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
-
-# NOTE: `sodacli dataset get <id>` is NOT available yet (API returns HTML).
-# Use `dataset list` with filters to find dataset details instead.
 ```
 
 ### Onboard a datasource (end-to-end)
@@ -232,14 +234,64 @@ sodacli iam group update <id> --remove-member bob@co.com
 sodacli iam group delete <id>
 ```
 
-### Job logs
+### Jobs (scan status & logs)
 
 ```bash
+# Check scan/job status (shows state, timing, check summary)
+sodacli job status <scan-id> --output json
+
+# View logs
 sodacli job logs <scan-id>
 sodacli job logs <scan-id> --follow    # stream live
 ```
 
-### Profiling and diagnostics
+### Secrets (encrypted credentials)
+
+```bash
+# List secrets
+sodacli secret list --output json
+
+# Create — value is encrypted client-side (AES-256-GCM + RSA-OAEP) before sending
+sodacli secret create --name DB_PASSWORD                       # masked interactive prompt
+sodacli secret create --name DB_PASSWORD --value "s3cret"      # via flag
+echo "s3cret" | sodacli secret create --name DB_PASSWORD       # via stdin pipe
+
+# Update value
+sodacli secret update <id>                                     # masked prompt
+sodacli secret update <id> --value "new-value"                 # via flag
+
+# Delete
+sodacli secret delete <id>
+
+# Reference in datasource configs: ${secret.DB_PASSWORD}
+```
+
+### User invite
+
+```bash
+sodacli iam user invite --email alice@co.com --email bob@co.com   # up to 10 per call
+```
+
+### Datasource connection & diagnostics
+
+```bash
+# Test a datasource connection (async via Runner)
+sodacli datasource test-connection config.yml
+
+# Update datasource label, runner, or connection
+sodacli datasource update <id> --label "Production DW"
+
+# View diagnostics warehouse config
+sodacli datasource diagnostics <id>
+
+# Configure diagnostics warehouse
+sodacli datasource diagnostics <id> --enable --warehouse same --collect-results --collect-failed-rows
+sodacli datasource diagnostics <id> --max-failed-rows 5000 --expose-failed-rows-query
+sodacli datasource diagnostics <id> --table-template "soda_{dataset_name}"
+sodacli datasource diagnostics <id> --failed-rows-cta --failed-rows-cta-title "View in Snowflake" --failed-rows-cta-url "https://app.snowflake.com"
+```
+
+### Profiling and dataset diagnostics
 
 ```bash
 # Enable profiling
@@ -251,7 +303,7 @@ sodacli dataset profiling <dataset-id> --output json
 # Set time-partition column
 sodacli dataset time-partition <dataset-id> --column created_at
 
-# Configure diagnostics
+# Configure dataset-level diagnostics overrides
 sodacli dataset diagnostics <dataset-id> --collect-results --collect-failed-rows
 ```