Skip to content

queenctl command-line client

The command-line client: build it, connect it to a node, and the command groups it has, with the flags and exit codes scripts rely on.

Updated View as Markdown

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 shell

With Go 1.24 or later:

go install github.com/smartpricing/queen/clients/client-cli/v2/cmd/queenctl@latest

The 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/queenctl

Each 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 ping

Contexts 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
EOF

status 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 kv or timer command. Use curl against /api/v1/kv and /api/v1/timers, or an SDK.
  • tx -f sends only ack and push operations. Each ack goes with its own leaseId, or, when it has none, the one lease requiredLeases names; an ack without a lease in a bundle that names several exits 1 before anything is sent. The items’ transactionId is dropped, so a retried push is not deduplicated. For an idempotent transaction, use the HTTP API or an SDK.
  • messages delete removes dead-letter rows only: a live message sits in the immutable queue log and answers 404. cg refresh-stats changes nothing on 2.0, whose counters are kept at apply. metrics without --prometheus prints {} on 2.0; use --prometheus.
  • --insecure affects only login. 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, and pop --namespace/--task without a queue. They work against a node’s own port.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close