# Check version

capysquash --version

# Verify Docker is running

docker ps

    </div>

    ## GLOBAL FLAGS

    Available for all commands:

    <div className="brutalist-card p-6 my-6">
    <div className="space-y-4">
    <div>
    <code className="brutalist-code inline-block px-3 py-1">--config, -c &lt;path&gt;</code>
    <p className="font-bold mt-2">Specify config file path (default: capysquash.config.json)</p>
    </div>
    - <div>
    - <code className="brutalist-code inline-block px-3 py-1">--verbose, -v</code>
    - <p className="font-bold mt-2">Enable verbose output with detailed processing logs</p>
    - </div>
    - <div>
    - <code className="brutalist-code inline-block px-3 py-1">--quiet, -q</code>
    - <p className="font-bold mt-2">Quiet mode - only show errors and final results (ideal for CI/CD)</p>
    - </div>
    - <div>
    - <code className="brutalist-code inline-block px-3 py-1">--no-emoji</code>
    - <p className="font-bold mt-2">Disable emoji characters in output (improves terminal compatibility)</p>
    - </div>
    - <div>
    - <code className="brutalist-code inline-block px-3 py-1">--help, -h</code>
    - <p className="font-bold mt-2">Show help for any command</p>
    - </div>
    - </div>
    </div>

    <div className="brutalist-card-sm p-4 my-4 section-accent-info">
    <p className="font-bold text-xs">
    💡 <strong>Note:</strong> The <code>--tui</code> flag is only available on <code>analyze</code> and <code>squash</code> commands, not globally. For the standalone TUI interface, use the <code>tui</code> command.
    </p>
    </div>

    ## CORE COMMANDS

    ### analyze

    Analyze migrations without making any modifications.

    <div className="brutalist-code my-4">
    ```bash

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:**


```bash

# Analyze all migrations in directory

capysquash analyze migrations/

# Analyze specific files

capysquash analyze migrations/\*.sql

# With verbose output

capysquash analyze migrations/ --verbose

    </div>

    **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

    <div className="brutalist-card p-6 my-6 section-accent-info">
    <p className="font-bold">
    <span className="inline-flex items-center gap-2"><Lightbulb size={20} weight="bold" /> <strong>Tip:</strong> Analysis is always safe - it never modifies your files. Use this to preview what squashing will do.</span>
    </p>
    </div>

    ### squash

    Process and optimize migrations with consolidation.

    <div className="brutalist-code my-4">
    ```bash

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:**



--safety, -s &lt;level&gt;
Safety level: paranoid | conservative | standard | aggressive
Default: standard




- --output, -o 

- Output directory for squashed migrations

- Default: squashed/





- --dry-run

- Preview changes without writing files





- --explain

- Show detailed consolidation plan with reasoning (implies --dry-run)





- --backup

- Generate backup before squashing (requires prod_db_dsn in config or env)





- --rollback

- Generate rollback scripts (saved to rollbacks/rollback_plans/)





- --tui

- Launch interactive TUI for squashing





**Common Usage:**


```bash

# 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/

    </div>

    **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 →](/docs/core-concepts/safety-levels)

    ### validate

    Validate squashed migrations match original schema using Docker.

    <div className="brutalist-code my-4">
    ```bash

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:**


```bash

# Validate after squashing

capysquash validate migrations/ squashed/

# With verbose output

capysquash validate migrations/ squashed/ --verbose

    </div>

    **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

    <div className="brutalist-card p-6 my-6 section-accent-success">
    <p className="font-bold">
    <span className="inline-flex items-center gap-2"><ShieldCheck size={20} weight="bold" /> <strong>Safety Guarantee:</strong> If validation passes, your squashed migrations are guaranteed to produce the same schema as the originals.</span>
    </p>
    </div>

    [Learn more about Docker validation →](/docs/core-concepts/docker-validation)

    ### tui

    Launch interactive Terminal UI for visual migration management.

    <div className="brutalist-code my-4">
    ```bash

# 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:**



capysquash tui analyze
Launch TUI directly in the analysis view




- capysquash tui config

- Launch TUI directly in the configuration wizard





- capysquash tui deps

- Launch TUI directly in the dependency graph view





**Navigation:**

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

**TUI Views:**



📊 DASHBOARD
Overview stats, recent runs, system status




- 🔍 ANALYSIS

- Live analysis results, lifecycle patterns, dependency graphs





- ⚙️ CONFIG

- Interactive configuration wizard with live preview





- 🌳 DEPENDENCIES

- Visual dependency graph explorer with filtering





[See complete TUI guide →](/docs/capysquash-cli/tui-guide)

### init-config

Generate default configuration file.


```bash
capysquash init-config [options]

