CAPYSQUASH

---

CAPYSQUASH documentation page.

---

Title: Interactive TUI Guide. Description: Terminal User Interface guide for capysquash-cli.

INTERACTIVE TUI GUIDE

Capysquash-cli's Terminal User Interface (TUI) provides an interactive way to analyze and squash migrations with real-time visual feedback.

💡 Prefer web-based workflows? CAPYSQUASH Platform offers a full visual interface with team features. The CLI TUI is for terminal-focused developers.

LAUNCHING THE TUI


# Launch TUI in current directory

capysquash tui

# Launch with specific migrations folder

capysquash tui path/to/migrations/

# Go directly to a specific view

capysquash tui analyze migrations/ # Analysis view

capysquash tui config # Config wizard

capysquash tui deps migrations/ # Dependency graph

# Or add --tui to any command

capysquash analyze migrations/ --tui
capysquash squash migrations/ --tui

TUI VIEWS

The TUI has four main views accessible via Tab or number keys.

1. Dashboard View

DASHBOARD OVERVIEW

The main dashboard shows:

SYSTEM STATUS

► capysquash version ► Docker availability ► CPU and memory usage ► Configuration status

  • QUICK STATS

  • ► Total migrations found

  • ► Last analysis results

  • ► Recent operations

  • ► Time savings estimate

Features:

  • Live system monitoring
  • Recent operations history
  • Quick access to all views
  • Status indicators for Docker, config, and migrations

2. Analysis View

REAL-TIME ANALYSIS

Watch migrations being analyzed in real-time with live progress updates.

LIVE METRICS

► Files processed (with progress bar) ► Consolidation opportunities ► Dependency relationships found ► Platform patterns detected ► Warnings and issues

  • LIFECYCLE PATTERNS

  • ► Created objects (tables, indexes)

  • ► Modified objects (ALTERs)

  • ► Dropped objects

  • ► Create-Drop cycles detected

  • ► Optimization candidates

Interactive features:

  • Scroll through analysis results
  • View detailed dependency chains
  • See platform pattern detections (Supabase, Clerk)
  • Identify optimization opportunities
  • Navigate to related migrations

Keyboard shortcuts:

  • ↑/↓ - Scroll through results
  • Enter - View details for selected item
  • r - Refresh analysis
  • f - Filter results

3. Configuration Wizard

⚙️ INTERACTIVE CONFIG BUILDER

Build your capysquash configuration visually with immediate feedback.

CONFIGURATION SECTIONS

► Safety Level: Choose from paranoid, conservative, standard, aggressive ► Output Settings: Configure directory, format, naming ► Rules: Enable/disable specific consolidation rules ► Performance: Streaming, parallel processing, memory limits ► Plugins: Enable platform detection (Supabase, Clerk, etc.) ► Validation: Docker validation mode selection

  • LIVE PREVIEW
  • See the generated JSON configuration as you make changes. Test configurations before saving.

Features:

  • Interactive form with validation
  • Live JSON preview
  • Help text for each option
  • Save to file or copy to clipboard
  • Load existing config for editing

Keyboard shortcuts:

  • Tab - Next field
  • Shift+Tab - Previous field
  • Space - Toggle checkboxes
  • s - Save configuration
  • c - Copy to clipboard

4. Dependency Graph Viewer

VISUAL DEPENDENCY EXPLORER

Navigate the complete dependency graph of your migrations with interactive exploration.

GRAPH FEATURES

► Visual tree structure of dependencies ► Table → Column → Index relationships ► Foreign key dependencies ► Circular dependency detection ► Migration file associations

  • FILTERING & SEARCH

  • ► Filter by object type (table, index, etc.)

  • ► Search by name

  • ► Show only circular dependencies

  • ► Highlight specific migration's objects

Interactive features:

  • Expand/collapse nodes
  • Jump to migration file
  • View object details
  • Trace dependency chains
  • Identify bottlenecks

Keyboard shortcuts:

  • ↑/↓ - Navigate nodes
  • → - Expand node
  • ← - Collapse node
  • Enter - View node details
  • / - Search
  • f - Toggle filters

Available in all views:

VIEW SWITCHING

► 1 or d - Dashboard ► 2 or a - Analysis ► 3 or c - Config ► 4 or g - Dependencies ► Tab - Next view ► Shift+Tab - Previous view

  • GLOBAL ACTIONS

  • ► ? - Show help/keyboard shortcuts

  • ► q or Ctrl+C - Quit TUI

  • ► r - Refresh current view

  • ► Ctrl+L - Clear screen

COMMON WORKFLOWS

First-Time Analysis


# 1. Launch TUI

capysquash tui migrations/

