kmsvc-cli/README.md

# kmsvc-cli

Thin CLI wrapper over [kmsvc-sdk](https://forgejo.riotpiao.homelab.com/rock/kmsvc-sdk) for operating the Kafka Management Service's message plane from the terminal — sending/receiving/deleting messages and inspecting/redriving DLQ contents.

Queue lifecycle is the Queue CRD on the cluster — `create-queue`/`delete-queue` apply/delete that CRD directly (same effect as `kubectl apply`/`kubectl delete`, just without a YAML file), and `kmsvc queue list`/`describe` read it back.

## Install

```bash
export GOPRIVATE=forgejo.riotpiao.homelab.com   # self-hosted Forgejo, skip public proxy/sumdb
go install forgejo.riotpiao.homelab.com/rock/kmsvc-cli/cmd/kmsvc@latest
```

## Configuration

Precedence: flag > env var > `~/.kmsvc/config.yaml` > default.

| Flag | Env var | Config key | Default |
|---|---|---|---|
| `--server` | `KMSVC_SERVER` | `server` | (required) |
| `--token` | `KMSVC_TOKEN` | — | (none) |
| `--output` | `KMSVC_OUTPUT` | `output` | `table` |
| `--insecure` | `KMSVC_INSECURE` | `insecure` | `false` |

By default the CLI dials `--server` over TLS — the default `kmsvc.riotpiao.homelab.com:443` is reached through an Ingress-terminated HTTPS/gRPC-passthrough endpoint, not a plaintext port. Pass `--insecure` (or set `KMSVC_INSECURE=1`) for cluster-internal/dev targets that speak plaintext gRPC directly.

```yaml
# ~/.kmsvc/config.yaml
server: kmsvc.riotpiao.homelab.com:443
output: table
```

## Usage

```bash
kmsvc send-message --queue orders --body '{"order_id": 123}'
kmsvc receive-message --queue orders --wait 20 --max-messages 10
kmsvc delete-message --queue orders --receipt-handle <handle>
kmsvc change-message-visibility --queue orders --receipt-handle <handle> --timeout 60

kmsvc dlq peek --queue orders.dlq --max-messages 10
kmsvc dlq redrive --queue orders.dlq --to orders --max-messages 10

kmsvc create-queue orders --set fifoQueue=true --set maxReceiveCount=5
kmsvc delete-queue orders
kmsvc queue list
kmsvc queue describe orders

kmsvc version
```

`dlq redrive` performs Receive → Send → Delete as three separate calls (not atomic). If Send succeeds but Delete fails, the command reports the message as left in the DLQ and may be duplicated on the next redrive, and exits non-zero.

## Development

```bash
export GOPRIVATE=forgejo.riotpiao.homelab.com
go build ./...
go vet ./...
go test ./... -race
```
# Test after gofmt fix
# Final test - clean cache removal
# Final CI validation - Forgejo ready