# 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

    </div>

    ### health

    Health check for container orchestration and monitoring.

    <div className="brutalist-code my-4">
    ```bash

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:**



--text
Output plain text instead of JSON



- --detailed
- Include system info (CPU, memory, Go version)




**Usage:**


```bash

# Basic health check (JSON)

capysquash health

# Plain text output

capysquash health --text

# Detailed system info

capysquash health --detailed

    </div>

    **Example Output (JSON):**

    <div className="brutalist-code my-4">
    ```json


"status": "healthy",
"version": "0.9.6",
"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:**


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

capysquash safe migrations/

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

capysquash fast migrations/*.sql

capysquash analyze-deep migrations/

# 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/

    </div>

    ### Regular Development Cleanup

    <div className="brutalist-code my-6">
    ```bash

# Quick squash for development

capysquash fast migrations/

# Or use interactive mode

capysquash tui migrations/



### Production Deployment


```bash

# Conservative approach with validation

capysquash safe migrations/

# Verify output

capysquash validate migrations/ squashed/

# Review before deploying

cat squashed/\*.sql

    </div>

    ## AI-POWERED COMMANDS

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

    ### Setup AI Provider

    <div className="brutalist-code my-6">
    ```bash

# 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.


```bash
capysquash ai-test

capysquash ai-demo

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

# 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

    </div>

    **Use cases:**
    - Fixing syntax errors automatically
    - Resolving dependency conflicts
    - Correcting schema inconsistencies
    - Quick migration debugging

    <div className="brutalist-card p-6 my-6 section-accent-warning">
    <p className="font-bold">
    ⚠️ <strong>Experimental Feature:</strong> ai-fix creates backups before applying changes, but always review fixes before deploying. Use in development environments first.
    </p>
    </div>

    **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:

    <div className="brutalist-code my-6">
    ```json


"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:

## COMMON PATTERNS

### Supabase Projects


```bash

# Auto-detects Supabase patterns (auth, storage, RLS)

capysquash squash supabase/migrations/ --safety=conservative

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

# Works with ORM-generated migrations

capysquash squash drizzle/migrations/

# Or Prisma

capysquash squash prisma/migrations/

    </div>

    ### Large Migration Sets (100+ files)

    <div className="brutalist-code my-6">
    ```bash

# Streaming mode auto-enables for memory efficiency

capysquash squash migrations/

# Or launch TUI for visual progress

capysquash tui migrations/



## TROUBLESHOOTING

### Docker Not Running


```bash

# Check Docker status

docker ps

# If not running, start Docker Desktop

# Then try validation again

capysquash validate migrations/ squashed/

    </div>

    ### Permission Denied

    <div className="brutalist-code my-6">
    ```bash

# Make capysquash executable

chmod +x $(which capysquash)



### Out of Memory


```bash

# Process in smaller batches

capysquash squash migrations/00\*.sql
capysquash squash migrations/01\*.sql

    </div>

    [Full troubleshooting guide →](/docs/troubleshooting)

    ## NEXT STEPS

    - [CAPYSQUASH Platform](/docs/capysquash/overview) - One-click squashing with team features
    - [Understanding Safety Levels](/docs/core-concepts/safety-levels)
    - [How Docker Validation Works](/docs/core-concepts/docker-validation)
    - [Engine Configuration](/docs/pgsquash-engine/configuration)
    - [Getting Started Tutorial](/docs/getting-started/quick-start)