Skip to content

Scripts Directory

This directory contains helper scripts for the CLI Utils project.

Available Scripts

cli-utils (Wrapper Script)

Purpose: System-wide wrapper script that allows running cli-utils from anywhere.

Location: scripts/cli-utils

Usage: 

# After installation (make link-global or make install-global)
cli-utils --help
cli-utils local text_utils uppercase "hello"
cli-utils version

How it works: 1. Resolves the project root directory (even when symlinked) 2. Locates the virtual environment at PROJECT_ROOT/.venv 3. Executes the CLI using the venv's Python with correct PYTHONPATH 4. Handles multiple scenarios: - Already in the correct virtual environment - Virtual environment exists but not activated - No virtual environment found (shows helpful error)

Installation: 

# Create symlink (recommended for development)
make link-global

# Or copy to ~/bin (more stable)
make install-global

# Verify installation
make check-global

Features: - ✅ Works from any directory - ✅ Automatically finds project root (even with symlinks) - ✅ Uses virtual environment without activation - ✅ Clear error messages if setup is incomplete - ✅ Fast execution (uses venv Python directly)

quickstart.sh (Setup Helper)

Purpose: Quick setup script for new developers.

Location: scripts/quickstart.sh

Usage: 

./scripts/quickstart.sh

What it does: 1. Checks if uv is installed 2. Checks for virtual environment 3. Creates venv if needed (prompts for activation) 4. Installs development dependencies 5. Runs initial tests 6. Shows version info 7. Displays next steps

When to use: - First time setting up the project - After cloning the repository - Resetting development environment

Script Internals

cli-utils Script Flow

┌─────────────────────────────────────┐
│ User runs: cli-utils <command>      │
└───────────────┬─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│ Resolve script location             │
│ (handles symlinks)                  │
└───────────────┬─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│ Calculate PROJECT_ROOT              │
│ (one level up from scripts/)        │
└───────────────┬─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│ Check: Already in correct venv?     │
└───────────────┬─────────────────────┘
                │
      ┌─────────┴─────────┐
      │ YES               │ NO
      ▼                   ▼
┌──────────┐     ┌────────────────────┐
│ Run with │     │ Check: venv exists?│
│ python   │     └────────┬───────────┘
└──────────┘              │
                ┌─────────┴─────────┐
                │ YES               │ NO
                ▼                   ▼
      ┌──────────────────┐   ┌──────────┐
      │ Run with venv's  │   │ Show     │
      │ python directly  │   │ error    │
      │ (+ PYTHONPATH)   │   │ message  │
      └──────────────────┘   └──────────┘

Environment Variables Used

  • VIRTUAL_ENV - Checked to see if already in a venv
  • PYTHONPATH - Set to include src/ directory
  • BASH_SOURCE[0] - Used to find script location

Key Directories

  • PROJECT_ROOT - Base directory of the project
  • VENV_PATH - $PROJECT_ROOT/.venv
  • VENV_PYTHON - $VENV_PATH/bin/python

Maintenance

Updating the Wrapper Script

If you modify scripts/cli-utils:

  1. For symlink install (link-global):
  2. Changes take effect immediately

  3. No reinstallation needed

  4. For copy install (install-global):

  5. Run make install-global to update
  6. Or run make uninstall-global && make install-global

Testing the Wrapper

# Test locally (without installation)
./scripts/cli-utils --help

# Test from different directory
cd /tmp && ~/bin/cli-utils --help

# Verify installation
make check-global

Common Issues

Issue: Script not found 

# Check if installed
ls -la ~/bin/cli-utils

# Reinstall
make link-global

Issue: Permission denied 

# Make executable
chmod +x scripts/cli-utils
chmod +x ~/bin/cli-utils

Issue: Virtual environment not found 

# Create and install
make install-dev

Best Practices

  1. Use symlink for development
  2. Automatically reflects code changes

  3. Easy to update

  4. Use copy for production

  5. More stable

  6. Doesn't break if project moves

  7. Always check installation 

    make check-global

  8. Keep PATH updated

  9. Ensure ~/bin is in PATH
  10. Add to ~/.zshrc: export PATH="$HOME/bin:$PATH"

See Also