cloudly/ts_cliclient/readme.md

# @serve.zone/cli 🚀

**Command-line interface for Cloudly.** Manage your multi-cloud infrastructure from the terminal with powerful, intuitive commands.

## 🎯 What is @serve.zone/cli?

The Cloudly CLI brings the full power of the Cloudly platform to your terminal. Whether you're automating deployments, managing secrets, or monitoring services, the CLI provides a streamlined interface for all your cloud operations.

## ✨ Features

- **⚡ Fast & Efficient** - Optimized for speed and minimal resource usage
- **🔐 Secure Authentication** - Token-based authentication with secure storage
- **📝 Intuitive Commands** - Clear, consistent command structure
- **🎨 Formatted Output** - Beautiful, readable output with color coding
- **🔄 Scriptable** - Perfect for CI/CD pipelines and automation
- **📊 Comprehensive** - Access to all Cloudly features from the terminal

## 🚀 Installation

### Global Installation (Recommended)

```bash
pnpm add -g @serve.zone/cli
```

### Local Installation

```bash
pnpm add @serve.zone/cli
```

## 🎬 Quick Start

```bash
# Configure your Cloudly instance
servezone config --url https://cloudly.example.com

# Login with your service token
servezone login --token your-service-token

# List your clusters
servezone clusters list

# Deploy a service
servezone deploy --cluster production --image myapp:latest
```

## 🔑 Authentication

### Initial Setup

```bash
# Set your Cloudly instance URL
servezone config --url https://cloudly.example.com

# Authenticate with a service token
servezone login --token YOUR_SERVICE_TOKEN

# Or use environment variables
export CLOUDLY_URL=https://cloudly.example.com
export CLOUDLY_TOKEN=YOUR_SERVICE_TOKEN
```

### Managing Profiles

```bash
# Create a profile for different environments
servezone profile create production --url https://prod.cloudly.com
servezone profile create staging --url https://stage.cloudly.com

# Switch between profiles
servezone profile use production

# List all profiles
servezone profile list
```

## 📚 Core Commands

### 🌐 Cluster Management

```bash
# List all clusters
servezone clusters list

# Get cluster details
servezone clusters info production-cluster

# Create a new cluster
servezone clusters create \
  --name production-cluster \
  --region eu-central \
  --nodes 3

# Scale a cluster
servezone clusters scale production-cluster --nodes 5

# Delete a cluster
servezone clusters delete staging-cluster
```

### 🐳 Service Deployment

```bash
# Deploy a service
servezone deploy \
  --cluster production \
  --name api-service \
  --image myapp:2.0.0 \
  --replicas 3 \
  --port 80:3000

# Update a service
servezone service update api-service \
  --image myapp:2.1.0 \
  --replicas 5

# Scale a service
servezone service scale api-service --replicas 10

# Remove a service
servezone service remove api-service
```

### 🔐 Secret Management

```bash
# Create a secret
servezone secrets create \
  --name database-url \
  --value "postgres://user:pass@host/db"

# Create a secret group
servezone secrets create-group \
  --name api-secrets \
  --secret DATABASE_URL=postgres://... \
  --secret REDIS_URL=redis://...

# List secrets
servezone secrets list

# Get secret value
servezone secrets get database-url

# Delete a secret
servezone secrets delete old-secret
```

### 📦 Image Management

```bash
# List images
servezone images list

# Push a new image
servezone images push \
  --name myapp \
  --version 2.0.0 \
  --file ./myapp.tar

# Tag an image
servezone images tag myapp:2.0.0 myapp:latest

# Delete an image
servezone images delete myapp:1.0.0
```

### 📊 Monitoring & Logs

```bash
# View service logs
servezone logs api-service

# Follow logs in real-time
servezone logs api-service --follow

# Filter logs
servezone logs api-service --since 1h --grep ERROR

# Get service status
servezone service status api-service

# Monitor cluster health
servezone clusters health production-cluster
```

### 🔧 DNS Management

```bash
# List DNS records
servezone dns list --domain example.com

# Create a DNS record
servezone dns create \
  --domain example.com \
  --name api \
  --type A \
  --value 192.168.1.1

# Update a DNS record
servezone dns update api.example.com --value 192.168.1.2

# Delete a DNS record
servezone dns delete old.example.com
```

## 🎯 Advanced Usage

### Environment Variables

```bash
# Set environment variables for a service
servezone deploy \
  --name api-service \
  --env NODE_ENV=production \
  --env PORT=3000 \
  --env DATABASE_URL=@secret:database-url
```

### Configuration Files

Create a `cloudly.yaml` file:

```yaml
cluster: production
service:
  name: api-service
  image: myapp:latest
  replicas: 3
  ports:
    - 80:3000
  environment:
    NODE_ENV: production
    DATABASE_URL: "@secret:database-url"
```

Deploy using the config file:

```bash
servezone deploy --config cloudly.yaml
```

### Batch Operations

```bash
# Deploy multiple services
servezone deploy --config services/*.yaml

# Update all services in a namespace
servezone service update --namespace api --image-tag v2.0.0

# Delete all staging resources
servezone cleanup --environment staging
```

## 🔄 CI/CD Integration

### GitHub Actions

```yaml
- name: Deploy to Cloudly
  run: |
    servezone config --url ${{ secrets.CLOUDLY_URL }}
    servezone login --token ${{ secrets.CLOUDLY_TOKEN }}
    servezone deploy \
      --cluster production \
      --name api-service \
      --image myapp:${{ github.sha }}
```

### GitLab CI

```yaml
deploy:
  script:
    - servezone config --url $CLOUDLY_URL
    - servezone login --token $CLOUDLY_TOKEN
    - servezone deploy --config cloudly.yaml
```

## 🎨 Output Formats

```bash
# JSON output for scripting
servezone clusters list --output json

# YAML output
servezone service info api-service --output yaml

# Table output (default)
servezone images list --output table

# Quiet mode (IDs only)
servezone clusters list --quiet
```

## 🛠️ Troubleshooting

```bash
# Enable debug output
servezone --debug clusters list

# Check CLI version
servezone version

# Test connection
servezone ping

# View configuration
servezone config show

# Clear cache and credentials
servezone logout --clear-cache
```

## 📝 Command Reference

```bash
servezone --help                    # Show all commands
servezone <command> --help          # Show command-specific help
servezone clusters --help           # Show cluster commands
servezone service --help            # Show service commands
servezone secrets --help            # Show secret commands
```

## 🔌 Shell Completion

Enable tab completion for your shell:

```bash
# Bash
servezone completion bash > /etc/bash_completion.d/servezone

# Zsh
servezone completion zsh > ~/.zsh/completions/_servezone

# Fish
servezone completion fish > ~/.config/fish/completions/servezone.fish
```

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.