Metadata-Version: 2.4
Name: superset-sup
Version: 0.1.1
Summary: 'sup - the official Preset CLI with a git-like interface for managing your analytics assets.
Author-email: Beto Dealmeida <beto@preset.io>, Max Beauchemin <max@preset.io>
License: Business Source License 1.1
        
        License text copyright © 2025 Preset Inc. All Rights Reserved.
        “Business Source License” is a trademark of MariaDB plc.
        
        ## Terms
        
        Preset Inc. (“Licensor”) hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.  
        The Licensor may make an Additional Use Grant, permitting limited production use as described below.
        
        Effective on the Change Date (or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first), the Licensor grants you rights under the Change License, and the rights granted in the paragraph above terminate.
        
        If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from Preset Inc., its affiliates, or authorized resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License.  
        This License applies separately for each version of the Licensed Work, and the Change Date may vary for each version released by Licensor.
        
        You must conspicuously display this License on each original or modified copy of the Licensed Work.  
        If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
        
        Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of Preset Inc. or its affiliates (provided that you may use a trademark or logo of Licensor as expressly required by this License).  
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN “AS IS” BASIS.  
        LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
        
        MariaDB hereby grants you permission to use this License’s text to license your works, and to refer to it using the trademark “Business Source License,” as long as you comply with the Covenants of Licensor below.
        
        ## Covenants of Licensor
        
        In consideration of the right to use this License’s text and the “Business Source License” name and trademark, Preset Inc. covenants to MariaDB plc, and to all other recipients of the Licensed Work to be provided by Licensor:
        
        - To specify as the Change License the GNU General Public License, version 2.0 or later, or a license that is compatible with GPL v2.0 or later (where “compatible” means that software provided under the Change License can be included in a program with software provided under GPL v2.0 or later).  
          Licensor may specify additional Change Licenses without limitation.
        - To either: (a) specify an Additional Use Grant that imposes no additional restriction on the right granted in this License; or (b) insert the text “None” if no Additional Use Grant is provided.  
          Not to modify this License in any other way.
        
        ## Notice
        
        The Business Source License (this document, or the “License”) is not an Open Source license.  
        However, the Licensed Work will eventually be made available under an Open Source License, as stated in this License.
        
        ---
        
        ### Fields to fill for each release
        
        - **Licensed Work:** name of the software/component  
        - **Change Date:** e.g., 3 years from the date of first public release of that version  
        - **Change License:** GPL-2.0-or-later (or other GPL-compatible license)  
        - **Additional Use Grant:** optional (e.g., “free for up to 5 users in production”) or “None”
        
Project-URL: Homepage, https://github.com/preset-io/superset-sup
Project-URL: Documentation, https://github.com/preset-io/superset-sup/blob/main/README.md
Project-URL: Support, https://preset.io/support
Project-URL: Repository, https://github.com/preset-io/superset-sup
Project-URL: Legacy CLI Documentation, https://github.com/preset-io/preset-cli
Keywords: superset,preset,cli,data,analytics,business-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS.rst
Requires-Dist: importlib-metadata; python_version < "3.8"
Requires-Dist: Cython>=0.29.26
Requires-Dist: PyYAML>=6.0
Requires-Dist: appdirs>=1.4.4
Requires-Dist: backoff>=1.10.0
Requires-Dist: beautifulsoup4>=4.10.0
Requires-Dist: click>=8.1.2
Requires-Dist: jinja2>=3.0.3
Requires-Dist: marshmallow>=3.17.0
Requires-Dist: numpy>=1.21.5
Requires-Dist: pandas>=1.3.5
Requires-Dist: prison>=0.2.1
Requires-Dist: prompt-toolkit>=3.0.24
Requires-Dist: pygments>=2.11.2
Requires-Dist: python-graphql-client>=0.4.3
Requires-Dist: requests>=2.26.0
Requires-Dist: rich>=12.3.0
Requires-Dist: sqlalchemy<2,>=1.4
Requires-Dist: sqlglot>=26
Requires-Dist: tabulate>=0.8.9
Requires-Dist: typing-extensions>=4.0.1
Requires-Dist: yarl>=1.7.2
Requires-Dist: greenlet>=1.1.3
Requires-Dist: aiohttp>=3.8.3
Requires-Dist: typer>=0.12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: halo>=0.0.31
Provides-Extra: snowflake
Requires-Dist: snowflake-sqlalchemy==1.4.4; extra == "snowflake"
Provides-Extra: testing
Requires-Dist: setuptools; extra == "testing"
Requires-Dist: freezegun; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: pytest-mock; extra == "testing"
Requires-Dist: pyfakefs; extra == "testing"
Requires-Dist: requests-mock; extra == "testing"
Requires-Dist: codespell; extra == "testing"
Requires-Dist: pre-commit; extra == "testing"
Requires-Dist: pip-tools>=6.6.0; extra == "testing"
Requires-Dist: ruff>=0.8.0; extra == "testing"
Dynamic: license-file

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

<img width="453" height="162" alt="Image" src="https://github.com/user-attachments/assets/76433889-e9f9-4813-bfe3-9fd1e4bbe75f" />

**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.

## 🎯 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

<img width="849" height="310" alt="Image" src="https://github.com/user-attachments/assets/994eba52-16cb-49aa-b370-deb7cf346c4c" />

## 🚀 Quick Start

### Installation

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

### Getting Started

The beautiful sectioned help guides you through the perfect workflow:

```bash
# 🔧 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:
```bash
--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:
```bash
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)
```bash
# 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
```bash
# 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:
```bash
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:
```bash
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

### Primary Focus: Preset-Hosted Instances
'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.

### Self-Hosted Superset
**Does it work with my Superset instance?** Most functionality should work, but
depending on your authentication setup, you may need to tweak the code. We
welcome contributions from the broader Superset community to improve
compatibility.

**Preset-free mode**: A future version could remove multi-workspace constructs
for single-instance Superset deployments. If you're interested in this, please
contribute or open an issue.

### Contributing for Broader Compatibility
We're open to contributions that enable 'sup for the entire Superset community.
Areas that likely need work for self-hosted instances:
- Authentication methods beyond Preset API tokens
- Single-instance mode (removing workspace concepts)
- Different API endpoint structures

## 🔐 Authentication

Multiple authentication methods supported:

### API Token (Recommended)
```bash
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
```bash
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
```bash
# 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](https://github.com/preset-io/preset-cli) 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:
```bash
# Legacy preset-cli
preset-cli --workspaces=https://workspace.preset.io/ superset export

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