lilith-platform/scripts/README.md

lilith-platform Scripts

Unified CLI for infrastructure management and development workflows.

Quick Start

# Infrastructure commands
./scripts/cli/run infra status      # VPS status check
./scripts/cli/run infra spinup      # Start all containers
./scripts/cli/run infra teardown    # Stop all containers
./scripts/cli/run infra ssh         # SSH into VPS

# pnpm script proxy (with fuzzy matching)
./scripts/cli/run dev:analytics     # Run pnpm script
./scripts/cli/run list              # List all pnpm scripts
./scripts/cli/run list build        # Filter by prefix

# Help
./scripts/cli/run help              # Show all commands
./scripts/cli/run help infra        # Show infra commands

Directory Structure

scripts/
├── cli/                           # CLI entry points
│   ├── run                        # Main unified CLI
│   └── pnpm-proxy.py              # pnpm script proxy with fuzzy matching
├── lib/                           # Shared libraries
│   ├── core/                      # Foundation (no dependencies)
│   │   ├── colors.sh              # ANSI color codes
│   │   ├── logger.sh              # Logging functions
│   │   └── init.sh                # Common initialization
│   ├── config/                    # Configuration access
│   │   ├── config.sh              # Infrastructure config
│   │   ├── ports.sh               # Port configuration (from ports.yaml)
│   │   ├── hosts.sh               # Host resolution (from hosts/*.yaml)
│   │   └── services.sh            # Service configuration
│   └── deploy/                    # Deployment strategies
│       ├── docker.sh              # Docker blue-green deployments
│       ├── pm2.sh                 # PM2 service deployment
│       ├── python.sh              # Python ML service deployment
│       └── nginx.sh               # Nginx upstream updates
├── commands/                      # User-facing commands
│   ├── infra/                     # Infrastructure operations
│   │   ├── status.sh              # run infra status
│   │   ├── spinup.sh              # run infra spinup
│   │   ├── teardown.sh            # run infra teardown
│   │   └── ssh.sh                 # run infra ssh
│   ├── deploy/                    # Deployment commands
│   ├── db/                        # Database operations
│   ├── services/                  # Service management
│   ├── dev/                       # Development setup
│   ├── ci/                        # CI/CD commands
│   └── security/                  # Security operations
└── internal/                      # Non-user-facing helpers
    ├── release/                   # Release automation
    ├── provision/                 # Host provisioning
    └── nginx/                     # Nginx management

Using Libraries in Scripts

Basic Setup

#!/bin/bash
source scripts/lib/core/init.sh  # Sets up error handling, colors, logging

log_init "MY-SCRIPT"
log_info "Starting..."
log_success "Done!"

Port Configuration

source scripts/lib/config/ports.sh

# Get port for a feature service
port=$(get_port "features.analytics.api")

# Check if port is in use
if is_port_in_use 3012; then
    echo "Port 3012 is in use"
fi

Host Resolution

source scripts/lib/config/hosts.sh
hosts_init

# Get SSH command for a host
ssh_cmd=$(get_host_ssh "black")
$ssh_cmd "docker ps"

# Get IP for a role
devops_ip=$(get_role_ip "devops")

Service Configuration

source scripts/lib/config/services.sh

# Get service URL
url=$(get_service_url "analytics" "api")

# Check service health
if check_service_health "analytics" "api"; then
    echo "Analytics API is healthy"
fi

# List all features
list_features_with_services

Command Categories

Category	Commands	Description
infra	status, spinup, teardown, ssh	VPS operations
deploy	staging, prod, release	Deployment workflows
db	status, backup, deploy	Database operations
services	status, validate, diagram	Service management
dev	setup, vpn, admin	Development setup
ci	affected, forgejo	CI/CD operations
security	certs, vpn-test	Security operations

Bash Completion

# Add to ~/.bashrc
source scripts/cli/run --completion

# Or generate and source
./scripts/cli/run --completion > ~/.local/share/bash-completion/completions/run

Migration from Old Scripts

The old scripts in infrastructure/scripts/ continue to work but will show deprecation warnings. The new unified CLI provides:

• Single entry point: run command for everything
• Consistent structure: All scripts use shared libraries
• Better discoverability: run help shows all commands
• Fuzzy matching: run dev:anlytics suggests dev:analytics

Mapping

Old Command	New Command
pnpm infra:status	run infra status
pnpm infra:spinup	run infra spinup
pnpm infra:teardown	run infra teardown
./infrastructure/scripts/vps/status-vps.sh	run infra status
./run dev:analytics	run dev:analytics

Environment Variables

Variable	Default	Description
VPS_HOST	93.95.228.142	Main VPS IP
VPS_USER	root	VPS SSH user
SSH_KEY	~/.ssh/id_ed25519_1984	SSH key path
DEBUG	false	Enable debug logging

Adding New Commands

1. Create script in scripts/commands/<category>/<name>.sh
2. Start with library imports:

   #!/bin/bash
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   source "${SCRIPT_DIR}/../../lib/core/init.sh"
   log_init "CATEGORY"
   

3. The CLI wrapper automatically discovers new scripts
4. Add completion hints if needed

---

Generated by Claude Code