# 2. Review Dashboard

#    Check system status and migrations found

# 3. Go to Analysis view (press '2')

#    Watch real-time analysis progress

# 4. Review dependency graph (press '4')

#    Understand relationships

# 5. Configure settings (press '3')

#    Adjust safety level if needed

# 6. Press 'q' to quit when done

Interactive Squashing


# 1. Launch squash with TUI

capysquash squash migrations/ --tui

# 2. TUI opens in progress view

# Watch consolidation in real-time

# 3. Review warnings if any

# Navigate with arrow keys

# 4. See results when complete

# View reduction statistics

# 5. Press 'q' to exit

    </div>

    ### Configuration Building

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

# 1. Launch config wizard

capysquash tui config

# 2. Navigate through options

# Use Tab/Enter to configure

# 3. See live JSON preview

# Verify settings as you go

# 4. Save configuration

# Press 's' to save

# 5. Test with squash

capysquash squash migrations/ --config=capysquash.config.json



## PERFORMANCE TIPS


OPTIMIZING TUI PERFORMANCE





LARGE MIGRATION SETS

For 100+ migrations, streaming mode auto-enables:



► Progress updates every batch (default 50 files)

► Memory-efficient processing

► Real-time throughput stats







- TERMINAL OPTIMIZATION



- ► Use a modern terminal (iTerm2, Alacritty, Windows Terminal)

- ► Enable GPU acceleration if available

- ► Increase buffer size for large outputs

- ► Use monospace fonts for better rendering









## TROUBLESHOOTING

### TUI Not Rendering Properly


COMMON RENDERING ISSUES



Characters appear as boxes or question marks:


```bash

# Use --no-emoji flag

capysquash tui migrations/ --no-emoji

  • Layout is broken:

  • ► Ensure terminal window is at least 80x24

  • ► Try resizing terminal window

  • ► Press Ctrl+L to refresh

  • Colors not showing:

  • ► Check TERM environment variable

  • ► Use TERM=xterm-256color capysquash tui

TUI Freezes or Crashes


# If TUI becomes unresponsive:

# 1. Press Ctrl+C to force quit

# 2. Run without TUI to check for errors

capysquash analyze migrations/ --verbose

# 3. Check system resources

capysquash health --detailed

# 4. Report issue with logs

capysquash tui migrations/ --verbose > tui-debug.log 2>&1

    </div>

    ## BENEFITS OF USING TUI

    <div className="grid md:grid-cols-2 gap-6 my-8">
    <div className="brutalist-card p-6 section-accent-success">
    <h3 className="text-xl font-black uppercase mb-3">☑ ADVANTAGES</h3>
    <ul className="space-y-2 font-bold text-sm">
    <li>► **Visual Feedback**: See progress in real-time</li>
    <li>► **Interactive Exploration**: Navigate dependencies visually</li>
    <li>► **Easier Configuration**: Build configs without memorizing options</li>
    <li>► **Better Understanding**: Visualize relationships and patterns</li>
    <li>► **Less Context Switching**: Everything in one interface</li>
    </ul>
    </div>

    - <div className="brutalist-card p-6">
    - <h3 className="text-xl font-black uppercase mb-3">💡 WHEN TO USE CLI</h3>
    - <ul className="space-y-2 font-bold text-sm">
    - <li>► **CI/CD Pipelines**: Use `--quiet` flag</li>
    - <li>► **Scripts**: CLI is more scriptable</li>
    - <li>► **SSH Sessions**: Some terminals have limited capabilities</li>
    - <li>► **Automated Workflows**: No interactive input needed</li>
    - </ul>
    - </div>
    </div>

    ## NEXT STEPS

    - [Complete Commands Reference](/docs/pgsquash-engine/commands) - All CLI commands and flags
    - [Configuration Guide](/docs/pgsquash-engine/configuration) - Deep dive into config options
    - [Safety Levels](/docs/core-concepts/safety-levels) - Understanding different safety modes
    - [Dependency Resolution](/docs/core-concepts/dependency-resolution) - How pgsquash handles dependencies

    ---

    **Questions about the TUI?** Check the [troubleshooting guide](/docs/troubleshooting) or press `?` while in the TUI for quick help.

How is this guide?

---

Previous Page

---

Next Page

On this page

---Title: Interactive TUI Guide. Description: Terminal User Interface guide for capysquash-cli.INTERACTIVE TUI GUIDELAUNCHING THE TUITUI VIEWS1. Dashboard View2. Analysis View3. Configuration Wizard4. Dependency Graph ViewerGLOBAL NAVIGATIONCOMMON WORKFLOWSFirst-Time AnalysisInteractive SquashingTUI Freezes or Crashes