CLI reference¶
Auto-generated from the live Click command tree at docs build time.
Every flag, default, and choice below is sourced from the same
metadata quicksight-gen --help reads — when the CLI changes, this
page changes with it on the next docs apply / Pages build.
For the spirit-of-the-tool walkthrough (when to use each verb,
typical sequences), start with the
For your role pages instead. This page
is the lookup-shaped reference: "what does --portable do?",
"which extras does audit verify need?", etc.
quicksight-gen¶
Generate + deploy AWS QuickSight dashboards from one L2 YAML.
Usage:
quicksight-gen [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Show the version and exit. | False |
--help |
boolean | Show this message and exit. | False |
audit¶
Per-instance PDF reconciliation report (cover, summary, exceptions).
Usage:
quicksight-gen audit [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
apply¶
Emit the audit report's Markdown source (or --execute to write a PDF).
Default: print the Markdown rendering of the report (cover +
section outline) to stdout. Pass -o FILE to write to a file.
Useful for review before committing to a PDF.
Pass --execute to render the report as a PDF via reportlab.
Default destination is report.pdf in the current working
directory; override with -o FILE.
Usage:
quicksight-gen audit apply [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
--from |
datetime (%Y-%m-%d) |
Period start (YYYY-MM-DD, inclusive). Default: today − 7 days (start of the 7-day window ending yesterday). | None |
--to |
datetime (%Y-%m-%d) |
Period end (YYYY-MM-DD, inclusive). Default: yesterday (today − 1). | None |
-o, --output |
path | Output path. Without --execute: Markdown source destination (default: stdout). With --execute: PDF destination (default: report.pdf). | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
clean¶
Print or remove the generated report file.
Default: print the path that would be deleted (no side effect).
Pass --execute to actually unlink it.
Usage:
quicksight-gen audit clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-o, --output |
path | PDF path to remove (default: report.pdf). | report.pdf |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
test¶
Run the audit test suite (pytest + pyright on the audit module).
Targets tests/audit/ for pytest — scenario expectations,
PDF/dashboard extractors, PDF-matches-scenario, persona-clean,
and smoke. Defers the browser matrix
(tests/e2e/test_audit_dashboard_agreement.py) to
QS_GEN_E2E=1 — not run here.
Pyright covers the audit package (cli/audit/).
Usage:
quicksight-gen audit test [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pytest-args |
text | Extra args passed verbatim to pytest (e.g. '-k smoke'). | `` |
--help |
boolean | Show this message and exit. | False |
verify¶
Verify an audit PDF's embedded provenance fingerprint.
Extracts the ProvenanceFingerprint JSON embedded in the
PDF's /Subject metadata, recomputes each input from current
sources (DB rows up to the embedded high-water-mark, L2 yaml
bytes on disk, current quicksight-gen code identity), and
reports per-source matches/diffs.
Recomputes against the EMBEDDED hwm (not current MAX(entry))
so the verification reproduces the report's snapshot point —
new rows added since report-generation time don't trigger a
false diff. A diff fires only when bytes that the fingerprint
actually covers have changed: a row at or below the embedded
hwm was modified, the L2 yaml was edited, or the code identity
changed.
Exits 0 on full match, 1 with a per-source diff on mismatch.
Usage:
quicksight-gen audit verify [OPTIONS] PDF_PATH
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
--help |
boolean | Show this message and exit. | False |
data¶
Per-prefix seed data: 90-day baseline + plant overlays.
Usage:
quicksight-gen data [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
apply¶
Emit the demo seed SQL (or --execute to insert against the demo DB).
The composition: 90-day baseline → densify per-kind plants ×5 → add 15 broken-rail stuck_pending plants → boost inv_fanout amounts ×5 → emit_full_seed.
Default: print every INSERT to stdout (or to -o FILE). Pass
--execute to connect + insert.
Assumes the schema is already applied (schema apply --execute
or a prior schema). After data apply --execute you'll likely
want data refresh --execute so the matviews see the new rows.
Usage:
quicksight-gen data apply [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
-o, --output |
path | Write the script to FILE instead of stdout. | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
clean¶
Emit TRUNCATE statements (or --execute to wipe seeded rows).
Default: print TRUNCATEs for <prefix>_transactions and
<prefix>_daily_balances to stdout (or to -o FILE). The
schema stays — only the rows go.
Pass --execute to actually run them.
To wipe schema + rows together, run data clean --execute
followed by schema clean --execute.
Usage:
quicksight-gen data clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
-o, --output |
path | Write the script to FILE instead of stdout. | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
etl-example¶
Emit canonical INSERT-pattern examples for ETL authors.
Output is exemplary, not executable against the real demo seed —
every pattern uses fixed sentinel IDs (xxx-EXAMPLE-001) so the
statements are self-contained. Each block carries a -- WHY:
header naming the business invariant and a -- Consumed by:
header naming the dashboard view that reads the resulting rows.
See docs/handbook/etl.md for the walkthroughs that reference this output.
Usage:
quicksight-gen data etl-example [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-o, --output |
path | Output path for the ETL examples SQL file. | demo/etl-examples.sql |
--help |
boolean | Show this message and exit. | False |
lock¶
Write or verify the canonical-anchor seed SQL.
The locked file lives at
tests/data/_locked_seeds/<instance>.<dialect>.sql and IS the
record of what data apply would emit at canonical anchor
(2030-01-01) for this (L2 instance, dialect) pair. The CLI keys
off -c config.yaml (dialect derived from demo_database_url);
--l2 picks the L2 to lock.
Default: refresh the locked file (overwrites the on-disk content
with a fresh emit). Pass --check to verify-only — exit non-zero
on drift, with a unified diff to stderr showing the first ~50 lines
that changed.
Run once per (postgres config, oracle config) to cover both dialects. Run after any seed-shape-changing commit (new plant kind, plant emitter change, baseline generator tweak) to refresh both locks before pushing.
Usage:
quicksight-gen data lock [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
--check |
boolean | Exit non-zero if the locked SQL file doesn't match a fresh emit. Use in CI to guard against unreviewed seed drift. | False |
--help |
boolean | Show this message and exit. | False |
refresh¶
Emit the REFRESH MATERIALIZED VIEW SQL (or --execute to refresh).
Default: print every REFRESH MATERIALIZED VIEW (in dependency
order: leaves → helpers → invariants → rollups) to stdout (or to
-o FILE). Pass --execute to run against the demo DB.
Run after every ETL load that mutates <prefix>_transactions
or <prefix>_daily_balances — the L1 invariant matviews +
Investigation matviews don't auto-refresh.
Usage:
quicksight-gen data refresh [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
-o, --output |
path | Write the script to FILE instead of stdout. | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
test¶
Run the data test suite (pytest + pyright on the seed pipeline).
Usage:
quicksight-gen data test [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pytest-args |
text | Extra args passed verbatim to pytest (e.g. '-k hash_lock'). | `` |
--help |
boolean | Show this message and exit. | False |
docs¶
mkdocs handbook site (build, serve, test, export, screenshot).
Usage:
quicksight-gen docs [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
apply¶
Build the docs site to site/ (or -o DIR).
Wraps mkdocs build. The L2 instance bound via --l2 (or
falling back to the bundled spec_example) drives every
{{ vocab.* }} substitution in the rendered prose.
With --portable, emits a static-site that opens via file://
— handy for shipping the rendered handbook on a USB stick, in a
zip attachment, or to a wiki that doesn't run a web server.
No --execute: building a static site IS the operation.
Usage:
quicksight-gen docs apply [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
-o, --output |
path | Output directory for the built site (default: site/). | site |
--strict / --no-strict |
boolean | Pass --strict to mkdocs (default on; treats warnings as errors). | True |
--portable |
boolean | Build with use_directory_urls: false so the rendered site opens via file:// without a web server (every page emits as |
False |
--help |
boolean | Show this message and exit. | False |
clean¶
Remove the built site directory.
Usage:
quicksight-gen docs clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-o, --output |
path | Directory to remove (default: site/). | site |
--help |
boolean | Show this message and exit. | False |
export¶
Copy the bundled mkdocs source to a folder for hand-build.
Different from docs apply: apply builds the site INTO a
directory; export copies the SOURCE FILES so an integrator
can use their own mkdocs config / theme / build pipeline.
Usage:
quicksight-gen docs export [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-o, --output |
path | Target directory; created if missing, merged into if existing. | Sentinel.UNSET |
--l2 |
path | Optional path to an L2 institution YAML to bind the rendered docs against. Validated here; binding happens at mkdocs build time via QS_DOCS_L2_INSTANCE env var. | Sentinel.UNSET |
--help |
boolean | Show this message and exit. | False |
screenshot¶
Capture per-sheet PNG screenshots from deployed dashboards.
Walks the requested app's tree via WebKit and writes one full-page
PNG per sheet to <output>/<app-slug>/<sheet_id>.png. Single CLI
surface for every app (replaces the per-app capture scripts that
used to live under scripts/).
Requires the dashboards already deployed (json apply --execute).
The handbook + walkthrough pages embed these screenshots by
relative path under docs/walkthroughs/screenshots/<app>/.
Usage:
quicksight-gen docs screenshot [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--app |
choice (executives | investigation | l1-dashboard | l2-flow-tracing) |
Single app to capture. Mutually exclusive with --all. | None |
--all |
boolean | Capture all 4 apps. Output goes to |
False |
-o, --output |
path | Target directory; per-app subdirs created under it. | Sentinel.UNSET |
-c, --config |
path | Config YAML (default: env vars). | None |
--l2 |
path | L2 institution YAML override. Defaults to each app's built-in default (spec_example for most). Pass when capturing a deploy against a non-default L2 (e.g. tests/l2/sasquatch_pr.yaml). | None |
--viewport |
text | Browser viewport WxH (default 1280x900). | 1280x900 |
--skip-warmup |
boolean | Skip the F12 SELECT 1 cluster warmup (use when DB is hot). | False |
--headless / --no-headless |
boolean | Run browser headless (default) or visible (debug). | True |
--initial-settle-ms |
integer | Settle delay after dashboard chrome appears, before first capture. | 10000 |
--per-sheet-settle-ms |
integer | Settle delay after each sheet-tab click, before capture. | 8000 |
--date-from |
text | YYYY-MM-DD override for each app's *DateStart parameter(s). Use to span the seed's anchor date when the dashboard's default rolling-window control doesn't reach it. |
None |
--date-to |
text | YYYY-MM-DD override for each app's *DateEnd parameter(s) (L1 also applies it to the Daily Statement single-day picker). |
None |
--help |
boolean | Show this message and exit. | False |
serve¶
Live-reload preview at http://localhost:PORT (default 8000).
Wraps mkdocs serve. Edit any docs source file and the browser
refreshes automatically. Useful for iterating on persona-block
YAML edits or new walkthrough drafts.
Usage:
quicksight-gen docs serve [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--port, -p |
integer | Port to bind for live-reload preview. | 8000 |
--help |
boolean | Show this message and exit. | False |
test¶
Run the docs gates (link sweep + persona-neutral check).
Usage:
quicksight-gen docs test [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pytest-args |
text | Extra args passed verbatim to pytest (e.g. '-k links -v'). | `` |
--help |
boolean | Show this message and exit. | False |
json¶
QuickSight dashboard JSON for all four apps.
Usage:
quicksight-gen json [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
apply¶
Emit JSON for all four apps (and optionally deploy to AWS).
Always emits to out/ (or -o DIR). Always operates on every
app: investigation / executives / l1-dashboard / l2-flow-tracing.
Default: write the four apps' JSON files (datasets, analyses, dashboards, theme, datasource) to the output directory. Inspect them; check them into git if you want; deploy them with whatever tool you use.
Pass --execute to also deploy to AWS QuickSight (delete-then-
create on every resource ID — idempotent re-runs).
Usage:
quicksight-gen json apply [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (DB connection + dialect). | config.yaml |
-o, --output |
path | Output directory (default: out/). | out |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
clean¶
Sweep AWS QuickSight resources tagged ManagedBy:quicksight-gen.
Default: dry-run. Lists every resource tagged ManagedBy:
quicksight-gen (for the active L2 instance) that is NOT in the
current out/ directory. Nothing is deleted.
Pass --execute to actually delete. The out/ directory
drives "what's safe" — anything currently emitted there is kept;
everything else carrying the tag goes.
Pass --all to skip the out/ carve-out entirely — every
resource matching the cfg's prefix scope (including the live
deploy) becomes eligible for deletion. Use to fully tear down
a deploy. The flag is independent of --execute: pair them
to actually nuke; just --all previews what would go.
Usage:
quicksight-gen json clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--config, -c |
path | Path to configuration file (DB connection + dialect). | config.yaml |
--output-dir, -o |
path | Directory holding current emit output. Resources NOT in this directory get deleted (so re-running emit + clean is safe). Default: out/. Ignored when --all is passed. |
out |
--all |
boolean | Purge mode: ignore out/ entirely and sweep EVERY resource matching the cfg's prefix scope, including the live deploy. Use to fully decommission a deploy. Pair with --execute. |
False |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
probe¶
Playwright sanity walk against every deployed dashboard.
Opens each of the four deployed dashboards via an embed URL, walks the sheets, and surfaces any visible 'failed to load' / spinner- forever / dataset-error states. Catches the silent-fail mode where datasets describe-cleanly but visuals stay frozen.
No --execute here — probe is read-only by definition.
Usage:
quicksight-gen json probe [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--config, -c |
path | Path to configuration file (DB connection + dialect). | config.yaml |
--output-dir, -o |
path | Directory holding the deployed-set JSON (used to find dashboard IDs). | out |
--help |
boolean | Show this message and exit. | False |
test¶
Run the JSON contract test suites (all four apps) + pyright.
Usage:
quicksight-gen json test [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pytest-args |
text | Extra args passed verbatim to pytest (e.g. '-k l1_drift'). | `` |
--browser |
boolean | Also run the Playwright e2e tests under tests/e2e/. | False |
--help |
boolean | Show this message and exit. | False |
schema¶
Per-prefix schema DDL: tables, views, materialized views.
Usage:
quicksight-gen schema [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
apply¶
Emit the schema DDL (or --execute to apply against the demo DB).
Default behavior: print every CREATE statement for the L2 instance's
per-prefix tables, views, and materialized views to stdout (or to
-o FILE). Pipe it to your DB tool: quicksight-gen schema
apply | psql ....
Pass --execute to connect to the demo DB named in the config
and actually run every CREATE.
Usage:
quicksight-gen schema apply [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
-o, --output |
path | Write the script to FILE instead of stdout. | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
clean¶
Emit DROP statements (or --execute to drop against the demo DB).
Default: print every DROP for the L2 instance's per-prefix matviews
/ views / tables (in dependency order) to stdout (or -o FILE).
Pass --execute to connect and actually drop them.
Schema-only cleanup. To wipe seeded rows without dropping the
schema, run data clean instead.
Usage:
quicksight-gen schema clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
-o, --output |
path | Write the script to FILE instead of stdout. | None |
--execute |
boolean | Actually run the script (connect to the DB / AWS and execute). Without this flag, the script is emitted to stdout (or to -o FILE) without any side effects. | False |
--help |
boolean | Show this message and exit. | False |
test¶
Run the schema test suite (pytest + pyright).
Usage:
quicksight-gen schema test [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pytest-args |
text | Extra args passed verbatim to pytest (e.g. '-k drift -v'). | `` |
--help |
boolean | Show this message and exit. | False |