preset-io · blarghmatey · Nov 24, 2025 · Nov 24, 2025 · Jan 7, 2026 · Jan 8, 2026
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,10 +5,29 @@ Changelog
 Next
 ====
 
+- **NEW**: Full dual-path CLI support for both Preset workspaces and self-hosted Superset instances
+  - New ``sup instance`` command group for managing self-hosted Superset instances
+  - Added ``--instance`` parameter to all entity commands (chart, dashboard, dataset, database, query, user, sql, dbt, group, sync)
+  - Intelligent dispatcher in ``SupSupersetClient.from_context()`` routes based on explicit parameters, context, environment, or config
+  - Seamless switching between Preset and self-hosted with same commands
+  - All changes 100% backward compatible - existing Preset workflows unchanged
+- **NEW**: Multiple authentication methods for self-hosted Superset
+  - OAuth2/OIDC support (works with Keycloak, Okta, Auth0, Dex, Azure AD, Cognito)
+  - Username/password authentication
+  - JWT token-based authentication
+  - Environment variable support for secrets (``${ENV:SECRET_NAME}``)
+- **NEW**: Enhanced ``sup config auth`` command with dual-path setup
+  - Interactive setup guides users through Preset or self-hosted configuration
+  - Multiple auth method selection for self-hosted instances
+  - Credential testing before saving to config
+  - Clear error messages and helpful guidance
+- **IMPROVED**: Graceful degradation for missing Preset credentials
+  - Workspace commands show helpful guidance suggesting Preset setup or self-hosted alternative
+  - Clear actionable error messages instead of cryptic auth failures
 - **BREAKING**: Package renamed from ``preset-cli`` to ``superset-sup`` for PyPI publication
 - All three CLIs now ship together: ``sup`` (modern, recommended), ``preset-cli`` (legacy), and ``superset-cli`` (legacy)
-- Added comprehensive beta/experimental release documentation for Preset customers
-- Enhanced README with migration guide from legacy CLIs to modern ``sup`` CLI
+- Enhanced README with self-hosted quick start and dual-path workflow examples
+- Comprehensive self-hosted setup guide with provider-specific examples and troubleshooting
 - Added PUBLISHING.md with detailed PyPI publication instructions
 
 Version 0.3.7 - 2025-07-24

diff --git a/README.md b/README.md
@@ -215,27 +215,143 @@ Efficient search across all entity types:
 
 ## 🏠 Superset Compatibility
 
-### Primary Focus: Preset-Hosted Instances
+### 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.
 
