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.3.0, aligned with the broker’s 1.3 line.

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 depth flags: --group (none). It is the cheap sibling of queue describe: one GET /api/v1/resources/queues/:queue/depth, watermark arithmetic only, no segment scan. The table view is a four-column summary (pending, partitions, partitionsPending, effective) while -o json prints the full per-partition array. partitionsPending comes from the broker on 1.1.0 and is derived client-side against older ones. effective appears only for a conflating group, where pending is log depth and effective is the handler runs that remain; on any other group the two are equal by construction and printing both would only raise the question of which one is real. 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.

configure merges: only the flags you actually typed go on the wire, and every option the command does not send keeps the value the queue already has. That is what makes the flag-driven shortcut safe to reach for, and it is the difference from queenctl apply -f, which sends mode: replace because a manifest is the whole configuration.

queenctl queue configure orders --lease-time 60     # the lease, nothing else
queenctl queue configure orders --dlq=false         # stop dead-lettering
queenctl queue configure orders --dlq               # start again

--dlq and --encrypt are sent only when you type them, and they are sent as literal values, so --dlq=false really does disable dead-lettering. That was not true before 1.6.0: the two flags were populated on every call from --dlq’s default of true, so nudging an unrelated option silently switched dead-lettering back on for a queue somebody had deliberately set to drop.

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 and retry both add --dry-run and --yes, and refuse to run without one of them.

drain pages through the filtered set in --limit-sized pages, defaulting to 200 when --limit is 0, and deletes every row it matches. It is the bulk delete you run after deciding not to replay.

retry is the replay, one address at a time. It wraps POST /api/v1/messages/:partitionId/:transactionId/retry, which since 1.6.0 moves the newest dead-letter snapshot at that address: claim the row under a lock, push the frame to its own queue and partition, delete the row, one transaction.

It still requires --yes, and the reason changed. It is now idempotent by row: the replayed frame carries the derived transaction id dlq:<row id>, and a second run answers 404 because the row went with the first move. What --yes guards is that the command appends a message and removes a record, both of which someone has to mean.

Three results are worth recognising at the prompt:

• dlqRowRemoved: false on a success is the duplicate verdict: the destination already carries that transaction id, so nothing was written and nothing was removed. The command says so and names the offset to read. Replay elsewhere, or purge the row.
• A 500 whose dlqRowRemoved is null means the broker never learned whether the move committed. The command prints a warning telling you to re-read the address with dlq list first: if the row is gone, the move happened.
• A 503 is push maintenance. A move cannot be spooled, so it is refused and the row stays.

The replay lands at the tail of the partition, out of order for its key, and its age clock restarts at the destination. queenctl sends the request exactly once and never resends it on a 5xx, so the verdict you read is the one that happened.

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
  deadLetterQueue: false
---
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.

apply sends mode: replace, and that is the point of a manifest: the document is the whole desired configuration of the queue it names, so an option it does not mention goes back to its default even if a previous apply or a queue configure had set it. Applying the same file twice, or applying it after someone nudged an option by hand, converges on the file. Reach for queenctl queue configure instead when you mean to nudge one option and leave the rest alone.

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 curated list of documentation links.

--topic and --llms cannot be combined. The short names the previous flat site used (concepts, architecture, server, sizing and the rest) still resolve, onto whichever page that content moved to. With -q, --llms prints the two URLs alone, which is the form to pipe into a fetch.

No kv and no timers commands

There is no queenctl kv and no queenctl timers, and their absence is a decision rather than an oversight.

The CLI’s value for those two surfaces is inspection: peek a timer, list a queue’s pending timers, read a key. That is exactly the part of them that a curl against the kv routes and the timer routes already covers, and the writing part, the part a CLI would make convenient, is the part that belongs in an application’s own transaction rather than at a prompt. A queenctl kv put next to a queenctl timers schedule would also make both surfaces look like operator tools, which they are not: they are application state, and the operator’s controls over them are the grants, the quotas and the runtime kill switches described under Self-hosting.

Those controls do have a place at a prompt, and they already have one: they are POST /api/v1/system/kv-timers and rows in queen.kv_quota, not a kv put.

Related