The completion system provides intelligent tab completion for command-line flags and options for all backup scripts in this repository. It's automatically installed and configured by the setup scripts.

Supported Scripts

Plex Management Scripts ⭐ NEW

plex.sh

start - Start Plex Media Server
stop - Stop Plex Media Server
restart - Restart Plex Media Server
status - Show detailed service status
scan - Launch library scanner (with sub-commands)
repair - Repair database corruption issues
nuclear - Nuclear database recovery (last resort)
help - Show help message

scan-plex-libraries.sh

list - List all library sections
scan - Scan for new media (with optional section ID)
refresh - Refresh metadata (with optional section ID and force flag)
analyze - Analyze media (with optional section ID and deep flag)
generate - Generate thumbnails (with optional section ID)
tree - Show library tree structure (requires section ID)
interactive - Interactive mode
-v, --verbose - Enable verbose output
-h, --help - Show help message

Plex Aliases

plex, px - Main plex.sh script with command completion
plex-start, plex-stop, plex-restart, plex-status - Direct service commands
plex-scan - Library scanner via plex.sh (supports scanner sub-commands)
plex-scanner - Direct access to scan-plex-libraries.sh

Backup Scripts

backup-immich.sh

--help, -h - Show help message
--dry-run - Preview backup without executing
--no-upload - Skip B2 upload (local backup only)
--verbose - Enable verbose logging

backup-plex.sh

--help, -h - Show help message
--auto-repair - Automatically attempt to repair corrupted databases
--check-integrity - Only check database integrity, don't backup
--non-interactive - Run in non-interactive mode (for automation)
--no-parallel - Disable parallel verification (slower but safer)
--no-performance - Disable performance monitoring
--webhook=URL - Send notifications to webhook URL
--email=ADDRESS - Send notifications to email address

backup-media.sh

--help, -h - Show help message
--dry-run - Show what would be backed up without actually doing it
--no-verify - Skip backup verification
--sequential - Run backups sequentially instead of in parallel
--interactive - Ask for confirmation before each backup
--webhook URL - Custom webhook URL for notifications

Generic backup scripts (backup-docker.sh, etc.)

--help, -h - Show help message
--dry-run - Preview mode
--verbose - Verbose output
--no-upload - Skip upload operations
--webhook - Webhook URL for notifications

Installation

The completion system is automatically installed when you run the setup scripts:

bootstrap.sh - Makes completion scripts executable
setup.sh - Copies completion scripts to the user's local completion directory (~/.local/share/bash-completion/completions/)
.zshrc - Sources the completion scripts in zsh with bash compatibility mode

Automatic Setup Process

When you run ./setup/bootstrap.sh or ./setup/setup.sh, the system will:

Install bash completion support in zsh
Copy completion scripts to the standard completion directory
Ensure completion scripts are executable
Source the completion in your shell configuration

Manual Installation

If you need to install manually or re-install:

# Enable bash completion compatibility in zsh
autoload -U +X bashcompinit && bashcompinit
autoload -U compinit && compinit -u

# Load custom backup scripts completion
if [ -f "$HOME/shell/completions/backup-scripts-completion.bash" ]; then
    source "$HOME/shell/completions/backup-scripts-completion.bash"
fi

# Load Plex scripts completion
if [ -f "$HOME/shell/completions/plex-scripts-completion.bash" ]; then
    source "$HOME/shell/completions/plex-scripts-completion.bash"
fi

# Load environment backup completion
if [ -f "$HOME/shell/completions/env-backup-completion.bash" ]; then
    source "$HOME/shell/completions/env-backup-completion.bash"
fi

Usage Examples

Basic Tab Completion

# Type the script name and start typing an option
$ backup-immich.sh --<TAB>
--help  --dry-run  --no-upload  --verbose

# Continue typing to filter
$ backup-immich.sh --d<TAB>
$ backup-immich.sh --dry-run

Plex Script Completion ⭐ NEW

# Main plex.sh command completion
$ plex.sh <TAB>
start  stop  restart  status  scan  repair  nuclear  help

# Scanner sub-command completion when using scan
$ plex.sh scan <TAB>
list  scan  refresh  analyze  generate  tree  interactive  -v  --verbose  -h  --help

# Direct scanner script completion
$ scan-plex-libraries.sh <TAB>
list  scan  refresh  analyze  generate  tree  interactive

# Scanner options completion
$ scan-plex-libraries.sh -<TAB>
-v  --verbose  -h  --help

# Boolean flag completion for refresh and analyze
$ scan-plex-libraries.sh refresh 29 <TAB>
true  false

$ scan-plex-libraries.sh analyze 29 <TAB>
true  false

# Alias completion works too
$ plex-scan <TAB>
list  scan  refresh  analyze  generate  tree  interactive

$ plex-scanner <TAB>
list  scan  refresh  analyze  generate  tree  interactive

Webhook URL Completion

# For scripts that support webhook URLs
$ backup-plex.sh --webhook <TAB>
https://notify.peterwood.rocks/lab

# Or for inline webhook options
$ backup-plex.sh --webhook=<TAB>
https://notify.peterwood.rocks/lab

Path-based Completion

Completion works with various invocation methods:

# Direct script name (if in PATH)
backup-immich.sh --<TAB>

# Relative path
./backup-immich.sh --<TAB>

# Absolute path
/home/acedanger/shell/immich/backup-immich.sh --<TAB>

Features

Intelligent Argument Completion

Flag completion: All available flags for each script
Value completion: Suggests common values for specific options
Context-aware: Different completions based on script type

Cross-Script Support

Specific completions: Tailored for each backup script
Generic fallback: Common options for any backup script
Pattern matching: Automatic completion for *backup*.sh scripts

Advanced Features

Webhook URL suggestions: Common webhook endpoints
Email address completion: For notification options
Multi-word option support: Handles --option value and --option=value

Troubleshooting

Completion Not Working

Verify the completion script is sourced:
```
complete -p | grep backup
```
Reload your shell configuration:
```
source ~/.zshrc
```

Check if bashcompinit is enabled:

# Should be in your .zshrc
autoload -U +X bashcompinit && bashcompinit

Adding New Scripts

To add completion for a new backup script:

Add the script patterns to the completion file
Define specific options for the script
Register the completion function

Example:

# Add to backup-scripts-completion.bash
complete -F _backup_generic_completion your-new-backup-script.sh

Development

Testing Completions

Use the test script to verify completions work:

./test-completion.sh

Adding New Options

Update the relevant completion function in backup-scripts-completion.bash
Add the new option to the opts variable
Handle any special argument completion if needed
Test the completion with compgen -W "options" -- "prefix"

Custom Completion Functions

Each script can have its own completion function following this pattern:

_script_name_completion() {
    local cur prev opts
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    opts="--option1 --option2 --option3"

    # Handle special cases
    case "${prev}" in
        --special-option)
            COMPREPLY=( $(compgen -W "value1 value2" -- ${cur}) )
            return 0
            ;;
    esac

    # Standard flag completion
    if [[ ${cur} == -* ]]; then
        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
        return 0
    fi
}