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 recon-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.
recon-gen¶
Generate + deploy AWS QuickSight dashboards from one L2 YAML.
Usage:
recon-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 |
recon-gen audit¶
Per-instance PDF reconciliation report (cover, summary, exceptions).
Usage:
recon-gen audit [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
recon-gen audit 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:
recon-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 |
recon-gen audit 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:
recon-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 |
recon-gen audit 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
RECON_GEN_E2E=1 — not run here.
Pyright covers the audit package (cli/audit/).
Usage:
recon-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 |
recon-gen audit 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 recon-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:
recon-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 |
recon-gen dashboards¶
Start the self-hosted HTMX/d3 dashboard server.
With no --app (the default all), builds the four real apps
(l1_dashboard / l2_flow_tracing / investigation /
executives) into one server — /dashboards lists them and you
switch between them in-process; same "no-arg = all" shape as json
apply. --app <one> narrows to a single app (faster startup
when iterating). --app smoke is the DB-free spike fixture (the
only one --stub applies to). Config + L2 instance are loaded the
same way the json / data / audit groups do; visual data comes from
the configured DB; one shared connection pool serves every app. The
mkdocs handbook (same --l2) is built on startup and embedded at
/docs when the [docs] extra is installed — --no-docs
skips it.
Studio (recon-gen studio) mounts everything dashboards
mounts plus the editor + diagram + data-shaping surface; reach for
that command when the integrator / trainer / ETL-engineer loops
matter. dashboards is the lean read-only mount.
Usage:
recon-gen dashboards [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--host |
text | Bind address. Use 0.0.0.0 to expose on the network. | 127.0.0.1 |
--port |
integer | TCP port to listen on. | 8765 |
--dev-log / --no-dev-log |
boolean | Forward HTMX + d3 click events to stderr for live debugging. Default off so production deploys stay silent. | False |
--stub / --no-stub |
boolean | Use the deterministic stub fetcher instead of querying the configured DB. Useful for iterating on the JS / page shell without a populated database. | False |
--app |
choice (all | smoke | l1_dashboard | l2_flow_tracing | investigation | executives) |
Which dashboard surface(s) to serve. all (default) builds the four real apps into one server — /dashboards lists them and you switch between them in-process, same as json apply with no --app. Pass a single app name to narrow to one (faster startup when iterating). smoke is the DB-free spike fixture (the only one that works without a configured database / and the only one --stub applies to). |
all |
--docs / --no-docs |
boolean | Build the mkdocs handbook (against the same --l2) on startup and serve it at /docs (X.2.i). Best-effort: silently skipped when mkdocs isn't installed (pip install recon-gen[docs]). --no-docs skips the build for a faster startup. The standalone docs apply / docs serve / docs export CLI is unaffected either way. |
True |
--help |
boolean | Show this message and exit. | False |
recon-gen data¶
Per-prefix seed data: 90-day baseline + plant overlays.
Usage:
recon-gen data [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
recon-gen data 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. --seed-density=N scales the three knobs.
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:
recon-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 |
--seed-density |
float | Y.2.gate.c.13.1 — scalar multiplier on plant density (densify factor / broken-rail count / fanout multiplier). 1.0 = byte-identical to pre-c.13 behavior; 2.0 = double the plants; 0.5 = halve. Operator opt-in for heavier nightly scenarios; default keeps locked SQL files valid. | 1.0 |
--help |
boolean | Show this message and exit. | False |
recon-gen data 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:
recon-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 |
recon-gen data 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:
recon-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 |
recon-gen data 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:
recon-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 |
recon-gen data 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:
recon-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 |
recon-gen data test¶
Run the data test suite (pytest + pyright on the seed pipeline).
Usage:
recon-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 |
recon-gen docs¶
mkdocs handbook site (build, serve, test, export, screenshot).
Usage:
recon-gen docs [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
recon-gen docs 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:
recon-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 |
recon-gen docs clean¶
Remove the built site directory.
Usage:
recon-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 |
recon-gen docs 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:
recon-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 |
recon-gen docs 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:
recon-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. your own institution's 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 |
recon-gen docs 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:
recon-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 |
recon-gen docs test¶
Run the docs gates (link sweep + persona-neutral check).
Usage:
recon-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 |
recon-gen json¶
QuickSight dashboard JSON for all four apps.
Usage:
recon-gen json [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
recon-gen json 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:
recon-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 |
recon-gen json clean¶
Sweep AWS QuickSight resources tagged ManagedBy:recon-gen.
Default: dry-run. Lists every resource tagged ManagedBy:
recon-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:
recon-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 |
recon-gen json 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:
recon-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 |
recon-gen json test¶
Run the JSON contract test suites (all four apps) + pyright.
Usage:
recon-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 |
recon-gen schema¶
Per-prefix schema DDL: tables, views, materialized views.
Usage:
recon-gen schema [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
recon-gen schema 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: recon-gen schema
apply | psql ....
Pass --execute to connect to the demo DB named in the config
and actually run every CREATE.
Usage:
recon-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 |
recon-gen schema 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:
recon-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 |
recon-gen schema test¶
Run the schema test suite (pytest + pyright).
Usage:
recon-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 |
recon-gen studio¶
Start Studio — the implementation-tools surface for the integrator, trainer, and ETL engineer.
Studio is a Starlette process that mounts the Dashboards routes plus a Studio-side editor, unified diagram, data-shaping panel, and Deploy-changes orchestration. One in-memory cache of the L2 YAML backs every Studio request; the YAML on disk stays the source of truth (every save is an atomic write through Studio).
X.4.a.4 ships only the landing placeholder; the unified diagram (X.4.c), editor (X.4.e), and Deploy pipeline (X.4.g) land in sub-phases. The CLI surface is stable from this commit forward.
Usage:
recon-gen studio [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--config, -c |
path | Path to configuration file (used for the dialect setting only). | config.yaml |
--l2 |
file | Path to L2 instance YAML. Default: bundled spec_example. | None |
--host |
text | Bind address. Use 0.0.0.0 to expose on the network. | 127.0.0.1 |
--port |
integer | TCP port to listen on. | 8765 |
--dev-log / --no-dev-log |
boolean | Forward HTMX + d3 click events to stderr for live debugging. Default off so production deploys stay silent. | False |
--app |
choice (all | l1_dashboard | l2_flow_tracing | investigation | executives) |
Which dashboard surface(s) Studio mounts under /dashboards. all (default) mounts the four real apps; pass a single name to narrow (faster startup when iterating on a single dashboard alongside Studio). Studio routes are unaffected by this knob. |
all |
--docs / --no-docs |
boolean | Build the mkdocs handbook (against the same --l2) on startup and serve it at /docs (X.2.i). Best-effort: silently skipped when mkdocs isn't installed (pip install recon-gen[docs]). |
True |
--demo-mode / --no-demo-mode |
boolean | AE.2.b lockdown for public-demo hosting (Phase AE Mac mini). When set: (1) L2 yaml mutation endpoints (POST/PUT/DELETE on /l2_shape/*) are not mounted; (2) POST /deploy (AWS deploy) is not mounted; (3) PUT /data/knobs/etl_hook (shell exec) is not mounted; (4) trainer knob state (.studio-state.yaml) writes to a per-process tmpdir wiped on restart instead of persisting next to cfg.yaml. Diagram + L2 read views + data-shaping knobs (plants/window/seed/scope/etc.) continue to work — this is a mutation-perimeter cut, not a feature blackout. Defense in depth: sandbox-exec profile under deploy/sandbox/ also denies file-write on L2 yaml + cfg.yaml regardless of this flag. |
False |
--help |
boolean | Show this message and exit. | False |