capysquash-cli COMMANDS

Complete guide to all capysquash-cli commands and workflows.

INSTALLATION CHECK

Before using capysquash, verify installation:

# Check version
capysquash --version

# Verify Docker is running
docker ps

GLOBAL FLAGS

Available for all commands:

CORE COMMANDS

analyze

Analyze migrations without making any modifications.

capysquash analyze [migration files or directory]

What it does:

• Parses SQL using PostgreSQL's actual parser (pg_query_go)
• Identifies consolidation opportunities
• Builds dependency graphs
• Tracks object lifecycles across migrations
• Generates detailed analysis report
• Auto-detects Supabase, Clerk, and other platform patterns

Basic Usage:

# Analyze all migrations in directory
capysquash analyze migrations/

# Analyze specific files
capysquash analyze migrations/*.sql

# With verbose output
capysquash analyze migrations/ --verbose

What You'll See:

The analysis shows:

• Total migrations found
• Consolidation opportunities identified
• Dependency graph complexity
• Platform patterns detected (Supabase, Clerk, etc.)
• Warnings about potential issues
• Estimated file reduction

squash

Process and optimize migrations with consolidation.

capysquash squash [migration files...] [flags]

What it does:

• Consolidates migrations based on safety level
• Removes redundant operations
• Optimizes SQL statements
• Validates schema equivalence (if configured)
• Generates organized output files

Key Flags:

Common Usage:

# Standard squash (recommended for most cases)
capysquash squash migrations/

# Conservative squash for production
capysquash squash migrations/ --safety=conservative

# Preview what will change
capysquash squash migrations/ --dry-run

# Custom output directory
capysquash squash migrations/ --output=clean/

Safety Levels:

• Paranoid: Maximum safety, requires database validation, 15-25% reduction
• Conservative: Production-ready, safe merges only, 20-35% reduction
• Standard: Balanced approach (recommended), 35-50% reduction
• Aggressive: Maximum cleanup for development, 50-70% reduction

Learn more about safety levels →

validate

Validate squashed migrations match original schema using Docker.

capysquash validate [original dir] [squashed dir]

What it does:

• Spins up Docker containers with PostgreSQL
• Applies original migrations to first container
• Applies squashed migrations to second container
• Compares schema dumps
• Reports any differences

This validates schema equivalence - Docker validation ensures your squashed migrations produce the same database schema as the originals.

Usage:

# Validate after squashing
capysquash validate migrations/ squashed/

# With verbose output
capysquash validate migrations/ squashed/ --verbose

How It Works:

1. Container 1: Apply original migrations → pg_dump --schema-only → original_schema.sql
2. Container 2: Apply squashed migrations → pg_dump --schema-only → squashed_schema.sql
3. Compare: diff original_schema.sql squashed_schema.sql
4. Result: ☑ Identical or ☒ Differences found

Learn more about Docker validation →

tui

Launch interactive Terminal UI for visual migration management.

# Launch TUI
capysquash tui [migrations-dir]

# Launch with specific view
capysquash tui analyze [migrations-dir]  # Go directly to analysis
capysquash tui config                     # Go directly to config wizard
capysquash tui deps [migrations-dir]      # Go directly to dependency graph

# Or add --tui to analyze/squash commands
capysquash analyze migrations/ --tui
capysquash squash migrations/ --tui

What it provides:

• Interactive Dashboard: Real-time stats and progress
• Analysis View: Live dependency graphs and optimization opportunities
• Config Wizard: Interactive configuration builder
• Dependency Viewer: Visual dependency graph with navigation
• Progress Tracking: Real-time squashing progress with throughput stats

Subcommands:

Navigation:

• Press ? for keyboard shortcuts
• Tab to switch between views
• Arrow keys to navigate
• Enter to select
• q to quit

TUI Views:

See complete TUI guide →

init-config

Generate default configuration file.

capysquash init-config [options]

Creates capysquash.config.json with documented options for:

• Safety levels
• Output formatting
• Rule configuration
• Performance tuning
• Platform integrations

Flags:

Example:

# Generate config
capysquash init-config

# Generate with custom name
capysquash init-config --config=custom.json

# Overwrite existing
capysquash init-config --force

# Then customize and use
capysquash squash migrations/ --config=capysquash.config.json

health

Health check for container orchestration and monitoring.

capysquash health [options]

What it does:

• Checks pgsquash-engine status
• Verifies Docker availability
• Reports system information
• Returns exit code 0 if healthy, 1 if not

Flags:

Usage:

# Basic health check (JSON)
capysquash health

# Plain text output
capysquash health --text

# Detailed system info
capysquash health --detailed

Example Output (JSON):

{
  "status": "healthy",
  "version": "0.9.7",
  "docker": true,
  "timestamp": "2025-10-21T04:42:00Z"
}

Use cases:

• Kubernetes liveness/readiness probes
• Docker HEALTHCHECK directive
• CI/CD pipeline validation
• Monitoring system integration

Example Docker Compose:

services:
  pgsquash:
    image: pgsquash:latest
    healthcheck:
      test: ["CMD", "pgsquash", "health"]
      interval: 30s
      timeout: 10s
      retries: 3

PRE-CONFIGURED WORKFLOWS

Shortcuts for common use cases.

safe

Production-ready workflow with maximum safety.

capysquash safe migrations/

What this does:

Equivalent to:

capysquash squash migrations/ \
  --safety=conservative \
  --validate

Best for:

• Production deployments
• First-time squashing
• Critical databases
• When you need proof

fast

Development-optimized squashing with minimal validation.

capysquash fast migrations/*.sql

analyze-deep

Comprehensive analysis with AI insights.

capysquash analyze-deep migrations/

Requires: AI provider configured (ANTHROPIC_API_KEY or OPENAI_API_KEY)

Provides:

• Full dependency graph analysis
• AI-powered semantic analysis
• Dead code detection
• Function complexity scoring
• Authentication pattern detection (Supabase, Clerk, Auth0)
• Optimization suggestions
• Risk assessment

NO file modifications - analysis only.

WORKFLOW EXAMPLES

First-Time Squashing

# 1. Analyze first to see what will happen
capysquash analyze migrations/

# 2. Try a dry run
capysquash squash migrations/ --safety=conservative --dry-run

# 3. Actually squash with validation
capysquash safe migrations/

# 4. Review the output
ls -la squashed/

Regular Development Cleanup

# Quick squash for development
capysquash fast migrations/

# Or use interactive mode
capysquash tui migrations/

Production Deployment

# Conservative approach with validation
capysquash safe migrations/

# Verify output
capysquash validate migrations/ squashed/

# Review before deploying
cat squashed/*.sql

AI-POWERED COMMANDS

Optional AI features for advanced analysis and debugging. Requires Claude (Anthropic) or OpenAI API key.

Setup AI Provider

# Set API key for Claude (recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# Or use OpenAI
export OPENAI_API_KEY="sk-..."

# Or Azure OpenAI
export AZURE_OPENAI_ENDPOINT="https://..."
export AZURE_OPENAI_API_KEY="..."

ai-test

Test AI provider connections and verify setup.

capysquash ai-test

What it does:

• Tests connection to configured AI providers
• Verifies API keys are valid
• Shows which providers are available
• Tests basic query functionality

Example output:

☑ Anthropic (Claude): Connected
☒ OpenAI: Not configured
☑ Azure OpenAI: Connected

Ready to use AI features!

ai-demo

Demonstrate AI capabilities with sample code.

capysquash ai-demo

What it shows:

• AI-powered semantic analysis examples
• Function similarity detection demo
• Dead code detection examples
• Complexity analysis demonstration

Requires: At least one AI provider configured

ai-fix

⚠️ Experimental - AI-assisted migration fixing with automatic retry.

capysquash ai-fix [migration-directory] [options]

What it does:

1. Analyzes migrations and detects errors
2. Uses AI to suggest fixes for issues
3. Applies fixes interactively (or automatically with --auto-apply)
4. Validates fixed migrations with Docker
5. Repeats until validation succeeds or max attempts reached

Key Flags:

Usage Examples:

# Interactive fixing (recommended)
capysquash ai-fix migrations/

# Automatic fixing with more attempts
capysquash ai-fix migrations/ --max-attempts=10 --auto-apply

# See AI reasoning
capysquash ai-fix migrations/ --verbose

Use cases:

• Fixing syntax errors automatically
• Resolving dependency conflicts
• Correcting schema inconsistencies
• Quick migration debugging

What AI provides across all commands:

• Semantic function similarity detection
• Dead code identification (unused functions, triggers)
• Complexity scoring for refactoring candidates
• Platform pattern recognition (Supabase, Clerk, Auth0)
• Optimization suggestions
• Automatic error fixing

Note: AI features are completely optional and also available in CAPYSQUASH Platform Pro/Enterprise plans.

CONFIGURATION

Config File

Generate with capysquash init-config, then customize:

{
  "safety_level": "standard",
  "output": {
    "format": "organized",
    "directory": "squashed"
  },
  "rules": {
    "table_operations": {
      "consolidate_create_alter": true,
      "remove_drop_create_cycles": true
    }
  }
}

Output Structure

capysquash creates organized output files:

squashed/
├── 001_extensions.sql          # CREATE EXTENSION statements
├── 002_schema_foundation.sql   # CREATE TABLE, types, enums
├── 003_constraints.sql          # Foreign keys, constraints
├── 004_indexes.sql              # Indexes for performance
├── 005_functions.sql            # Functions and procedures
├── 006_triggers.sql             # Triggers and rules
├── 007_security.sql             # RLS policies, permissions
└── README.md                    # Consolidation report

COMMON PATTERNS

Supabase Projects

# Auto-detects Supabase patterns (auth, storage, RLS)
capysquash squash supabase/migrations/ --safety=conservative

# Preserves auth.users, storage.buckets, RLS policies

Drizzle/Prisma

# Works with ORM-generated migrations
capysquash squash drizzle/migrations/

# Or Prisma
capysquash squash prisma/migrations/

Large Migration Sets (100+ files)

# Streaming mode auto-enables for memory efficiency
capysquash squash migrations/

# Or launch TUI for visual progress
capysquash tui migrations/

TROUBLESHOOTING

Docker Not Running

# Check Docker status
docker ps

# If not running, start Docker Desktop
# Then try validation again
capysquash validate migrations/ squashed/

Permission Denied

# Make capysquash executable
chmod +x $(which capysquash)

Out of Memory

# Process in smaller batches
capysquash squash migrations/00*.sql
capysquash squash migrations/01*.sql

Full troubleshooting guide →

NEXT STEPS

• CAPYSQUASH Platform - One-click squashing with team features
• Understanding Safety Levels
• How Docker Validation Works
• Engine Configuration
• Getting Started Tutorial