tools-installer/TEA_CLI_ADVANCED_README.md

Tea CLI Installer - Advanced Version Management

Enhanced Installation Strategy

The Tea CLI installer now implements sophisticated version management with user-specific installations:

Installation Priority Order

1. User Bin Directory (~/bin) - Preferred

   • Checks if ~/bin exists and is in PATH
   • Installs binaries with version-specific names
   • Creates symlinks for easy version switching
   • Allows multiple versions side-by-side

2. System Installation (/usr/local/bin) - Fallback

   • Used when user bin is not available
   • Requires sudo for system-wide installation
   • Single version installation

Version Management Features

Symlink-Based Version Control

~/bin/
├── tea -> tea-v0.11.1    # Active version symlink
├── tea-v0.11.0           # Previous version
├── tea-v0.11.1           # Current version
└── tea-v0.12.0           # Future version (when available)

Automatic Updates

• Detects current version via symlink
• Downloads newer versions with version suffix
• Updates symlink to point to latest version
• Preserves old versions for rollback

Installation Strategies

user_install - Fresh User Installation

• When Tea CLI not found in user bin
• Creates versioned binary and symlink
• No sudo required

user_update - User Version Update

• When newer version available
• Downloads new version with suffix
• Updates symlink to new version
• Keeps old versions

user_upgrade - User Upgrade (No Symlink)

• When existing binary found but no symlink
• Creates versioned structure
• Adds symlink management

system_install - System Installation

• When user bin not available/in PATH
• Installs to /usr/local/bin
• Requires sudo privileges

Usage Examples

Normal Usage (Auto-detects strategy)

./install-tea-cli.sh
# Detects user bin, checks versions, updates if needed

Force Binary Installation

./install-tea-cli.sh --force --binary
# Forces binary download regardless of current version

Check Current Status

./install-tea-cli.sh
# Shows current version and installation type
# Exits if no update needed

Version Detection Logic

1. Check PATH: Finds tea command location
2. Installation Type: Determines user vs system installation
3. Symlink Check: Detects version-specific symlinks
4. Version Comparison: Compares with latest release
5. Strategy Selection: Chooses appropriate installation method

Benefits

✅ User Isolation: Installations don't affect other users
✅ Version Control: Multiple versions can coexist
✅ Easy Updates: Symlinks automatically point to latest
✅ Rollback Support: Old versions preserved
✅ No Sudo Required: User installations don't need root
✅ System Fallback: Falls back to system installation when needed

Directory Structure

User Installation

~/bin/
├── tea -> tea-v0.11.1
├── tea-v0.11.0
└── tea-v0.11.1

System Installation

/usr/local/bin/
├── tea -> tea-v0.11.1
├── tea-v0.11.0
└── tea-v0.11.1

PATH Requirements

For user installations, ensure ~/bin is in PATH:

# Add to ~/.bashrc or ~/.profile
export PATH="$HOME/bin:$PATH"

Troubleshooting

Version Not Updating

# Check current symlink
ls -la ~/bin/tea

# Force reinstall
./install-tea-cli.sh --force

PATH Issues

# Check if user bin is in PATH
echo $PATH | grep -q "$HOME/bin" && echo "OK" || echo "Add to PATH"

# Test tea command
which tea
tea --version

Permission Issues

# For system installation
sudo ./install-tea-cli.sh --binary

Integration with Setup Script

The installer integrates seamlessly with the main setup script:

• Automatically called when Tea CLI is needed
• Respects user preferences for installation location
• Provides clear feedback on installation strategy
• Handles both new installations and updates