Looker Demo Creator (demo-create)

From zero to production Looker demo in minutes. Automated, deterministic orchestrator for creating end-to-end Looker demos, synthetic BigQuery datasets, 3NF Snowflake LookML semantic models, 100% test-verified dashboards, Conversational Analytics (CA) Agents published to Gemini Enterprise (GE), and Embedded Analytics portals.

---

Overview

demo-create unifies the entire full-stack Looker demo creation lifecycle into a single automated pipeline:

1. Pre-flight & Environment Audit (pre-check): Verifies active GCP/ADC accounts, installs/patches global MCP tools (data-designer, bigquery, knowledge-catalog), checks Looker authentication (OAuth / API keys), and organizes agent skills into intent-based subfolders.
2. Dataset Decision & Synthesis: Automatically checks for existing BigQuery datasets, enables data augmentation or green-field relational schema generation, and validates referential integrity.
3. BigQuery Loading: Creates datasets and partitioned/clustered tables in BigQuery.
4. LookML Generation & Direct Code-Mode Deployment: Autogenerates production-ready views, explores, and executive dashboards, provisioning and deploying them directly to the Looker instance using lkr code-mode without requiring an MCP server.
5. Conversational Analytics & Gemini Enterprise: Provisions Looker CA AI Agents, extracts dashboard queries into 1:1 Golden Queries, and publishes to Gemini Enterprise.
6. Embedded Portal Scaffolding: Clones and configures a clean, dedicated looker-embed-demo workspace for external client demos.

---

What Gets Automated: Production Deliverables Inventory

Instead of spending days or weeks stitching together synthetic data scripts, debugging LookML joins, hand-crafting dashboard tiles, writing validation queries, and plumbing AI agent endpoints, demo-create produces a complete, production-grade enterprise demo in minutes:

Production Asset	What Gets Automated	Exact Output Format
BigQuery Data Warehouse	3NF relational schema synthesis, realistic engineering distributions, PK/FK referential integrity, and batch Parquet upload	Clean BigQuery dataset with partitioned/clustered tables
LookML 3NF Semantic Model	Explore Base View selection, Chasm Trap elimination with Native Derived Table (NDT) rollups joined one_to_one, role-playing diamond joins, and field metadata (label:, description:, value_format_name:, drill_fields:)	Complete views/*.view.lkml, explores/*.explore.lkml, and models/*.model.lkml
Executive Tabbed Dashboard	Executive tabbed report architecture, single-value KPI banners, dual-axis timelines, advanced_vis_config rounded geometry, cross-filtering, and popovers	Production dashboards/*.dashboard.lookml deployed via API
LookML Performance Optimization	Static suggestions: [...] on low-cardinality dims, suggestable: no on unique IDs/text, model datagroup caching, BigQuery partition pruning filters, and raw foreign key hiding	Production-hardened LookML avoiding database query spikes
Pre-Deployment QA Audit	Dev branch push, LookML project validator, 100% test execution of all dashboard queries via Looker API, and bounded self-healing (max 3 iterations)	100% HTTP 200 OK query pass certificate before production release
Conversational Analytics (CA) Agent	Auto-generated domain persona and query rules, extraction of dashboard tiles into 1:1 Looker 4.0 Golden Queries with expanded_share_url grounding	Live AI Agent in Looker with natural language chat UI
Gemini Enterprise (GE) Integration	Automated registration and one-click publishing to connected Gemini Enterprise apps via Looker internal API	Natural language querying across enterprise Gemini apps in minutes
White-Labeled Embed Portal (Optional)	Scaffolding of React/Vite application (looker-embed-demo), .env configuration (VITE_CHAT_AGENT_ID), and CSS brand design tokens	Complete web application ready to run (npm run dev)

---

⚡ Spotlight: From Raw Data to Gemini Enterprise in Minutes

A flagship capability of demo-create is bridging the gap between raw data synthesis and cross-organizational enterprise AI in minutes:

graph LR
    Tiles["Dashboard Query Tiles"] --> Ground["Extract & Ground Golden Queries<br/>(expanded_share_url)"]
    Ground --> LinkAgent["Link to Looker CA Agent<br/>(PATCH /api/4.0/agents/{id})"]
    LinkAgent --> PublishGE["One-Click Publish to GE<br/>(POST /api/4.0/internal/agents/{id}/publish)"]
    PublishGE --> Chat["Natural Language Querying<br/>in Gemini Enterprise Apps"]

1. Deterministic Dashboard-to-Query Extraction: Every query tile from your generated executive dashboard is inspected and translated into an active Looker query.
2. Looker 4.0 Golden Query Grounding: Base queries are created via POST /api/4.0/queries to obtain deterministic expanded_share_url permalinks, then registered as 1:1 Golden Queries (POST /api/4.0/golden_queries).
3. Agent Linking: Golden queries are bound to the Conversational Analytics Agent (PATCH /api/4.0/agents/{agent_id}), establishing high-precision semantic grounding.
4. One-Click Gemini Enterprise Publishing: The agent is published directly to connected Gemini Enterprise apps via POST /api/4.0/internal/agents/{agent_id}/publish.

Within minutes of starting the flow, non-technical users and executives can query the entire domain dataset in natural language directly within Gemini Enterprise.

---

📄 Inspect a Real Deliverable

Curious what the final output looks like? Inspect a real deliverable produced by a completed run:

👉 View Canonical Delivery Report: IoT Trucking Fleet Analytics

Key highlights from the report:

• BigQuery Summary: 6 relational tables, 21,675 rows across dim_vehicles, fct_trips, fct_sensor_telemetry, etc.
• LookML Architecture: 3NF ERD with Native Derived Table (vehicle_metrics_ndt) eliminating Chasm Traps.
• Quality Audit: 19 / 19 (100%) dashboard tile queries tested with HTTP 200 OK before production release.
• Live AI Agent: 7 pre-seeded Golden Queries and verified Gemini Enterprise publish state.

---

---

Getting Started: Two Ways to Build

🚀 Mode 1: AI Agent Pair-Programmer (Primary Hero Flow)

Run interactively with your AI coding assistant (Jetski, Claude Code, or AgentAPI) using the looker-demo-orchestrator skill.

Step 1: Install Persistent CLI Tools

On any fresh machine, bootstrap the environment globally in seconds using uv:

uv tool install looker-demo-cli

This installs demo-create, looker-demo-cli, and lkr (lkr-dev-cli) into an isolated, persistent environment available across all terminal sessions.

Step 2: Run Pre-Flight Audit & Auto-Fix

Immediately run pre-check --fix to configure MCP servers, check dependencies, and sync agent skills:

demo-create pre-check --fix

Step 3: Configure Authentication (If Blocked)

1. Google Cloud & Application Default Credentials (ADC):

   gcloud auth login
   gcloud auth application-default login
   gcloud config set project <PROJECT_ID>
   

2. Looker Authentication (lkr auth login): Run the interactive Looker OAuth login:

   lkr auth login
   

   (Or ephemerally: uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli auth login)

Step 4: Launch the AI Demo Creation Flow

Once authenticated, instruct your AI assistant in chat:

"Create an end-to-end Looker demo for IoT Fleet Analytics (or SaaS ARR, Retail, Fintech)."

The AI agent orchestrates the entire workflow interactively:

• Interactive Schema Co-Design: Collaborate with the agent on ERD diagrams, field definitions, and micro-sample data previews before generating full scale.
• Fast-Path Deterministic CLI Execution: The parent agent runs compiled CLI subcommands directly (demo-create data, demo-create lookml model, demo-create lookml optimize, demo-create lookml deploy, demo-create agent create), eliminating subagent initialization drag and serialization latency.
• On-Demand Specialized Subagents: Spawned strictly for complex or non-deterministic recovery paths:
  • lookml-snowflake-modeler (3NF semantic modeling, NDT rollups & diamond joins when normalized schemas are detected)
  • lookml-dashboard-designer (Authors executive tabbed dashboards using the looker-visualizations suite)
  • lookml-qa-validator (Dev push, validator & max 3 query self-healing when deployment tests fail)
  • embed-portal-engineer (Vite embed portal; conditional on user confirmation)

---

⚙️ Gemini Enterprise (GE) Integration & Automated Provisioning

When deploying Conversational Analytics (CA) Agents to publish into Gemini Enterprise (GE), demo-create automatically verifies and configures Looker GE settings:

1. Automated Inspection (GET /api/4.0/gemini_enablement):
   • Inspects active Looker Gemini enablement settings.
   • If already configured, prompts to publish directly to the configured app or reconfigure.
2. Automated GCP Discovery & Configuration (PATCH /api/4.0/gemini_enablement):
   • If unconfigured, scans the GCP project for active Discovery Engine apps across standard regions (global, us, eu).
   • Updates Looker GE settings sending the full enablement payload with ai_ge_publish_enabled: true.
3. Automated Looker Service Account IAM Role:
   • Automatically grants the Looker Service Account (ai_ge_service_account_email) the Discovery Engine Admin (roles/discoveryengine.admin) role via gcloud projects add-iam-policy-binding.
4. Standalone CLI Inspection & Management:

   # Check Looker GE status
   demo-create ge status
   
   # Configure Looker GE settings interactively
   demo-create ge configure --gcp-project <PROJECT_ID>
   

---

💻 Mode 2: Standalone CLI (Headless Engine)

Execute demo-create directly from your terminal or CI/CD pipeline, one gate at a time:

demo-create pre-check --fix
demo-create data generate --domain retail --row-count 25000 --output-dir scratch/parquet
demo-create data upload --parquet-dir scratch/parquet --gcp-project my-gcp-project --dataset retail_analytics
demo-create lookml model --looker-project retail_analytics --dataset retail_analytics --connection my_bq_connection
demo-create lookml deploy --looker-project retail_analytics --lookml-dir lookml

State is persisted to .demo-state.json between calls, so later gates inherit earlier answers and you only pass what changes.

---

Alternative Installation Methods

Run Ephemerally with uvx (Zero-Install Alternative)

You can also execute the CLI on-demand in an ephemeral cache without pre-installing:

# Run pre-flight audit and auto-fix MCP / skills
uvx looker-demo-cli pre-check --fix

# Generate a synthetic dataset without pre-installing anything
uvx looker-demo-cli data generate --domain retail --row-count 25000 --output-dir scratch/parquet

Workspace Virtual Environment & Script Runner

To eliminate missing dependency errors across agent scratch scripts or data synthesis pipelines:

# Initialize a local .venv with all demo packages pre-installed:
demo-create env init
source .venv/bin/activate

# Execute ad-hoc scratch scripts using the CLI's bundled Python environment:
demo-create run-script scratch/generate_data.py

# Run one-off Python commands in the demo environment:
demo-create python -c "import pandas, pyarrow, google.cloud.bigquery; print('Ready!')"

Running from Local Source or Git (Development)

# Run directly from local source directory:
uvx --from . demo-create pre-check --fix

# Run directly from Git:
uvx --from git+https://github.com/lkrdev/looker-demo-cli.git demo-create pre-check --fix

# Local Editable Installation:
cd ~/looker-demo-cli
demo-create env init
source .venv/bin/activate
uv pip install -e .

---

Documentation

Document	Purpose
docs/COMMANDS.md	Full command reference -- every command, flag, and default, generated from the implementation and enforced by a CI drift test.
docs/ARCHITECTURE.md	How the CLI is layered, and the invariants a change must preserve.
CONTRIBUTING.md	Setup, the local gate, and how to add a command.
AGENTS.md	Instructions for an AI agent orchestrating a build.

The sections below are a guided tour; docs/COMMANDS.md is the exhaustive reference.

Commands & Usage

1. Where Am I? (status)

The orientation command. It reads .demo-state.json and reports which gates are done, which gate is current, and the literal next command to run with every value it already knows substituted in. Anything it does not know appears as an obvious <placeholder>.

# Human-readable gate table
demo-create status

# Machine-readable: an agent can drive the entire pipeline from this
demo-create status --json

The JSON payload carries completed_gates, current_gate, next_command, and requires_human_confirmation — the last being the single field an orchestrating agent branches on to decide whether it must stop and ask the user before proceeding. When is_complete is true, next_command is null and next_actions is empty, so a loop over next_actions terminates naturally.

$ demo-create status
┏━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
┃   ┃ Gate ┃ Stage                                    ┃ Status  ┃ Human gate ┃
┡━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
│ ✓ │    0 │ Environment audit & 4-target confirmation│ done    │ confirm    │
│ ✓ │    1 │ Schema co-design, synthesis & BQ load    │ done    │ confirm    │
│ ▶ │    2 │ Semantic modeling & dashboard generation │ current │ --         │
│ · │    3 │ Optimization, validation & release       │ pending │ confirm    │
│ · │    4 │ Conversational Analytics agent grounding │ pending │ confirm    │
│ · │    5 │ Gemini Enterprise publishing             │ pending │ confirm    │
└───┴──────┴──────────────────────────────────────────┴─────────┴────────────┘
→ Gate 2: Semantic modeling & dashboard generation
    $ demo-create lookml model --looker-project retail_demo --dataset retail \
        --connection acme_bigquery --gcp-project acme-analytics

2. Environment & Skill Audit (pre-check)

# Run visual audit of GCP credentials, MCP tools, and intent skills
demo-create pre-check

# Automatically install missing MCP configs and symlink skills into intent subfolders
demo-create pre-check --fix

# Emit raw JSON report for programmatic agent consumption
demo-create pre-check --json

3. Gated Pipeline Commands

Every phase runs independently and in any order that respects the gates. State is automatically persisted in .demo-state.json across executions, so each command inherits the previous one's answers. Every command accepts --state-file to point at an explicit state file instead of the discovered one, and --json to emit the machine-readable envelope:

Data Synthesis & Ingestion (demo-create data)

# Synthesize local Parquet files
demo-create data generate --domain retail --row-count 25000 --output-dir scratch/parquet

# Upload Parquet tables to BigQuery
demo-create data upload --parquet-dir scratch/parquet --gcp-project my-gcp-project --dataset retail_analytics

# Inspect existing BigQuery tables and schema (table view or raw JSON)
demo-create data inspect --gcp-project my-gcp-project --dataset retail_analytics
demo-create data inspect --gcp-project my-gcp-project --dataset retail_analytics --json

Semantic Modeling, Optimization & Deployment (demo-create lookml)

# Generate LookML from an existing BigQuery dataset with Knowledge Catalog / Dataplex introspection
demo-create lookml model --looker-project retail_analytics --dataset retail_analytics --connection bigquery_connection

# Generate LookML from local Parquet files
demo-create lookml model --looker-project retail_analytics --parquet-dir scratch/parquet --connection bigquery_connection

# Audit and delete orphaned duplicate LookML files at project root (e.g. users.view.lkml vs views/users.view.lkml)
demo-create lookml clean-root --looker-project retail_analytics
demo-create lookml clean-root --looker-project retail_analytics --dry-run
demo-create lookml clean-root --looker-project retail_analytics --json

# Audit and optimize staged LookML with Google Cloud server best practices (auto-snapshots to .backup_pre_opt)
demo-create lookml optimize --lookml-dir lookml/

# Atomically restore LookML files from snapshot (headless 1-command rollback, no Git required)
demo-create lookml restore --lookml-dir lookml/

# Deploy staged LookML files to dev workspace, run query tests, and release to production
demo-create lookml deploy --looker-project retail_analytics --lookml-dir lookml/

Conversational Analytics & Golden Queries (demo-create agent)

# Provision CA Agent and extract dashboard Golden Queries (Gate 4 - decoupled from GE)
demo-create agent create --model retail_analytics --explore orders --dashboard-file lookml/dashboards/overview.dashboard.lookml

# Extract and link Golden Queries from dashboard files or deployed dashboard to an existing agent
demo-create agent golden-queries --agent-id 1042 --dashboard-id retail_analytics::executive_overview

# Publish agent to connected Gemini Enterprise apps (Gate 5)
demo-create agent publish --agent-id 1042
demo-create agent publish --agent-id 1042 --json

Standalone Embed Portal Scaffolding (demo-create embed)

# Scaffold React/Vite portal with .env configured for Looker, dashboard, and CA chat
demo-create embed scaffold --looker-project retail_analytics --dashboard-id 1042 --agent-id 1042 --brand-name "Retail Insights"

Gemini Enterprise Management (demo-create ge)

# Check Looker Gemini enablement and GE status (visual table or raw JSON)
demo-create ge status
demo-create ge status --json

# Discover GCP GE instances, configure Looker, and grant IAM roles
demo-create ge configure --instance-id my-ge-app --location us

# Publish CA Agent to connected Gemini Enterprise apps (Gate 5)
demo-create ge publish --agent-id 1042

---

Intent-Based Skill Organization

When you run demo-create pre-check --fix, skills are automatically pulled from remote repositories and organized into ~/.gemini/config/skills/:

~/.gemini/config/skills/
├── data-design/
│   ├── data-designer/
│   ├── data-designer-architect/
│   ├── data-designer-engineer/
│   ├── data-designer-evaluator/
│   └── vertex-ai/
├── lookml/
│   ├── lkr-code-mode/
│   ├── repo-lookml/
│   ├── lookml-model/
│   ├── lookml-explore/
│   ├── lookml-view/
│   ├── lookml-dashboard/
│   ├── lookml-dashboard-to-query/
│   ├── lookml-snowflake-modeler/
│   ├── looker-visualizations/
│   │   ├── looker-vis-cartesian/
│   │   ├── looker-vis-tabular-kpi/
│   │   ├── looker-vis-specialty-maps/
│   │   └── looker-vis-advanced-config/
│   └── embed-themes/
└── embed-portal/
    ├── looker-demo-orchestrator/
    ├── setup-embed-demo/
    ├── customize-frontend/
    ├── customize-frontend-branding/
    ├── customize-frontend-theme/
    └── sso-embed/

This guarantees that any Jetski agent in any directory can discover and execute Looker demo workflows.