@aerocorp/cli/README.md

AeroCorp CLI 5.1.0 - Future-Proofed Enterprise Infrastructure with Live Preview, Tunneling & Advanced DevOps

# AeroCorp CLI 5.0.0 - Coolify-Aware Edition

🚀 **Enterprise CLI with Battle-Tested Coolify Integration & PR Previews**

The AeroCorp CLI is a powerful, enterprise-grade command-line tool implementing **battle-tested deployment patterns** for Coolify with proper API authentication, PR preview deployments, and WSL integration.

## 🆕 What's New in 5.0.0

✅ **Battle-tested Coolify integration** with proper `/api/version` health checks
✅ **PR Preview deployments** with automatic lifecycle management
✅ **WSL integration** for SSH and Docker operations on Windows
✅ **Enhanced authentication** using API tokens (not SSH credentials)
✅ **GitHub Actions** workflow for automated preview deployments
✅ **Improved error handling** with clear troubleshooting guidance

## ✨ Core Features

- 🔐 **Proper API Authentication** - Uses Coolify API tokens, not SSH credentials
- 🔄 **PR Preview Deployments** - Create/destroy preview environments per PR
- 🐧 **WSL Integration** - SSH fallback for logs and Docker operations
- 🏥 **Health Monitoring** - Proper `/api/version` endpoint checks
- 🚀 **One-Command Deployment** - Deploy to production, staging, or preview
- 📊 **Real-time Monitoring** - Live deployment status and log streaming
- 🛡️ **Security First** - Zero-trust architecture with rate limiting
- 🌐 **Multi-Environment** - Production, staging, and ephemeral preview envs

## 🚀 Quick Start

### Installation

```bash
# Install globally via NPM
npm install -g @aerocorp/cli

# Or use directly with npx
npx @aerocorp/cli --version
```

### Authentication (Battle-Tested Method)

#### Option 1: Environment Variable (Recommended for CI/CD)
```bash
# Generate API token in Coolify: Dashboard → Keys & Tokens → API tokens
export COOLIFY_TOKEN="your-coolify-api-token-here"
aerocorp coolify health  # Test connection
```

#### Option 2: Interactive Login
```bash
aerocorp coolify login
# Enter your Coolify URL and API token when prompted
```

#### Option 3: Legacy Root Token (Deprecated)
```bash
export AEROCORP_CLI_ROOT_API_TOKEN="your-legacy-token"
aerocorp login
```

> **⚠️ Important**: Use Coolify API tokens for automation, SSH keys for terminal access. Both are required for full functionality.

### 🚀 Vercel-like Deployment (Windows Native)

```bash
# Deploy like Vercel - works natively on Windows, macOS, Linux
aerocorp deploy                    # Deploy to staging
aerocorp deploy --prod             # Deploy to production
aerocorp deploy --preview          # Deploy to preview

# With specific options
aerocorp deploy --prod --app <uuid> --branch main
aerocorp deploy --preview --app <uuid> --branch feature/new-ui
```

### 🔄 PR Preview Deployments

```bash
# Create PR preview (like Vercel)
aerocorp preview up --pr 123 --app <uuid> --branch feature/awesome

# Destroy PR preview
aerocorp preview down --pr 123 --app <uuid>
```

### 🪟 Windows Native Setup (No WSL Required)

```powershell
# Check Windows environment
aerocorp windows check

# Install OpenSSH client (requires admin)
aerocorp windows install-ssh

# Setup SSH keys for fallback access
aerocorp windows setup-ssh

# Test all functionality
aerocorp windows test

# Get system information
aerocorp windows info
```

### 📋 Logs & Monitoring

```bash
# Get logs via API (primary method)
aerocorp logs <uuid>

# Get logs via SSH (fallback)
aerocorp logs <uuid> --ssh

# Follow logs in real-time
aerocorp logs <uuid> --follow

# Windows native SSH logs
aerocorp logs <uuid> --ssh --lines 200
```

### Basic Usage (Legacy)

```bash
# Deploy to production
aerocorp deploy --prod

# Deploy to staging
aerocorp deploy --staging

# List all projects and applications
aerocorp list

# View application logs
aerocorp logs my-app --follow

# Check system health
aerocorp health

# Show system status
aerocorp status
```

## 🪟 Windows Native Setup Guide

### Prerequisites
- Windows 10 (1803+) or Windows 11
- Node.js 18+ installed
- PowerShell 5.1+ or PowerShell Core 7+

### Quick Setup (Automated)
```powershell
# Run as Administrator for complete setup
.\scripts\setup-windows.ps1 -All
```

### Manual Setup Steps

#### 1. Install OpenSSH Client (if not available)
```powershell
# Check if SSH is available
ssh -V

# If not available, install (requires admin)
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

# Or use the CLI
aerocorp windows install-ssh
```

#### 2. Setup SSH Keys (for fallback access)
```powershell
# Generate SSH keys
aerocorp windows setup-ssh

# Or manually
ssh-keygen -t ed25519 -C "aerocorp-cli@windows" -f %USERPROFILE%\.ssh\id_ed25519
```

#### 3. Test Everything
```powershell
# Test Windows environment
aerocorp windows check

# Test Coolify API connectivity
aerocorp coolify health

# Test SSH connectivity (fallback)
aerocorp windows test
```

### 🎯 How It Works (Like Vercel)

1. **Primary Method**: HTTP API calls to Coolify (no SSH required)
2. **Fallback Method**: Windows native SSH client (`ssh.exe`)
3. **Pure Node.js**: ssh2 library for cross-platform compatibility
4. **Auto-detection**: Automatically chooses best method available

```bash
# This works exactly like "npx vercel --prod"
aerocorp deploy --prod
```

