Smart Supabase Tool

Execute common Supabase operations with intelligent context detection, including table queries, RPC calls, and storage management.

When to Use This Command

Run this command when you need to:

• Run ad-hoc SQL queries or RPC function calls against your Supabase database from the terminal
• Manage Supabase Storage buckets, upload files, or generate signed URLs quickly
• Inspect table schemas, row counts, and index statistics without opening the Supabase dashboard

Consider alternatives when:

• You need to create or manage database migrations (use supabase-migration-assistant-launcher)
• You need to audit security policies and RLS rules (use efficient-supabase-security-audit)

Quick Start

Configuration

Copy
name: smart-supabase-tool
type: command
category: database

Example Invocation

Copy
claude command:run smart-supabase-tool --query "SELECT * FROM users WHERE created_at > now() - interval '7 days'" --project myapp

Example Output

[Connect] Project: myapp | Region: us-east-1
[Detect] Query type: SELECT (read-only)
[Execute] Running query...

| id   | email                | created_at          | plan    |
|------|----------------------|---------------------|---------|
| 1042 | [email protected]    | 2026-03-10 14:22:01 | pro     |
| 1043 | [email protected]      | 2026-03-11 09:15:33 | free    |
| 1044 | [email protected]    | 2026-03-14 18:40:12 | pro     |

[Result] 3 rows returned in 42ms

Core Concepts

Supabase Tool Overview

Aspect	Details
Operations	SQL queries, RPC calls, storage CRUD, schema introspection
Context Detection	Auto-identifies query type (read/write) and applies safety checks
Auth	Uses Supabase service role key for full access or anon key for RLS testing
Output Formats	Table, JSON, CSV, or piped to file

Operation Workflow

[Parse Command + Detect Operation Type]
            |
[Load Project Credentials]
            |
[Safety Check] --> Write? --> Confirm?
            |
[Execute via Supabase Client/REST API]
            |
[Format + Display Results]

Configuration

Parameter	Type	Default	Description
query	string	none	SQL query or RPC function call to execute
project	string	auto	Supabase project reference (auto-detected from .env)
role	string	service	Auth role: service (full access) or anon (RLS enforced)
format	string	table	Output format: table, json, or csv
confirm-writes	boolean	true	Require confirmation before executing INSERT, UPDATE, DELETE

Best Practices

1. Use Anon Role for RLS Testing - Switch to --role anon to test that your Row Level Security policies work correctly from the client perspective. Service role bypasses all RLS.

2. Always Preview Destructive Queries - Keep --confirm-writes enabled. The command will show a dry-run of affected rows before executing any INSERT, UPDATE, or DELETE statement.

3. Pipe Large Results to Files - For queries returning hundreds of rows, redirect output with --format csv > output.csv to avoid terminal flooding and enable further analysis in spreadsheets.

4. Auto-Detect Project from .env - Place your SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in a .env file. The command reads these automatically, eliminating the need to specify --project each time.

5. Use RPC for Complex Operations - Prefer Supabase RPC function calls over raw SQL for multi-step operations. RPC functions run inside a transaction and benefit from server-side error handling.

Common Issues

1. Permission Denied with Anon Key - RLS policies are blocking the query. This is expected behavior. Switch to --role service for admin access, or verify your RLS policies grant the needed permissions.

2. Connection Refused on localhost - Ensure your Supabase local dev instance is running with supabase start. The command tries the URL from .env, which may point to a stopped local instance.

3. Query Timeout on Large Tables - Add LIMIT clauses to queries on large tables. Full table scans without limits can exceed Supabase's default statement timeout of 8 seconds.