tableau-cli 0.1.4

CLI for Tableau Server/Cloud, designed for AI agent integration

tableau-cli

A command-line interface for Tableau Server / Tableau Cloud, designed for AI agent integration. All output is structured JSON to stdout, with agent-friendly error messages that include actionable hints.

Why CLI over MCP?

MCP (Model Context Protocol) servers continuously occupy agent context — every tool description is loaded into the system prompt, even when only one command is needed. A CLI follows a simpler call-execute-exit pattern: the agent invokes a command, reads the JSON output, and moves on.

The companion Claude Code skill under skills/ extends the same idea to command knowledge — the full reference is loaded only when the agent is about to execute a command, not kept in context upfront. See Use with Claude Code below.

This project provides the same capabilities as the tableau-mcp server, with behavioral alignment in data transformations, error handling, and output structures.

Quick Start

Prerequisites

• Python >= 3.10
• A Tableau Server or Tableau Cloud instance
• A Personal Access Token (PAT)

Install

git clone https://github.com/i-richardwang/tableau-cli.git
cd tableau-cli
pip install -e .

# Optional: install conversion dependencies (TDSX/HYPER → Parquet/CSV)
pip install -e ".[convert]"

Configure

# Option 1: CLI config (saved to ~/.tableau-cli.json)
tableau-cli config set \
  --server https://your-tableau-server.com \
  --site-name YourSite \
  --pat-name your-token-name \
  --pat-value your-token-value

# Option 2: Environment variables
export SERVER=https://your-tableau-server.com
export SITE_NAME=YourSite
export PAT_NAME=your-token-name
export PAT_VALUE=your-token-value

Environment variables take precedence over the config file. siteName defaults to "" (the default site) if not set.

# Verify configuration
tableau-cli config show

Use with Claude Code

This repository ships with a Claude Code skill under skills/. Once loaded, it gives an agent enough context to route a user's request to the right command — without putting the full CLI reference into the system prompt.

skills/
├── SKILL.md              # Intent routing + environment check
└── references/
    ├── cli.md            # Full command reference (loaded before executing)
    └── installation.md   # Install + auth setup (loaded if not configured)

Once Claude Code has loaded the skill, a typical interaction looks like:

1. The agent runs tableau-cli --help to verify the CLI is installed and configured. If not, it loads references/installation.md and stops until setup is complete.
2. The agent maps the user's intent to a subcommand using the Intent Routing table in SKILL.md (e.g., "find datasources with Sales in the name" → ds list --filter "name:has:Sales").
3. Before constructing the actual command, the agent loads references/cli.md — the skill explicitly forbids guessing flags from memory, so the reference is the source of truth for syntax.
4. The agent runs the command and parses the structured JSON output, including the hint field on errors.

Common workflows (e.g., ds download --to parquet → load with Polars/Pandas) are pre-defined under Intent Routing in SKILL.md, so the agent doesn't have to reason about chaining from scratch.

You can of course use tableau-cli directly from a shell without the skill — the skill is only needed when you want an agent to drive the tool.

Commands

Search

Search across all content types (workbooks, views, datasources, etc.).

tableau-cli search "Superstore"
tableau-cli search "Sales" --type workbook,view
tableau-cli search "Revenue" --limit 10 --order-by hitsTotal:desc

Datasources

# List all datasources
tableau-cli datasources list
tableau-cli ds list --filter "name:has:Sales" --limit 50

# Download datasource file (.tdsx)
tableau-cli datasources download <datasourceId> -o ./data/

# Download and convert to Parquet or CSV in one step (requires tableau-cli[convert])
tableau-cli ds download <datasourceId> -o ./data/ --to parquet
tableau-cli ds download <datasourceId> -o ./data/ --to csv

# Get field metadata (VizQL Data Service + Metadata API enrichment).
# On Tableau >= 2025.3 the result also includes the datasource model:
# logical tables and their relationships.
tableau-cli datasources metadata <luid>

# Query datasource data (VizQL Data Service)
tableau-cli datasources query <luid> --query '{"fields": [{"fieldCaption": "Category"}, {"fieldCaption": "Sales"}]}'
tableau-cli ds query <luid> --query '{"fields": [...]}' --limit 100

Views

