# Asset List Filter Matrix

Use this reference before composing a `sup ... list` command with filters.

Filter availability is per-entity, not universal.

| Entity | `--id` | `--ids` | `--search` | `--name` | `--mine` | `--limit` | Other |
|---|---|---|---|---|---|---|---|
| `chart` | yes | yes | yes (multi-field) | no | yes | yes | `--dashboard-id`, `--dataset-id`, `--viz-type`, `--team` |
| `dashboard` | yes | yes | yes (title/slug) | no | yes | yes | `--published`, `--draft`, `--folder` |
| `dataset` | yes | yes | yes (table name) | no | yes | yes | `--database-id`, `--schema`, `--table-type`, `--team` |
| `query` | yes | no | no | yes (label pattern, wildcards) | yes | yes | `--database-id`, `--schema` |
| `database` | no | no | no | no | no | no | output flags + `--workspace-id` only |
| `user` | no | no | no | no | no | yes | output flags + `--workspace-id` only |

`--workspace-id <id>` (long form) or `-w <id>` (short form) is accepted on every `list` command for per-command workspace override. Output flags (`--json`, `--yaml`, `--porcelain`) are also universal; see [output-formats.md](output-formats.md).

Do not emit invalid combinations such as `sup database list --mine`, `sup user list --search`, or `sup query list --search`. For saved queries, use `--name "<pattern>"` with wildcards rather than `--search`.

# Non-Destructive Asset Reads and Exports

Use this reference for `list`, `info`, and `pull` workflows that do not mutate workspace state.

## Supported Entities

| Entity | Commands | Notes |
|---|---|---|
| `database` | `sup database list`, `sup database info`, `sup database pull` | Connection metadata; secrets never returned. |
| `dataset` | `sup dataset list`, `sup dataset info`, `sup dataset pull` | Includes columns, metrics, and dataset YAML. |
| `chart` | `sup chart list`, `sup chart info`, `sup chart pull`, `sup chart data`, `sup chart sql` | `chart data` returns query results; `chart sql` returns compiled SQL. |
| `dashboard` | `sup dashboard list`, `sup dashboard info`, `sup dashboard pull` | Layout and chart references. |
| `query` | `sup query list`, `sup query info` | Saved query metadata and SQL. |
| `user` | `sup user list`, `sup user info`, `sup user pull` | User metadata, role memberships, and team assignments. `sup user push` and `sup user invite` exist and are mutating — load `preset-cli-mutations` for those. |

`pull` writes asset definitions to the local filesystem (YAML files in `./assets/` or a path supplied to the command). It does not modify the source workspace.

For entity-specific list filters, load [asset-filter-matrix.md](asset-filter-matrix.md). Do not assume a filter exists on every entity.

## Common Read Patterns

```bash
# Detail
sup chart info 3628 --json
sup dashboard info 254 --json

# Compiled SQL behind a chart (no execution)
sup chart sql 3628

# Run a chart's query and return its data (data-returning read; bounded output)
sup chart data 3628 --limit 100 --csv > chart-3628.csv
```

## Data-Returning Reads

`sup chart data` and `sup sql` are data-returning reads, not pure metadata. On familiar workspaces, run user-requested reads directly with bounded output and the disclosure rules in [sql-data-safety.md](sql-data-safety.md). A familiar workspace is one the user named in the current session or the active workspace verified with `sup config show` / `sup workspace show`. For unfamiliar workspaces, SQL that is not a pure single-statement `SELECT`, untrusted-source SQL, or broad outputs, load [safety-policy.md](safety-policy.md) and confirm first.

## Pull Without Mutation

`sup … pull` writes only to local disk. It is safe to run after resolving the workspace. The corresponding `push` and `sync` commands are mutating and live in `preset-cli-mutations`. There is no `sup database push` — database connections are not pushed via the CLI.

# CLI vs. API Decision Matrix

Use this reference when deciding whether a task is better served by `sup` (this package, `preset-cli-skills`) or by direct HTTP through the separate `preset-api-skills` package.

## Choose `sup` (this package) when

