superset-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{superset_cli-0.2.0 → superset_cli-0.3.0}/AGENTS.md

@@ -82,6 +82,14 @@ For CLI changes:
 - preserve existing JSON output shape unless the contract is intentionally changed
 - when changing the contract, update tests and docs in the same task
 
+## CLI output and CI verification
+
+- Before adding CLI tests, inspect nearby tests and reuse their output normalization and environment setup.
+- Assert semantic help text, not raw terminal output. For Rich/Typer help, normalize with `Text.from_ansi(result.stdout).plain`.
+- Every new help-output test must cover forced-color and no-color environments. Do not disable colors merely to hide failures.
+- Before committing, inspect `.github/workflows/ci.yml` and reproduce relevant CI conditions, including supported Python versions, locked dependencies, and terminal/color settings. Report any untested matrix conditions explicitly.
+- After an authorized push, inspect all CI checks. Report pending or failed checks explicitly; local test success is not CI success.
+
 ## Decision memory rules
 
 - Treat `docs/decisions/` as the canonical long-term memory for why this repository works the way it does.

{superset_cli-0.2.0 → superset_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: superset-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: CLI for self-hosted Apache Superset
 Project-URL: Source, https://github.com/RobinOnHisOwn/superset_cli
 Project-URL: Issues, https://github.com/RobinOnHisOwn/superset_cli/issues
@@ -32,6 +32,23 @@ Current scope (read by default, write opt-in):
 - shared list-query controls on all list commands via `--page` (0-based), `--page-size`, `--search`, `--order-column`, and `--order-direction`
 - user-friendly error messages for auth expiry, missing resources, and network failures (exit code 1, no raw tracebacks)
 
+## HTTP timeouts
+
+Use the root `--timeout SECONDS` option **before the command** for slow API requests:
+
+```bash
+superset-cli --timeout 90 charts data prod 7 --json
+superset-cli --timeout 90 api prod /api/v1/dashboard/
+```
+
+The default remains 30 seconds. Values must be finite and positive. The option
+applies to API requests, authentication validation/recovery, CSRF acquisition,
+and JWT login/refresh. It controls HTTPX connect/read/write/pool phase or
+inactivity timeouts, **not a total command deadline**. It is not saved in config.
+A timeout exits non-zero; a sent mutation's outcome is unknown. Check server
+state before retrying. The CLI never automatically retries a sent mutation;
+`--allow-write` is still required on every write invocation.
+
 ## Decision log
 
 Long-lived technical reasoning lives in `docs/decisions/`.
@@ -58,7 +75,7 @@ superset-cli --help
 
 Upgrade with `uv tool upgrade superset-cli`. Python 3.12 or newer is required;
 uv can provision Python when needed. `pipx install superset-cli` is an alternative.
-PyPI `0.1.0` was verified on 2026-10-06: its wheel includes the API command, CSRF handling, validated cookie-import fallback, and `--clear-query-context`, but no `--version` flag. A local installation also labeled `0.1.0` lacked those capabilities; version labels alone are insufficient. This checkout builds distinct **0.2.0** artifacts with `--version`; they have not been published.
+PyPI `0.1.0` was verified on 2026-10-06: its wheel includes the API command, CSRF handling, validated cookie-import fallback, and `--clear-query-context`, but no `--version` flag. A local installation also labeled `0.1.0` lacked those capabilities; version labels alone are insufficient. PyPI **0.2.0** was rechecked on 2026-10-07 and includes `--version`, owners, CSRF handling, and Playwright export. This checkout builds distinct unpublished **0.3.0** artifacts with the new cache controls. An isolated upgrade from 0.1.0 through 0.2.0 to the built 0.3.0 wheel preserved synthetic config/auth files; no publication was performed.
 
 Check `command -v superset-cli`, then its installation owner (`uv tool list` or `pipx list`). If it is installed but missing from PATH, use `uv tool update-shell` or `pipx ensurepath` rather than installing another copy. Upgrade with the same tool (`uv tool upgrade superset-cli` or `pipx upgrade superset-cli`). Config/auth files remain separate from the package installation. Check `api --help` and `charts update --help` once per session for required capabilities; use `--version` when available. Inside this source checkout, select `uv run superset-cli` explicitly.
 
@@ -180,6 +197,72 @@ loopback development (`localhost` or loopback IP literals); embedded URL
 credentials and malformed bearer values are rejected without echoing secrets.
 Updating an instance URL preserves its selected auth mode and bindings.
 
+## API-key authentication (capability-gated)
+
+The source-verified combination is **Superset 6.1.0 with Flask-AppBuilder 5.2.2**,
+`FAB_API_KEY_ENABLED=True`, initialized key storage, an active issued key, and a
+matching prefix. Superset's version alone does not guarantee support. No real
+API-key deployment was exercised during implementation; see [ADR 0023](docs/decisions/0023-environment-bound-api-keys.md).
+
+Provide an existing issued key through a secure environment injector, never a
+literal CLI argument or config value. Register only its environment-variable name:
+
+```bash
+superset-cli auth api-key set prod --env EXAMPLE_SUPERSET_API_KEY --json
+superset-cli auth validate prod --json
+superset-cli charts list prod --json
+superset-cli auth api-key clear prod --json
+```
+
+`set` verifies a read-only `/api/v1/me/` request before saving the binding. Use
+`--prefix` if the server's configured prefix differs from `sst_`. The CLI does not
+issue/revoke keys, enable server flags, or upgrade server dependencies. Unsupported
+or rejected authentication fails without saving a binding or browser/JWT fallback.
+Keys are reread from the environment per invocation and never saved in auth files.
+HTTPS is required except loopback HTTP development; redirects and embedded URL
+credentials are rejected. CSRF, timeouts, and per-invocation `--allow-write` remain
+required as applicable; sent mutations never replay. `auth status` reports local
+credential availability, not current server acceptance. `clear` returns to cookie
+mode without deleting cookie/JWT files. Selecting API-key mode replaces prior auth
+bindings; clearing it does not restore JWT credential bindings or the previous mode.
+Reconfigure JWT explicitly when switching back. API keys cannot be exported to Playwright.
+
+## Resource list controls
+
+All 15 resource/security lists support optional `--filter`, `--columns`, and `--all`.
+`instances list` is local, not paginated. Ordinary single-page output is unchanged.
+
+```bash
+superset-cli charts list prod --filter '{"col":"viz_type","opr":"eq","value":"table"}' --columns id --columns slice_name --json
+superset-cli logs list prod --filter '{"col":"dttm","opr":"gt","value":"2026-01-01"}' --json
+superset-cli dashboards list prod --all --page-size 100 --json
+```
+
+Repeat JSON-object filters with exactly `col`, `opr`, and `value`. Values retain
+JSON types (strings, numbers, booleans, null, arrays); filters AND together and
+append to `--search`. This is distinct from chart-data `--filter col=value`.
+Resource `_info` determines supported fields/operators; unsupported combinations
+fail rather than using a guessed universal catalog. When a resource omits `_info`
+(as Superset 6.1.0 logs do), the list endpoint validates the filter directly.
+Permission failures never trigger this fallback.
+
+Repeat `--columns FIELD` once per unique field. Resource list metadata is checked
+before requesting `q.columns` on the server. Projected human output is compact
+JSON per returned row, so omitted default fields do not produce `None` placeholders.
+Single-page `--json` preserves the server envelope.
+
+`--all` starts at page zero, rejects explicit `--page`, and requests 100 records
+per page unless `--page-size` is given. Server caps are respected. Filters,
+projection, and ordering persist across pages; ID ordering is preferred only
+when advertised, otherwise explicit/server ordering is retained. Server `ids`
+allow duplicate checks without adding an unrequested ID field to the projection.
+The aggregate JSON envelope is exactly `{count, ids, result}`. No aggregate is
+printed if a later page fails, counts change, identities duplicate, or pages stop
+early. **This is not an atomic snapshot**: non-unique ordering and concurrent
+changes can still affect completeness even when checks pass. Buffering `--all`
+uses memory proportional to the result. Capability checks add small read requests;
+legacy single-page lists without new controls add none. See [ADR 0022](docs/decisions/0022-explicit-list-query-controls.md).
+
 ## Current commands
 
 ```bash
@@ -277,6 +360,57 @@ original saved-chart GET endpoint is used. The chart must have a usable saved
 uv run superset-cli charts data prod 10 --time-range '2026-04-01 : 2026-05-01' --filter region=west --json
 ```
 
+### Chart cache controls
+
+```bash
+uv run superset-cli charts data prod 10 --cache-info
+uv run superset-cli charts data prod 10 --force --allow-write --json
+uv run superset-cli charts data prod 10 --time-range 'Last week' --filter region=west --force --allow-write --csv
+uv run superset-cli cache invalidate prod --dataset 21 --dataset 22 --allow-write --json
+```
+
+Use discovered numeric IDs; these examples do not authorize live writes.
+`--cache-info` reports each query's server-supplied cache hit/miss, key, timestamp,
+and timeout without extra requests. Missing metadata is unknown, null stays null,
+false means a miss, zero stays zero, and -1 denotes disabled caching. JSON and CSV
+remain unchanged, including errors/empty-result exits. Different native-filter
+combinations can have different cache keys; HTTP success is not freshness proof.
+
+`--force` loads the exact requested queries from source and normally replaces
+those cache entries, unless caching is disabled. It does not update saved chart
+configuration or invalidate every dataset/filter combination. Saved-chart GET
+uses `force=true`; copied override POST uses top-level boolean `force`. Because
+force refresh deliberately changes cached state, it requires literal
+`--allow-write` before auth/network access. Ordinary chart reads and non-force
+query overrides retain their existing behavior. Source-verified on Superset 6.1.0;
+unsupported endpoints/contexts fail rather than inventing another transport.
+
+`cache invalidate` requires at least one positive numeric SQLA dataset ID; repeat
+`--dataset`, duplicates are removed. UUIDs and implicit all-dataset targets are
+not supported. IDs map to `<ID>__table` datasource UIDs, not dataset UUIDs. The
+target OpenAPI must support `POST /api/v1/cachekey/invalidate` with string
+`datasource_uids`; configured auth, CSRF, and server `CacheRestApi` invalidate
+permissions apply. No service users, keys, or configuration are created.
+
+**External prerequisites:** `STORE_CACHE_KEYS_IN_METADATA_DB=True`, tracked keys,
+and compatible cache/data-cache backend, database, and key-prefix configuration.
+Existing untracked entries are not indexed retroactively. Superset 6.1.0 deletes
+through `cache_manager.cache` while chart results use `data_cache`; an incompatible
+setup can remove tracking metadata and return 201 without evicting chart results.
+The endpoint can also log incomplete deletion yet return success. JSON therefore
+reports `{dataset_ids, datasource_uids, accepted, eviction_verified, response}`,
+with `eviction_verified=false`, never invented deletion counts. Human output says
+request accepted, **not verified eviction**.
+
+A network failure leaves the outcome unknown; inspect server state before an
+explicit rerun. Sent invalidations never replay automatically. Even a retry's
+success cannot prove eviction after tracking records disappeared. Live acceptance
+requires an explicitly authorized isolated instance: pre-cache multiple filter
+combinations plus an unrelated dataset, invalidate only targets, and verify normal
+non-forced rendered requests stop reusing old target results while unrelated
+cache/session/Celery state stays intact. That live check has not been run. No
+Redis flush or fallback is provided. See [ADR 0024](docs/decisions/0024-targeted-cache-controls.md).
+
 ### Read-only ZIP exports
 
 ```bash

{superset_cli-0.2.0 → superset_cli-0.3.0}/README.md

@@ -16,6 +16,23 @@ Current scope (read by default, write opt-in):
 - shared list-query controls on all list commands via `--page` (0-based), `--page-size`, `--search`, `--order-column`, and `--order-direction`
 - user-friendly error messages for auth expiry, missing resources, and network failures (exit code 1, no raw tracebacks)
 
+## HTTP timeouts
+
+Use the root `--timeout SECONDS` option **before the command** for slow API requests:
+
+```bash
+superset-cli --timeout 90 charts data prod 7 --json
+superset-cli --timeout 90 api prod /api/v1/dashboard/
+```
+
+The default remains 30 seconds. Values must be finite and positive. The option
+applies to API requests, authentication validation/recovery, CSRF acquisition,
+and JWT login/refresh. It controls HTTPX connect/read/write/pool phase or
+inactivity timeouts, **not a total command deadline**. It is not saved in config.
+A timeout exits non-zero; a sent mutation's outcome is unknown. Check server
+state before retrying. The CLI never automatically retries a sent mutation;
+`--allow-write` is still required on every write invocation.
+
 ## Decision log
 
 Long-lived technical reasoning lives in `docs/decisions/`.
@@ -42,7 +59,7 @@ superset-cli --help
 
 Upgrade with `uv tool upgrade superset-cli`. Python 3.12 or newer is required;
 uv can provision Python when needed. `pipx install superset-cli` is an alternative.
-PyPI `0.1.0` was verified on 2026-10-06: its wheel includes the API command, CSRF handling, validated cookie-import fallback, and `--clear-query-context`, but no `--version` flag. A local installation also labeled `0.1.0` lacked those capabilities; version labels alone are insufficient. This checkout builds distinct **0.2.0** artifacts with `--version`; they have not been published.
+PyPI `0.1.0` was verified on 2026-10-06: its wheel includes the API command, CSRF handling, validated cookie-import fallback, and `--clear-query-context`, but no `--version` flag. A local installation also labeled `0.1.0` lacked those capabilities; version labels alone are insufficient. PyPI **0.2.0** was rechecked on 2026-10-07 and includes `--version`, owners, CSRF handling, and Playwright export. This checkout builds distinct unpublished **0.3.0** artifacts with the new cache controls. An isolated upgrade from 0.1.0 through 0.2.0 to the built 0.3.0 wheel preserved synthetic config/auth files; no publication was performed.
 
 Check `command -v superset-cli`, then its installation owner (`uv tool list` or `pipx list`). If it is installed but missing from PATH, use `uv tool update-shell` or `pipx ensurepath` rather than installing another copy. Upgrade with the same tool (`uv tool upgrade superset-cli` or `pipx upgrade superset-cli`). Config/auth files remain separate from the package installation. Check `api --help` and `charts update --help` once per session for required capabilities; use `--version` when available. Inside this source checkout, select `uv run superset-cli` explicitly.
 
@@ -164,6 +181,72 @@ loopback development (`localhost` or loopback IP literals); embedded URL
 credentials and malformed bearer values are rejected without echoing secrets.
 Updating an instance URL preserves its selected auth mode and bindings.
 
+## API-key authentication (capability-gated)
+
+The source-verified combination is **Superset 6.1.0 with Flask-AppBuilder 5.2.2**,
+`FAB_API_KEY_ENABLED=True`, initialized key storage, an active issued key, and a
+matching prefix. Superset's version alone does not guarantee support. No real
+API-key deployment was exercised during implementation; see [ADR 0023](docs/decisions/0023-environment-bound-api-keys.md).
+
+Provide an existing issued key through a secure environment injector, never a
+literal CLI argument or config value. Register only its environment-variable name:
+
+```bash
+superset-cli auth api-key set prod --env EXAMPLE_SUPERSET_API_KEY --json
+superset-cli auth validate prod --json
+superset-cli charts list prod --json
+superset-cli auth api-key clear prod --json
+```
+
+`set` verifies a read-only `/api/v1/me/` request before saving the binding. Use
+`--prefix` if the server's configured prefix differs from `sst_`. The CLI does not
+issue/revoke keys, enable server flags, or upgrade server dependencies. Unsupported
+or rejected authentication fails without saving a binding or browser/JWT fallback.
+Keys are reread from the environment per invocation and never saved in auth files.
+HTTPS is required except loopback HTTP development; redirects and embedded URL
+credentials are rejected. CSRF, timeouts, and per-invocation `--allow-write` remain
+required as applicable; sent mutations never replay. `auth status` reports local
+credential availability, not current server acceptance. `clear` returns to cookie
+mode without deleting cookie/JWT files. Selecting API-key mode replaces prior auth
+bindings; clearing it does not restore JWT credential bindings or the previous mode.
+Reconfigure JWT explicitly when switching back. API keys cannot be exported to Playwright.
+
+## Resource list controls
+
+All 15 resource/security lists support optional `--filter`, `--columns`, and `--all`.
+`instances list` is local, not paginated. Ordinary single-page output is unchanged.
+
+```bash
+superset-cli charts list prod --filter '{"col":"viz_type","opr":"eq","value":"table"}' --columns id --columns slice_name --json
+superset-cli logs list prod --filter '{"col":"dttm","opr":"gt","value":"2026-01-01"}' --json
+superset-cli dashboards list prod --all --page-size 100 --json
+```
+
+Repeat JSON-object filters with exactly `col`, `opr`, and `value`. Values retain
+JSON types (strings, numbers, booleans, null, arrays); filters AND together and
+append to `--search`. This is distinct from chart-data `--filter col=value`.
+Resource `_info` determines supported fields/operators; unsupported combinations
+fail rather than using a guessed universal catalog. When a resource omits `_info`
+(as Superset 6.1.0 logs do), the list endpoint validates the filter directly.
+Permission failures never trigger this fallback.
+
+Repeat `--columns FIELD` once per unique field. Resource list metadata is checked
+before requesting `q.columns` on the server. Projected human output is compact
+JSON per returned row, so omitted default fields do not produce `None` placeholders.
+Single-page `--json` preserves the server envelope.
+
+`--all` starts at page zero, rejects explicit `--page`, and requests 100 records
+per page unless `--page-size` is given. Server caps are respected. Filters,
+projection, and ordering persist across pages; ID ordering is preferred only
+when advertised, otherwise explicit/server ordering is retained. Server `ids`
+allow duplicate checks without adding an unrequested ID field to the projection.
+The aggregate JSON envelope is exactly `{count, ids, result}`. No aggregate is
+printed if a later page fails, counts change, identities duplicate, or pages stop
+early. **This is not an atomic snapshot**: non-unique ordering and concurrent
+changes can still affect completeness even when checks pass. Buffering `--all`
+uses memory proportional to the result. Capability checks add small read requests;
+legacy single-page lists without new controls add none. See [ADR 0022](docs/decisions/0022-explicit-list-query-controls.md).
+
 ## Current commands
 
 ```bash
@@ -261,6 +344,57 @@ original saved-chart GET endpoint is used. The chart must have a usable saved
 uv run superset-cli charts data prod 10 --time-range '2026-04-01 : 2026-05-01' --filter region=west --json
 ```
 
+### Chart cache controls
+
+```bash
+uv run superset-cli charts data prod 10 --cache-info
+uv run superset-cli charts data prod 10 --force --allow-write --json
+uv run superset-cli charts data prod 10 --time-range 'Last week' --filter region=west --force --allow-write --csv
+uv run superset-cli cache invalidate prod --dataset 21 --dataset 22 --allow-write --json
+```
+
+Use discovered numeric IDs; these examples do not authorize live writes.
+`--cache-info` reports each query's server-supplied cache hit/miss, key, timestamp,
+and timeout without extra requests. Missing metadata is unknown, null stays null,
+false means a miss, zero stays zero, and -1 denotes disabled caching. JSON and CSV
+remain unchanged, including errors/empty-result exits. Different native-filter
+combinations can have different cache keys; HTTP success is not freshness proof.
+
+`--force` loads the exact requested queries from source and normally replaces
+those cache entries, unless caching is disabled. It does not update saved chart
+configuration or invalidate every dataset/filter combination. Saved-chart GET
+uses `force=true`; copied override POST uses top-level boolean `force`. Because
+force refresh deliberately changes cached state, it requires literal
+`--allow-write` before auth/network access. Ordinary chart reads and non-force
+query overrides retain their existing behavior. Source-verified on Superset 6.1.0;
+unsupported endpoints/contexts fail rather than inventing another transport.
+
+`cache invalidate` requires at least one positive numeric SQLA dataset ID; repeat
+`--dataset`, duplicates are removed. UUIDs and implicit all-dataset targets are
+not supported. IDs map to `<ID>__table` datasource UIDs, not dataset UUIDs. The
+target OpenAPI must support `POST /api/v1/cachekey/invalidate` with string
+`datasource_uids`; configured auth, CSRF, and server `CacheRestApi` invalidate
+permissions apply. No service users, keys, or configuration are created.
+
+**External prerequisites:** `STORE_CACHE_KEYS_IN_METADATA_DB=True`, tracked keys,
+and compatible cache/data-cache backend, database, and key-prefix configuration.
+Existing untracked entries are not indexed retroactively. Superset 6.1.0 deletes
+through `cache_manager.cache` while chart results use `data_cache`; an incompatible
+setup can remove tracking metadata and return 201 without evicting chart results.
+The endpoint can also log incomplete deletion yet return success. JSON therefore
+reports `{dataset_ids, datasource_uids, accepted, eviction_verified, response}`,
+with `eviction_verified=false`, never invented deletion counts. Human output says
+request accepted, **not verified eviction**.
+
+A network failure leaves the outcome unknown; inspect server state before an
+explicit rerun. Sent invalidations never replay automatically. Even a retry's
+success cannot prove eviction after tracking records disappeared. Live acceptance
+requires an explicitly authorized isolated instance: pre-cache multiple filter
+combinations plus an unrelated dataset, invalidate only targets, and verify normal
+non-forced rendered requests stop reusing old target results while unrelated
+cache/session/Celery state stays intact. That live check has not been run. No
+Redis flush or fallback is provided. See [ADR 0024](docs/decisions/0024-targeted-cache-controls.md).
+
 ### Read-only ZIP exports
 
 ```bash

{superset_cli-0.2.0 → superset_cli-0.3.0}/docs/architecture/README.md

@@ -35,10 +35,57 @@ Typical command flow:
 2. Typer command registration and command implementations live in `src/superset_cli/cli.py`.
 3. `src/superset_cli/instance_selection.py` resolves omitted instances before native argument parsing; handlers load configuration through `src/superset_cli/config.py`.
 4. Cookie login uses `src/superset_cli/auth.py` and `browser-cookie3`, validating candidate state through the current-user API. JWT login/refresh uses `src/superset_cli/jwt_auth.py` with environment-only credentials and separate private token state.
-5. API-backed handlers select browser or JWT state per instance, then construct `src/superset_cli/client.py`'s authenticated client.
+5. API-backed handlers select cookie/JWT state or an environment-bound API key per instance through `cli.py::_client`, then construct the authenticated `SupersetClient`.
 6. `SupersetClient` sends REST requests, fetching and caching Superset's CSRF token before writes, and returns JSON payloads.
 7. `cli.py` formats those payloads for human-readable output or emits compact `--json` output.
 
+## Resource list controls
+
+All 15 resource/security list callbacks expose `--filter`, `--columns`, and `--all`.
+CLI callbacks validate JSON/field syntax and conflicting page options before
+access. `client.py::build_list_params` composes typed filters with search and
+server-side projection. Every list method delegates to `_list_resource`, which
+checks `_info` filter capabilities separately from list column/order metadata,
+then runs ordinary or checked all-page reads. The all-page envelope is
+`{count, ids, result}`; no partial aggregate is emitted on failure. Projection
+uses server identity metadata without adding fields; `_print_list_projection`
+handles human projected rows. Tests: `tests/test_list_controls.py`. Policy and
+snapshot limitations: [ADR 0022](../decisions/0022-explicit-list-query-controls.md).
+
+## API-key authentication entry point
+
+`auth api-key set/clear` manages only environment bindings. `api_key_auth.py`
+reads and validates the key without persisting it. `cli.py::_client` is the shared
+factory for every API-backed handler and selects explicit instance auth settings;
+API-key mode skips saved browser/JWT files. `SupersetClient` applies Bearer auth,
+HTTPS/redirect safety, existing CSRF, and no cookie/JWT recovery for that mode.
+`auth status` reports local availability; `auth validate` performs the acceptance
+read. Tests: `tests/test_api_key_auth.py`. Verified version/configuration limits:
+[ADR 0023](../decisions/0023-environment-bound-api-keys.md).
+
+## Cache control entry points
+
+`charts data --force` uses `charts_data` and `SupersetClient.get_chart_data(force=True)`;
+`_require_allow_write` runs before access. Saved reads use GET `force=true`; overrides
+use top-level boolean `force` in the copied context. `--cache-info` formats existing
+response metadata only in human output, preserving JSON/CSV and query exit rules.
+
+`cache invalidate` maps to `cli.py::cache_invalidate` and
+`client.py::invalidate_dataset_cache`. It validates numeric targets and the target
+OpenAPI request schema, maps IDs to SQLA datasource UIDs, and reuses `_post`/CSRF
+and the shared auth factory. Acceptance is distinct from verified eviction;
+network outcomes are unknown and no sent write replays. Tests:
+`tests/test_cache_controls.py`. See [ADR 0024](../decisions/0024-targeted-cache-controls.md).
+
+## HTTP timeout entry point
+
+The root `--timeout` option is validated in `cli.py` before command execution.
+It sets the context-local `client.py::HTTP_TIMEOUT` and resets it on invocation
+close. `SupersetClient` uses that value for all requests, including auth recovery
+and CSRF acquisition; direct JWT login/refresh clients receive it explicitly.
+`tests/test_timeout.py` covers request metadata, validation, invocation isolation,
+write guards, and unknown mutation outcomes. See [ADR 0021](../decisions/0021-per-invocation-http-timeout.md).
+
 ## Instance/auth entry points
 
 - `instances use NAME`, `--show`, `--clear`: `cli.py`, `config.py`, `instance_selection.py`; `tests/test_default_instance.py`.
@@ -57,7 +104,8 @@ Typical command flow:
 - `src/superset_cli/auth.py` — browser-state paths/inspection, installed-browser cookie import, explicit private Playwright export
 - `src/superset_cli/jwt_auth.py` — DB/LDAP login/refresh, private separate token state, display-only expiry metadata
 - `src/superset_cli/instance_selection.py` — default precedence and Typer command arity adapter
-- `src/superset_cli/client.py` — cookie/JWT auth selection, bounded GET-only JWT refresh, CSRF-protected API access
+- `src/superset_cli/client.py` — cookie/JWT/API-key transport, bounded GET-only JWT refresh, CSRF-protected API access, checked list traversal
+- `src/superset_cli/api_key_auth.py` — environment-only API-key validation; no state file or key-management API
 - `scripts/verify_dashboard.py` — optional Playwright rendered-content/tab/screenshot verification (not part of core dependencies)
 - `tests/` — pytest coverage grouped by command area and helper module
 - `docs/plans/` — plans and temporary implementation reasoning
@@ -95,6 +143,7 @@ Current command groups:
 - `saved-queries` (read + write)
 - `queries`, `logs`
 - `sqllab` (write-only group: execute, format-sql, estimate, stop-query)
+- `cache` (explicitly targeted tracked-key invalidation; requires `--allow-write`)
 - `security` (role/user/RLS reads and explicit opt-in writes)
 - `explore` (saved-chart state and cached form-data reads)
 - `import` (write-only group: server-side multipart asset bundles)

{superset_cli-0.2.0 → superset_cli-0.3.0}/docs/decisions/0010-write-scope-expansion.md

@@ -20,6 +20,7 @@ Expand the product scope from read-only to "read by default, write opt-in." The
 - **charts**: create, update, delete, favorite, unfavorite.
 - **dashboards**: create, update, delete, favorite, unfavorite, copy.
 - **datasets**: create, update, delete, refresh.
+- **cache controls** (2026-10-07): targeted dataset cache invalidation and explicit chart-result force refresh; see [ADR 0024](0024-targeted-cache-controls.md). No global backend deletion or deployment changes.
 - **databases**: create, update, delete, test-connection.
 - **saved-queries**: create, update, delete.
 - **sqllab**: execute, format-sql, estimate, stop-query.

superset_cli-0.3.0/docs/decisions/0021-per-invocation-http-timeout.md

@@ -0,0 +1,35 @@
+# 0021: Per-invocation HTTP timeout
+
+- Status: accepted
+- Date: 2026-10-06
+- Related: [plan](../plans/2026-10-06-http-timeout.md), `src/superset_cli/cli.py`, `src/superset_cli/client.py`, `src/superset_cli/jwt_auth.py`, `tests/test_timeout.py`
+
+## Context
+
+Slow chart-data and SQL requests need a longer timeout without replacing the authenticated client or bypassing CSRF handling. Existing commands use 30 seconds. Bounded authentication recovery and no sent-mutation retries remain required by [ADR 0011](0011-custom-api-authentication.md) and [ADR 0018](0018-per-instance-jwt-auth.md).
+
+## Decision
+
+Expose one root `--timeout SECONDS` option before the command. Validate finite positive values before browser/network access, retain the 30-second default, and apply the value to every HTTP client created by that invocation, including authentication and CSRF requests.
+
+Use HTTPX connect/read/write/pool phase/inactivity timeout semantics, not a total command deadline. A context-local value, reset when the invocation closes, avoids changing every command signature or leaking settings between invocations. Direct JWT clients receive the value explicitly. Do not persist it or add retries.
+
+Timeouts exit non-zero with a bounded stderr diagnostic. When the timed-out request was a mutation, report that its outcome is unknown and advise checking server state before retrying. Do not echo exception contents or replay the request.
+
+## Consequences
+
+Users can accommodate slow requests while preserving auth handling and write guards. A continuously progressing command can run longer than the timeout. A total deadline would require a separate design. Context-local configuration must be reset even on command failure; tests cover custom/default invocations and request timeout metadata.
+
+## Alternatives considered
+
+### Per-command options
+
+Rejected: duplicated declarations and forwarding across dozens of handlers make auth/CSRF coverage easy to miss.
+
+### Persistent instance configuration
+
+Rejected: this ticket requests an explicit per-invocation override; persistence hides a previous operator's choice.
+
+### Total runtime deadline or automatic retries
+
+Rejected: neither is provided by a scalar HTTPX timeout, and retrying mutations can duplicate writes.

superset_cli-0.3.0/docs/decisions/0022-explicit-list-query-controls.md

@@ -0,0 +1,39 @@
+# 0022: Explicit server-side list query controls
+
+- Status: accepted
+- Date: 2026-10-06
+- Related: [plan](../plans/2026-10-06-remaining-open-todos.md), `src/superset_cli/client.py`, `src/superset_cli/cli.py`, `tests/test_list_controls.py`
+
+## Context
+
+Agents currently handwrite API queries for typed filtering, small projections, and complete inventories. FAB exposes resource-specific filter metadata and list column metadata; guessing a universal catalog would reject valid deployments or silently select invalid columns. Some servers cap page size, and concurrent changes can make pagination incomplete.
+
+## Decision
+
+Apply the same optional controls to all 15 paginated resource/security lists:
+
+- Repeat `--filter '{"col":"viz_type","opr":"eq","value":"table"}'`. Exact object keys and finite JSON values are required before access. Values retain JSON types. Generated `q` serializes literal `+`, `%`, and `&` as JSON Unicode escapes so FAB's extra `parse_qs` decode cannot corrupt them; both ordinary JSON and FAB decoding recover the same values. Filters AND together and append to existing `--search`; chart-data `--filter col=value` remains distinct.
+- Repeat `--columns FIELD`. Require unique non-empty field identifiers. Validate resource support from list metadata, then request `q.columns` on the server. Human projection output is compact JSON per returned record, avoiding invented missing-field placeholders. Ordinary human/JSON output is unchanged without projection.
+- `--all` starts at page zero and rejects explicit `--page`. It defaults to requesting 100 records per page unless a positive `--page-size` is provided; server caps remain authoritative. Preserve filters/projection/order on every page. Prefer ID ordering only if advertised; otherwise preserve explicit or server ordering rather than invent support.
+
+Obtain filter/operator capabilities from `_info`; obtain list/order columns from a one-row list metadata request. These are different endpoints. Malformed metadata and permission failures fail closed. If `_info` returns 404 (Superset 6.1.0's log API omits it), send the syntactically valid filter to the list endpoint's native validation instead; never bypass a 403 or guess a field catalog. FAB 5.2.2 advertises datetime `gt`/`lt`, not a universal `ge` operator. No new network calls are added to ordinary single-page lists without these new controls.
+
+Emit an aggregate `{count, ids, result}` only after every page passes count, identity, duplicate, and progress checks. Use server `ids` independently of projection, falling back to record IDs when available; do not silently add ID to the requested projection. Later-page failures or inconsistent/empty premature pages exit non-zero without printing a partial aggregate. Single-page JSON retains the raw server envelope.
+
+## Consequences
+
+The new controls add small capability reads and buffer an all-page result in memory. Pagination is **not an atomic snapshot**: equal counts and unique IDs cannot detect every concurrent replacement, and non-unique server ordering can still change traversal. Freeze relevant writes or use a server snapshot facility for stronger guarantees; the CLI does not claim one. HTTP timeout/auth/write safety policies remain unchanged.
+
+## Alternatives considered
+
+### Fetch everything and trim locally
+
+Rejected: defeats response-size reduction and hides unsupported server projections.
+
+### Resource-independent filter catalog or mandatory ID ordering
+
+Rejected: fields/operators/order support vary. Superset 6.1.0 charts do not advertise ID ordering.
+
+### Stream pages directly to stdout
+
+Rejected for `--all`: a later failure would leave plausible but incomplete inventory output. Explicit ordinary page calls remain available for streaming clients.

superset_cli-0.3.0/docs/decisions/0023-environment-bound-api-keys.md

@@ -0,0 +1,37 @@
+# 0023: Environment-bound API keys on verified server capabilities
+
+- Status: accepted
+- Date: 2026-10-06
+- Related: [corrected research](../plans/2026-06-06-api-key-auth-design.md), [continuation](../plans/2026-10-06-remaining-open-todos.md), `src/superset_cli/api_key_auth.py`, `tests/test_api_key_auth.py`
+
+## Context
+
+API-key authentication is version/configuration dependent. Earlier research examined FAB's abstract manager but missed Superset's inheritance of FAB's concrete SQLA manager. Superset 6.1.0 permits FAB 5.2.2, which implements API-key verification and blueprint registration. This establishes a source-verified combination, not support on every 6.1.0 deployment. No live key or deployment was exercised.
+
+## Decision
+
+Add explicit per-instance API-key mode with only an environment-variable binding and configured prefix (default `sst_`). `auth api-key set` requires syntactically valid credentials and successful read-only `/api/v1/me/` authentication before saving the binding. Reject redirects and preserve old config on failed validation. `clear` returns to cookie mode and preserves existing cookie/JWT files. Explicit `set` replaces prior auth bindings, and `clear` does not restore previous JWT bindings or mode; switching back requires explicit JWT configuration.
+
+Use a shared CLI client factory for every API-backed handler. Read the key afresh per invocation, enforce bearer syntax and prefix, require HTTPS except loopback HTTP, and reject embedded URL credentials. No auth file is needed or created. Never persist/log the key, fall back to cookies/JWT, retry a sent mutation, issue/revoke keys, or change server flags/dependencies. Existing CSRF handling, HTTP timeouts, and literal per-invocation `--allow-write` apply unchanged.
+
+Document the verified combination as Superset 6.1.0 + FAB 5.2.2 with `FAB_API_KEY_ENABLED=True`, initialized key storage, matching prefix, active issued key, and sufficient RBAC. Do not infer capability from the Superset version alone or from Next documentation. CLI binding validation, not a hardcoded version guess, determines acceptance on a target deployment.
+
+Status reports local credential availability without implying current server acceptance; `auth validate` performs the live read. API keys cannot substitute for browser state in rendering/export recipes.
+
+## Consequences
+
+Operators can use issued keys without browser-cookie extraction or local secret files. The environment must be populated on each invocation. Server-side key creation/revocation and rollout remain operator responsibilities. GET authentication may update server-side key usage bookkeeping; the CLI performs no key-management mutation.
+
+## Alternatives considered
+
+### Persist keys or accept literal key arguments
+
+Rejected: exposes secrets in configuration, shell history, process arguments, or logs.
+
+### Treat every Superset 6.1.0 installation as supported
+
+Rejected: its FAB dependency range includes versions predating API keys and server enablement/storage vary.
+
+### Block forever because Superset has no direct override
+
+Rejected after source verification: the concrete inherited implementation exists. Requiring successful credential validation before binding handles the actual deployment prerequisite without inventing availability.

superset_cli-0.3.0/docs/decisions/0024-targeted-cache-controls.md

@@ -0,0 +1,36 @@
+# 0024: Targeted cache controls with truthful acceptance reporting
+
+- Status: accepted
+- Date: 2026-10-07
+- Related: [implementation plan](../plans/2026-10-07-complete-open-todos.md), [write guard](0009-write-command-explicit-opt-in.md), [chart output](0012-chart-data-output-contract.md), `tests/test_cache_controls.py`
+
+## Context
+
+Operators need fresh chart queries, per-query cache evidence, and targeted dataset invalidation without direct backend access. Superset 6.1.0 implements these surfaces, but invalidation success does not prove chart-result eviction. CacheRestApi deletes through `cache_manager.cache`, whereas chart results use `data_cache`; tracked metadata can be removed even if backend deletion is incomplete.
+
+## Decision
+
+Expose the existing server mechanisms only. `charts data --force` uses GET `force=true` for saved-chart reads or top-level boolean `force` in copied override query contexts. It affects every query in that context, not every native-filter combination. Superset bypasses cache reads and normally writes successful results back under their query keys; disabled caching remains disabled. Require literal `--allow-write` before auth/network access for this deliberate cache refresh. Existing non-force reads and ADR 0015 overrides remain unchanged.
+
+Opt-in `--cache-info` adds per-query human diagnostics from the existing response: `is_cached`, `cache_key`, `cached_dttm`, and `cache_timeout`. Missing fields are unknown; null, false, zero, and -1 remain distinct. Only -1 denotes disabled caching in the verified contract; zero is reported without inventing its deployment-specific meaning. JSON/CSV output and ADR 0012 exit rules remain unchanged.
+
+`cache invalidate INSTANCE --dataset ID [--dataset ID ...] --allow-write` accepts positive numeric dataset IDs, deduplicates them, and maps SQLA datasets to source-verified `<ID>__table` UIDs, not UUIDs. Validate the target's OpenAPI POST request schema for string `datasource_uids`, then reuse configured cookie/JWT/API-key auth and CSRF transport. Server RBAC remains authoritative (`CacheRestApi` invalidate permission); the CLI does not grant permissions or provision credentials. No retry of a sent invalidation.
+
+The JSON envelope is `{dataset_ids, datasource_uids, accepted, eviction_verified, response}`. A successful request sets `accepted=true`, `eviction_verified=false`, and preserves the server response, including an empty object for empty 201. Never invent counts or claim eviction. Network failures report unknown outcomes and require inspection before an explicit rerun.
+
+## Consequences
+
+Requires external `STORE_CACHE_KEYS_IN_METADATA_DB=True`, tracked entries, and compatible cache/data-cache backend, database, and key-prefix configurations. Previously untracked entries are not retroactively indexed. The CLI cannot infer these conditions from OpenAPI or HTTP success. Live acceptance remains unverified: an explicitly authorized isolated instance must demonstrate multiple normal non-forced filter combinations refresh while unrelated dataset entries and session/Celery state remain intact. No Redis flush/fallback, configuration rollout, service-account provisioning, or orchestration is included.
+
+New cache capabilities use unpublished version 0.3.0 because PyPI 0.2.0 was verified as already published. No package is published by this change.
+
+## Alternatives considered
+
+- Generic `api` only: retains transport but makes target validation, UID conversion, and truthful acceptance reporting each caller's responsibility.
+- Unguarded force refresh: resembles a read but intentionally changes cached state; explicit invocation permission makes that effect visible.
+- Automatically inspect/delete Redis: bypasses server permissions, risks unrelated data, and still cannot establish rendering freshness. Rejected.
+- Optional CSV query selection: no recurring concrete use case supplied; preserve existing blank-line-separated CSV and raw JSON rather than add another output/exit contract.
+
+## Sources
+
+Pinned Superset 6.1.0: [chart-data API](https://github.com/apache/superset/blob/6.1.0/superset/charts/data/api.py), [schemas](https://github.com/apache/superset/blob/6.1.0/superset/charts/schemas.py), [query cache manager](https://github.com/apache/superset/blob/6.1.0/superset/common/utils/query_cache_manager.py), [SQLA UID](https://github.com/apache/superset/blob/6.1.0/superset/connectors/sqla/models.py), [invalidation API](https://github.com/apache/superset/blob/6.1.0/superset/cachekeys/api.py), [invalidation schema](https://github.com/apache/superset/blob/6.1.0/superset/cachekeys/schemas.py), [tracking](https://github.com/apache/superset/blob/6.1.0/superset/utils/cache.py).

{superset_cli-0.2.0 → superset_cli-0.3.0}/docs/decisions/README.md

@@ -57,6 +57,13 @@ For a copyable starting point, use `../templates/decision-record-template.md`.
 
 ## Current decision records
 
+- [0024: Targeted cache controls](./0024-targeted-cache-controls.md)
+
+- [0022: Explicit server-side list query controls](./0022-explicit-list-query-controls.md)
+- [0023: Environment-bound API keys](./0023-environment-bound-api-keys.md)
+
+- [0021: Per-invocation HTTP timeout](./0021-per-invocation-http-timeout.md)
+
 - [0010: Write-scope expansion](./0010-write-scope-expansion.md)
 - [0011: Custom API authentication](./0011-custom-api-authentication.md)
 - [0012: Chart-data output contract](./0012-chart-data-output-contract.md)