# List views (includes upstream datasources via Metadata API enrichment)
tableau-cli views list
tableau-cli views list --filter "name:has:Dashboard" --format table

# Get view details: upstream datasources, workbook/project/owner info, and web URL
tableau-cli views get <viewId>

# Get view data as CSV
tableau-cli views data <viewId>

# Get view data with view filters applied
tableau-cli views data <viewId> --vf "Region=West" --vf "Category=Technology"

# Download view image
tableau-cli views image <viewId> -o dashboard.png
tableau-cli views image <viewId> --width 1200 --height 800 --img-format SVG -o dashboard.svg
tableau-cli views image <viewId> --vf "Region=West" -o west.png

Convert

Convert local TDSX/HYPER files to Parquet or CSV.

Conversion needs heavier packages (pantab, polars, pyarrow). You have two options:

• Install them into the CLI: pip install tableau-cli[convert].
• Don't install anything: if uv is on your PATH, conversion transparently falls back to running the step in an ephemeral uv run --with ... environment, so those packages never land in your host Python. The first run provisions the environment (a few seconds); later runs use uv's cache. This is the recommended path when the CLI itself was installed via uv tool install tableau-cli.

For most use cases, ds download --to parquet (or --to csv) is simpler — it downloads and converts in one step. The convert command is useful when you already have a .tdsx or .hyper file on disk.

# Convert TDSX to Parquet (default)
tableau-cli convert data.tdsx
tableau-cli convert data.tdsx -o ./output/

# Convert to CSV
tableau-cli convert data.tdsx --to csv
tableau-cli convert data.tdsx --to csv -o ./output/

# Convert standalone HYPER file
tableau-cli convert extract.hyper --to csv -o ./output/result.csv

Workbooks

# List workbooks (includes upstream datasources via Metadata API enrichment)
tableau-cli workbooks list
tableau-cli wb list --filter "name:eq:Finance" --format table

# Get workbook details (includes views with usage statistics,
# upstream datasources, and the default view's web URL)
tableau-cli workbooks get <workbookId>

Projects

# List projects
tableau-cli projects list
tableau-cli projects list --filter "topLevelProject:eq:true" --format table

Config

tableau-cli config set --server https://tableau.example.com
tableau-cli config show

Output

All commands output structured JSON to stdout by default. Use --format table for human-readable table output.

# JSON (default, for agent consumption)
tableau-cli ds list

# Table (for human reading)
tableau-cli ds list --format table

File Output

Commands that save files (ds download, views image -o, convert) output a JSON object with the file path to stdout, enabling agents to chain operations:

# Download and convert in one step
tableau-cli ds download <id> -o ./data/ --to parquet  # → {"filePath": ".../data.parquet"}

# Or as separate steps (useful for keeping the original .tdsx)
tableau-cli ds download <id> -o ./data/               # → {"filePath": ".../data.tdsx"}
tableau-cli convert ./data/data.tdsx -o ./data/        # → {"filePath": ".../data.parquet"}

Error Output

Errors are also structured JSON, designed to guide agents toward resolution:

{
  "isError": true,
  "errorType": "feature-disabled",
  "message": "The VizQL Data Service is disabled on this Tableau Server.",
  "hint": "To enable it, use TSM using the instructions at https://help.tableau.com/..."
}

Error types include: authentication-error, feature-disabled, tableau-api-error, config-error, validation-error, and translated VDS error codes with actionable hints.

API Coverage

Area	APIs Used
Authentication	REST API v3.24 — PAT sign-in / sign-out
Datasources	REST API (list, download) + VizQL Data Service (metadata, model, query) + Metadata API (GraphQL enrichment)
Views	REST API (list, get, data, image with view filters) + Metadata API (lineage enrichment)
Workbooks	REST API (list, get with view enrichment) + Metadata API (lineage enrichment)
Projects	REST API (list)
Search	Content Exploration API + Metadata API (lineage enrichment)
Convert	Local file conversion: TDSX/HYPER → Parquet/CSV (optional dependencies)

Development

# Run directly
python -m tableau_cli.cli views list

# Install in editable mode
pip install -e .

Acknowledgements

This project is derived from @tableau/mcp-server, adapting its Tableau REST API, VizQL Data Service, and Metadata API integrations into a CLI format.

License

Apache License 2.0