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

# opsctl CLI

> The command-line interface for cluster analysis, rebalancing, resource prediction, and CRD status inspection.

`opsctl` is the command-line interface for Autopilot. It provides interactive cluster
analysis, rebalancing, resource prediction, and CRD status inspection without requiring the
full controller to be running.

<Note>
  `opsctl` keeps its original command name — it is a runtime binary, not a brand name.
</Note>

## Installation

Build from source:

```bash theme={null}
make opsctl
```

The binary is placed at `bin/opsctl`. Move it onto your `PATH`:

```bash theme={null}
sudo mv bin/opsctl /usr/local/bin/
```

**Prerequisites:**

* A valid kubeconfig file (defaults to `~/.kube/config`)
* For GKE mode: GCP credentials configured (`gcloud auth application-default login`)
* For the `predict` command: a reachable Prometheus endpoint

## Commands

### rebalance (default)

Analyze cluster resource distribution and optionally rebalance pods across nodes. This is
the default command when no subcommand is specified.

```
opsctl [flags]
```

| Flag                | Default          | Description                                          |
| ------------------- | ---------------- | ---------------------------------------------------- |
| `--kubeconfig`      | `~/.kube/config` | Path to kubeconfig file                              |
| `--dry-run`         | `true`           | Analyze only, do not execute movements               |
| `--min-imbalance`   | `0.2`            | Minimum imbalance score (0–1) to trigger rebalancing |
| `--max-movements`   | `10`             | Maximum pod movements per run                        |
| `--target-util`     | `0.7`            | Target resource utilization (0–1)                    |
| `--show-nodes`      | `true`           | Show node utilization table                          |
| `--show-candidates` | `false`          | Show pod movement candidates                         |

**GKE provision-first mode flags** — when `--gke` is set, opsctl provisions new nodes before
migrating workloads, avoiding resource contention during rebalancing:

| Flag                | Default         | Description                                    |
| ------------------- | --------------- | ---------------------------------------------- |
| `--gke`             | `false`         | Enable GKE provision-first mode                |
| `--gke-project`     | (required)      | GCP project ID                                 |
| `--gke-location`    | (required)      | GKE cluster location or region                 |
| `--gke-cluster`     | (required)      | GKE cluster name                               |
| `--machine-type`    | `e2-standard-4` | Machine type for new nodes                     |
| `--spot`            | `false`         | Use spot VMs for new nodes (60–91% cheaper)    |
| `--auto-delete-old` | `false`         | Automatically delete old nodes after migration |

### predict

Predict resource usage trends and detect anomalies using Prometheus historical data.

```
opsctl predict [flags]
```

| Flag               | Default          | Description                                           |
| ------------------ | ---------------- | ----------------------------------------------------- |
| `--kubeconfig`     | `~/.kube/config` | Path to kubeconfig file                               |
| `--prometheus-url` | (required)       | Prometheus endpoint URL                               |
| `--horizon`        | `10m`            | Prediction time horizon                               |
| `--namespace`      | (all)            | Namespace filter for predictions                      |
| `--pod`            | (none)           | Specific pod name to predict (requires `--namespace`) |

When both `--namespace` and `--pod` are provided, opsctl runs a detailed single-pod
prediction including trend analysis, pattern classification, forecasting, peak estimation,
and anomaly detection. When only `--namespace` is given (or neither), it runs a cluster-wide
analysis with node utilization and fragmentation scoring.

### status

Show the current state of all Autopilot CRD resources in the cluster.

```
opsctl status [flags]
```

| Flag           | Default          | Description             |
| -------------- | ---------------- | ----------------------- |
| `--kubeconfig` | `~/.kube/config` | Path to kubeconfig file |
| `--namespace`  | (all)            | Namespace to query      |

Displays tables for RebalancePolicy (schedule, dry-run mode, last run), NodeScalingPolicy
(min/max nodes, current/desired counts, last action), and PodResizePolicy (resize mode,
recommendation count, total resizes).

### help

```
opsctl help
```

## Common usage examples

### Dry-run cluster analysis (default)

```bash theme={null}
opsctl
```

Gathers cluster state, prints a node utilization table, computes the imbalance score, and
lists proposed pod movements without executing anything. Since `--dry-run` defaults to
`true`, this is always safe.

### Execute rebalancing

```bash theme={null}
opsctl --dry-run=false
```

Only movements that improve the imbalance score are executed. Pods are evicted through the
Kubernetes eviction API, which respects PodDisruptionBudgets.

### Adjust thresholds

```bash theme={null}
opsctl --min-imbalance=0.1 --max-movements=20 --target-util=0.6
```

### GKE provision-first rebalance (dry-run)

```bash theme={null}
opsctl --gke \
  --gke-project=my-project \
  --gke-location=us-central1 \
  --gke-cluster=production \
  --machine-type=e2-standard-8 \
  --spot
```

### GKE provision-first rebalance (execute)

```bash theme={null}
opsctl --gke \
  --gke-project=my-project \
  --gke-location=us-central1 \
  --gke-cluster=production \
  --machine-type=e2-standard-8 \
  --spot \
  --auto-delete-old \
  --dry-run=false
```

### Predict resource usage for a specific pod

```bash theme={null}
opsctl predict \
  --prometheus-url=http://prometheus.monitoring:9090 \
  --namespace=default \
  --pod=my-app-7b9d4c6f8-x2k9l \
  --horizon=30m
```

### Check CRD status

```bash theme={null}
opsctl status                        # all namespaces
opsctl status --namespace=production # one namespace
```

## Exit codes

| Code | Meaning                                                                                                                     |
| ---- | --------------------------------------------------------------------------------------------------------------------------- |
| 0    | Success                                                                                                                     |
| 1    | Error — kubeconfig failure, cluster state gathering failure, analysis failure, execution failure, or missing required flags |

All errors are printed to stderr with a descriptive message. Diagnostic output (node tables,
analysis results) goes to stdout.

## Tips

* Always start with a dry run. The default `--dry-run=true` ensures no cluster changes are made until you explicitly opt in.
* In GKE mode, `--spot` can reduce costs by 60–91% for new nodes, but spot VMs can be preempted — use it for fault-tolerant workloads.
* The `predict` command requires at least 5 historical data points from Prometheus. If your retention is too short, predictions won't be available.
* The `status` command works even if the controller is not running — it reads CRD resources directly from the API server.