Quick Supabase Operator

Perform routine Supabase project operations including status checks, service restarts, configuration updates, and log inspection.

When to Use This Command

Run this command when you need to:

• Check the health and status of your Supabase project services (database, auth, storage, realtime)
• Restart individual Supabase services or update project configuration settings
• Stream and filter Supabase service logs for troubleshooting production issues

Consider alternatives when:

• You need to write SQL queries or manage data (use smart-supabase-tool)
• You need to create or apply database migrations (use supabase-migration-assistant-launcher)

Quick Start

Configuration

Copy
name: quick-supabase-operator
type: command
category: database

Example Invocation

Copy
claude command:run quick-supabase-operator --action status --project myapp-prod

Example Output

[Project] myapp-prod | Region: us-east-1 | Plan: Pro

[Services Status]
  Database:   HEALTHY  | CPU: 12% | Memory: 340MB/1GB | Connections: 24/100
  Auth:       HEALTHY  | Active sessions: 1,842
  Storage:    HEALTHY  | Used: 2.1 GB / 8 GB
  Realtime:   HEALTHY  | Active channels: 38 | Subscribers: 156
  Edge Funcs: HEALTHY  | Deployed: 7 functions

[Recent Alerts] None in last 24h
[Uptime] 99.97% (last 30 days)

Core Concepts

Supabase Operations Overview

Aspect	Details
Services	Database (Postgres), Auth (GoTrue), Storage, Realtime, Edge Functions
Actions	Status, restart, logs, config update, connection pooling management
Monitoring	CPU, memory, connection count, storage usage, request rates
Access	Via Supabase Management API with service role or management tokens

Operations Workflow

[Authenticate with Project]
          |
[Select Operation]
  /    |     |      \
Status Restart Logs  Config
  |    |     |      |
[Execute Operation]
          |
[Display Results + Recommendations]

Configuration

Parameter	Type	Default	Description
action	string	status	Operation: status, restart, logs, config, or connections
project	string	auto	Supabase project reference (auto-detected from .env)
service	string	all	Target service: database, auth, storage, realtime, or all
log-lines	number	50	Number of log lines to retrieve for the logs action
follow	boolean	false	Stream logs continuously (like tail -f)

Best Practices

1. Check Status Before Deployments - Invoke --action status before deploying application updates. Deploying against an unhealthy database or near-capacity storage can compound issues.

2. Restart Services Individually - When troubleshooting, restart one service at a time with --service database rather than restarting everything. This isolates which service recovery resolves the issue.

3. Filter Logs by Service - Production logs are noisy. Use --service auth to focus on authentication logs only, or pipe output through grep for specific error patterns.

4. Monitor Connection Pooling - Use --action connections regularly to check pool utilization. Exhausted connection pools cause cascading failures that are difficult to diagnose from application logs alone.

5. Automate Health Checks - Schedule this command via cron to run --action status every 5 minutes and alert on degraded services. Proactive monitoring prevents user-reported outages.

Common Issues

1. Management API Token Expired - The Supabase management API requires a valid access token. Refresh it from the Supabase dashboard under Project Settings > API and update your environment variable.

2. Restart Does Not Fix the Issue - If a service remains unhealthy after restart, check logs for the root cause. Common culprits include exhausted disk space, connection limits, or corrupted extensions.

3. Log Output Truncated - Default log retrieval is capped at 50 lines. Increase with --log-lines 500 or use --follow for continuous streaming to capture intermittent errors.