Diagnostic Commands

Quick reference for diagnosing issues with Seed & Source templates. Run these commands to check system health, identify problems, and gather debugging information.

Quick Navigation:

System Check
License Check
Service Health Check
Docker Diagnostics
Logs
Network Check
Database Check
File Integrity Check
Performance Check

System Check

Verify all required tools are installed and up to date:

# CLI version
sscli --version

# Expected: sscli version 2.x.x

# Docker version
docker --version
docker-compose --version

# Expected: Docker version 20.10+ and docker-compose 2.x+

# Python version
python --version
python3 --version

# Expected: Python 3.10+

# Node.js version (for React templates)
node --version
npm --version

# Expected: Node 18+ and npm 9+

# Git version
git --version

# Expected: git 2.30+

One-liner system check:

echo "CLI: $(sscli --version 2>&1 | head -1)" && \
echo "Docker: $(docker --version)" && \
echo "Python: $(python --version 2>&1)" && \
echo "Node: $(node --version 2>&1)" && \
echo "Git: $(git --version)"

License Check

Verify authentication and license tier:

# Show current user and license info
sscli whoami

# Expected output:
# 👤 User: your-email@example.com
# 🏆 Tier: PRO/ALPHA
# 📅 Expires: 2027-01-01
# ✨ Status: ACTIVE

# Check if authenticated
sscli auth login --check

# View available templates for your tier
sscli explore

# Check license config file
cat ~/.config/sscli/config.json

# Re-authenticate if needed
sscli auth login YOUR_LICENSE_KEY

Service Health Check

Check if all services are running and accessible:

# Check backend service
curl http://localhost:8000/health

# Expected: {"status":"healthy"} or similar

# Check frontend service
curl http://localhost:3000

# Expected: HTML content or redirect

# Check with headers
curl -I http://localhost:8000/health

# Expected: HTTP/1.1 200 OK

# Test API endpoint
curl http://localhost:8000/api/users

# Check all service URLs
echo "Backend: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/health)"
echo "Frontend: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000)"

Quick health check script:

#!/bin/bash
# save as check_health.sh

services=("Backend:http://localhost:8000/health" "Frontend:http://localhost:3000")

for service in "${services[@]}"; do
    name="${service%%:*}"
    url="${service#*:}"
    status=$(curl -s -o /dev/null -w '%{http_code}' "$url")

    if [ "$status" -eq 200 ]; then
        echo "✅ $name is healthy ($status)"
    else
        echo "❌ $name is down ($status)"
    fi
done

Docker Diagnostics

Check Docker containers, images, and resources:

# List running containers
docker ps

# List all containers (including stopped)
docker ps -a

# Check container status with filters
docker ps --filter "status=running"
docker ps --filter "status=exited"

# Show Docker images
docker images

# Check Docker disk usage
docker system df

# Output shows:
# - Images size
# - Containers size
# - Local volumes size
# - Build cache size

# Detailed disk usage
docker system df -v

# Check specific container
docker inspect seedsource-marketing-backend

# Check container resource usage
docker stats

# One-time stats (no realtime)
docker stats --no-stream

# Check if Docker daemon is healthy
docker info

Quick Docker health check:

# Check if containers are running
RUNNING=$(docker ps --filter "status=running" --format "{{.Names}}" | wc -l)
TOTAL=$(docker ps -a --format "{{.Names}}" | wc -l)

echo "Running containers: $RUNNING/$TOTAL"

# Show containers with exit codes
docker ps -a --filter "status=exited" --format "table {{.Names}}\t{{.Status}}"

Logs

View application and service logs:

# All services logs (realtime)
docker-compose logs -f

# Specific service logs
docker logs seedsource-marketing-backend

# Follow specific service logs (realtime)
docker logs -f seedsource-marketing-backend

# Last 100 lines
docker-compose logs --tail=100

# Last 50 lines with timestamps
docker-compose logs -f --tail=50 --timestamps

# Logs for specific service
docker-compose logs backend
docker-compose logs frontend
docker-compose logs db

# Logs since specific time
docker logs --since 30m seedsource-marketing-backend
docker logs --since 2024-01-01T10:00:00 seedsource-marketing-backend

# Search logs for errors
docker-compose logs | grep -i error
docker-compose logs | grep -i exception
docker-compose logs | grep -i failed

# Export logs to file
docker-compose logs > docker-logs.txt
docker logs seedsource-marketing-backend > backend-logs.txt 2>&1

Log analysis commands:

# Count errors
docker-compose logs | grep -c ERROR

# Show unique error messages
docker-compose logs | grep ERROR | sort | uniq

# Find errors with context (5 lines before/after)
docker-compose logs | grep -B 5 -A 5 ERROR

Network Check

Check ports, connections, and network availability:

# Check if ports are in use
lsof -i :8000  # Backend
lsof -i :3000  # Frontend
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis (if used)

# Check all listening ports
lsof -i -P | grep LISTEN

# Check network connectivity
ping -c 3 localhost
ping -c 3 google.com

# Check DNS resolution
nslookup localhost
nslookup google.com

# Test specific endpoint with timing
time curl http://localhost:8000/health

# Check Docker network
docker network ls

# Inspect Docker network
docker network inspect [network_name]

# Check if containers can reach each other
docker-compose exec backend ping db
docker-compose exec backend curl http://db:5432

# Check open connections to database
# macOS/Linux:
lsof -i | grep postgres | wc -l

# Check firewall rules (Linux)
sudo iptables -L

Port conflict check:

#!/bin/bash
# Check common ports used by templates

PORTS=(8000 3000 5432 6379)

for port in "${PORTS[@]}"; do
    if lsof -Pi :$port -sTCP:LISTEN -t >/dev/null; then
        echo "⚠️  Port $port is in use:"
        lsof -i :$port
    else
        echo "✅ Port $port is available"
    fi
done

Database Check

Verify database connectivity and health:

# Check if PostgreSQL container is running
docker ps | grep postgres

# Check database connection
psql $DATABASE_URL -c "SELECT 1"

# Or with docker-compose:
docker-compose exec db psql -U postgres -d myapp -c "SELECT 1"

# List databases
docker-compose exec db psql -U postgres -l

# Check database size
docker-compose exec db psql -U postgres -d myapp -c "SELECT pg_size_pretty(pg_database_size('myapp'))"

# Count tables
docker-compose exec db psql -U postgres -d myapp -c "\dt"

# Check active connections
docker-compose exec db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity"

# Show running queries
docker-compose exec db psql -U postgres -c "SELECT pid, usename, query, state FROM pg_stat_activity WHERE state = 'active'"

# Check database logs
docker logs seedsource-marketing-db

# Test connection from Python
python -c "
from sqlalchemy import create_engine
import os
engine = create_engine(os.getenv('DATABASE_URL'))
print('✅ Database connection successful')
print(engine.connect())
"

Database health script:

#!/bin/bash
# Check PostgreSQL health

# Connection test
if docker-compose exec -T db psql -U postgres -c "SELECT 1" > /dev/null 2>&1; then
    echo "✅ Database connection: OK"
else
    echo "❌ Database connection: FAILED"
    exit 1
fi

# Check if migrations applied
MIGRATION_COUNT=$(docker-compose exec -T db psql -U postgres -d myapp -t -c "SELECT count(*) FROM alembic_version" 2>/dev/null | tr -d ' ')

if [ -n "$MIGRATION_COUNT" ]; then
    echo "✅ Migrations: $MIGRATION_COUNT applied"
else
    echo "⚠️  Migrations: Table not found (may need to run migrations)"
fi

File Integrity Check

Verify project structure and important files:

# Check if project generated with sscli
cat .sscli-metadata.json

# Expected: JSON with template info and features

# Check essential files exist
ls -la .env
ls -la docker-compose.yml
ls -la Dockerfile
ls -la requirements.txt  # Python
ls -la package.json      # Node.js
ls -la Gemfile          # Ruby

# Check injection markers (Python)
grep -r "# SSCLI:" src/

# Check injection markers (JavaScript)
grep -r "// SSCLI:" src/

# Validate Python syntax
find . -name "*.py" -not -path "*/venv/*" -not -path "*/.venv/*" | xargs python -m py_compile

# Validate JSON files
find . -name "*.json" | xargs -I {} sh -c 'echo "Checking {}" && python -m json.tool {} > /dev/null'

# Check for common issues
# - Mixed indentation
find . -name "*.py" | xargs grep -l $'\t' | head -10

# - Trailing whitespace
find . -name "*.py" | xargs grep -l ' $' | head -10

# Check git status
git status

# Check for uncommitted changes
git diff --stat

Project structure validator:

#!/bin/bash
# Validate expected project structure

REQUIRED_FILES=(
    ".sscli-metadata.json"
    "docker-compose.yml"
    "Dockerfile"
    ".env.example"
)

echo "Checking project structure..."

for file in "${REQUIRED_FILES[@]}"; do
    if [ -f "$file" ]; then
        echo "✅ $file exists"
    else
        echo "❌ $file missing"
    fi
done

# Check template-specific files
if grep -q "python-saas" .sscli-metadata.json 2>/dev/null; then
    echo "Template: python-saas"
    [ -f "requirements.txt" ] && echo "✅ requirements.txt exists" || echo "❌ requirements.txt missing"
    [ -f "pyproject.toml" ] && echo "✅ pyproject.toml exists" || echo "❌ pyproject.toml missing"
fi