- The task is a one-shot shell command or pipeline (`sup chart list --json | jq …`).
- You need batch export to local YAML files (`sup chart pull`, `sup dashboard pull`).
- You want ad-hoc SQL with a single argument and immediate output (`sup sql "…" --json`).
- The workflow is CI/CD-driven (GitHub Actions, GitLab CI, Jenkins, etc.) and benefits from a CLI binary plus environment variables.
- The user is operating from a terminal and would otherwise have to write a bespoke HTTP script.
- The user explicitly mentions `sup`, `preset-cli`, `superset-cli`, or "the CLI".

## Choose `preset-api-skills` (HTTP) when

- You need in-process HTTP from a long-running Python program (web app, notebook, agent runtime).
- The flow requires fine-grained pagination, retries with backoff, or custom error handling.
- You need to call an endpoint that `sup` does not yet expose.
- You need request/response correlation IDs, custom headers, or non-default content types.
- You need async SQL Lab execution with explicit polling against `/api/v1/sqllab/results/`.
- You are composing multiple API calls in a single transaction-style flow where a CLI invocation per call would be wasteful.

## MCP Is a Different Surface

If the user mentions MCP, MCP tools, MCP clients, Superset MCP, Preset MCP, or Copilot/MCP behavior, do not use this package at all. Route to the separate `preset-mcp-skills` package. CLI is not a fallback for MCP-only work.

## Decision Table

| Task | CLI command | API chain |
|---|---|---|
| List my charts | `sup chart list --mine --json` | `preset-api-skills` (preset-dashboards) |
| Export 50 dashboards to YAML | `sup dashboard pull --ids=…` | `preset-api-skills` (preset-import-export) |
| Run a single ad-hoc query | `sup sql "…" --json` | `preset-api-skills` (preset-sql-execution) |
| Stop a long-running query | _(use API)_ | `preset-api-skills` (preset-sql-execution) |
| Rotate trusted domains | _(use API)_ | `preset-api-skills` (preset-embedding) |
| Promote dashboard between workspaces | `preset-cli-mutations` (sync) | `preset-api-skills` (preset-import-export + preset-destructive-imports) |
| Read query history | `sup query list --json` | `preset-api-skills` (preset-sqllab) |

## Hybrid Workflows

It is fine to mix CLI and API in a single workflow when each step plays to its strengths. Examples:

- `sup workspace list --json` to discover the workspace, then `preset-api-skills` to call a non-CLI endpoint against the resolved hostname.
- `sup dashboard pull` to fetch YAML locally, then `preset-api-skills` to introspect dashboard metadata via the Superset OpenAPI before pushing changes.

In hybrid flows, always document which step is CLI and which is HTTP in handoff notes so a reader can reproduce the result. Each package's safety policy applies to the calls it owns; this package's policy lives at [safety-policy.md](safety-policy.md).

## When in Doubt

Default to `sup` for terminal- and CI-style tasks; default to `preset-api-skills` for application code. If the user asks for a "one-liner", they almost always want `sup`.

# Registered `sup` Command Coverage

Use this reference before composing a command from a `sup` group that is not covered by a focused reference. The goal is to prevent agents from guessing command semantics when the CLI exposes more commands than this package documents in detail.

## Coverage Status

