███████╗██╗   ██╗██████╗  █████╗ ██████╗  █████╗ ███████╗███████╗     ██████╗██╗     ██╗
██╔════╝██║   ██║██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔════╝    ██╔════╝██║     ██║
███████╗██║   ██║██████╔╝███████║██████╔╝███████║███████╗█████╗      ██║     ██║     ██║
╚════██║██║   ██║██╔═══╝ ██╔══██║██╔══██╗██╔══██║╚════██║██╔══╝      ██║     ██║     ██║
███████║╚██████╔╝██║     ██║  ██║██████╔╝██║  ██║███████║███████╗    ╚██████╗███████╗██║
╚══════╝ ╚═════╝ ╚═╝     ╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝     ╚═════╝╚══════╝╚═╝

Production-ready Supabase Management API CLI built for AI agents, automation, and developers. Built with oclif, TypeScript, and enterprise patterns for reliability, performance, and maintainability.

---

Unofficial CLI - Important Notice

This CLI is NOT affiliated with or endorsed by Supabase.

This is an independent, community-built CLI for the Supabase Management API. For the official Supabase CLI, visit:

• Official CLI: https://github.com/supabase/cli
• Official Documentation: https://supabase.com/docs/guides/cli
• Supabase Support: https://supabase.com/support

If you need official support or are working on production systems, we recommend using the official Supabase CLI. This CLI is provided as-is for developers who need Management API access from the command line.

---

Features

• 28 Working Commands across 6 major categories
• Interactive REPL Mode with context management, command history, and autocomplete
• SQL-Based Operations for database metadata (14 pre-built queries)
• Watch Mode for real-time monitoring (auto-refresh commands at configurable intervals)
• Batch Operations for running multiple commands in parallel with progress tracking
• Production-Ready Infrastructure
  • LRU cache with TTL support
  • Request deduplication for concurrent operations
  • Exponential backoff retry logic
  • Circuit breaker pattern for fault tolerance
  • Cascading cache invalidation
  • Comprehensive error handling
• Beautiful CLI Output
  • Color-coded status indicators
  • Progress bars for batch operations
  • Spinners for async operations
  • Formatted tables with cli-table3
  • JSON, Table, YAML output formats
  • Size formatting (bytes to GB/MB)
  • Policy enforcement badges
• Developer Experience
  • TypeScript strict mode
  • 98.1% test coverage (262/267 tests passing)
  • Comprehensive error messages
  • Interactive prompts with CI/CD fallback
  • Extensive debugging capabilities
  • Shell autocomplete for bash, zsh, and fish

Installation

npm install -g @coastal-programs/supabase-cli

Or use with npx:

npx @coastal-programs/supabase-cli
n### Autocomplete not working

If autocomplete isn't working after setup:

1. **Verify installation**: Run `supabase-cli autocomplete bash` (or your shell)
2. **Refresh cache**: Run `supabase-cli autocomplete --refresh-cache`
3. **Restart shell**: Close and reopen your terminal
4. **Check shell config**: Ensure the autocomplete script was added to your shell config file

Security Considerations

Please read this section carefully before using this CLI. For complete security documentation, see SECURITY.md.

Credential Storage

This CLI uses a three-tier credential storage system:

1. OS Keychain (Default - Most Secure)

Credentials are stored using your operating system's native secure storage:

• macOS: macOS Keychain (viewable in Keychain Access app)
• Windows: Windows Credential Manager
• Linux: libsecret (requires libsecret-1-dev or gnome-keyring)

This is the most secure option and is used automatically when available.

2. Encrypted File Fallback (Requires Consent)

If OS keychain is unavailable, an encrypted file fallback is used:

• Location: ~/.supabase/credentials.enc
• Encryption: AES-256-GCM with PBKDF2 key derivation (100,000 iterations)
• Permissions: 0600 (owner read/write only)
• Machine-specific: Uses hostname and username for key derivation
• Requires consent: CLI will ask for permission before first use

Important: Encrypted file credentials cannot be decrypted on a different machine and will be lost if hostname/username changes.

To explicitly consent to encrypted file storage:

