# CLI Reference

Citadel has two CLIs serving different purposes.

## `citadel` — Operator Deployment

Installed via pip. Manages the operator within an existing Kubernetes cluster.

### `citadel install`

Install the operator, CRDs, RBAC, and default policies into a cluster.

```bash
citadel install [--namespace NS] [--image IMG] [--with-default-policies] [--no-default-policies] [--with-network-policies] [--timeout SECS]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--namespace` | `citadel-system` | Target namespace for operator deployment |
| `--image` | `citadel-operator:latest` | Operator container image |
| `--with-default-policies` | `true` | Apply built-in NodeTerminationPolicies |
| `--no-default-policies` | — | Skip applying default policies |
| `--with-network-policies` | `false` | Also apply bundled Cilium network policies (requires Cilium CRDs) |
| `--timeout` | `120` | Seconds to wait for Deployment rollout |

**What it creates:**
1. Namespace
2. CRDs (`NodeTerminationPolicy`, `NamespaceInfrastructure`)
3. ServiceAccount `citadel-operator`
4. ClusterRole with 14 permission rules
5. ClusterRoleBinding
6. Deployment (1 replica, non-root uid 1000, resource limits 100m/128Mi → 500m/256Mi)
7. Default policies (if enabled): `max-age-48h`, `disk-pressure`, `memory-pressure`, `not-ready`, `stuck-volume-detector` (disabled), `gpu-health-detector` (disabled)
8. Network policies (if `--with-network-policies`): bundled CiliumClusterwideNetworkPolicies (default-deny, allow-dns, allow-apiserver, allow-health-checks, allow-host-services)

**Idempotent.** Safe to re-run — uses create-or-patch strategy (409 Conflict triggers patch).

### `citadel uninstall`

Remove the operator from the cluster.

```bash
citadel uninstall [--namespace NS] [--delete-crds]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--namespace` | `citadel-system` | Namespace to remove operator from |
| `--delete-crds` | `false` | Also delete CRDs (**destructive** — removes all CRD instances) |

### `citadel status`

Check operator installation health.

```bash
citadel status [--namespace NS]
```

Reports: namespace existence, CRD registration, Deployment readiness, pod status.

### `citadel manifests`

Print all Kubernetes manifests to stdout for review. No cluster connection required.

```bash
citadel manifests [--namespace NS] [--image IMG] [--with-network-policies]
```

Outputs YAML for: Namespace, CRDs, ServiceAccount, ClusterRole, ClusterRoleBinding, Deployment, and default policies. With `--with-network-policies`, also includes bundled Cilium network policies.

Useful for GitOps workflows:

```bash
citadel manifests > operator.yaml
kubectl apply -f operator.yaml
```

---

## `./citadel-ctl` — Infrastructure Setup

Executable Python script in the repository root. Wraps shell scripts and kubectl commands for bootstrapping cluster infrastructure.

**Requires**: scripts in `scripts/` directory and policies in `policies/` directory (i.e., run from the repo root).

### Cluster Management

```bash
./citadel-ctl cluster status
```

Show the Rancher Desktop K3s cluster state: kubernetes version, node name, readiness, flannel/traefik status, container engine.

```bash
./citadel-ctl cluster configure
```

Configure K3s for Cilium (disable flannel/traefik, fix mount propagation). Required before installing Cilium.

```bash
./citadel-ctl cluster reset
```

Factory-reset the K3s cluster via `rdctl factory-reset`.

```bash
./citadel-ctl cluster wait [--timeout SECS]
```

Wait for the K3s API server to become reachable (default timeout: 120s).

### Image Management

```bash
./citadel-ctl image build <path> <tag>
```

Build a container image via nerdctl into the `k8s.io` namespace (available to K3s without a registry push).

```bash
./citadel-ctl image list
```

List images in the `k8s.io` containerd namespace.

### Node Operations

```bash
./citadel-ctl node status
```

Show node ages and health using `scripts/node-lifecycle.sh status`.

```bash
./citadel-ctl node list
```

Display nodes with lifecycle-specific columns: NAME, AGE, READY, SCHEDULABLE, TERMINATE-REASON, POLICY-NAME.

### Lifecycle Management

```bash
./citadel-ctl lifecycle install
```

Apply CRDs and RBAC for node lifecycle management. Runs `kubectl apply` on `crds/nodeterminationpolicy.yaml`, `crds/rbac.yaml`, and `crds/default-policies.yaml`.

```bash
./citadel-ctl lifecycle policies
```

List active NodeTerminationPolicy resources: `kubectl get nodeterminationpolicies.citadel.dev -o wide`.

### Network Operations

```bash
./citadel-ctl network install
```

Install Cilium CNI with Hubble. Runs `scripts/02-install-cilium.sh`.

```bash
./citadel-ctl network policies
```

Apply all network policies from the `policies/` directory (sorted alphabetically). Each `.yaml` file is applied via `kubectl apply -f`.

```bash
./citadel-ctl network test
```

Run network policy verification tests. Runs `scripts/05-test-policies.sh`.

### Monitoring

```bash
./citadel-ctl monitor install
```

Install the Prometheus + Grafana monitoring stack. Runs `scripts/03-install-monitoring.sh`.

### Security

```bash
./citadel-ctl security enable-wireguard
```

Enable transparent WireGuard pod-to-pod encryption. Runs `scripts/06-enable-wireguard.sh`.

```bash
./citadel-ctl security enable-audit
```

Enable Kubernetes API audit logging. Runs `scripts/07-enable-audit-logging.sh`. Requires K3s restart.

### Help

```bash
./citadel-ctl help
./citadel-ctl -h
./citadel-ctl --help
```

---

## Environment Variables

| Variable | Default | Used By |
|----------|---------|---------|
| `KUBECONFIG` | `/etc/rancher/k3s/k3s.yaml` | All scripts, `citadel` CLI |
| `NODE_MAX_AGE_HOURS` | `48` | `node-lifecycle.sh` |
| `DRAIN_TIMEOUT` | `300` | `node-lifecycle.sh` |
| `DRY_RUN` | `false` | `node-lifecycle.sh` |

## CLI Comparison

| Feature | `citadel` | `./citadel-ctl` |
|---------|-----------|-----------|
| Install method | `pip install jaymd96-citadel-operator` | Run from repo root |
| Cluster creation | No | Yes (Rancher Desktop) |
| Operator deployment | Yes | No |
| Network setup | No | Yes (Cilium, policies) |
| Monitoring setup | No | Yes (Prometheus, Grafana) |
| Security tools | No | Yes (WireGuard, audit) |
| Requires repo checkout | No | Yes |
| Idempotent | Yes | Varies by script |
