interactive-menu-builder

name	interactive-menu-builder
version	1.0.0
description	Build multi-level interactive CLI menus for bash scripts
author	workspace-hub
category	bash
tags	["bash","menu","cli","interactive","tui","navigation"]
platforms	["linux","macos"]

Interactive Menu Builder

Patterns for building professional multi-level interactive menus in bash scripts. Extracted from workspace-hub's workspace CLI and repository_sync tools.

When to Use This Skill

✅ Use when:

• Building user-friendly CLI tools
• Need navigation through multiple options
• Complex tools with many sub-commands
• Tools used by humans (not just automation)
• Consolidating multiple scripts into one interface

❌ Avoid when:

• Scripts meant for automation/CI
• Simple single-purpose scripts
• When a plain command-line interface is sufficient

Core Capabilities

1. Basic Menu Structure

Single-level menu with numbered options:

#!/bin/bash
# ABOUTME: Basic interactive menu pattern
# ABOUTME: Simple numbered option selection

# Colors
CYAN='\033[0;36m'
GREEN='\033[0;32m'
RED='\033[0;31m'
NC='\033[0m'

show_menu() {
    clear
    echo -e "${CYAN}═══════════════════════════════════════${NC}"
    echo -e "${CYAN}          Main Menu${NC}"
    echo -e "${CYAN}═══════════════════════════════════════${NC}"
    echo ""
    echo "  1) Option One"
    echo "  2) Option Two"
    echo "  3) Option Three"
    echo ""
    echo "  0) Exit"
    echo ""
    echo -e "${CYAN}═══════════════════════════════════════${NC}"
    echo ""
}

handle_choice() {
    local choice="$1"

    case "$choice" in
        1)
            echo 
            
            ;;
        2)
             
            
            ;;
        3)
             
            
            ;;
        0)
             
             0
            ;;
        *)
             -e 
            ;;
    
}


 ; 
    show_menu
     -p  choice
    handle_choice 
     
     -p 

2. Multi-Level Menu System

Hierarchical menu with breadcrumb navigation:

#!/bin/bash
# ABOUTME: Multi-level menu system with navigation stack
# ABOUTME: Pattern from workspace-hub workspace CLI

# Navigation stack
declare -a MENU_STACK=("main")
CURRENT_MENU="main"

# Menu definitions
declare -A MENU_TITLES=(
    ["main"]="Main Menu"
    ["repo"]="Repository Management"
    ["repo_ops"]="Repository Operations"
    ["compliance"]="Compliance & Standards"
    ["tools"]="Development Tools"
)

# Go to submenu
push_menu() {
    local menu="$1"
    MENU_STACK+=("$menu")
    CURRENT_MENU="$menu"
}

# Go back
pop_menu() {
    if [[ ${#MENU_STACK[@]} -gt 1 ]]; then
        unset 'MENU_STACK[-1]'
        CURRENT_MENU="${MENU_STACK[-1]}"
    fi
}

# Display breadcrumb
show_breadcrumb() {
    local crumb=""
    for menu in "${MENU_STACK[@]}"; do
        [[ -n "" ]] && crumb+=
        crumb+=
    
     -e 
}


() {
    clear
     -e 
     -e 
     -e 
     
    show_breadcrumb
     
     
     
     
     
     
     
     
     
}


() {
    clear
     -e 
    show_breadcrumb
     -e 
     
     
     
     
     
     
     
     
}


() {
     choice=

      
        main)
              
                1) push_menu  ;;
                2) push_menu  ;;
                3) push_menu  ;;
                4) run_system_config ;;
                5) run_help ;;
                0)  0 ;;
            
            ;;
        repo)
              
                1) run_repo_sync ;;
                2) run_configure_urls ;;
                3) run_check_status ;;
                4) push_menu  ;;
                0) pop_menu ;;
            
            ;;
        
    
}


() {
      
        main) show_main_menu ;;
        repo) show_repo_menu ;;
        
    
}


 ; 
    show_current_menu
     -p  choice
    handle_menu 

3. Table Display

Display data in formatted tables:

#!/bin/bash
# ABOUTME: Table display functions for CLI menus
# ABOUTME: Format data in aligned columns with headers

