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) to a configured AI provider — a local Ollama instance by default, so workbook metadata stays on your machine. The one exception is the Command Center AI Assistant's /data command: when you ask it a question about data it just captured from a live dashboard, that capture is sent with the question. 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

# List every element (datasources, fields, calculations, parameters, worksheets, dashboards) as
# one flat table, with health/usage/publish/Git status per element
tableau-inspector inventory workbook.twbx

# 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

The Command Center (tableau-inspector command-center) has an AI Assistant panel with / commands (/search, /document, /formula, /perf, /data, /edit), exact item references, command chaining, and short multi-message chats. See AI_ASSISTANT.md.

The Command Center also has a UAT Testing page that compares a PROD and a STAGING Tableau Server/Cloud site before promoting changes. It runs the read-only checks a tool can genuinely verify, such as permissions, groups, refresh schedules and jobs, exports, and workbook definitions. You can narrow a run to chosen workbooks (their projects, data sources and groups follow), users and groups; the scope is saved between runs. After a run, optional browser checks exercise selected, sampled or all eligible views in your signed-in browser, and PROD and STAGING screenshots can be compared side by side. Everything else becomes a manual test with steps and a recorded outcome. It needs the server extra (pip install "tableau-inspector[server]") and a Personal Access Token for each environment, kept in your OS keychain. UAT_TESTS.md explains what each test checks and what its result means.

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