kctl-supa 0.6.3__tar.gz

kctl_supa-0.6.3/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_supa-0.6.3/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: kctl-supa
+Version: 0.6.3
+Summary: Kodemeio Supabase CLI — manage self-hosted Supabase instances
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: kctl-lib>=0.8.0
+Requires-Dist: paramiko<4.0.0,>=3.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: sshtunnel>=0.4.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_supa-0.6.3/README.md

@@ -0,0 +1,79 @@
+# kctl-supa
+
+kctl-supa — Kodemeio Supabase CLI for managing self-hosted Supabase instances.
+
+## Installation
+
+```bash
+uv pip install -e packages/kctl-supa
+```
+
+## Quick Start
+
+```bash
+# Add a profile
+kctl-supa config add terakidz \
+  --url https://supa.terakidz.com \
+  --service-role-key <key> \
+  --ssh-host 49.13.14.79 \
+  --container-prefix terakidz-supabase-prod
+
+# Set as default
+kctl-supa config use terakidz
+
+# Check health
+kctl-supa health check
+
+# Dashboard overview
+kctl-supa dashboard show
+```
+
+## Command Reference
+
+| Group | Panel | Description |
+|-------|-------|-------------|
+| config | Admin & Config | Profile management |
+| security | Admin & Config | RLS policies, JWT inspection, API keys |
+| doctor | Admin & Config | Diagnostic checks |
+| health | Services | Service health checks |
+| status | Services | Container status |
+| dashboard | Services | Overview dashboard |
+| monitor | Services | Performance monitoring |
+| db | Database | Database operations |
+| backup | Database | Backup management |
+| maintenance | Database | Vacuum, reindex, analyze |
+| migrate | Database | SQL migrations |
+| auth | Auth & Users | User management |
+| storage | Storage & Files | Bucket operations |
+| realtime | Realtime & Functions | Realtime status |
+| functions | Realtime & Functions | Edge functions |
+| logs | Operations | Log tailing/search |
+| deploy | Operations | Stack deployment |
+
+## Config Format
+
+```yaml
+# ~/.config/kodemeio/config.yaml
+profiles:
+  terakidz:
+    supabase:
+      url: https://supa.terakidz.com
+      service_role_key: <key>
+      anon_key: <key>
+      db_password: <pass>
+      ssh_host: 49.13.14.79
+      ssh_user: root
+      ssh_key: ~/.ssh/id_ed25519
+      container_prefix: terakidz-supabase-prod
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KCTL_SUPA_URL` | Supabase instance URL |
+| `KCTL_SUPA_SERVICE_ROLE_KEY` | Service role JWT key |
+| `KCTL_SUPA_ANON_KEY` | Anonymous JWT key |
+| `KCTL_SUPA_SSH_HOST` | SSH host for container access |
+| `KCTL_SUPA_CONTAINER_PREFIX` | Docker container name prefix |
+| `KCTL_SUPA_PROFILE` | Active config profile name |