export SUPABASE_CLI_ACCEPT_ENCRYPTED_FALLBACK="true"

3. Environment Variables (CI/CD Only)

For automated environments and CI/CD pipelines:

export SUPABASE_ACCESS_TOKEN="sbp_your_token_here"
export SUPABASE_CLI_ACCEPT_ENCRYPTED_FALLBACK="true"  # For CI/CD

Warning: Environment variables are the least secure option. Only use in controlled CI/CD environments.

Destructive Operations

The following commands can cause irreversible data loss and require explicit confirmation:

• backup:delete - Permanently deletes backups
• backup:restore - Overwrites current database with backup
• backup:pitr:restore - Point-in-time recovery (overwrites data)
• projects:delete - Permanently deletes entire project
• db:replicas:delete - Deletes read replica
• security:restrictions:remove - Removes network security rules
• storage:buckets:delete - Deletes storage bucket

Confirmation Prompts: All destructive operations require interactive confirmation unless you use the --yes flag.

CI/CD Usage: Use --yes flag to bypass prompts in automated environments:

supabase-cli backup:create --yes

Best Practice: Always verify the command output before confirming destructive operations.

Service Role Keys

Some operations may require service role keys, which bypass Row Level Security (RLS) and have full database access:

• What they are: Administrative keys with unrestricted database access
• Storage: Stored in OS keychain by default (encrypted file fallback requires consent)
• User consent: CLI will always ask before storing service role keys
• Rotation: Rotate regularly in Supabase dashboard (every 90 days recommended)
• Never commit: Never commit service role keys to version control

To revoke stored credentials:

supabase-cli auth:logout
# or delete the credentials directory
rm -rf ~/.supabase

CI/CD Usage

For automated deployments and CI/CD pipelines:

1. Use GitHub Secrets or equivalent:

# GitHub Actions example
env:
  SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
  SUPABASE_CLI_ACCEPT_ENCRYPTED_FALLBACK: "true"

2. Use --yes flag to bypass prompts:

supabase-cli backup:create --project my-ref --yes

3. Limit token permissions:

• Use project-specific tokens when possible
• Rotate CI/CD tokens more frequently (every 30 days)
• Monitor token usage via Supabase dashboard

4. Use --quiet flag for minimal output:

supabase-cli projects:list --quiet --format json

Security Best Practices

When using this CLI:

1. Never commit credentials to version control (add .supabase/ to .gitignore)
2. Keep the CLI updated to the latest version for security patches
3. Use strong access tokens with minimal required permissions
4. Enable 2FA on your Supabase account
5. Rotate access tokens regularly (every 90 days recommended)
6. Review command output before confirming destructive operations
7. Monitor access logs in the Supabase dashboard
8. Delete credentials when uninstalling: rm -rf ~/.supabase

For complete security documentation, vulnerability reporting, and security best practices, see SECURITY.md.

Quick Start

Easy Setup (Recommended):

# AI-assisted setup wizard (recommended for first-time users)
supabase-cli auth:setup

The setup wizard will:

• Guide you to get your Supabase token
• Optionally open your browser to the tokens page
• Validate your token
• Securely store it in your OS keychain

Manual Setup:

1. Set your Supabase access token:

export SUPABASE_ACCESS_TOKEN=sbp_your_token_here

Get your token from: https://supabase.com/dashboard/account/tokens

2. Initialize configuration:

supabase-cli config:init

3. List your projects:

supabase-cli projects:list

4. Query your database:

supabase-cli db:query "SELECT version()" --project your-project-ref

Interactive Mode (NEW!):

For faster, iterative development:

# Start interactive REPL
supabase-cli interactive

# Or start with project context
supabase-cli interactive --project your-project-ref

Interactive mode features:

• No need to type supabase-cli prefix
• Project context management (set once, use everywhere)
• Command history with arrow keys
• TAB autocomplete
• Built-in help and special commands

See docs/INTERACTIVE_MODE.md for complete documentation.

Shell Autocomplete

The CLI supports shell autocomplete for faster command entry in bash, zsh, and fish shells.

Quick Setup

Bash:

# Add autocomplete to your shell
printf "$(supabase-cli autocomplete:script bash)" >> ~/.bashrc
source ~/.bashrc

# Start using autocomplete
supabase-cli pro[TAB][TAB]        # Completes to "projects"
supabase-cli projects:[TAB][TAB]  # Shows: list, get, create, etc.
supabase-cli db:[TAB][TAB]        # Shows: query, info, schemas, etc.

Zsh:

# Add autocomplete to your shell
printf "$(supabase-cli autocomplete:script zsh)" >> ~/.zshrc
source ~/.zshrc

# Start using autocomplete
supabase-cli pro[TAB]        # Completes to "projects"
supabase-cli projects:[TAB]  # Shows: list, get, create, etc.

Fish:

# View setup instructions
supabase-cli autocomplete fish

# Follow the instructions to set up fish autocomplete

What Gets Autocompleted

• Command names: projects, db, functions, storage, backup, etc.
• Subcommands: projects:list, db:info, functions:deploy, etc.
• Flags: --project, --format, --recent, --debug, etc.
• Flag values: --format json|table|yaml|list

Interactive Instructions

For detailed setup instructions for your shell:

# View instructions for all shells
supabase-cli autocomplete

# View instructions for a specific shell
supabase-cli autocomplete bash
supabase-cli autocomplete zsh
supabase-cli autocomplete fish

Refreshing the Cache

If you've updated the CLI or added new commands, refresh the autocomplete cache:

supabase-cli autocomplete --refresh-cache

Limitations