### 🔧 Troubleshooting Windows Issues

#### SSH Client Not Found
```powershell
# Install OpenSSH client
aerocorp windows install-ssh

# Or manually via Settings
# Settings → Apps → Optional Features → Add "OpenSSH Client"
```

#### Connection Issues
```powershell
# Check network connectivity
Test-NetConnection -ComputerName 128.140.35.238 -Port 22

# Test SSH connection
aerocorp windows test

# Get detailed system info
aerocorp windows info
```

#### PowerShell Execution Policy
```powershell
# If scripts are blocked
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run with bypass
powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1
```

## 📖 Commands

### Authentication & Configuration

```bash
# Login to Coolify
aerocorp login [--url <coolify-url>] [--token <api-token>]

# Manage configuration
aerocorp config --list                    # List all config
aerocorp config --set key=value          # Set config value
aerocorp config --get key                # Get config value
aerocorp config --reset                  # Reset all config
```

### Deployment

```bash
# Deploy commands
aerocorp deploy [options]
aerocorp d [options]                     # Short alias

# Deployment options
--prod                                   # Deploy to production
--staging                               # Deploy to staging
--preview                               # Deploy as preview
--force                                 # Force deployment without cache
--build-env "KEY1=value1,KEY2=value2"  # Build environment variables
--env "KEY1=value1,KEY2=value2"        # Runtime environment variables
--name <app-name>                       # Override application name
--region <regions>                      # Deploy to specific regions
--scale <replicas>                      # Number of replicas
```

### Project Management

```bash
# List projects and applications
aerocorp list [--format json]           # List all projects
aerocorp ls                             # Short alias

# Project operations (coming soon)
aerocorp create <project-name>          # Create new project
aerocorp delete <project-id>            # Delete project
```

### Monitoring & Logs

```bash
# View logs
aerocorp logs <app-name> [options]

# Log options
--follow                                # Follow log output
--tail <lines>                         # Number of lines to show (default: 100)

# Health & Status
aerocorp health                         # Run health checks
aerocorp status                         # Show system status
```

## ⚙️ Configuration

The CLI stores configuration in `~/.aerocorp/config.json`:

```json
{
  "coolify_url": "https://coolify.aerocorpindustries.org",
  "api_token": "your-api-token",
  "server_ip": "128.140.35.238",
  "environment": "production",
  "authenticated": true,
  "root_access": true
}
```

### Environment Variables

- `AEROCORP_CLI_ROOT_API_TOKEN` - Root API token for automatic authentication
- `COOLIFY_URL` - Override default Coolify URL
- `AEROCORP_DEBUG` - Enable debug logging

## 🏗️ Project Configuration

Create an `aerocorp.json` file in your project root:

```json
{
  "name": "my-awesome-app",
  "description": "My awesome AeroCorp application",
  "environment": "production",
  "buildEnv": {
    "NODE_ENV": "production",
    "BUILD_TARGET": "production"
  },
  "runtimeEnv": {
    "PORT": "3000",
    "DATABASE_URL": "postgresql://..."
  },
  "regions": ["us-east-1", "eu-west-1"],
  "replicas": 2,
  "healthCheck": {
    "path": "/health",
    "interval": 30
  }
}
```

## 🔧 Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/aerocorp13/aerocorp-cli.git
cd aerocorp-cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link for local development
npm link

# Test the CLI
aerocorp --version
```

### Running Tests

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- --grep "auth"
```

## 🚀 Deployment Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AeroCorp CLI  │───▶│  Coolify Server  │───▶│  Docker Swarm   │
│                 │    │  128.140.35.238  │    │   Applications  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       ▼                       ▼
         │              ┌──────────────────┐    ┌─────────────────┐
         │              │   AI-Proxy API   │    │   Load Balancer │
         │              │    Port: 8082    │    │   Traefik/Nginx │
         │              └──────────────────┘    └─────────────────┘
         │
         ▼
┌─────────────────┐
│  Configuration  │
│ ~/.aerocorp/    │
└─────────────────┘
```

## 🔐 Security

- **API Token Encryption** - Tokens are stored securely in local config
- **Root Access Control** - Root tokens provide full system access
- **Environment Isolation** - Separate configs for different environments
- **Secure Communication** - All API calls use HTTPS with proper headers

## 🐛 Troubleshooting

### Common Issues

1. **Authentication Failed**
   ```bash
   # Check your token
   aerocorp config --get api_token

   # Re-authenticate
   aerocorp login
   ```

2. **Deployment Stuck**
   ```bash
   # Check deployment status
   aerocorp status

   # Force redeploy
   aerocorp deploy --prod --force
   ```

3. **Connection Issues**
   ```bash
   # Run health check
   aerocorp health

   # Check server connectivity
   ping 128.140.35.238
   ```

### Debug Mode

```bash
export AEROCORP_DEBUG=true
aerocorp deploy --prod
```

## 📞 Support

- 📧 **Email**: support@aerocorpindustries.org
- 🐛 **Issues**: [GitHub Issues](https://github.com/aerocorp13/aerocorp-cli/issues)
- 📖 **Documentation**: [AeroCorp Docs](https://docs.aerocorpindustries.org)
- 💬 **Discord**: [AeroCorp Community](https://discord.gg/aerocorp)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🚀 Roadmap

- [ ] **Multi-Cloud Support** - AWS, GCP, Azure deployments
- [ ] **Advanced Monitoring** - Metrics and alerting integration
- [ ] **CI/CD Integration** - GitHub Actions, GitLab CI templates
- [ ] **Database Management** - Database migrations and backups
- [ ] **Secret Management** - Encrypted environment variables
- [ ] **Team Collaboration** - Multi-user project management

---

**Made with ❤️ by AeroCorp Industries**