| Command group | Status | Routing |
|---|---|---|
| `sup config auth`, `sup config show` | Covered | Use [install-and-auth.md](install-and-auth.md) and [config-precedence.md](config-precedence.md). Treat config output as sensitive metadata. |
| `sup config set`, `sup config init` | Covered with local-context caution | Use [workspace-and-config.md](workspace-and-config.md). Explain whether the change writes global config or project-local state before running. |
| `sup workspace list/use/info/show` | Covered | Use [workspace-and-config.md](workspace-and-config.md). Bare `workspace use` is project-local unless `--persist` is supplied. |
| `sup workspace set-target` | Covered with mutation-adjacent caution | Use [workspace-and-config.md](workspace-and-config.md), then `preset-cli-mutations` before any command that writes to the target workspace. |
| `sup database list/use/info/pull` | Covered | Use [assets-read.md](assets-read.md) and [workspace-and-config.md](workspace-and-config.md). `database use` changes local context; it does not mutate a workspace asset. |
| `sup dataset list/info/pull` | Covered | Use [assets-read.md](assets-read.md) and [asset-filter-matrix.md](asset-filter-matrix.md). |
| `sup chart list/info/sql/data/pull` | Covered | Use [assets-read.md](assets-read.md). For `chart data`, load [sql-data-safety.md](sql-data-safety.md). |
| `sup dashboard list/info/pull` | Covered | Use [assets-read.md](assets-read.md) and [asset-filter-matrix.md](asset-filter-matrix.md). |
| `sup query list/info` | Covered | Use [saved-query-reads.md](saved-query-reads.md). Saved query SQL text can be sensitive. |
| `sup user list/info/pull` | Covered | Use [assets-read.md](assets-read.md). User metadata can include role and team membership context. |
| `sup sql` | Covered | Use [sql-and-query.md](sql-and-query.md) and [sql-data-safety.md](sql-data-safety.md). Treat as data-returning even for read-only SQL. |
| `sup chart/dashboard/dataset push` | Covered with mutation gates | Stop and load `preset-cli-mutations`; use its write preview, diff, and confirmation references. |
| `sup user push/invite` | Covered with mutation gates | Stop and load `preset-cli-mutations`; these commands expose native `--dry-run` and require confirmation before execution. |
| `sup sync create/validate/run` | Covered with mutation gates | Use `preset-cli-mutations`. `validate` is non-mutating; `run` can mutate every configured target workspace. |
| `sup sync native` | Known but not operationally covered | Treat as high-risk mutation. It can push assets from a directory, use `--overwrite` / `--force`, and accept database password inputs. Stop and ask whether to proceed with an explicit CLI mutation plan or switch to API import guidance. |
| `sup theme list/pull` | Known but not operationally covered | Treat like asset read/export. Confirm workspace and output path, then prefer `--json` / `--porcelain` for automation. |
| `sup theme push` | Known but mutation-gated | Treat like an asset write with overwrite risk. Stop and ask for a preview/confirmation plan before running. |
| `sup role pull` / `sup rls pull` / `sup ownership pull` | Known but not operationally covered | Treat as governance/security export. Confirm workspace and destination; avoid pasting full role, RLS, or ownership payloads into shared transcripts. |
| `sup role push/sync`, `sup rls push`, `sup ownership push` | Known but mutation-gated | Governance/security mutations. Require native `--dry-run` when available, summarize the affected roles/rules/assets, and get explicit confirmation before execution. |
| `sup group list` | Known but not operationally covered | Team/SCIM metadata read. Confirm team and limit output; do not paste full membership payloads unless requested. |
| `sup group sync/create` | Known but mutation-gated | Team/SCIM mutation. Require dry-run or preview where available, summarize group and member counts, and get explicit confirmation before execution. |
| `sup dbt core/cloud/list-models` | Known but not operationally covered | Advanced integration workflow. Run only when the user explicitly asks for dbt metadata sync or model discovery; otherwise stop and ask. |

## Rules for Uncovered Commands

- Do not invent examples for command groups marked "known but not operationally covered".
- For any `push`, `sync`, `create`, import, overwrite, or force-style command not covered by a focused reference, stop before execution and ask for an explicit mutation plan.
- For any command that can return row-level data, SQL text, role/RLS configuration, ownership, user, group, or team membership data, summarize or write to a file rather than pasting full payloads into chat.
- Prefer `sup <group> <command> --help` when the user asks for syntax for a known-but-undocumented group, then quote only the relevant flags needed for the task.

# Common CLI Command Examples

Use this reference when the user needs concrete `sup` command examples after routing and safety checks are complete.

## Discovery

```bash
sup workspace list --json
sup dashboard list --mine --json --limit 100
sup chart list --search="revenue" --json
sup dataset list --search="users" --json
sup query list --name="*revenue*" --json
```

## Detail and Export