if grep -q "react-client" .sscli-metadata.json 2>/dev/null; then
    echo "Template: react-client"
    [ -f "package.json" ] && echo "✅ package.json exists" || echo "❌ package.json missing"
    [ -f "tsconfig.json" ] && echo "✅ tsconfig.json exists" || echo "❌ tsconfig.json missing"
fi

Performance Check

Monitor resource usage and performance:

# Docker container resource usage
docker stats --no-stream

# Check CPU and memory per container
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# System resource usage
top -l 1 | head -10  # macOS
htop                  # Linux

# Disk space
df -h

# Check inode usage (Linux)
df -i

# Memory usage
free -h  # Linux
vm_stat  # macOS

# Check load average
uptime

# Measure API response time
time curl -s http://localhost:8000/health > /dev/null

# Measure with detailed timing
curl -w "@-" -o /dev/null -s http://localhost:8000/health <<'EOF'
    time_namelookup:  %{time_namelookup}\n
       time_connect:  %{time_connect}\n
    time_appconnect:  %{time_appconnect}\n
   time_pretransfer:  %{time_pretransfer}\n
      time_redirect:  %{time_redirect}\n
 time_starttransfer:  %{time_starttransfer}\n
                    ----------\n
         time_total:  %{time_total}\n
EOF

# Database query performance
docker-compose exec db psql -U postgres -d myapp -c "EXPLAIN ANALYZE SELECT * FROM users LIMIT 10"

Performance monitoring script:

#!/bin/bash
# Monitor system and container performance

echo "=== System Resources ==="
df -h | grep -E '^/dev/' | awk '{print "Disk: " $5 " used of " $2}'
free -h | grep Mem | awk '{print "Memory: " $3 " used of " $2}'

echo -e "\n=== Docker Containers ==="
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}"

echo -e "\n=== API Response Time ==="
time curl -s http://localhost:8000/health > /dev/null

Complete Diagnostic Report

Run all checks and generate a report:

#!/bin/bash
# Complete system diagnostic report
OUTPUT="diagnostic_report_$(date +%Y%m%d_%H%M%S).txt"

{
    echo "=== SEED & SOURCE DIAGNOSTIC REPORT ==="
    echo "Generated: $(date)"
    echo ""

    echo "=== SYSTEM INFO ==="
    echo "OS: $(uname -a)"
    echo "CLI: $(sscli --version 2>&1)"
    echo "Docker: $(docker --version 2>&1)"
    echo "Python: $(python --version 2>&1)"
    echo "Node: $(node --version 2>&1)"
    echo ""

    echo "=== LICENSE INFO ==="
    sscli whoami 2>&1
    echo ""

    echo "=== DOCKER CONTAINERS ==="
    docker ps -a
    echo ""

    echo "=== DOCKER RESOURCES ==="
    docker system df
    echo ""

    echo "=== SERVICE HEALTH ==="
    curl -s -o /dev/null -w "Backend (8000): %{http_code}\n" http://localhost:8000/health
    curl -s -o /dev/null -w "Frontend (3000): %{http_code}\n" http://localhost:3000
    echo ""

    echo "=== PORTS IN USE ==="
    lsof -i :8000,3000,5432 2>&1
    echo ""

    echo "=== PROJECT METADATA ==="
    cat .sscli-metadata.json 2>&1
    echo ""

    echo "=== RECENT DOCKER LOGS (Last 50 lines) ==="
    docker-compose logs --tail=50 2>&1
    echo ""

    echo "=== END OF REPORT ==="
} | tee "$OUTPUT"

echo "Report saved to: $OUTPUT"

Usage:

# Make executable
chmod +x diagnostic_report.sh

# Run diagnostic
./diagnostic_report.sh

# Output saved to: diagnostic_report_20260228_143022.txt

Emergency Troubleshooting

When something is completely broken:

# 1. Stop everything
docker-compose down

# 2. Clean Docker
docker system prune -a
docker volume prune

# 3. Restart Docker Desktop (macOS)
killall Docker && open -a Docker

# 4. Fresh start
docker-compose up -d --build

# 5. Check logs
docker-compose logs -f

# 6. If still broken, generate diagnostic report
./diagnostic_report.sh

# 7. Create GitHub issue with report
# https://github.com/seed-source/stack-cli/issues

Common Errors & Solutions - Detailed solutions for top 20 errors
Injection Issues - Feature injection troubleshooting
Webhook Failures - Webhook debugging guide

Last Updated: February 28, 2026 Version: 1.0 Maintainer: Seed & Source Team

Diagnostic Commands

Diagnostic Commands

System Check

License Check

Service Health Check

Docker Diagnostics

Logs

Network Check

Database Check

File Integrity Check

Performance Check

Complete Diagnostic Report

Emergency Troubleshooting

Related Documentation