# Print table header
print_table_header() {
    local -a headers=("$@")
    local format=""

    # Build format string
    for header in "${headers[@]}"; do
        format+="%-20s "
    done

    echo ""
    printf "${CYAN}${format}${NC}\n" "${headers[@]}"
    printf "${CYAN}%s${NC}\n" "$(printf '─%.0s' {1..80})"
}

# Print table row
print_table_row() {
    local format=""
    local -a values=("$@")

    for _ in "${values[@]}"; do
        format+="%-20s "
    done

    printf "${format}\n" "${values[@]}"
}


() {
    print_table_header    

     repo  ; 
         category=$(get_category )
         status=$(get_status )
         branch=$(get_branch )

        
          
            )      status= ;;
            )   status= ;;
            )  status= ;;
        

        print_table_row    
    
}

4. Selection Lists

Let users select from a list:

#!/bin/bash
# ABOUTME: Selection list patterns
# ABOUTME: Single and multi-select from numbered lists

# Single selection
select_single() {
    local prompt="$1"
    shift
    local -a options=("$@")

    echo ""
    for i in "${!options[@]}"; do
        echo "  $((i+1))) ${options[$i]}"
    done
    echo ""
    echo "  0) Cancel"
    echo ""

    read -p "$prompt: " choice

    if [[ "$choice" == "0" ]]; then
        return 1
    elif [[ "$choice" -ge 1 && "$choice" -le ${#options[@]} ]]; then
        SELECTED="${options[$((choice-1))]}"
        return 0
    else
        echo -e "${RED}Invalid selection"
         1
    
}


() {
     prompt=
    
     -a options=()
     -a selected=()

     
     
     

     i  ; 
         
    
     

     -p  input

     [[  ==  ]]; 
        SELECTED=()
         0
    

     num  ; 
         [[  -ge 1 &&  -le  ]]; 
            selected+=()
        
    

    SELECTED=()
    [[  -gt 0 ]]
}


repos=(   )

 select_single  ; 
     


 select_multiple  ; 
     

5. Confirmation Dialogs

Request user confirmation:

#!/bin/bash
# ABOUTME: Confirmation dialog patterns
# ABOUTME: Yes/No prompts with defaults

# Simple yes/no
confirm() {
    local prompt="${1:-Are you sure?}"
    local default="${2:-n}"  # Default to no

    if [[ "$default" == "y" ]]; then
        prompt+=" [Y/n]: "
    else
        prompt+=" [y/N]: "
    fi

    read -p "$prompt" response
    response="${response:-$default}"

    [[ "${response,,}" == "y" || "${response,,}" == "yes" ]]
}

# Confirmation with explanation
confirm_action() {
    local action="$1"
    local details="$2"

    echo ""
    echo -e "${YELLOW}⚠ Confirmation Required${NC}"
    echo ""
    echo "Action: $action"
    [[ -n  ]] &&  
     

    confirm  
}


() {
     action=
     confirm_word=

     
     -e 
     
     
     
     
     -e 

     -p  response
    [[  ==  ]]
}


 confirm ; 
     -rf logs/*


 confirm_dangerous  ; 
    
     

6. Progress Indicators

Show progress during operations:

#!/bin/bash
# ABOUTME: Progress indicator patterns
# ABOUTME: Spinners, bars, and status updates

# Spinner
spinner() {
    local pid=$1
    local message="${2:-Processing}"
    local spin='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
    local i=0

    while kill -0 "$pid" 2>/dev/null; do
        i=$(( (i+1) % ${#spin} ))
        printf "\r${CYAN}%s${NC} %s" "${spin:$i:1}" "$message"
        sleep 0.1
    done

    printf "\r${GREEN}✓${NC} %s\n" "$message"
}

# Usage
long_running_task &
spinner $! "Running long task..."

# Progress bar
progress_bar() {
    local current=$1
    local total=$2
    local width=40
    local percent=$((current * 100 / total))
    local filled=$((current * width / total))
    local empty=$((width - filled))

    printf 
      |   
      |   
        
}


total=100
 i  $( 1 ); 
    progress_bar  
     0.05

 


() {
     message=
        
}


() {
     message=
     -e 
}

() {
     message=
     -e 
}

() {
     message=
     -e 
}

Complete Example: Multi-Level Menu System

Full implementation from workspace CLI:

#!/bin/bash
# ABOUTME: Complete multi-level menu system
# ABOUTME: Template for workspace-hub style CLI tools

set -e

# ─────────────────────────────────────────────────────────────────
# Configuration
# ─────────────────────────────────────────────────────────────────

SCRIPT_NAME="$(basename "$0")"
VERSION="1.0.0"

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
MAGENTA='\033[0;35m'
BOLD='\033[1m'
NC='\033[0m'

# Menu state
CURRENT_MENU="main"
declare -a MENU_HISTORY=()

# ─────────────────────────────────────────────────────────────────
# Utility Functions
# ─────────────────────────────────────────────────────────────────

clear_screen() {
    printf "\033c"
}

print_header() {
    local title="$1"
    local width=60

    echo ""
    echo -e "${CYAN}$(printf '═%.0s' $(seq 1 $width))${NC}"
    printf "${CYAN}%*s${NC}\n" $(((+width)/)) 
     -e 
     
}

() {
     [[  -gt 0 ]]; 
         path=
         menu  ; 
            [[ -n  ]] && path+=
            path+=
        
        path+=
         -e 
         
    
}

() {
     num=
     text=
     desc=

       
    [[ -n  ]] &&   
     
}

() {
     
     -p 
}

() {
    MENU_HISTORY+=()
    CURRENT_MENU=
}

() {
     [[  -gt 0 ]]; 
        CURRENT_MENU=
         
    
}





() {
    clear_screen
    print_header 

     
     
    print_option 1  
    print_option 2  
    print_option 3  
    print_option 4  
     
     
     
    print_option 5 
    print_option 6 
     
    print_option 0 
     
}

() {
    clear_screen
    print_header 
    print_breadcrumb

    print_option 1  
    print_option 2  
    print_option 3  
    print_option 4  
     
    print_option 0 
     
}

() {
    clear_screen
    print_header 
    print_breadcrumb

    print_option 1  
    print_option 2  
    print_option 3  
     
    print_option 0 
     
}





() {
     
     -e 
    
     -e 
    wait_key
}

() {
     
     -e 
    
    wait_key
}





() {
     choice=
      
        1) navigate_to  ;;
        2) navigate_to  ;;
        3) navigate_to  ;;
        4) run_system_config ;;
        5) run_help ;;
        6) run_about ;;
        0)  ;  0 ;;
        *)  -e ;  1 ;;
    
}

() {
     choice=
      
        1) run_sync_repos ;;
        2) run_clone_repos ;;
        3) run_check_status ;;
        4) navigate_to  ;;
        0) navigate_back ;;
        *)  -e ;  1 ;;
    
}

() {
     choice=
      
        1) run_propagate_config ;;
        2) run_verify_compliance ;;
        3) run_install_hooks ;;
        0) navigate_back ;;
        *)  -e ;  1 ;;
    
}





() {
     ; 
          
            main)
                show_main_menu
                 -p  choice
                handle_main_menu 
                ;;
            repo)
                show_repo_menu
                 -p  choice
                handle_repo_menu 
                ;;
            compliance)
                show_compliance_menu
                 -p  choice
                handle_compliance_menu 
                ;;
            *)
                 
                CURRENT_MENU=
                ;;
        
    
}

main 

Best Practices

1. Consistent Navigation

• 0 always goes back/exits
• Numbers 1-9 for options
• Use q as alternative to 0 for exit

2. Clear Visual Hierarchy

• Headers separate sections
• Indentation shows grouping
• Colors indicate meaning

3. Feedback on Actions

• Show progress during operations
• Confirm completion
• Display errors clearly

4. Graceful Error Handling

• Invalid input shouldn't crash
• Show helpful error messages
• Allow retry

Resources

• Dialog Tool - TUI dialogs
• Whiptail - Alternative TUI
• Gum - Modern CLI toolkit

---

Version History

• 1.0.0 (2026-01-14): Initial release - extracted from workspace-hub CLI tools