```bash
sup chart info 3628 --json
sup dashboard info 254 --json
sup chart pull 3628
sup dashboard pull 254
sup dataset pull 914
```

## Data-Returning Reads

Load [sql-data-safety.md](sql-data-safety.md) before running these:

```bash
sup chart sql 3628
sup chart data 3628 --csv > chart-3628.csv
sup sql "SELECT COUNT(*) FROM users" --json
sup sql "SELECT * FROM sales" --csv > sales.csv
```

# `sup` Configuration Precedence

Use this reference when a command depends on credentials, workspace IDs, database IDs, assets folders, or target workspace context.

`sup` resolves configuration with two different precedence chains depending on the field. The CLI's own `sup config` help text shows env > global > project for everything, but upstream `src/sup/config/settings.py` only follows that order for credentials. For workspace, database, assets-folder, and target-workspace context, project state shadows global config.

## Credentials

`SUP_PRESET_API_TOKEN` and `SUP_PRESET_API_SECRET` resolve as env -> global:

1. `SUP_PRESET_API_TOKEN` / `SUP_PRESET_API_SECRET` environment variables.
2. Global `~/.sup/config.yml`.

There is no project-local credential store; tokens live in env or `~/.sup/config.yml`.

## Context Fields

Workspace ID, database ID, assets folder, and target workspace resolve as override -> env -> project -> global:

1. Per-command CLI override (`--workspace-id`, `--database-id`, etc.).
2. `SUP_*` environment variables such as `SUP_WORKSPACE_ID`.
3. Project-local `.sup/state.yml`.
4. Global `~/.sup/config.yml`.

So an agent that runs `sup config set workspace-id 123` (writes to `~/.sup/config.yml`) and then `sup workspace use 456` (writes to `.sup/state.yml` by default) will see workspace 456 win in the current directory. Project-local state shadows the global default.

## Verification

Always verify active values with `sup config show` before relying on a precedence claim; it prints resolved values, not the precedence chain. In handoffs, record whether credentials and context came from environment, project state, or global config when running in CI.

# Install and Authenticate `sup`

Use this reference for installing the Preset CLI, choosing an entry point, and wiring up authentication without leaking secrets.

## Install

The modern `sup` entry point ships in the `superset-sup` PyPI distribution.

```bash
pip install superset-sup
```

Verify the install:

```bash
sup --version
sup --help
```

The legacy `preset-cli` distribution (separate PyPI package) ships the older `preset-cli` and `superset-cli` entry points. Do **not** `pip install preset-cli` when you want `sup` — that installs the legacy CLI and does not provide the `sup` binary.

## Entry Points

| Entry point | PyPI package | Status | Use for |
|---|---|---|---|
| `sup` | `superset-sup` | Primary | Modern, agent-friendly UX. All new agent workflows should target `sup`. |
| `preset-cli` | `preset-cli` | Legacy | Long-form Preset workspace flows (`preset-cli --workspaces=… superset …`). |
| `superset-cli` | `preset-cli` | Legacy | Standalone Superset deployments not managed by Preset. |

When writing agent scripts, default to `sup`. Only fall back to `preset-cli` or `superset-cli` if the user references a legacy workflow or a `sup` subcommand is documented as missing.

## Configure Authentication

The CLI authenticates against the Preset Management API using the same API token/secret you get from `https://manage.app.preset.io/app/user`. `sup` reads them from `SUP_*`-prefixed environment variables (not the `PRESET_CLIENT_ID` / `PRESET_CLIENT_SECRET` pair used by direct API skills).

```bash
export SUP_PRESET_API_TOKEN="your-api-token"
export SUP_PRESET_API_SECRET="your-api-token-secret"

sup config auth
sup config show
```

`sup config auth` is interactive. It prompts for the API token and secret, tests them, then offers to either store them in `~/.sup/config.yml`, print export lines for your shell profile, or skip storage so you set `SUP_PRESET_API_TOKEN` / `SUP_PRESET_API_SECRET` yourself.

When credentials are stored in `~/.sup/config.yml`, they are written as plaintext YAML — the file is not hashed or encrypted. Protect that file with filesystem permissions and avoid committing it to source control. For CI/CD, prefer the env-var path so the secret never touches disk.