-### 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
+```bash
+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
+
+```bash
+# 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`:
+
+```yaml
+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:
+```bash
+export SUPERSET_OAUTH_SECRET="your-client-secret"
+export SUPERSET_SERVICE_PASSWORD="your-service-password"
+```
+
+#### Dual-Path Workflows
+
+Switch between Preset and self-hosted seamlessly:
+
+```bash
+# 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:
+```yaml
+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:
+```bash
+$ 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:
+```yaml
+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:
+```yaml
+auth_method: username_password
+username: admin
+password: ${ENV:SUPERSET_PASSWORD}
+```
+
+**JWT Token** - Pre-generated tokens:
+```yaml
+auth_method: jwt
+jwt_token: eyJhbGc...
+```
+
+#### Complete Setup Guides
+- **[Self-Hosted Setup Guide](docs/self_hosted_setup.rst)** - Step-by-step OAuth2/OIDC configuration
+- **[Provider Examples](docs/self_hosted_setup.rst#oauth2-oidc-setup)** - Keycloak, Okta, Auth0, Azure AD, Cognito
+- **[Troubleshooting](docs/self_hosted_setup.rst#troubleshooting)** - Common issues and solutions
+- **[Security Best Practices](docs/self_hosted_setup.rst#security-best-practices)** - Credential management
 
 ## 🔐 Authentication
 

diff --git a/docs/authentication.rst b/docs/authentication.rst
@@ -0,0 +1,176 @@
+Authentication
+==============
+
+sup supports multiple authentication methods for Preset and self-hosted Superset instances.
+
+Preset Workspaces
+-----------------
+
+API Token (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Use API token and secret from Preset workspace settings:
+
+.. code-block:: bash
+
+   export SUP_PRESET_API_TOKEN="your-token"
+   export SUP_PRESET_API_SECRET="your-secret"
+
+Or configure in ``~/.sup/config.yml``:
+
+.. code-block:: yaml
+
+   preset:
+     api_token: ${ENV:PRESET_API_TOKEN}
+     api_secret: ${ENV:PRESET_API_SECRET}
+
+Self-Hosted Superset
+--------------------
+
+Configure instances in ``~/.sup/config.yml`` under ``superset_instances``.
+
+Interactive OAuth (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For interactive use with zero configuration - browser-based authentication with PKCE:
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       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
+       oauth_scope: "openid profile email"
+
+**No secrets needed!** Tokens are cached in ``~/.sup/tokens/`` after first authentication.
+
+First run:
+
+.. code-block:: bash
+
+   $ sup dataset list
+   🔐 Opening browser for authentication...
+   ⏳ Waiting for you to complete authentication in browser...
+   ✓ Authentication successful!
+   [Shows datasets]
+
+Subsequent runs use cached tokens:
+
+.. code-block:: bash
+
+   $ sup chart list
+   [Uses cached token - instant, no browser!]
+
+Token features:
+
+- **Zero configuration**: No secrets to manage
+- **Automatic refresh**: Tokens refreshed automatically when expired
+- **Secure storage**: Cached with 0600 permissions in ``~/.sup/tokens/``
+- **Per-instance**: Separate cache for each Superset instance
+- **PKCE flow**: Industry-standard secure authentication without client secrets
+
+OAuth2 with Service Account
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For automation, CI/CD, and service accounts (requires client secret):
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: oauth
+       oauth_token_url: https://auth.example.com/oauth2/token
+       oauth_client_id: superset-service
+       oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
+       oauth_username: superset-service
+       oauth_password: ${ENV:SUPERSET_SERVICE_PASSWORD}
+       oauth_scope: "openid profile email"
+
+Set environment variables:
+
+.. code-block:: bash
+
+   export SUPERSET_OAUTH_SECRET="your-client-secret"
+   export SUPERSET_SERVICE_PASSWORD="your-service-password"
+
+Benefits:
+
+- Centralized identity management
+- Automatic token refresh with 5-minute safety buffer
+- No passwords in config files
+- Works with service accounts
+
+Username/Password
+~~~~~~~~~~~~~~~~~
+
+For instances with built-in Superset authentication:
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: username_password
+       username: superset-service
+       password: ${ENV:SUPERSET_PASSWORD}
+
+JWT Token
+~~~~~~~~~
+
+For pre-generated JWT tokens:
+
+.. code-block:: yaml
+
+   superset_instances:
+     production:
+       url: https://superset.example.com
+       auth_method: jwt
+       jwt_token: ${ENV:SUPERSET_JWT_TOKEN}
+
+Security Best Practices
+-----------------------
+
+1. **Use environment variables for secrets**
+
+   .. code-block:: yaml
+
+      oauth_client_secret: ${ENV:SUPERSET_OAUTH_SECRET}
+      password: ${ENV:SUPERSET_PASSWORD}
+
+2. **Protect config files**
+
+   .. code-block:: bash
+
+      chmod 600 ~/.sup/config.yml
+
+3. **Create dedicated service accounts** (not personal user accounts)
+
+   - Limit permissions to required scope
+   - Use strong, unique passwords
+
+4. **Never commit secrets to git**
+
+   - Add ``.env`` files to ``.gitignore``
+   - Use secrets management in CI/CD
+
+5. **Rotate credentials regularly**
+
+   - Change client secrets in OIDC provider
+   - Update passwords periodically
+
+Provider-Specific Setup
+-----------------------
+
+See :doc:`self_hosted_setup` for step-by-step instructions for:
+
+- Keycloak
+- Okta
+- Auth0
+- Azure AD
+- Amazon Cognito
+
+Includes configuration examples, troubleshooting, and detailed security guidance.