CLI

queenctl

One static binary, kubectl-style command tree, NDJSON pipelines. Built on top of the Go SDK so any new endpoint exposed in client-go is one Cobra file away from a CLI flag.

Install

# Pre-built binary (recommended) — download from GitHub Releases,
# extract the matching archive, and put `queenctl` on $PATH.

# Go modules (requires Go 1.22+)
go install github.com/smartpricing/queen/clients/client-cli/cmd/queenctl@latest

# From source
cd clients/client-cli && make build  # ./bin/queenctl

Pre-built archives for linux/{amd64,arm64}, darwin/{amd64,arm64} and windows/amd64 ship on GitHub Releases under tag prefix clients/client-cli/v*.

Contexts

~/.queen/config.yaml follows the kubectl model: many contexts, one default, easy switching.

queenctl config set-context local --server http://localhost:6632
queenctl config set-context prod  --server https://queen.prod.internal:6632 --token "$JWT"
queenctl config use-context prod
queenctl config get-contexts

Precedence: file < $QUEEN_CONTEXT < --context < $QUEEN_SERVER/$QUEEN_TOKEN < --server/--token. Tokens are stored in the OS keychain by default.

Auth

queenctl login --method password -u alice
queenctl login --method google
queenctl login --method token   # paste a JWT (works for any IdP / JWKS)
queenctl logout

The proxy's POST /api/login sets a token cookie; queenctl scrapes it and stores the JWT in the keychain. Google flow opens the proxy's OAuth URL in your browser and prompts you to paste the JWT back.

Top-level shortcuts

Command	What it does
`queenctl ping`	Health probe; exit 0 on healthy, 2 otherwise. Liveness in CI scripts.
`queenctl version`	CLI build info + server version.
`queenctl status [queue]`	Cluster overview, or a single-queue depth + lag table with `--partitions`.
`queenctl lag`	Every consumer group with current lag; `--min-seconds` for alerts.
`queenctl tail <q> -f --cg <cg>`	Live-stream messages as NDJSON. Composes with `jq`.
`queenctl push <q>`	NDJSON on stdin, batched. `--partition-key` reads a JSON path per message.
`queenctl pop <q> -n N --auto-ack`	One-shot pop, NDJSON output.
`queenctl ack <tx> / --batch -`	Single or batched acks; reads NDJSON straight from `tail`/`pop`.
`queenctl apply -f file.yaml`	Declarative queue / consumer-group manifests.
`queenctl replay <q> --cg c --to '15m ago'`	Top-level alias for the cg-seek workflow.

Pipeline example

# Replay from src into dst, transforming on the way
queenctl tail src --cg replay --auto-ack \
  | jq -c '.data | .processed = true' \
  | queenctl push dst --batch 500

Declarative apply

kind: Queue
name: orders
namespace: billing
config:
  leaseTime: 60
  retryLimit: 5
  maxSize: 100000
---
kind: ConsumerGroup
name: analyzer
queue: orders
seek-to: beginning

Resources

Subcommand	Verbs
`queue`	`list` · `describe` · `configure` · `delete` · `clear` · `stats`
`partition`	`list` · `describe` · `seek` · `clear`
`messages`	`list` · `get` · `delete` · `retry` · `dlq` · `traces`
`cg`	`list` · `describe` · `lag` · `seek` · `delete` · `refresh-stats`
`dlq`	`list` · `describe` · `requeue` · `drain`
`namespace` · `task`	`list`

Ops & analytics

Subcommand	What it does
`tx -f bundle.json`	Atomic ack+push transaction posted to `/api/v1/transaction`.
`lease extend <leaseId>`	Renew a message lease (long-running consumers).
`maintenance get / on / off [--pop]`	Inspect / toggle broker (or pop-only) maintenance mode.
`metrics [--prometheus]`	Fetch `/metrics` JSON or the Prometheus exposition.
`analytics overview / queue-lag / queue-ops / queue-parked / retention / system / worker / postgres`	The full `/api/v1/analytics/*` series, dumped as JSON or YAML.
`traces names / by-name / by-message`	Inspect message trace events.
`bench --total N --partitions K`	Smoke benchmark: push N messages, pop them, report p50/p95/p99 RTT.

Output formats

-o is auto-detected: table when stdout is a TTY, json when piped. Override explicitly:

-o table humanised columns
-o wide table + columns hidden by default
-o json pretty-printed
-o ndjson one JSON object per line — composes with jq and queenctl push
-o yaml
-o jsonpath=.queues[0].name kubectl-style accessor

tail always emits NDJSON regardless of -o so pipelines stay deterministic.

Exit codes

Code	Meaning
0	Success
1	User error (bad flag, missing arg)
2	Server unreachable / 5xx
3	Auth failed
4	Successful no-op (empty pop, no DLQ rows)

Shell completion

source <(queenctl completion bash)
source <(queenctl completion zsh)
queenctl completion fish | source
queenctl completion powershell | Out-String | Invoke-Expression