Use `sup config show` to confirm the active workspace, target workspace, and authentication status before running subsequent commands.

## Secret Hygiene

- Never pass `SUP_PRESET_API_TOKEN` or `SUP_PRESET_API_SECRET` inline on the command line; set them as environment variables before invoking `sup config auth` or let `sup config auth` prompt for them interactively.
- Do not commit `~/.sup/config.yml` or any `.sup/state.yml` containing tokens to source control.
- For CI/CD, inject credentials via the runner's secret store (GitHub Actions secrets, GitLab CI variables, Vault, etc.) and reference them as environment variables only.
- Redact tokens, JWTs, and any `Authorization:` headers in command transcripts and screenshots.

For precedence between environment variables, project-local state, and global config, load [config-precedence.md](config-precedence.md).

# `sup` Output Formats

Use this reference when choosing output flags for an agent, automation script, or CI job.

## Format Flags

| Flag | When to use |
|---|---|
| `--json` | Default for agents. Structured, parsable, stable field names. |
| `--csv` | Tabular data export from data-returning commands only (`sup sql`, `sup chart data`); spreadsheets, downstream pandas/duckdb. Not supported on `list` commands. |
| `--yaml` | Configuration-friendly output that round-trips with `sup` config files. |
| `--porcelain` | Machine-readable, no decorations, stable across versions for scripting (`xargs`, `awk`, `cut`). |
| _(none)_ | Rich human tables. Never produce these in agent-driven contexts. |

## Examples

```bash
sup chart list --mine --json
sup dataset list --search="sales" --json > sales-datasets.json
sup workspace list --porcelain | awk '{print $1}'
sup sql "SELECT COUNT(*) FROM users" --json
sup sql "SELECT * FROM sales" --csv > sales.csv
sup chart data 3628 --csv > chart-3628.csv
```

`--csv` is supported on `sup sql` and `sup chart data` (data-returning commands). `list` commands only support `--json`, `--yaml`, and `--porcelain` — there is no `--csv` on list. Pipe through `jq` to `@csv` if you need CSV-shaped list output.

## Default for Agents

When you cannot tell what downstream system will consume the output, default to `--json`:

- Field names are stable.
- Empty results produce `[]` (or `{}`), not blank lines.
- Errors are reported via exit code and stderr, not embedded in the stdout payload.

Only switch off `--json` when the user explicitly asks for CSV/YAML or when piping into a tool that needs porcelain.

## Exit Codes and Streams

- Exit code `0` indicates success.
- Non-zero exit codes indicate failures (auth, validation, transport, server-side error). Surface the exit code in any agent transcript.
- Structured output goes to **stdout**; warnings, spinner frames, and human-facing logs go to **stderr**.
- For agent capture, redirect cleanly: `sup chart list --json 2>/dev/null` keeps stdout clean for JSON parsing, while `sup chart list --json 2>chart.log` preserves diagnostics for incident review.

## Large Results

When listing many assets or exporting query rows, pair the format flag with an explicit `--limit` to bound output. `list` commands default to unbounded with a `--page-size 100` server fetch — they will return every result the server has if you do not cap. `sup sql` is the exception: `--limit 1000` (rows fetched) and `--max-rows 100` (rows displayed) are the upstream defaults. Always set `--limit` deliberately when the consumer cannot handle large payloads.

# CLI Safety Policy

<!-- gate-policy v2 -->

Use this reference before mutations, SQL that is not a pure single-statement `SELECT`, untrusted-source SQL, unfamiliar workspaces, or broad outputs. It is the local, CLI-flavored safety policy for this package; it does not link out to other plugins so this package remains independently installable. Gates scale with blast radius, reversibility, and disclosure sensitivity — data-returning reads on familiar workspaces that the user asked for run directly with bounded output.

## Default Posture