kctl_supa-0.6.3/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-supa"
+version = "0.6.3"
+description = "Kodemeio Supabase CLI — manage self-hosted Supabase instances"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.8.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.27.0",
+    "paramiko>=3.4.0,<4.0.0",
+    "sshtunnel>=0.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-supa = "kctl_supa.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_supa"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_supa-0.6.3/skills/supa-admin/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: supa-admin
+description: >
+  Self-hosted Supabase administration via kctl-supa CLI (22 groups, ~50+ commands).
+  MUST use for ANY kctl-supa operation.
+  Triggers on: "advisors", "auth", "backup", "config", "cron", "dashboard", "db", "deploy",
+  "doctor", "functions", "health", "integrations", "kctl-supa", "logs", "maintenance",
+  "migrate", "monitor", "profile", "publications", "queues", "realtime", "security",
+  "settings", "status", "storage", "supabase", "upgrade", "vault".
+  Auto-generated: 2026-05-03
+---
+
+# supa-admin -- kctl-supa CLI Reference
+
+> Auto-generated from `kctl-supa` command registry. Do not edit manually.
+> To regenerate: `kctl-supa skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-supa`
+**Command groups:** 22
+**Total commands:** ~50+
+**Install:** `cd packages/kctl-supa && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON |
+| `--quiet`, `-q` | Suppress info messages |
+| `--profile`, `-p` | Config profile name |
+| `--url` | Supabase URL override |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### Admin & Config
+
+#### `kctl-supa config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config init` | Initialize CLI configuration. |
+| `config show` | Show configuration (keys masked). |
+| `config add` | Add a new profile. |
+| `config use` | Switch default profile. |
+| `config remove` | Remove a profile. |
+
+#### `kctl-supa security`
+
+Security audit and management for the Supabase instance.
+
+#### `kctl-supa doctor`
+
+Run diagnostic checks (API connectivity, auth, config).
+
+#### `kctl-supa vault`
+
+Supabase Vault secret management.
+
+#### `kctl-supa integrations`
+
+Manage third-party integrations.
+
+#### `kctl-supa settings`
+
+View and update Supabase instance settings.
+
+### Services
+
+#### `kctl-supa health`
+
+Health checks for the Supabase instance.
+
+#### `kctl-supa status`
+
+Quick status overview of all Supabase services.
+
+#### `kctl-supa dashboard`
+
+Dashboard overview with key metrics.
+
+#### `kctl-supa monitor`
+
+Continuous monitoring and alerting.
+
+#### `kctl-supa advisors`
+
+Performance advisors and recommendations.
+
+### Database
+
+#### `kctl-supa db`
+
+Core database operations (query, schemas, tables, extensions).
+
+#### `kctl-supa backup`
+
+Database backup and restore operations.
+
+#### `kctl-supa maintenance`
+
+Database maintenance tasks (vacuum, reindex, analyze).
+
+#### `kctl-supa migrate`
+
+Database migration management.
+
+#### `kctl-supa cron`
+
+Cron job scheduling (pg_cron).
+
+#### `kctl-supa queues`
+
+Database queue management (pgmq).
+
+### Auth & Users
+
+#### `kctl-supa auth`
+
+Authentication user management (list, create, ban, invite).
+
+### Storage & Files
+
+#### `kctl-supa storage`
+
+Storage bucket and file management.
+
+### Realtime & Functions
+
+#### `kctl-supa realtime`
+
+Realtime channel and subscription management.
+
+#### `kctl-supa functions`
+
+Edge Function deployment and management.
+
+#### `kctl-supa publications`
+
+Postgres logical replication publications.
+
+### Operations
+
+#### `kctl-supa logs`
+
+View and stream service logs.
+
+#### `kctl-supa deploy`
+
+Deployment operations (compose up/down, config push).
+
+#### `kctl-supa upgrade`
+
+Version upgrade management.
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-supa config init       # Interactive setup
+kctl-supa config show       # Show current config
+kctl-supa doctor run        # Full diagnostics
+kctl-supa self-update       # Check for updates
+kctl-supa completions zsh --install  # Install shell completions
+```
+
+**Examples:**
+```bash
+# Check Supabase health
+kctl-supa health check -p kodemeio
+
+# View service status overview
+kctl-supa status overview -p kodemeio
+
+# List auth users
+kctl-supa auth list -p kodemeio
+
+# Create a database backup
+kctl-supa backup create -p kodemeio
+
+# Run database maintenance
+kctl-supa maintenance vacuum -p kodemeio
+
+# List storage buckets
+kctl-supa storage list -p kodemeio
+
+# Deploy edge functions
+kctl-supa functions deploy -p kodemeio
+
+# View logs and manage cron jobs
+kctl-supa logs tail -p kodemeio
+kctl-supa cron list -p kodemeio
+```

kctl_supa-0.6.3/src/kctl_supa/__init__.py

@@ -0,0 +1,3 @@
+"""Kodemeio Supabase CLI."""
+
+__version__ = "0.6.3"

