> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultrabalancer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Simple command-line reference for UltraBalancer

## Quick Start

```bash theme={null}
# Basic usage - 2 backends, round-robin
ultrabalancer -b server1:8080 -b server2:8080

# Custom port
ultrabalancer -p 80 -b backend1:8080 -b backend2:8080

# With weights
ultrabalancer -b server1:8080:200 -b server2:8080:100
```

## Commands

### start

Start the load balancer.

```bash theme={null}
ultrabalancer start round-robin server1:8080 server2:8080
```

### dashboard

Deploy Grafana/Prometheus monitoring.

```bash theme={null}
ultrabalancer dashboard --start    # Interactive setup
ultrabalancer dashboard --status   # Check status
ultrabalancer dashboard --stop     # Stop dashboard
```

### validate

Check config file syntax.

```bash theme={null}
ultrabalancer validate -f config.yaml
```

### example

Print example config.

```bash theme={null}
ultrabalancer example
```

### info

Show version and algorithms.

```bash theme={null}
ultrabalancer info
```

## Options

| Flag              | Description                | Default     |
| ----------------- | -------------------------- | ----------- |
| `-p, --port`      | Listen port                | 8080        |
| `-b, --backend`   | Backend server (host:port) | Required    |
| `-a, --algorithm` | Load balancing algorithm   | round-robin |
| `-w, --weight`    | Default backend weight     | 100         |
| `-c, --config`    | Config file path           | -           |
| `--host`          | Bind address               | 0.0.0.0     |

## Algorithms

| Algorithm           | Description                 |
| ------------------- | --------------------------- |
| `round-robin`       | Even distribution (default) |
| `least-connections` | Fewest active connections   |
| `ip-hash`           | Same client → same server   |
| `random`            | Random backend              |
| `weighted`          | Weight-based distribution   |
| `power-of-two`      | Pick 2, use least loaded    |
| `fastest-response`  | Fastest recent response     |

## Admin API

Secure API for managing backends (requires API key).

```bash theme={null}
# List backends
curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/admin/backends

# Add backend
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10.0.0.5:8080","weight":100}' \
  http://localhost:8080/admin/backends

# Remove backend
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  -d '{"address":"10.0.0.5:8080"}' \
  http://localhost:8080/admin/backends

# Update weight
curl -X PUT -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10.0.0.5:8080","weight":150}' \
  http://localhost:8080/admin/backends/weight
```

### Admin Endpoints

| Method | Endpoint                  | Description       |
| ------ | ------------------------- | ----------------- |
| GET    | `/admin/backends`         | List all backends |
| POST   | `/admin/backends`         | Add backend       |
| DELETE | `/admin/backends`         | Remove backend    |
| PUT    | `/admin/backends/weight`  | Update weight     |
| POST   | `/admin/backends/drain`   | Start draining    |
| POST   | `/admin/backends/undrain` | Stop draining     |
| GET    | `/admin/health`           | API health check  |

## Exit Codes

| Code | Meaning |
| ---- | ------- |
| 0    | Success |
| 1    | Error   |