tableau-inspector (Python)

Local-first CLI that statically analyzes Tableau workbooks (.twb / .twbx) for common issues — dev-only DB connections, hidden worksheets, unused calculations/parameters, duplicate calculations, default filters, blank dashboard titles, missing captions, duplicate field aliases — before you publish. Everything is parsed from the workbook's embedded XML.

An optional AI assistant (ask, explain, summarize, docs --ai) can explain calculations, summarize dashboards, and answer questions in plain English. It sends only already-extracted metadata (never raw XML, never live Tableau data) to a configured AI provider — a local Ollama instance by default, so workbook metadata stays on your machine. Every other command makes no network calls at all.

This is a Python port of the Node.js tableau-inspector CLI, with the same functionality and zero runtime dependencies (stdlib only) -- the AI provider layer is implemented with stdlib urllib, so this holds even with the assistant enabled.

Install

pip install -e .

Quick start

# Lint a workbook for common publishing issues
tableau-inspector analyze workbook.twbx

# Generate a self-contained interactive HTML explorer (overview, lineage, calculations, health)
tableau-inspector explore workbook.twbx

# Trace what a field/calculation depends on and what depends on it
tableau-inspector lineage workbook.twbx --field "Customer Segment"

# Search fields, calculations, dashboards, worksheets, filters, parameters, and datasources
tableau-inspector search workbook.twbx "profit"
tableau-inspector search workbook.twbx "DATEDIFF" --formula
tableau-inspector search workbook.twbx "sales" --type field

# Diff two versions of a workbook
tableau-inspector compare old.twbx new.twbx

# Ask a question about a workbook (requires a running Ollama instance)
tableau-inspector ask workbook.twbx "What does Profit Margin calculate?" --model llama3.1

# Explain a calculation, field, or dashboard in plain English -- runs a deterministic
# investigation (formula, dependencies, lineage, usage) before asking the AI to explain it
tableau-inspector explain workbook.twbx --calculation "Profit Margin" --model llama3.1
tableau-inspector explain workbook.twbx --field "Customer Segment" --model llama3.1
tableau-inspector explain workbook.twbx --dashboard "Executive Dashboard" --model llama3.1 --level quick

# Summarize a dashboard's purpose, contents, filters, parameters, and key calculations
tableau-inspector summarize workbook.twbx --dashboard "Executive Dashboard" --model llama3.1

# Generate documentation with AI-written summaries and calculation explanations woven in
tableau-inspector docs workbook.twbx --ai --model llama3.1

# Point any AI command at a local business-context file for domain knowledge (custom metric
# definitions, fiscal-calendar notes, etc.) -- read locally only, never uploaded or persisted
tableau-inspector explain workbook.twbx --calculation "Profit Margin" --model llama3.1 --context company-context.md

# Lint (analyze + check-filters + compare), then git commit and push a workbook change,
# with an AI-generated commit message
tableau-inspector push workbook.twb --model llama3.1

Every command also supports --json for machine-readable output, and analyze/compare support --html for a shareable, self-contained HTML report.

AI assistant

ask/explain/summarize/docs --ai require a model name via --model, the TABLEAU_INSPECTOR_AI_MODEL environment variable, or (for a non-default provider) --provider/TABLEAU_INSPECTOR_AI_PROVIDER. The default provider is a local Ollama instance at http://localhost:11434 (override with --ollama-host / TABLEAU_INSPECTOR_OLLAMA_HOST). Start Ollama and pull a model before using these commands:

Every AI command also accepts --context <path> (or TABLEAU_INSPECTOR_CONTEXT_FILE) to inject a local business-context file — .md, .txt, or .json, up to 20KB — as supplementary domain knowledge in the AI prompt. It's read locally and sent only to the configured AI provider, never uploaded or persisted, and it never overrides actual workbook metadata.

ollama serve
ollama pull llama3.1

Documentation

See USAGE.md for the full command reference (every flag, exit codes, AI provider setup, and example workflows), or run tableau-inspector --help / tableau-inspector <command> --help for the same option reference from the CLI itself.

License

MIT © Joshua Bowen