kctl_supa-0.6.3/src/kctl_supa/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_supa."""
+
+from kctl_supa.cli import _run
+
+_run()

kctl_supa-0.6.3/src/kctl_supa/cli.py

@@ -0,0 +1,169 @@
+"""Main CLI entry point for kctl-supa."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import handle_cli_error
+
+from kctl_supa import __version__
+from kctl_supa.commands.advisors_cmd import app as advisors_app
+from kctl_supa.commands.auth_cmd import app as auth_app
+from kctl_supa.commands.backup_cmd import app as backup_app
+from kctl_supa.commands.config_cmd import app as config_app
+from kctl_supa.commands.cron_cmd import app as cron_app
+from kctl_supa.commands.dashboard_cmd import app as dashboard_app
+from kctl_supa.commands.db_cmd import app as db_app
+from kctl_supa.commands.deploy_cmd import app as deploy_app
+from kctl_supa.commands.doctor_cmd import app as doctor_app
+from kctl_supa.commands.functions_cmd import app as functions_app
+from kctl_supa.commands.health_cmd import app as health_app
+from kctl_supa.commands.integrations_cmd import app as integrations_app
+from kctl_supa.commands.logs_cmd import app as logs_app
+from kctl_supa.commands.maintenance_cmd import app as maintenance_app
+from kctl_supa.commands.migrate_cmd import app as migrate_app
+from kctl_supa.commands.monitor_cmd import app as monitor_app
+from kctl_supa.commands.publications_cmd import app as publications_app
+from kctl_supa.commands.queues_cmd import app as queues_app
+from kctl_supa.commands.realtime_cmd import app as realtime_app
+from kctl_supa.commands.security_cmd import app as security_app
+from kctl_supa.commands.settings_cmd import app as settings_app
+from kctl_supa.commands.skill_cmd import app as skill_app
+from kctl_supa.commands.status_cmd import app as status_app
+from kctl_supa.commands.storage_cmd import app as storage_app
+from kctl_supa.commands.upgrade_cmd import app as upgrade_app
+from kctl_supa.commands.vault_cmd import app as vault_app
+from kctl_supa.core.callbacks import AppContext
+from kctl_supa.core.exceptions import SupabaseError
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-supa {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-supa",
+    help="Kodemeio Supabase CLI - manage self-hosted Supabase instances.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="Supabase URL override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Supabase CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        url_override=url,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-supa", __version__)
+
+
+_P_ADMIN = "Admin & Config"
+app.add_typer(config_app, name="config", rich_help_panel=_P_ADMIN)
+app.add_typer(security_app, name="security", rich_help_panel=_P_ADMIN)
+app.add_typer(doctor_app, name="doctor", rich_help_panel=_P_ADMIN)
+app.add_typer(vault_app, name="vault", rich_help_panel=_P_ADMIN)
+app.add_typer(integrations_app, name="integrations", rich_help_panel=_P_ADMIN)
+app.add_typer(settings_app, name="settings", rich_help_panel=_P_ADMIN)
+
+_P_SERVICES = "Services"
+app.add_typer(health_app, name="health", rich_help_panel=_P_SERVICES)
+app.add_typer(status_app, name="status", rich_help_panel=_P_SERVICES)
+app.add_typer(dashboard_app, name="dashboard", rich_help_panel=_P_SERVICES)
+app.add_typer(monitor_app, name="monitor", rich_help_panel=_P_SERVICES)
+app.add_typer(advisors_app, name="advisors", rich_help_panel=_P_SERVICES)
+
+_P_DATABASE = "Database"
+app.add_typer(db_app, name="db", rich_help_panel=_P_DATABASE)
+app.add_typer(backup_app, name="backup", rich_help_panel=_P_DATABASE)
+app.add_typer(maintenance_app, name="maintenance", rich_help_panel=_P_DATABASE)
+app.add_typer(migrate_app, name="migrate", rich_help_panel=_P_DATABASE)
+app.add_typer(cron_app, name="cron", rich_help_panel=_P_DATABASE)
+app.add_typer(queues_app, name="queues", rich_help_panel=_P_DATABASE)
+
+_P_AUTH = "Auth & Users"
+app.add_typer(auth_app, name="auth", rich_help_panel=_P_AUTH)
+
+_P_STORAGE = "Storage & Files"
+app.add_typer(storage_app, name="storage", rich_help_panel=_P_STORAGE)
+
+_P_RT = "Realtime & Functions"
+app.add_typer(realtime_app, name="realtime", rich_help_panel=_P_RT)
+app.add_typer(functions_app, name="functions", rich_help_panel=_P_RT)
+app.add_typer(publications_app, name="publications", rich_help_panel=_P_RT)
+
+_P_OPS = "Operations"
+app.add_typer(logs_app, name="logs", rich_help_panel=_P_OPS)
+app.add_typer(deploy_app, name="deploy", rich_help_panel=_P_OPS)
+app.add_typer(upgrade_app, name="upgrade", rich_help_panel=_P_OPS)
+
+app.add_typer(skill_app, name="skill", hidden=True)
+add_tui_command(app, service_key="supa", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-supa."""
+    actx = ctx.obj
+    out = actx.output
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-supa", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-supa")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-supa", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-supa", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except SupabaseError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_supa-0.6.3/src/kctl_supa/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for kctl-supa."""