- Default to non-destructive reads: `sup … list`, `sup … info`, `sup … pull`, `sup workspace show`, `sup config show`.
- Treat `sup chart data` and `sup sql` as data-returning reads: they can expose customer data even though they do not change workspace state.
- Treat every push, sync, `--force`, and `--overwrite` invocation as state-changing. Refuse to execute these directly from `preset-cli`; route to `preset-cli-mutations`, which loads its confirmation template by construction.
- A familiar workspace is one the user named in the current session or the active workspace verified with `sup config show` / `sup workspace show`; if the workspace cannot be proven from that context, treat it as unfamiliar.

## Confirmation Required

Before any of the following, summarize the exact target, payload, and expected effect, then get explicit user confirmation:

- `sup chart push`, `sup dashboard push`, `sup dataset push` (single-workspace writes).
- Any `--force` or `--overwrite` invocation.
- `sup sync run` against any target workspace.
- `sup chart data <id>` or `sup chart data <id> --csv|--json` on an unfamiliar workspace (data-returning read).
- `sup sql "<query>"` that runs against an unfamiliar workspace, or any SQL statement that is not a pure single-statement `SELECT`.
- Exporting query rows or chart data to a destination other than a local file the user already named.

For mutations, the confirmation must name the target workspace by its human-readable name. If `--force` or `--overwrite` is part of the planned command, the confirmation must also contain the literal flag strings.

## Secret Hygiene

- Never paste `SUP_PRESET_API_TOKEN`, `SUP_PRESET_API_SECRET`, or any bearer token onto a command line. Use environment variables or `sup config auth`.
- Do not enumerate `SUP_*` environment variables on the user's behalf. If a user needs to debug their environment, ask them to run `env | grep SUP_` themselves, locally, and redact any token/secret values before sharing the output. The agent must not run any "dump all env vars" command in a shared transcript.
- Do not commit `~/.sup/config.yml` or any `.sup/state.yml` that contains stored credentials.
- Redact access tokens, refresh tokens, JWTs, database passwords, SQLAlchemy URIs, and signed guest tokens in transcripts, screenshots, PR comments, and CI logs.
- When dataset push pushes a referenced database connection, treat the database connection as a credential-bearing surface even if `sup` does not print the secret.

## Cross-Workspace Sync

`sup sync run` can mutate every target workspace listed in the configuration in a single command. Before executing:

- Confirm each target workspace by name (not just ID).
- Confirm the asset counts per target from the dry-run output.
- Confirm whether any target hosts production-facing dashboards; if so, escalate the confirmation.
- Recognize the rollback model: there is no automatic rollback. The sync configuration in git is the source of truth; recovery means reverting the sync directory in git and rerunning.

## Pull-and-Diff for Entity Push

`sup chart push`, `sup dashboard push`, and `sup dataset push` do **not** expose a native `--dry-run` flag. The CLI commands that do expose native `--dry-run` are `sup sync run`, `sup user push`, and `sup user invite` — use the native flag there. For chart/dashboard/dataset push, the agent must pull the current target state with the matching `sup … pull` command and diff against the assets folder, then present the diff as the preview. Skipping this step is equivalent to skipping `--dry-run` on a sync, and is refused by `preset-cli-mutations`.

## Headless / CI Contexts

- Row-returning data exports (`sup sql`, `sup chart data`) need explicit row/output bounds in the command or script.
- Full workspace/asset exports need an explicit destination and disclosure handling (where the archive lands, who can read it) — row limits are not required for full exports.
- Destructive operations (push, sync, `--force`, `--overwrite`) always require an interactive operator; CI or automation context never bypasses the confirmation step.

## Transcripts and Audit Trail

- Record the resolved workspace ID and name before running anything mutating.
- Capture the `sup` exit code after every mutating run.
- Note the audit log location in the target workspace so the operator can review the change there.

## When to Stop

If a CLI workflow cannot satisfy the request safely - because the required preview is missing, because a credential would have to be inlined, or because the user has not named the target workspace - stop and ask. Do not silently fall back to direct HTTP or to MCP tools; surface the limitation and let the user choose the next surface explicitly.

# Saved Query Reads

Use this reference for `sup query list` and `sup query info`.