• PowerShell: Not supported (PowerShell doesn't support colon-separated commands)
• Windows CMD: Not supported (use Git Bash or WSL instead)

Command Shortcuts

All commands support shortcuts for faster typing! Use shorter aliases to speed up your workflow.

Quick Examples

# Instead of full commands...
supabase-cli projects:list
supabase-cli db:query "SELECT 1"
supabase-cli functions:list

# ...use shortcuts!
supabase-cli pl              # projects:list
supabase-cli query "SELECT 1"  # db:query
supabase-cli fn:list           # functions:list

Popular Shortcuts

Full Command	Shortcuts	Description
projects:list	pl, projects:ls, proj:list	List all projects
projects:get	pg, proj:get	Get project details
db:query	query, db:sql	Execute SQL query
db:info	info, db:database-info	Database info
functions:list	fn:list, functions:ls	List functions
functions:deploy	fn:deploy, functions:push	Deploy function
config:init	init, configure	Initialize config
config:doctor	doctor, health	Health check
auth:setup	setup, auth:init	Setup wizard
recent	r, history	Recent projects

All Available Shortcuts

See docs/COMMAND_SHORTCUTS.md for a complete reference of all 100+ command shortcuts.

Create Your Own Shell Aliases

Make commands even shorter:

# Add to ~/.bashrc or ~/.zshrc
alias sb='supabase-cli'
alias sbl='supabase-cli projects:list'
alias sbq='supabase-cli db:query'

# Usage
sb pl              # projects:list
sbl               # projects:list
sbq "SELECT 1"    # db:query

Interactive Mode

Interactive mode provides a REPL (Read-Eval-Print Loop) interface for running commands without typing the supabase-cli prefix each time.

Starting Interactive Mode

# Start REPL
supabase-cli interactive

# Start with project context
supabase-cli interactive --project your-project-ref

Example Session

╔══════════════════════════════════════╗
║   Supabase CLI Interactive Mode      ║
╚══════════════════════════════════════╝

Type commands without 'supabase-cli' prefix
Special commands: help, clear, exit, history, .commands

> projects:list
[Shows projects in table format]

> use ygzhmowennlaehudyyey
Switched to project: ygzhmowennlaehudyyey

[my-project] > db:info
Database: PostgreSQL 15.1
Size: 142 MB
Tables: 8

[my-project] > functions:list
[Shows functions list]

[my-project] > exit
Goodbye!

Key Features

• No prefix needed: Type projects:list instead of supabase-cli projects:list
• Context management: Set project once with use <ref>, applies to all commands
• Command history: Arrow up/down to navigate, persistent across sessions
• TAB autocomplete: Auto-complete commands and flags
• Special commands: help, clear, history, .commands, .stats, etc.
• Error recovery: Errors don't exit REPL, fix and retry

Special Commands

Command	Description
help, ?	Show help message
clear, cls	Clear screen
exit, quit, q	Exit interactive mode
history	Show command history
.commands	List all available commands
.context	Show current context (project, etc.)
.stats	Show session statistics
use <project-ref>	Set project context
unuse	Clear project context

When to Use Interactive Mode

Use Interactive Mode for:

• Exploring a project interactively
• Running multiple commands on the same project
• Learning available commands
• Quick debugging and troubleshooting
• Ad-hoc queries and checks

Use Normal CLI for:

• Scripting and automation
• CI/CD pipelines
• Single command execution
• Cron jobs and scheduled tasks

Complete Documentation

See docs/INTERACTIVE_MODE.md for:

• Detailed usage guide
• All special commands
• Keyboard shortcuts
• Context management
• Tips and tricks
• Troubleshooting

Commands

Core Management (3)

• projects:list - List all Supabase projects
• projects:get <ref> - Get project details
• projects:restore <ref> - Restore a paused project

Organizations (2)

• organizations:list - List all organizations
• organizations:get <id> - Get organization details

Database (12)

• db:query <sql> - Execute SQL query
• db:extensions - List installed extensions
• db:schema - List all tables
• db:info - Database version, size, and settings
• db:schemas - List all schemas with owners
• db:policies - List RLS policies
• db:connections - Show active connections
• db:table-sizes - List tables sorted by size
• db:user-info - List database users and permissions
• db:config:get - Get database configuration
• db:config:set - Set database configuration
• db:webhooks:list - List database webhooks

Backups (1)

• backup:list - List all backups
• backup:pitr:restore - Point-in-time restore (requires PITR enabled)

Edge Functions (3)

• functions:list - List Edge Functions
• functions:invoke <name> - Invoke an Edge Function
• functions:deploy - Deploy an Edge Function

Branches (2)

• branches:list - List preview branches
• branches:create - Create a preview branch

Security (2)

Storage (4)

• storage:buckets:list - List storage buckets
• storage:buckets:get <id> - Get bucket details
• storage:buckets:create - Create a storage bucket
• storage:buckets:delete <id> - Delete a storage bucket

Storage Authentication Limitation

The storage commands use the Supabase Management API (PAT-based authentication), not the Storage API (service_role key-based). This means:

• Full bucket metadata (creation, deletion, public/private status) is supported
• File operations (upload, download, list files) are NOT supported
• Advanced RLS policies require using the Supabase SDK directly

For file operations and advanced storage management, use the Supabase SDK:

# Install the SDK
npm install @supabase/supabase-js

# Use it in your application
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(PROJECT_URL, SERVICE_ROLE_KEY)
await supabase.storage
  .from('bucket-name')
  .upload('path/to/file.txt', file)

See docs/STORAGE_AUTHENTICATION_LIMITATION.md for detailed technical information.

Configuration (6)

• config:init - Initialize CLI configuration
• config:doctor - Check configuration health
• config:auth:get - Get auth configuration
• config:ssl:get - Get SSL enforcement status
• config:api-keys - List API keys (masked)
• config:secrets:list - List project secrets

Monitoring (1)

• monitoring:readonly - Check if project is in read-only mode

Utilities (3)

• upgrade:check - Check Postgres upgrade eligibility
• types:generate - Generate TypeScript types from database schema
• interactive - Start interactive REPL mode

Migrations (3)

• migrations:list - List database migrations
• migrations:apply - Apply database migrations
• migrations:apply-batch - Apply multiple pending migrations with progress bar

Projects (3 additional)

• projects:create - Create a new project
• projects:pause - Pause a project
• projects:delete - Delete a project

Batch Operations (1)

• batch - Execute multiple CLI commands from a file in parallel

Usage Examples

Basic Operations

# List all projects
supabase-cli projects:list --format table

# Get project details
supabase-cli projects:get ygzhmowennlaehudyyey

# Execute SQL query
supabase-cli db:query "SELECT * FROM users LIMIT 10" --project my-project-ref

Interactive Mode

# Start interactive REPL
supabase-cli interactive

# In interactive mode:
> projects:list
> use ygzhmowennlaehudyyey
[my-project] > db:info
[my-project] > functions:list
[my-project] > .stats
[my-project] > exit

Database Management

# List installed extensions
supabase-cli db:extensions --project my-project-ref

# Check table sizes
supabase-cli db:table-sizes --project my-project-ref --format table

# List RLS policies
supabase-cli db:policies --project my-project-ref

# Get database info (version, size, settings)
supabase-cli db:info --project my-project-ref

# List active connections
supabase-cli db:connections --project my-project-ref

Batch Operations with Progress Bars

Progress bars provide visual feedback for long-running batch operations:

# Apply multiple pending migrations with progress tracking
supabase-cli migrations:apply-batch --project my-project-ref

# Apply up to 5 migrations with progress bar
supabase-cli migrations:apply-batch --project my-project-ref --limit 5

# Non-interactive batch operation (for CI/CD)
supabase-cli migrations:apply-batch --project my-project-ref --yes --quiet

Progress Bar Features:

• Real-time progress tracking (e.g., [████████░░] 80% | 4/5 | Applying migration...)
• Individual operation status (success/failure indicators)
• Automatic quiet mode support (disabled with --quiet)
• Error-resilient (stops gracefully on errors)

See docs/PROGRESS_INDICATORS.md for complete documentation on using progress bars vs spinners.

Batch Command Execution

Execute multiple CLI commands from a file in parallel - perfect for health checks, data collection, and automated testing:

# Execute commands from text file (simple format)
supabase-cli batch --file commands.txt

# Execute from JSON file with metadata
supabase-cli batch --file commands.json --parallel 10

# Dry run to preview commands
supabase-cli batch --file commands.txt --dry-run

# Continue on errors with result export
supabase-cli batch --file commands.txt --continue-on-error --output results.json

# Set timeout and parallel execution
supabase-cli batch --file commands.txt --timeout 60 --parallel 5

Batch Command Features:

• Parallel Execution: Run up to 20 commands concurrently
• Progress Tracking: Multi-progress bars showing status of each command
• Error Handling: Stop on first error or continue through all commands
• Timeout Support: Per-command or global timeouts
• Multiple Formats: Simple text or structured JSON
• Result Export: Save detailed results to JSON for analysis

Simple text format (commands.txt):

# One command per line
supabase-cli projects:list --format json
supabase-cli db:info --project my-project-ref
supabase-cli functions:list --project my-project-ref

JSON format (commands.json):

[
  {
    "command": "supabase-cli",
    "args": ["projects:list", "--format", "json"],
    "id": "list-projects",
    "timeout": 30
  },
  {
    "command": "supabase-cli",
    "args": ["db:info", "--project", "my-project-ref"],
    "id": "db-info",
    "timeout": 60
  }
]

Use Cases:

• Multi-Project Health Checks: Check status of multiple projects in parallel
• Data Collection: Gather data from multiple projects for reporting
• Automated Testing: Run test suites with progress tracking
• Monitoring Scripts: Periodic health checks with result logging
• Migration Verification: Verify migrations across multiple environments

See docs/BATCH_OPERATIONS.md for complete documentation including examples, best practices, and integration guides.

Watch Mode (Real-time Monitoring)

Watch mode auto-refreshes command output at configurable intervals. Perfect for monitoring during load tests, deployments, or debugging.

# Watch active database connections (refresh every 5 seconds - default)
supabase-cli db:connections --project my-project-ref --watch

# Watch with custom interval (refresh every 10 seconds)
supabase-cli db:connections --project my-project-ref --watch --interval 10

# Watch database info (refresh every 30 seconds)
supabase-cli db:info --project my-project-ref --watch --interval 30

# Watch projects list
supabase-cli projects:list --watch --interval 30

# Combine with table format for better readability
supabase-cli db:connections --project my-project-ref --watch --format table

Supported Commands: db:connections, db:info, projects:list

See docs/WATCH_MODE.md for complete documentation on watch mode features, use cases, and best practices.

Security & Monitoring

# Run security audit
supabase-cli monitoring:readonly --project my-project-ref

Storage & Functions

# List storage buckets
supabase-cli storage:buckets:list --project my-project-ref

# List Edge Functions
supabase-cli functions:list --project my-project-ref

# Invoke an Edge Function
supabase-cli functions:invoke my-function --project my-project-ref --data '{"key":"value"}'

Automation & CI/CD

# Non-interactive mode (for scripts)
supabase-cli backup:list --project my-project-ref --quiet --format json

# Generate TypeScript types for your database
supabase-cli types:generate --project my-project-ref > database.types.ts

# Check configuration health
supabase-cli config:doctor

# Run batch health check for multiple projects
supabase-cli batch --file health-check.json --parallel 10 --output results.json --quiet

Configuration

Credential Storage Locations

This CLI stores credentials securely using a three-tier system:

OS Keychain (Default)

Credentials are stored in your operating system's secure storage:

macOS:

• Storage: macOS Keychain
• View: Keychain Access app → Search for "supabase-cli"
• Delete: Open Keychain Access → Search "supabase-cli" → Delete items

Windows:

• Storage: Windows Credential Manager
• View: Control Panel → Credential Manager → Windows Credentials
• Delete: Credential Manager → Remove "supabase-cli" entries

Linux:

• Storage: libsecret / GNOME Keyring
• Requirements: libsecret-1-dev or gnome-keyring package
• View: Seahorse (GNOME Passwords and Keys) app
• Delete: Seahorse → Search "supabase-cli" → Delete items

Encrypted File Fallback

If OS keychain is unavailable:

• Location: ~/.supabase/credentials.enc
• Encryption: AES-256-GCM with PBKDF2 (100,000 iterations)
• Permissions: 0600 (owner read/write only)
• Delete: rm -rf ~/.supabase

Legacy Configuration File (Deprecated)

Old plaintext configuration (not used for credentials anymore):

• Location: ~/.supabase-cli/credentials.json
• Status: Deprecated (migrated to secure storage)
• Delete: rm -rf ~/.supabase-cli

Environment Variables

See .env.example for all available configuration options:

• SUPABASE_ACCESS_TOKEN - Your Supabase access token (required for CI/CD)
• SUPABASE_CLI_ACCEPT_ENCRYPTED_FALLBACK - Accept encrypted file fallback (default: false)
• CACHE_ENABLED - Enable/disable caching (default: true)
• CACHE_TTL - Cache TTL in milliseconds (default: 300000)
• RETRY_ENABLED - Enable/disable retry logic (default: true)
• RETRY_MAX_ATTEMPTS - Maximum retry attempts (default: 3)
• DEBUG - Enable debug logging (default: false)

Configuration Commands

Initialize configuration:

supabase-cli config:init

Check configuration health:

supabase-cli config:doctor

Delete all stored credentials:

supabase-cli auth:logout
# or manually delete the credentials directory
rm -rf ~/.supabase

View where credentials are stored:

supabase-cli config:doctor --verbose

Performance

• Startup Time: <1,700ms (optimized with lazy loading)
• Command Execution: <2s for most operations
• Memory Usage: <200MB peak
• Cache Hit Rate: >75% for cached operations
• Test Coverage: 98.1% (262/267 tests passing)

Troubleshooting

"Authentication failed"

Make sure your access token is set:

export SUPABASE_ACCESS_TOKEN=sbp_your_token_here

Get your token from: https://supabase.com/dashboard/account/tokens

"Project not found"

Verify the project reference is correct:

supabase-cli projects:list

Slow startup time

Run with built code instead of ts-node:

npm run build
supabase-cli --version  # Should be faster

Command not found

Make sure you installed globally:

npm install -g @coastal-programs/supabase-cli

Or use npx:

npx @coastal-programs/supabase-cli
n### Autocomplete not working

If autocomplete isn't working after setup:

1. **Verify installation**: Run `supabase-cli autocomplete bash` (or your shell)
2. **Refresh cache**: Run `supabase-cli autocomplete --refresh-cache`
3. **Restart shell**: Close and reopen your terminal
4. **Check shell config**: Ensure the autocomplete script was added to your shell config file

Need more help?

Check the user guides:

• Getting Started Guide
• Database Operations Guide
• Automation Guide
• Troubleshooting Guide

Documentation

• User Guides - Step-by-step guides
• Architecture Guide - System design
• API Reference - API documentation
• Developer Guide - For contributors
• Interactive Mode Guide - REPL mode documentation
• Watch Mode Guide - Real-time monitoring documentation
• Progress Indicators Guide - Using progress bars and spinners
• Batch Operations Guide - Multi-command execution with parallel processing
• Performance Reports
• Storage Authentication Limitation - Technical details on storage API limitations

Development

See CONTRIBUTING.md for contribution guidelines and CLAUDE.md for detailed development guide.

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

Architecture

This CLI follows enterprise patterns inspired by Notion CLI v5.7.0:

• Cache Layer: LRU cache with TTL support and cascading invalidation
• Retry Logic: Exponential backoff with circuit breaker
• Request Deduplication: Prevents duplicate concurrent API calls
• Response Envelopes: Consistent response format across all commands
• Base Command: Shared functionality for all commands
• Helper Utilities: Output formatting, validation, parsing
• Error Handling: Hierarchical error system with helpful messages

See docs/architecture.md for detailed architecture documentation.

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run performance tests
npm run test:performance

Contributing

See CONTRIBUTING.md for guidelines on:

• Development setup
• Code style
• Commit messages
• Pull request process
• Testing requirements

Security

This CLI takes security seriously. We use OS keychain storage, encrypted file fallback with AES-256-GCM, and require user consent for sensitive operations.

See SECURITY.md for complete information on:

• Security Policy: Supported versions and vulnerability response timeline
• Vulnerability Reporting: How to report security issues responsibly
• Credential Management: OS keychain, encrypted fallback, and CI/CD usage
• Destructive Operations: Commands that can cause data loss
• Service Role Keys: Storage and rotation best practices
• Security Best Practices: Comprehensive guidelines for users and developers
• Secure Coding Patterns: Examples for contributors

Quick Security Tips:

• Credentials stored in OS keychain by default (macOS Keychain, Windows Credential Manager, Linux libsecret)
• Encrypted file fallback requires explicit user consent
• All destructive operations require confirmation (bypass with --yes flag)
• Service role keys stored securely with user consent
• Delete credentials: rm -rf ~/.supabase or use OS-specific credential manager

To report a security vulnerability, please use GitHub Security Advisories or email security@coastal-programs.com.

License

MIT - see LICENSE file for details

Support

• Documentation: docs/
• User Guides: docs/guides/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Roadmap

• Sprint 1: Core infrastructure (cache, retry, errors) - COMPLETE
• Sprint 2: Authentication & configuration - COMPLETE
• Sprint 3: Project management commands - COMPLETE
• Sprint 4: Database management commands - COMPLETE
• Phase 4A: Cleanup & validation - COMPLETE
• Phase 4B: Performance optimization - COMPLETE
• Phase 4C: SQL expansion & GoTrue API - COMPLETE
• Phase 5: User documentation & guides - IN PROGRESS
• Interactive REPL mode - COMPLETE
• Future: Bulk operations, advanced command aliases

What's New in v0.1.0

• 28 production-ready commands across 6 categories
• Interactive REPL mode with context management and autocomplete
• SQL-based database metadata commands (14 pre-built queries)
• Request deduplication for concurrent operations
• Cascading cache invalidation
• Color-coded CLI output with status indicators
• Progress bars for batch operations with visual feedback
• Batch command execution with parallel processing
• Performance optimizations (22.7% startup improvement)
• Comprehensive error handling
• 40+ documentation files
• 98.1% test coverage
• Shell autocomplete for bash, zsh, and fish
• Watch mode for real-time monitoring

See CHANGELOG.md for full release notes.

Credits

Built by Coastal Programs

Architecture inspired by Notion CLI v5.7.0

Acknowledgments

• Supabase team for the Management API
• oclif framework for CLI infrastructure
• All contributors and testers