kmsvc-cli/README.md

kmsvc-cli

Thin CLI wrapper over 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

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.

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

Usage

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

export GOPRIVATE=forgejo.riotpiao.homelab.com
go build ./...
go vet ./...
go test ./... -race