'sup! - Probably the Best Unofficial Apache Superset CLI 🚀

A modern command-line interface for Apache Superset and Preset workspaces

Brought to you and fully compatible with Preset • For power users and AI agents

🧪 Beta Release: This is an experimental beta release for Preset customers and the Superset community. We welcome feedback and contributions! Please report issues at https://github.com/preset-io/superset-sup/issues

✨ What is 'sup!?

'sup is a solid CLI for Apache Superset power users and their agents. It provides sectioned help, rich terminal formatting, and git-like workflows for managing Superset and Preset workspaces efficiently.

[Screenshot of beautiful ASCII art and sectioned help will go here]

🎯 Key Capabilities

Run any SQL through Superset's data access layer - get results as rich tables, CSV, YAML or JSON
Backup and restore charts, dashboards, and datasets with full dependency tracking
Synchronize assets across Superset instances with Jinja2 templating for customization
Enrich metadata to/from dbt Core/Cloud - more integrations to come
Automate workflows and integrate with CI/CD pipelines
Perfect for scripting and AI-assisted data exploration

🚀 Quick Start

Installation

pip install superset-sup

pip install git+https://github.com/preset-io/superset-sup.git

Getting Started

The beautiful sectioned help guides you through the perfect workflow:

# 🔧 Configuration & Setup
sup config auth          # Set up authentication credentials
sup config show          # Verify current settings

# 🔍 Direct Data Access
sup sql "SELECT COUNT(*) FROM users"           # Beautiful Rich table
sup sql "SELECT * FROM sales" --json           # JSON for agents
sup sql "SELECT * FROM sales" --csv            # CSV export

# 📊 Manage Assets
sup workspace list       # Find your workspace
sup workspace use 123    # Set default workspace
sup chart list --mine    # Your charts with server-side search
sup chart data 3628 --csv # Export chart data directly

# 🔄 Synchronize Assets Across Workspaces
sup sync create ./my_sync --source 123 --targets 456,789  # Git-ready sync
sup sync run ./my_sync --dry-run                          # Preview operations
sup sync run ./my_sync                                    # Execute sync

📋 Command Reference

Configuration & Setup

sup config - Beautiful configuration guide with sources, settings, and setup steps
sup config auth - Set up authentication credentials
sup config show - Display current configuration
sup config set workspace-id 123 - Set default workspace

Direct Data Access

sup sql "query" - Execute SQL with beautiful output
sup sql --interactive - Interactive SQL session (coming soon)
sup sql "query" --json - JSON output for automation
sup sql "query" --porcelain - Machine-readable output

Manage Assets

sup workspace list - List available workspaces
sup database list - Database operations
sup dataset list --search="users" - Server-side search by table name
sup chart list --mine --search="revenue" - Multi-field chart search
sup chart sql 3628 - Get compiled SQL behind any chart
sup chart data 3628 --csv - Export actual chart data
sup dashboard list --search="exec" - Dashboard title/slug search
sup query list --mine - Discover saved queries
sup user list - User management

Synchronize Assets Across Workspaces

sup sync create - Create sync configuration with templating
sup sync run --dry-run - Preview sync operations
sup sync validate - Validate sync configuration
Enterprise cross-workspace workflows with Jinja2 templating

🎨 Beautiful Features

Sectioned Help System

Commands are organized in logical sections that guide your workflow:

Configuration & Setup → Direct Data Access → Manage Assets → Synchronize

Rich Output Formats

Rich Tables: Colorful, clickable tables with emerald green Preset branding
JSON: Perfect for AI agents and automation (--json)
CSV: Direct data export (--csv)
YAML: Configuration-friendly format (--yaml)
Porcelain: Machine-readable, no decorations (--porcelain)

Filtering

Every entity command supports powerful, consistent filters:

--mine                      # Objects owned by current user
--name "pattern*"           # Name pattern matching with wildcards
--limit 50                  # Result pagination (default: 50)
--search "revenue"          # Server-side search (charts, dashboards,
                           # datasets)
--json                      # JSON output for automation

Agent-Optimized

Perfect for AI assistants and automation:

sup chart data 3628 --json --limit=100        # Structured data access
sup sql "SELECT COUNT(*) FROM users" --json   # Direct SQL with JSON
sup dashboard list --search="exec" --porcelain # Machine-readable output

