CAPYSQUASH

Interactive TUI Guide

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

Configuration Building

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

# 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

BENEFITS OF USING TUI

☑ ADVANTAGES

  • ► Visual Feedback: See progress in real-time
  • ► Interactive Exploration: Navigate dependencies visually
  • ► Easier Configuration: Build configs without memorizing options
  • ► Better Understanding: Visualize relationships and patterns
  • ► Less Context Switching: Everything in one interface

💡 WHEN TO USE CLI

  • ► CI/CD Pipelines: Use --quiet flag
  • ► Scripts: CLI is more scriptable
  • ► SSH Sessions: Some terminals have limited capabilities
  • ► Automated Workflows: No interactive input needed

NEXT STEPS

Questions about the TUI? Check the troubleshooting guide or press ? while in the TUI for quick help.

How is this guide?

On this page

INTERACTIVE TUI GUIDELAUNCHING THE TUITUI VIEWS1. Dashboard View2. Analysis View3. Configuration Wizard4. Dependency Graph ViewerGLOBAL NAVIGATIONCOMMON WORKFLOWSFirst-Time AnalysisInteractive SquashingConfiguration BuildingPERFORMANCE TIPSTROUBLESHOOTINGTUI Not Rendering ProperlyTUI Freezes or CrashesBENEFITS OF USING TUINEXT STEPS