queenctl is a single static binary over the HTTP API, built on the Go SDK. It is what we reach
for when we want to look at a running broker without writing code: push a few messages, follow a
queue, see who is lagging, put a dead letter back, rewind a consumer group. Everything it does is
an HTTP call you could make with curl, so its output always tells you what the broker said.
Install
queenctl 2.7.1 is built for QueenMQ 2.7. Its archives are on the release
queenctl 2.7.1, named
queenctl_<version>_<os>_<arch>: linux and macos on x86_64 and arm64, and windows on
x86_64 as a .zip. Each archive holds the binary, the README and shell completions. On a Mac with
Apple silicon:
curl -sSL https://github.com/queen-mq/queen/releases/download/clients/client-cli/v2.7.1/queenctl_2.7.1_macos_arm64.tar.gz | tar -xz queenctl
sudo mv queenctl /usr/local/bin/
source <(queenctl completion zsh) # completion for this shellWith Go 1.24 or later:
go install github.com/smartpricing/queen/clients/client-cli/v2/cmd/queenctl@latestThe module keeps the path it had before the repository moved to queen-mq. A path under
github.com/queen-mq/queen resolves to the whole repository, and go install fails with
module source tree too large.
To build it from a checkout of the repository instead, where the Go workspace (go.work, which
declares Go 1.26) links the CLI to the SDK in the same tree:
cd clients/client-cli && make build # ./bin/queenctlEach version is released from its clients/client-cli/vX.Y.Z tag, as the release queenctl X.Y.Z
on that tag in the queen-mq/queen GitHub Releases.
Connect
queenctl config set-context local --server http://localhost:6632
queenctl pingContexts live in ~/.queen/config.yaml (--config or $QUEEN_CONFIG moves it), and
set-context makes the context current when none is. Each setting is taken from, lowest to
highest: the file’s current-context, $QUEEN_CONTEXT, --context, then $QUEEN_SERVER and
$QUEEN_TOKEN, then --server and --token.
| Credential | Command |
|---|---|
A JWT or a proxy API key (qk_...) |
queenctl login --method token (or --token <value> with no prompt) |
| Email and password on the proxy | queenctl login --method password -u you@example.com |
| Google or GitHub through the proxy | queenctl login --method google (or github) |
A token is stored in the OS keychain. config set-context --no-keychain keeps it in the file in
plain text, and --token-ref env reads $QUEEN_TOKEN at run time instead. A token pasted after a
Google or GitHub sign-in lasts 15 minutes, so for CI use an API key, which does not expire.
Commands
| Group | Commands |
|---|---|
| Data | push, pop, tail, ack, tx -f, lease extend |
| Queues | queue list|describe|configure|delete|depth|stats, partition list|describe|seek, namespace list, task list, apply -f |
| Consumer groups | cg list|describe|lag|seek|delete|refresh-stats, lag, replay |
| Messages and DLQ | messages list|get|delete|traces, dlq list|describe|retry|redrive|drain, traces names|by-name|by-message |
| Ephemeral queues | ephemeral push|pop|ack|configure|reset|delete|queues|depth |
| Node | ping, version, status, metrics [--prometheus], analytics overview|queue-lag|queue-ops|queue-parked|retention|system|worker, bench |
| Plumbing | config view|current-context|get-contexts|set-context|use-context|delete-context, login, logout, completion, docs |
queenctl <command> --help lists every flag. The commands that remove data (queue delete,
cg delete, messages delete, dlq retry, dlq redrive, dlq drain, ephemeral reset, ephemeral delete)
refuse to run without --yes. push, tx, apply, replay, cg seek, dlq retry, dlq redrive and
dlq drain take --dry-run, which prints what would happen and needs no --yes.
Examples
# Push NDJSON, one partition per user, 500 messages per request
cat events.ndjson | queenctl push events --batch 500 --partition-key user_id
# Follow a queue as consumer group "debug", acking what it prints
queenctl tail orders --cg debug --follow --auto-ack | jq '.data'
# Depth and lag of every queue, then of one
queenctl status
queenctl status orders
# Rewind a consumer group fifteen minutes, then check who is lagging
queenctl replay orders --cg analyzer --to '15m ago'
queenctl lag --min-seconds 30
# Look at the dead letters of a queue and put one back, then all of last night's
queenctl dlq list --queue orders
queenctl dlq retry <partitionId> <transactionId> --yes
queenctl dlq redrive --queue orders --from '12h ago' --dry-run
queenctl dlq redrive --queue orders --from '12h ago' --yes
# Declare a queue from a manifest
cat <<EOF | queenctl apply -f -
kind: Queue
name: orders
config:
leaseTime: 60
retryLimit: 5
EOFstatus prints one row per queue, counted from its slowest consumer group: PENDING waits for a
consumer, PROCESSING is leased, COMPLETED is consumed and still retained, DLQ is
dead-lettered. LAG is the largest time lag among the groups reading the queue, queue mode
included, and - for a queue no group has read; lag lists the groups one by one. If the group
listing fails, status still prints the counts, leaves LAG empty and says so on stderr.
--namespace and --task keep the queues with that label, and status <queue> prints the row of
one queue with its partition count.
lag prints one row per consumer group and queue: MESSAGES is what the group has not consumed
and LAG the age of the oldest of those messages. With --min-seconds N the rows are partitions
instead, one for each partition a group is more than N seconds behind on, oldest first, and the
table has no CONFLATION column. queue list prints each queue’s labels, partition count,
priority and lease time in seconds. Its --namespace, --task, --offset and --limit are
applied by queenctl to the whole listing, which the broker sends newest queue first.
tail acks nothing unless you pass --auto-ack: without it the messages it prints stay leased to
its group (queenctl-tail when you name none) and are delivered again when the lease expires.
Without --follow it stops once it has printed --batch messages (100 when unset), which on a
quiet queue can take a long time, so give it -n or --idle-millis there.
To include a tail invocation in the dashboard’s Workers view (Queues › Workers), pass
--supervision-group billing-production. This optional application/deployment name is separate
from --cg; reporting is off by default. The Go reporter publishes live consumer counts and
handler progress through KV. Each completed handler means a message was printed, not that a
pipe’s downstream consumer processed it or an acknowledgement succeeded. Publication failures
do not stop tailing, and status stays out of stdout. See the client README for heartbeat and
expiry details. This option does not restart or scale CLI processes.
Each tail invocation starts a new instance ID and fresh counters, even with the same host,
queue and publication group. Normal exits caused by --limit, --idle-millis or the default
one-shot batch limit publish stopped with zero running workers. The final observation has
a 60-second TTL; expired records can remain visible until the broker sweeps them. A shell
loop that restarts short tails can show several stopped cards while the shell keeps running.
For a persistent observed tail, use --follow without stopping limits; it does not override
an explicit --limit or --idle-millis. If an outer scheduler’s lifetime is what you want to
observe, omit --supervision-group on its short commands and
publish that scheduler’s status.
pop prints leased messages: ack each one with queenctl ack, or it is delivered again when the
lease expires. With --commit-on-delivery the broker moves the group’s cursor past the messages
as it hands them out, so there is no lease and nothing to ack. That is at-most-once delivery: a
crash after the pop loses the messages. ephemeral pop takes the same flag.
A Queue manifest is the whole configuration of its queue: apply sends mode: "replace", so an
option the manifest leaves out goes back to its default, and applying the same file twice
converges on the file. queue configure --flag merges and changes only the flags you pass. A
manifest can also carry a ConsumerGroup document (queue, seek-to: beginning|end|<time>);
it seeks an existing group’s cursor and registers nothing, so on a queue nobody has pushed to yet
the seek answers 404.
Output and exit codes
Output is a table on a terminal and JSON in a pipe; describe-shaped commands show YAML on a
terminal. -o table|wide|json|ndjson|yaml|jsonpath=<expr> overrides it. tail, pop and
ephemeral pop always write NDJSON.
| Exit code | Meaning |
|---|---|
| 0 | Success. |
| 1 | A user error the command itself detected: bad input, a manifest that does not parse, a route the proxy does not serve to tenants. |
| 2 | The server answered an error (a 401 or 403 included) or could not be reached. Flag and argument errors caught by the parser also exit 2. |
| 3 | login --method password was refused, or set-context could not write the keychain. |
| 4 | Success with nothing to do: an empty pop, nothing pushed, dlq drain with nothing matched, no documents applied, no current context. |
Limits
- There is no
kvortimercommand. Usecurlagainst/api/v1/kvand/api/v1/timers, or an SDK. tx -fsends only ack and push operations. Each ack goes with its ownleaseId, or, when it has none, the one leaserequiredLeasesnames; an ack without a lease in a bundle that names several exits1before anything is sent. The items’transactionIdis dropped, so a retried push is not deduplicated. For an idempotent transaction, use the HTTP API or an SDK.messages deleteremoves dead-letter rows only: a live message sits in the immutable queue log and answers 404.cg refresh-statschanges nothing on 2.0, whose counters are kept at apply.metricswithout--prometheusprints{}on 2.0; use--prometheus.--insecureaffects onlylogin. The broker calls of every other command verify TLS.- Through the proxy, the routes that cannot be scoped to one tenant answer 404:
metrics,analytics system|worker,cg refresh-stats, andpop --namespace/--taskwithout a queue. They work against a node’s own port.