queenctl

queenctl is a single static Go binary built on the Go client. It exposes the broker’s data plane (push, pop, ack, transaction, lease) and its management plane (queues, partitions, consumer groups, DLQ, traces, maintenance, metrics, analytics). Version 1.0.0, aligned with the broker.

Every command below is registered in clients/client-cli/cmd. Nothing else is: if a name is not in this page, the binary does not have it.

Install

make -C clients/client-cli build

Puts the binary in clients/client-cli/bin/queenctl. make install runs go install into $GOBIN (or $HOME/go/bin). Both pass -ldflags that stamp the version, commit and build date; a build without them reports dev, none and unknown.

Global flags

Bound to the root command, so they work on every subcommand.

Output formats

pop and tail always emit NDJSON regardless of -o: they are designed to be piped.

Exit codes

Code 4 is the only one whose message is not printed to stderr. It is not a failure, so scripts can treat it as “nothing to do”.

Configuration

Resolution order

1. Context name: --context, then $QUEEN_CONTEXT, then current-context from the file.
2. Server: the context’s server, then $QUEEN_SERVER, then --server.
3. Token: the context’s token-ref resolved, then $QUEEN_TOKEN, then --token.
4. Insecure: the context’s insecure, then --insecure, but only when the flag was actually passed, so an absent flag never overrides the file with false.

With no server resolved, every command that talks to a broker fails with no server configured: set --server, QUEEN_SERVER, or run 'queenctl config set-context'.

Environment variables

Config file

~/.queen/config.yaml, kubectl-shaped. A missing file is not an error: first-run users get the environment-only experience.

current-context: prod
contexts:
  - name: prod
    server: https://queen.internal:6632
    token-ref: keychain://prod
  - name: local
    server: http://localhost:6632
    insecure: true

token-ref is one of:

Writes are atomic (a .tmp file renamed over the target), with the file at 0600 and the parent directory at 0700.

Authentication

queenctl login

With no --method: --token implies token, --user implies password, otherwise token. The context must already exist: run config set-context first. An unknown --method exits 1.

The captured credential goes into the OS keychain and the config file keeps only keychain://<context>. If the keychain is unavailable (a CI container, a headless box), the CLI prints a warning to stderr and falls back to literal:<token> in the config file.

queenctl logout deletes the keychain entry, clears token-ref on the context and saves the file. It takes --context <name>.

Data plane

queenctl push <queue>

Reads NDJSON from stdin by default, one JSON object per line, and pushes in batches.

cat events.ndjson | queenctl push events --batch 500 --partition-key user_id

--wrapped is what makes replication between brokers possible: it lets each line carry its own partition and transaction id, so dedup stays meaningful on the receiving side.

queenctl pop [queue]

One-shot pop, printed as NDJSON. The queue argument is optional: omit it and use --namespace / --task.

Each emitted line carries queue, partition, transactionId, partitionId, createdAt, retryCount and data, plus leaseId and producerSub when present. An empty pop exits 4.

queenctl tail <queue>

Live-tail, always NDJSON on stdout regardless of -o.

queenctl tail src --auto-ack | queenctl push dst --batch 100

queenctl ack [transactionId]

Each line of a --batch file must be a JSON object with at least transactionId, partitionId and leaseId, exactly the shape pop and tail emit.

queenctl tail q --cg c -n 100 | queenctl ack --batch -

queenctl tx -f <bundle.json>

Posts a bundle to /api/v1/transaction: pushes and acks in one PostgreSQL transaction.

The file shape maps directly to the route:

{
  "operations": [
    {"type": "ack", "transactionId": "…", "partitionId": "…", "status": "completed"},
    {"type": "push", "items": [{"queue": "orders", "payload": {"id": 1}}]}
  ],
  "requiredLeases": ["lease-uuid"]
}

Only ack and push operation types are accepted; anything else exits 1. Push items are grouped by queue and partition before being handed to the builder, preserving first-seen order.

queenctl lease extend <leaseId>

Renews one lease, POST /api/v1/lease/:leaseId/extend. No flags of its own.

Queues and partitions

queenctl queue (aliases queues, q)

queue list flags: --namespace, --task, --limit (0), --offset (0). queue stats flags: --namespace, --task. queue delete requires --yes.

queue configure flags:

A positive --retention or --completed-retention sets retentionEnabled: true automatically, because the broker’s retention service only sweeps queues with that flag set.

With -o json or -o yaml, configure renders the full response including the echoed options block, which is what to assert against in tests. Without -o, it prints configured "<queue>".

queenctl partition (aliases partitions, p)

partition seek only supports seek-to-end: the stored procedure behind POST /api/v1/consumer-groups/:cg/queues/:q/partitions/:p/seek takes no timestamp. --to accepts end, now, latest or an empty value; anything else exits 1. For a timestamp, use queenctl cg seek, which is queue-wide.

queenctl namespace (aliases namespaces, ns)

namespace list (alias ls) lists namespaces with their queues. No flags.

queenctl task (alias tasks)

task list (alias ls) lists tasks with their queues. No flags.

Consumer groups

queenctl cg (aliases consumer-group, consumer-groups)

cg delete without --queue deletes the group everywhere; with it, only for that queue. --metadata also removes the subscription metadata rows. --yes is required.

queenctl lag

--min-seconds <n> (default 0). At 0 it lists every group from /api/v1/consumer-groups; above 0 it queries /api/v1/consumer-groups/lagging. queenctl cg lag is the same command.

queenctl replay [queue]

Moves a consumer group’s cursor so the next pop returns messages from --to onward.

--to accepts:

queenctl cg seek <cg> <queue> is the same operation with the arguments the other way round.

Messages, DLQ and traces

queenctl messages (aliases msg, msgs)

messages list flags: --queue, --partition, --status (pending, processing, completed, failed), --cg, --limit (100), --offset (0). messages delete requires --yes.

queenctl dlq

list and drain share the filters: --queue, --cg, --partition, --from, --to, --limit (0), --offset (0). drain adds --dry-run and --yes, and refuses to run without one of them.

queenctl traces

traces by-message is the same as messages traces.

Status and observability

queenctl status [queue]

No argument prints the cluster view: queues with depth, completed, failed and lag. With a queue name it prints the detailed view.

queenctl ping

Calls /health. Exits 0 when the broker reports healthy with the database connected, 2 otherwise. Prints status, database, version and measured latency.

queenctl version

Prints the CLI’s build metadata, then probes the server for its version, status and database state, and echoes the active context. --short prints only the CLI version and contacts nothing.

queenctl metrics

Reads /metrics (a JSON snapshot) by default. --prometheus reads /metrics/prometheus and prints the raw text/plain exposition.

queenctl metrics --prometheus | grep queue_pop_messages

queenctl analytics (aliases a, an)

Every subcommand takes --from and --to (both empty by default), which accept the same time forms as replay --to.

system, worker and postgres are operator-only through a proxy.

Operations

queenctl apply -f <file>

Applies YAML or JSON manifests. Multiple documents separated by ---; -f - reads stdin. Operations are idempotent and tolerant of resources that already exist.

Two kinds, flat, with no apiVersion dance. kind defaults to Queue; a document with no name is skipped, and an unknown kind exits 1.

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

Queue accepts name, namespace, task and a config block whose keys are the Go QueueConfig field names in camelCase. ConsumerGroup accepts name, queue (required) and seek-to, which takes the same forms as replay --to; a ConsumerGroup with no seek-to has nothing to apply and is reported as skipped. Applying nothing exits 4.

The zero-value omission described under queue configure applies to the config block too: a key you set to 0 or false is not sent, and /configure replaces the whole configuration. Spell out every option you care about with a non-zero value.

queenctl maintenance (alias maint)

--pop is a persistent flag on the parent, so it applies to all three: it scopes the operation to pop-only maintenance (/api/v1/system/maintenance/pop) instead of push maintenance (/api/v1/system/maintenance).

queenctl bench

An end-to-end smoke benchmark: push --total messages across --partitions partitions in --batch-sized batches from --producers goroutines, then drain with --consumers goroutines.

It reports the push wall time, the pop wall time, and per-message residency percentiles.

Utility

queenctl config

set-context flags:

view prints the resolved configuration as YAML. delete-context also clears current-context when it pointed at the removed context.

queenctl completion [bash|zsh|fish|powershell]

Writes a completion script to stdout. Exactly one argument, from that list.

queenctl docs

Prints a list of documentation links, with --open to launch the site in the default browser and --topic <name> to deep-link.

Related