```bash
sup query list --mine --json
sup query list --name="*revenue*" --json
sup query info <query-id> --json
```

Saved-query filtering uses `--name "<pattern>"` (label pattern, supports wildcards), not `--search`. The `--search` flag exists for `sup chart/dashboard/dataset list` but is not implemented for `sup query list`; passing it will error.

Saved queries can contain SQL text owned by other users. Listing returns metadata; fetching a saved query returns the SQL body. Treat the SQL body as sensitive because it may encode business logic, table names, or filtering conditions. Avoid printing it in shared transcripts unless the user has approved that disclosure.

# SQL and Saved Queries via `sup`

Use this reference for basic ad-hoc SQL routing through `sup sql`. For row disclosure rules, load [sql-data-safety.md](sql-data-safety.md). For saved query metadata and SQL text reads, load [saved-query-reads.md](saved-query-reads.md).

## Ad-hoc SQL Execution

```bash
sup sql "SELECT COUNT(*) FROM users" --json
sup sql "SELECT * FROM sales LIMIT 100" --csv
sup sql "SELECT id, email FROM users WHERE active" --porcelain
```

`sup sql` runs through Superset's data access layer in the active workspace, so it inherits the same database connections, row limits, and RLS policies as SQL Lab. It is not a direct database connection.

## Read-Only Stance

Treat `sup sql` as read-only by default:

- Run `SELECT` statements freely after confirming the workspace.
- Refuse `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, `DROP`, `ALTER`, `CREATE`, `MERGE`, `REPLACE`, `GRANT`, `REVOKE`, `CALL`, and `COPY` without explicit user confirmation that the upstream database is the intended target and that DML/DDL is in scope. Route confirmation through [sql-data-safety.md](sql-data-safety.md) and [safety-policy.md](safety-policy.md).
- Do not paste user-supplied SQL into shell strings without confirming there are no shell metacharacters that would break quoting; prefer single-quoted heredocs for multi-line statements.

## Large Result Handling

- `sup sql` exposes two row-limit knobs: `--limit <n>` / `-l <n>` controls how many rows are fetched from Superset (default `1000`), and `--max-rows <n>` controls how many of those are displayed in the terminal (default `100`). Both are CLI flags. The workspace SQL Lab row cap still applies as a hard upper bound.
- For exports over a few thousand rows, pipe to a file: `sup sql "SELECT …" --csv > export.csv`. Pair with `--limit` to cap fetched rows; `--max-rows` is irrelevant when piping (it only gates terminal display). Never paste large CSV/JSON bodies into chat transcripts.
- For analyst-facing iteration, prefer `sup sql` with `--json` over `--csv` so that null handling and types survive intermediate processing.

## When to Use the API Instead

Use the separate `preset-api-skills` package (instead of `sup sql`) when you need:

- Programmatic pagination of result chunks.
- Async execution with explicit `client_id` correlation.
- Result polling via `/api/v1/sqllab/results/`.
- Permalink creation or query-history correlation.

See [cli-vs-api.md](cli-vs-api.md) for the decision matrix.

# SQL and Data-Returning Read Safety

Use this reference before `sup sql`, `sup chart data`, or any CLI command that returns row-level data.

## Scope Checks

For familiar workspaces and user-requested reads, run directly with explicit output bounds. A familiar workspace is one the user named in the current session or the active workspace verified with `sup config show` / `sup workspace show`; if the workspace cannot be proven from that context, treat it as unfamiliar. Before running a data-returning read on an unfamiliar workspace, confirm:

- The workspace and chart/query target.
- The expected row volume.
- The destination of the output: local file, transcript, or downstream pipeline.
- Whether the output may include customer data, PII, business logic, or SQL text.

Use `--limit` to cap fetched rows and avoid pasting large CSV/JSON bodies into chat transcripts.

## `sup sql`

`sup sql` runs through Superset's data access layer in the active workspace, so it inherits the same database connections, row limits, and RLS policies as SQL Lab. It is not a direct database connection.

Treat `sup sql` as read-only by default. Refuse `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, `DROP`, `ALTER`, `CREATE`, `MERGE`, `REPLACE`, `GRANT`, `REVOKE`, `CALL`, and `COPY` unless the user explicitly confirms that the upstream database is the intended target and DML/DDL is in scope.

