Skip to content
ChasquiMQ ChasquiMQ

Inspecting with the CLI

You’ve got jobs flowing. Now learn the operator surface — the CLI you’ll reach for when something looks off.

1. Install chasqui

Section titled “1. Install chasqui”

The CLI ships as a separate Rust binary so you don’t drag operator tooling into your application bindings. Pick whichever path fits your environment:

With cargo binstall (recommended if you have Rust):

Terminal window
cargo binstall chasquimq-cli

This pulls the prebuilt tarball from GitHub Releases (no source compile, ~3 seconds) and drops chasqui into ~/.cargo/bin. If you don’t have cargo binstall, install it once with cargo install cargo-binstall.

Without Rust (one-liner installer):

Terminal window
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jotarios/chasquimq/releases/latest/download/chasquimq-cli-installer.sh | sh

Covers macOS (Apple Silicon + Intel), Linux (x86_64 + aarch64), and Windows. Or download a platform-specific tarball from the Releases page and extract chasqui somewhere on your $PATH.

From source (Rust 1.85+):

Terminal window
cargo install chasquimq-cli

Verify:

Terminal window
chasqui --version

2. Inspect a queue

Section titled “2. Inspect a queue”

chasqui inspect is a one-shot snapshot of every health metric for a queue. One Redis pipeline; six numbers out.

Terminal window
chasqui inspect emails
queue: emails
stream depth     │       128
pending          │         3
dlq depth        │         0
delayed depth    │        17
oldest delayed   │   1.4s
repeatable count │         2

Each row is one Redis call:

FieldRedis call
stream depthXLEN {chasqui:emails}
pendingXPENDING {chasqui:emails} <group>
dlq depthXLEN {chasqui:emails}:dlq
delayed depthZCARD {chasqui:emails}:delayed
oldest delayedZRANGE {chasqui:emails}:delayed 0 0 WITHSCORES
repeatable countZCARD {chasqui:emails}:repeat

If the consumer group name isn’t the engine default, pass --group <name>.

3. Watch live

Section titled “3. Watch live”

chasqui watch re-runs the inspect snapshot every interval (default 1s) and renders a delta column for stream + DLQ depth.

Terminal window
chasqui watch emails --interval-ms 500

Press Ctrl+C to exit. The watch view does not use raw mode or an alternate screen — when you exit, the final snapshot stays in your scrollback.

4. Peek the DLQ

Section titled “4. Peek the DLQ”

When a job exhausts its retry budget, panics, or throws UnrecoverableError, the engine relocates it to the DLQ stream ({chasqui:emails}:dlq).

Terminal window
chasqui dlq peek emails
queue: emails


reason histogram
  retries_exhausted        12
  unrecoverable             2
  decode_fail               0
  malformed                 0
  oversize                  0


most recent
  source_id            reason               name        attempt
  1731072123-0         retries_exhausted    welcome     5
  1731072098-0         unrecoverable        welcome     1
  ...

Each entry includes the original payload so you can decode it and figure out what went wrong.

5. Replay the DLQ

Section titled “5. Replay the DLQ”

Once you’ve fixed the bug:

Terminal window
chasqui dlq replay emails --limit 50

replay_dlq is atomic: each entry is removed from the DLQ stream and re-XADD’d to the main stream in one Lua script. The attempt counter resets to zero so the replayed job gets a full retry budget.

See Replay the DLQ for idempotency caveats.

6. Tail events

Section titled “6. Tail events”

The engine emits transition events (waiting, active, completed, failed, retry-scheduled, delayed, dlq, drained) onto a per-queue events stream. chasqui events tails it live.

Terminal window
chasqui events emails
2026-05-08T13:42:01Z  e=active        id=01HV...  n=welcome  attempt=1
2026-05-08T13:42:01Z  e=completed     id=01HV...  n=welcome  duration_us=1842
2026-05-08T13:42:02Z  e=active        id=01HW...  n=daily-rollup  attempt=1
2026-05-08T13:42:02Z  e=failed        id=01HW...  n=daily-rollup  attempt=1
2026-05-08T13:42:02Z  e=retry-scheduled  id=01HW...  n=daily-rollup  attempt=1  backoff_ms=200

Default --from $ reads only new events. Pass --from 0 to replay history.

7. List repeatable specs

Section titled “7. List repeatable specs”
Terminal window
chasqui repeatable list emails
key                                       job-name        next-fire (UTC)
welcome::cron:0 9 * * *:UTC               welcome         2026-05-09T09:00:00Z
daily-rollup::cron:0 3 * * *:UTC          daily-rollup    2026-05-09T03:00:00Z

Remove a spec:

Terminal window
chasqui repeatable remove emails 'daily-rollup::cron:0 3 * * *:UTC'

You’ve now got production-grade ops surface

Section titled “You’ve now got production-grade ops surface”

That’s every CLI command. With chasqui inspect, chasqui watch, chasqui dlq peek/replay, chasqui events, and chasqui repeatable list/remove you have the same surface a Sidekiq Pro or Bull Board user has — one binary, no web server, talks straight to Redis.

Next steps

Section titled “Next steps”