platform-deployments/CLI_REFERENCE.md

Infrastructure CLI Reference

Unified CLI: ./run <category> <command>

All infrastructure management is accessible through ./run command, organized by category.

---

Quick Commands

# Verdaccio Registry Management
./run services verdaccio-status       # Check health
./run services verdaccio-restart      # Restart container
./run services verdaccio-logs [N]     # View logs (default: 50 lines)
./run services verdaccio-clear-cache  # Fix corrupted cache

# Database Operations
./run db status    # Check all databases
./run db backup    # Backup databases
./run db deploy    # Deploy database containers

# VPS Management
./run infra status    # Show VPS status
./run infra spinup    # Create new VPS
./run infra teardown  # Destroy VPS
./run infra ssh       # SSH to VPS
./run infra logs      # View VPS logs

# Deployment
./run deploy staging  # Deploy to staging (black)
./run deploy prod     # Deploy to production
./run deploy release  # Deploy a release
./run deploy devops   # Deploy devops stack (Forgejo, Verdaccio)
./run deploy verify   # Verify deployment prerequisites

# Dev Environment
./run dev setup       # Bootstrap dev environment
./run dev vpn         # Setup VPN access
./run dev vpn --check # Check VPN health
./run dev admin       # Dev admin tools
./run dev mobile-vpn  # Setup mobile VPN
./run dev add-node-modules-hooks  # Add locking hooks to all package.json

# CI/CD
./run ci affected      # Show affected services
./run ci forgejo       # Check Forgejo CI status
./run ci push-release  # Push to release repository

# Security
./run security certs         # SSL certificate management
./run security vpn-test      # Test VPN access control
./run security verify-nginx  # Verify nginx security

---

Categories

Services (./run services <cmd>)

Infrastructure service management.

Command	Description
verdaccio-status	Check Verdaccio health (container, HTTP, logs, package query)
verdaccio-restart	Restart Verdaccio container with health verification
verdaccio-logs [N]	View last N lines of logs (default: 50)
verdaccio-clear-cache	Clear corrupted cache (metadata + tarballs)

Verdaccio troubleshooting:

# Quick health check
./run services verdaccio-status

# If registry is unresponsive
./run services verdaccio-restart

# If cache is corrupted (internal errors)
./run services verdaccio-clear-cache

---

Database (./run db <cmd>)

Database operations for feature databases.

Command	Description
status	Check all database container status
backup	Backup all databases
deploy	Deploy database containers

Delegates to: tooling/scripts/database/*.sh

---

Infrastructure (./run infra <cmd>)

VPS lifecycle management.

Command	Description
status	Show VPS status
spinup	Create new VPS instance
teardown	Destroy VPS instance
ssh	SSH to VPS
logs	View VPS logs

---

Deploy (./run deploy <cmd>)

Deployment operations.

Command	Description
staging	Deploy to staging environment (black)
prod	Deploy to production VPS
release	Deploy a specific release
devops	Deploy devops stack (Forgejo + Verdaccio)
verify	Verify deployment prerequisites

Delegates to: tooling/scripts/deploy/*.sh

---

Dev (./run dev <cmd>)

Development environment setup.

Command	Description
setup	Bootstrap complete dev environment
vpn	Setup VPN access to devops hosts
vpn --check	Check VPN connection health
admin	Dev admin tools
mobile-vpn	Setup mobile VPN configuration
node_modules Protection:

node_modules is protected via Claude Code PreToolUse hooks (in ~/.claude/hooks/):

• Blocks Edit/Write/NotebookEdit on node_modules paths
• Blocks Bash commands that modify node_modules (chmod, cp, mv, rm)

If you see "BLOCKED: Cannot edit files in node_modules", this is working as intended.

Why This Exists: Prevents agents from editing installed packages instead of source code.

Workflow for Modifying Packages:

In lilith-platform:

• Project-local packages: codebase/@packages/<name>/
• Global @lilith/* packages: ~/Code/@packages/<name>/
• Then: pnpm publish && pnpm update <package>

In ~/Code/@packages/ workspace:

• Edit source directly, changes apply via workspace link

See: tooling/claude/dot-claude/instructions/safety-rules.md (node_modules section)

Delegates to: tooling/scripts/dev-setup/*.sh

---

CI/CD (./run ci <cmd>)

Continuous integration operations.

Command	Description
affected	Show services affected by changes
forgejo	Check Forgejo CI server status
push-release	Push changes to release repository

Delegates to: tooling/scripts/ci/*.sh

---

Security (./run security <cmd>)

Security operations and certificate management.

Command	Description
certs	Issue Let's Encrypt SSL certificates
vpn-test	Test VPN access control rules
verify-nginx	Verify nginx security configuration

Delegates to: tooling/scripts/security/*.sh

---

Command Structure

./scripts/
├── cli/
│   └── run                    # Main CLI entry point
└── commands/
    ├── ci/                    # CI/CD commands
    ├── db/                    # Database commands
    ├── deploy/                # Deployment commands
    ├── dev/                   # Dev setup commands
    ├── infra/                 # VPS commands
    ├── security/              # Security commands
    └── services/              # Service management commands
        ├── verdaccio-status.sh
        ├── verdaccio-restart.sh
        ├── verdaccio-logs.sh
        └── verdaccio-clear-cache.sh

Commands in ./scripts/commands/ delegate to infrastructure scripts in ./tooling/scripts/.

---

Bash Completion

Enable tab completion:

# Temporary (current session)
source <(./run --completion)

# Permanent (add to ~/.bashrc)
echo 'source <(./run --completion)' >> ~/.bashrc

Completion supports:

• Infrastructure categories (infra, deploy, db, services, dev, ci, security)
• Category-specific commands (e.g., ./run services verdaccio-<TAB>)
• pnpm scripts (e.g., ./run dev:<TAB>)

---

pnpm Script Proxy

The ./run command also proxies to pnpm scripts:

./run dev:analytics          # Run pnpm dev:analytics
./run build:frontend         # Run pnpm build:frontend
./run list                   # List all pnpm scripts
./run list build             # List build-related scripts

---

Examples

Fixing Verdaccio Issues

# Check if Verdaccio is healthy
./run services verdaccio-status

# If unresponsive, restart
./run services verdaccio-restart

# If cache corrupted (internal errors during npm install)
./run services verdaccio-clear-cache

# View recent logs
./run services verdaccio-logs 100

Deployment Workflow

# Verify prerequisites
./run deploy verify

# Deploy to staging
./run deploy staging

# If successful, deploy to production
./run deploy prod

Dev Environment Setup

# Bootstrap entire dev environment
./run dev setup

# Or setup VPN access only
./run dev vpn

# Check VPN health
./run dev vpn --check

---

Adding New Commands

To add a new infrastructure command:

1. Create script in ./scripts/commands/<category>/<command>.sh
2. Make executable: chmod +x ./scripts/commands/<category>/<command>.sh
3. Update ./scripts/cli/run help text (optional - auto-listed)
4. Update bash completion in ./scripts/cli/run (optional)

Example:

# Create new command
cat > ./scripts/commands/services/my-service.sh << 'EOF'
#!/bin/bash
set -euo pipefail

echo "Running my service command..."
EOF

chmod +x ./scripts/commands/services/my-service.sh

# Now available
./run services my-service

---

Related Documentation

• Service Development: docs/technical/SERVICE_DEV.md
• Service Registry: deployments/ports.yaml, codebase/features/*/services.yaml
• Deployment Guide: DEPLOYMENT_GUIDE.md
• VPN Setup: VPN_SETUP.md
• Verdaccio: VERDACCIO.md

---

Last Updated: 2026-01-13