`sup sql` exposes two row-limit knobs: `--limit <n>` / `-l <n>` controls how many rows are fetched from Superset (default `1000`), and `--max-rows <n>` controls how many of those are displayed in the terminal (default `100`). The workspace SQL Lab row cap still applies as a hard upper bound.

## `sup chart data`

`sup chart data` returns a chart's query results. Treat it like `sup sql`: use a small limit, prefer file output for larger exports, and summarize rather than pasting raw payloads.

Load [safety-policy.md](safety-policy.md) before SQL that is not a pure single-statement `SELECT`, untrusted-source SQL, unfamiliar workspaces, broad outputs, or any mutation.

# Workspace Selection and Configuration

Use this reference when listing workspaces, switching the active workspace, or overriding the workspace for a single command.

## Inspect Configuration

```bash
sup config show          # Active workspace, target workspace, auth status
```

`sup config show` is the safe first call when an agent needs to verify which workspace will receive subsequent commands. Resolve the workspace before data-returning reads; a familiar workspace is one the user named in the current session or the active workspace verified with `sup config show` / `sup workspace show`. Confirm for unfamiliar workspaces, broad outputs, or operations that could be construed as state-changing. There is no `sup config list`; use `show` for current settings.

Do not run a "dump all env vars" command in agent transcripts. `SUP_PRESET_API_TOKEN` and `SUP_PRESET_API_SECRET` are sensitive; if a user needs to debug their environment, ask them to run `env | grep SUP_` themselves, locally, and to redact any token/secret values before sharing the output. The agent should not enumerate `SUP_*` environment variables on the user's behalf.

## List and Choose Workspaces

```bash
sup workspace list --json
sup workspace use <workspace-id>             # Project-local: writes to .sup/state.yml in the current directory
sup workspace use <workspace-id> --persist   # Global: writes to ~/.sup/config.yml (short form: -p)
sup workspace show                # Display source + target workspace context
sup workspace info <workspace-id> # Inspect a single workspace
```

`sup workspace use` accepts a numeric workspace ID, a workspace URL (e.g. `https://myworkspace.us1a.app.preset.io/`), or a bare hostname. **Without `--persist`, the selection is project-local** — `sup` writes to `.sup/state.yml` in the current directory and the CLI reports "Using workspace `{id}` for this project". Pass `--persist` (or `-p`) to save the selection to the global `~/.sup/config.yml`. For ephemeral overrides in CI or scripts, prefer the env var `SUP_WORKSPACE_ID=<id>` instead of either persistence mode.

Pair with `sup workspace list --json` to discover IDs before calling `use`.

## Set Configuration Values

```bash
sup config set workspace-id 123
sup config set target-workspace-id 456    # cross-workspace operations; see preset-cli-mutations
```

`target-workspace-id` is only meaningful for push/sync workflows; it has no effect on read commands. Setting a target workspace does not authorize a mutation — it is still gated by `preset-cli-mutations`.

## Per-Command Override

For one-off operations against a non-default workspace, prefer the per-command flag over editing config:

```bash
sup chart list --workspace-id 456 --json
sup dataset list --workspace-id 789 --search="orders" --json
```

The flag accepts `--workspace-id <id>` (long form) or `-w <id>` (short form). Per-command overrides keep `~/.sup/config.yml` stable for the user's interactive session and make agent intent explicit in scripts and CI logs.

For file locations and context precedence, load [config-precedence.md](config-precedence.md). Do not commit `.sup/state.yml` if it pins workspaces that other contributors should not inherit; add it to `.gitignore` instead.

## Verifying Workspace Before Mutations

Before chaining to `preset-cli-mutations` for any push or sync, the agent must:

1. Run `sup config show` (or `sup workspace show`) and record the source and target workspace.
2. Confirm both with the user by name (not just ID).
3. Hand off to `preset-cli-mutations` only after the user confirms.