Tools for working with semantic layers from the terminal

The Sidemantic CLI provides tools for working with semantic layers from the terminal.

Installation

pip install sidemantic
# or
uv add sidemantic

Quick Start

# Get version
sidemantic --version

# Launch workbench with your models
sidemantic workbench ./models

# Try the demo
sidemantic workbench --demo

Commands

workbench

Interactive TUI for exploring models, writing SQL queries, and visualizing results.

# Launch with your models
sidemantic workbench ./models

# Try demo mode
sidemantic workbench --demo

# With database connection
sidemantic workbench ./models --db data/warehouse.db

# Run without installing (using uvx)
uvx sidemantic workbench --demo

Options:

• directory: Directory containing semantic layer files (default: .)
• --demo: Use demo data
• --connection: Database connection string
• --db: Path to DuckDB database file

See Workbench for detailed guide.

query

Execute SQL queries and output results as CSV.

# Query to stdout (SQL is first positional argument)
sidemantic query "SELECT orders.revenue, customers.region FROM orders"

# With explicit models directory
sidemantic query "SELECT * FROM orders" --models ./models

# Save to file
sidemantic query "SELECT * FROM orders" --output results.csv

# Show generated SQL without executing
sidemantic query "SELECT * FROM orders" --dry-run

# With database connection
sidemantic query "SELECT * FROM orders" --db data/warehouse.db

Options:

• SQL query (positional argument, required)
• --models, -m: Directory containing semantic layer files (default: .)
• --output, -o: Output file path (default: stdout)
• --connection: Database connection string
• --db: Path to DuckDB database file
• --dry-run: Show generated SQL without executing

validate

Validate semantic layer definitions and show errors/warnings.

# Basic validation
sidemantic validate ./models

# Verbose output with detailed info
sidemantic validate ./models --verbose

Options:

• --verbose, -v: Show detailed validation results

info

Display quick summary of the semantic layer.

sidemantic info ./models

Shows:

• Number of models
• List of models and their metrics
• Relationships between models

serve

Start a PostgreSQL-compatible server for your semantic layer.

# Basic server
sidemantic serve ./models

# Custom port
sidemantic serve ./models --port 5433

# With authentication
sidemantic serve ./models --username admin --password secret

# Demo mode
sidemantic serve --demo

Options:

• directory: Directory containing semantic layer files (default: .)
• --port, -p: Port to listen on (default: 5433)
• --username, -u: Username for authentication (optional)
• --password: Password for authentication (optional)
• --demo: Use demo data
• --connection: Database connection string
• --db: Path to DuckDB database file

Connect with any PostgreSQL client:

# psql
psql -h 127.0.0.1 -p 5433 -U admin -d sidemantic

# DBeaver, Tableau, Power BI, etc.
# Host: 127.0.0.1
# Port: 5433
# Database: sidemantic

The server exposes:

• Models as tables in semantic_layer schema
• Dimensions and metrics as columns
• Full semantic layer query rewriting
• PostgreSQL catalog compatibility

mcp-serve

Start a Model Context Protocol (MCP) server for AI integration.

# Serve your models
sidemantic mcp-serve ./models

# With DuckDB database
sidemantic mcp-serve ./models --db data/warehouse.db

# Demo mode
sidemantic mcp-serve --demo

Options:

• --db: Path to DuckDB database file
• --demo: Use demo data

The MCP server provides:

• list_models: List all available models
• get_models: Get detailed model information
• run_query: Execute SQL queries

Configure in Claude Desktop:

{
  "mcpServers": {
    "sidemantic": {
      "command": "sidemantic",
      "args": ["mcp-serve", "./models"]
    }
  }
}

migrator

Generate model definitions from existing SQL queries or analyze query coverage.

# Generate models from SQL queries
sidemantic migrator --queries queries/ --generate-models output/

# Coverage analysis against existing models
sidemantic migrator ./models --queries queries/ --verbose

Options:

• directory: Directory containing semantic layer files (default: .)
• --queries, -q: Path to file or folder containing SQL queries to analyze
• --verbose, -v: Show detailed analysis for each query
• --generate-models, -g: Generate model definitions from queries

lsp

Start the Language Server Protocol (LSP) server for Sidemantic SQL dialect.

sidemantic lsp  # Starts server on stdio

The LSP server provides:

• Autocompletion for MODEL, DIMENSION, METRIC, RELATIONSHIP, SEGMENT
• Context-aware property suggestions
• Validation errors from pydantic models
• Hover documentation

preagg

Pre-aggregation management commands.

preagg recommend

Show pre-aggregation recommendations based on query patterns.

# From database query history
sidemantic preagg recommend --connection "bigquery://project/dataset"

# From DuckDB with options
sidemantic preagg recommend --db data.db --min-count 50 --top 10

# From SQL query files
sidemantic preagg recommend --queries queries.sql --min-score 0.5

Options:

• --queries, -q: Path to file/folder with SQL queries
• --connection: Database connection string to fetch query history
• --db: Path to DuckDB database file
• --days, -d: Days of query history to fetch (default: 7)
• --limit, -l: Max queries to analyze (default: 1000)
• --min-count: Minimum query count for recommendation (default: 10)
• --min-score: Minimum benefit score 0-1 (default: 0.3)
• --top, -n: Show only top N recommendations

preagg apply

Apply pre-aggregation recommendations to model YAML files.

sidemantic preagg apply ./models --connection "bigquery://project/dataset"
sidemantic preagg apply ./models --db data.db --top 5
sidemantic preagg apply ./models --queries queries.sql --dry-run

Options: Same as recommend plus:

• directory: Directory containing semantic layer YAML files (default: .)
• --dry-run: Show what would be added without writing files

preagg refresh

Refresh pre-aggregation tables.

sidemantic preagg refresh ./models --db data.db
sidemantic preagg refresh ./models --model orders --mode full
sidemantic preagg refresh ./models --connection "postgres://localhost:5432/db"

Options:

• directory: Directory containing semantic layer files (default: .)
• --model, -m: Only refresh pre-aggregations for this model
• --preagg, -p: Only refresh this specific pre-aggregation
• --mode: Refresh mode: full, incremental, or merge (default: incremental)
• --connection: Database connection string
• --db: Path to DuckDB database file

Configuration

The CLI can use a configuration file for default settings:

# Specify config file
sidemantic --config sidemantic.yaml <command>

# Or auto-discover sidemantic.yaml/sidemantic.json in current directory

Shell Completion

Install completion for your shell:

sidemantic --install-completion

Supports bash, zsh, fish, and PowerShell.

Next Steps

• Workbench - Interactive TUI guide
• Query - Query syntax reference
• Python API - Programmatic usage