🔄 Git-like Asset Workflows

Chart Lifecycle (Production Ready)

# Pull charts + dependencies to filesystem
sup chart pull --mine                         # Pull your charts + datasets +
                                              # databases
sup chart pull --name="*revenue*"             # Pull revenue charts +
                                              # dependencies
sup chart pull --id=3586                      # Pull specific chart +
                                              # dependencies

# Push from filesystem to workspace
sup chart push                                # Push to configured target
                                              # workspace
sup chart push --workspace-id=456             # Push to specific workspace
sup chart push --overwrite --force            # Push with overwrite, skip
                                              # confirmations

Advanced Sync Workflows

# Multi-target synchronization with templating
sup sync create ./templates --source 123 --targets 456,789,101
sup sync run ./templates --option env=prod    # Jinja2 templating for
                                              # environments
sup sync run --bidirectional                 # Two-way sync with conflict
                                              # resolution

🏗️ Architecture

Modern Tech Stack

Typer 0.12+: Type-safe CLI with automatic help generation
Rich 13+: Beautiful terminal formatting and tables
Pydantic 2.0+: Configuration validation and type safety
Pandas: Data processing and multiple output formats

Configuration

Global: ~/.sup/config.yml for user preferences
Project: .sup/state.yml for project-specific settings
Environment: SUP_* variables override everything
Priority: Environment → Global → Project

Enterprise Features

Cross-workspace sync: Source workspace → multiple target workspaces
Asset dependencies: Automatic resolution of charts → datasets → databases
Jinja2 templating: Environment-specific customization
Git-ready: YAML-based assets work perfectly with version control

🎯 Extra Features

Chart SQL Access

Get the compiled SQL behind any chart - business logic included:

sup chart sql 3628
# Output: Complex SQL with filters, aggregations, joins - the actual query
# Superset runs

Chart Data Export

Access actual chart results as structured data:

sup chart data 3628 --json     # Perfect for analysis, reporting, AI
                               # models
sup chart data 3628 --csv      # Direct CSV export

Server-Side Search

Efficient search across all entity types:

Charts: --search uses multi-field search (title, description, etc.)
Dashboards: --search searches title and slug
Datasets: --search searches table names
All searches work with --limit for performance

🏠 Superset Compatibility

Preset-Hosted Instances (Primary Focus)

'sup is primarily designed for Preset-hosted Superset instances and has been extensively tested with Preset workspaces. All features work seamlessly with Preset's multi-workspace environment.

sup config auth           # Set up Preset API credentials
sup workspace list        # Browse your workspaces
sup workspace use 123     # Set default workspace
sup chart list --mine     # List your charts
sup chart pull --mine     # Pull charts with dependencies

Self-Hosted Superset ✨ (NEW - Full Support!)

Dual-Path CLI Complete: Full support for self-hosted Superset with OAuth2/OIDC and multiple auth methods!

'sup now supports self-hosted Superset instances alongside Preset workspaces in the same CLI:

OAuth2/OIDC - Works with Keycloak, Okta, Auth0, Dex, Azure AD, Cognito
Username/Password - Direct Superset authentication
JWT Tokens - Pre-generated JWT tokens
Seamless switching - Use sup instance commands to switch between self-hosted instances
100% backward compatible - Existing Preset workflows work unchanged

Quick Start: Self-Hosted Setup

# 1. Configure self-hosted instance
sup config auth
# → Choose "self-hosted Superset"
# → Enter instance details and credentials

# 2. View configured instances
sup instance list

# 3. Set your default instance
sup instance use production

# 4. Use 'sup with self-hosted
sup dataset list
sup chart pull --mine
sup sql "SELECT * FROM your_table"

Configuration (Manual Setup)

Add to ~/.sup/config.yml:

superset_instances:
  production:
    url: https://superset.example.com
    auth_method: oauth
    oauth_token_url: https://auth.example.com/oauth2/token
    oauth_client_id: superset-cli
    oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
    oauth_username: superset-service
    oauth_password: ${ENV:SUPERSET_SERVICE_PASSWORD}

Set environment variables:

export SUPERSET_OAUTH_SECRET="your-client-secret"
export SUPERSET_SERVICE_PASSWORD="your-service-password"

