Version: v5.7.0

opschain admin queue

Included from Basic tier

The dispatch plane's X-ray: the admin-gated v2 SystemService.GetDispatchQueue read, showing ready-queue depth per queue/lane bucket, the age of the oldest waiting step, and every live job lease — run, step, attempt, which replica's dispatcher claimed it (JOB HOLDER), whether the runner has renewed it, when it expires, and which replica is DRIVING the owning run under its drive lease (DRIVE HOLDER / DRIVE EXPIRES; drive_holder / drive_expires_at in -o json). The two holders are different things by design: the job lease stays with whichever dispatcher offered the step (the runner keeps renewing it on whichever replica answers, so a dead replica's id can sit there for the step's lifetime), while the drive lease names the replica applying the run's events — it moves to a peer within the staleness window when the driver dies (opschain docs cli/admin-status for replica liveness). An empty DRIVE HOLDER (-) means no live drive lease: the run is adoptable and a peer's sweep claims it within seconds. Reach for it when work was created but nothing seems to run: a deep ready count with idle runners, or leases that never renew, each point at a different culprit (opschain docs fleet-queue walks the verdict ladder).

Three subverbs (on the API v2 FleetQueueService) go per-entry: opschain admin queue list renders every entry with its owning work item (change / workflow run / node background task), target path and correlation chain; terminate <run-id> cancels an entry's owner through its own lane; sweep discards parked entries whose owner is already finalised. Each has its own manual page.

Flags

Flag	Meaning
`--server <url>`	Server base URL (default: the active context / `OPSCHAIN_SERVER`).
`--auth-token <token>`	Admin bearer token override (default: your `opschain login` session, then `$OPSCHAIN_ADMIN_TOKEN`).
`--filter <column>[!]=<value>`	Keep only rows matching the term (repeatable; terms AND). Columns are the printed table headers lowercased (spaces/dashes fold to `_`); `*` wildcards match the whole cell case-insensitively, `!=` negates, commas mean any-of. Filters the lease rows only (the ready summary above the table is unaffected); `-o json`/`-o yaml` carry the filtered leases. Grammar: `opschain docs cli`.

Like every admin verb, this command rides your opschain login session by default, with the admin-token lanes as the automation fallback. -o json|yaml prints the raw queue document.

Exit codes

Code	Meaning
0	Queue fetched.
1	Request failed, non-200 response, or the token was rejected.
2	Usage error — missing server or token.

Named errors

this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login' — exit 2.
the server rejected the credential — run 'opschain login' again, or check the admin token — HTTP 401 (exit 1).
the server answered <code>: <message> — any other refusal (exit 1).

Examples

opschain admin queue --server https://ops.example.com
ready: 2
  default/runs: 2
oldest waiting: 34.6s
leases: 1
RUN       STEP      ATTEMPT  JOB HOLDER  RENEWED  EXPIRES               DRIVE HOLDER  DRIVE EXPIRES
01999a7e  0199a1c2  1        replica-a   true     2026-10-14T03:12:09Z  replica-b     2026-10-14T03:09:24Z

Filter columns follow the headers: --filter job_holder=replica-a, --filter drive_holder=replica-b.

leases: 0 with a growing ready count means nothing is being offered — check runner liveness, group bindings and demand before suspecting the queue itself.

Flags​

Exit codes​

Named errors​

Examples​

See also​

Flags

Exit codes

Named errors

Examples

See also