Dual-Path Workflows

Switch between Preset and self-hosted seamlessly:

# Use Preset workspace
sup workspace use 123
sup chart list

# Switch to self-hosted instance
sup instance use production
sup chart list         # Same commands, different backend!

# Or use explicit flags
sup chart list --workspace-id 123           # Preset
sup chart list --instance production        # Self-hosted

# Even pull/push across different systems
sup chart pull --instance staging --mine    # From self-hosted
sup chart push --workspace-id 456           # To Preset

Authentication Methods

Interactive OAuth (Recommended) - Browser-based, zero-configuration:

auth_method: oauth
oauth_authorization_url: https://auth.example.com/oauth2/authorize
oauth_token_url: https://auth.example.com/oauth2/token
oauth_client_id: superset-cli
# No secrets needed! Browser-based auth with PKCE

First run opens your browser for authentication, then tokens are cached:

$ sup dataset list
🔐 Opening browser for authentication...
✓ Authentication successful!
[Shows datasets]

$ sup chart list
[Uses cached token - no browser needed!]

OAuth2 with Service Account - For automation/CI:

auth_method: oauth
oauth_token_url: https://auth.example.com/oauth2/token
oauth_client_id: your-client-id
oauth_client_secret: ${ENV:OAUTH_SECRET}
oauth_username: service-account
oauth_password: ${ENV:SERVICE_PASSWORD}

Username/Password - Direct auth:

auth_method: username_password
username: admin
password: ${ENV:SUPERSET_PASSWORD}

JWT Token - Pre-generated tokens:

auth_method: jwt
jwt_token: eyJhbGc...

Complete Setup Guides

Self-Hosted Setup Guide - Step-by-step OAuth2/OIDC configuration
Provider Examples - Keycloak, Okta, Auth0, Azure AD, Cognito
Troubleshooting - Common issues and solutions
Security Best Practices - Credential management

🔐 Authentication

Multiple authentication methods supported:

API Token (Recommended)

sup config auth  # Interactive setup
# Or set environment variables:
export SUP_PRESET_API_TOKEN="your-token"
export SUP_PRESET_API_SECRET="your-secret"

Environment Variables

SUP_WORKSPACE_ID=123        # Default workspace
SUP_DATABASE_ID=5           # Default database
SUP_TARGET_WORKSPACE_ID=456 # Cross-workspace sync target
SUP_ASSETS_FOLDER=./assets  # Asset storage location

🎨 For Developers

AI Agent Integration

'sup is designed to be AI-friendly:

Consistent patterns: All commands follow the same filter patterns
Structured output: JSON and porcelain modes for automation
Server-side filtering: Efficient data access
Minimal tokens: Optimized for AI context windows

CI/CD Integration

# In your CI pipeline:
sup chart pull --mine --skip-dependencies     # Pull only charts
sup chart push --workspace-id=$PROD_WS --force # Deploy to production
sup sync run ./deploy --option env=production  # Multi-environment deploy

🆚 Legacy CLIs (preset-cli & superset-cli)

This package includes three command-line tools:

sup - The modern, recommended CLI with beautiful UX (🆕 focus of development)
preset-cli - Legacy CLI for Preset workspaces (maintenance mode)
superset-cli - Legacy CLI for standalone Superset (maintenance mode)

All three CLIs are installed together, ensuring backward compatibility with existing workflows while providing a smooth migration path to the modern sup experience.

Why 'sup?

'sup replaces and modernizes the legacy tools while maintaining full compatibility:

Beautiful UX: Rich formatting vs plain text
Logical organization: Sectioned help vs long command lists
Git-like workflows: Intuitive pull/push vs complex export/import
Agent-optimized: Perfect for AI assistants
Type-safe: Modern Python with full type hints

Legacy CLI Documentation

For users still using preset-cli or superset-cli, please refer to the original preset-cli repository for comprehensive documentation. We recommend migrating to sup for the best experience, but the legacy CLIs will continue to work.

Migration path: Most commands have direct equivalents in sup. For example:

# Legacy preset-cli
preset-cli --workspaces=https://workspace.preset.io/ superset export

# Modern sup
sup workspace use 123
sup chart pull --mine

Uh oh!

FilesExpand file tree

README.md

Latest commit

History