Skip to main content
Version: v5.7.0

opschain admin runners list

Included from Basic tier

opschain admin runners list [--group <name>]

Lists every registered runner (the v2 RunnerService.ListRunners RPC) with its group, liveness, current job and lifecycle state — the fleet's at-a-glance health view. Rows are sorted by group, then name; an exclusive group is annotated (exclusive) in the GROUP column.

Flags​

FlagMeaning
--group <name>Only list runners of this group (passed to the server as the group query parameter).
--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, then the token stored by opschain admin login.
--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. Applied client-side; --group narrows server-side. Grammar: opschain docs cli.

-o json|yaml prints the runner rows as a machine document instead of the table.

Output​

GROUP               NAME      ID       ATTRIBUTES                 ONLINE  LAST SEEN             JOB       STATE
default             build-01  r-01…    -                          ✓       2026-10-14T03:12:09Z  step-7#1  ready
secure (exclusive)  vault-01  r-02…    location=dc1,network=sec   -       never                 -         -
  • ONLINE is ✓ or -; LAST SEEN is RFC 3339 UTC, or never for a runner that registered but has not reported in.
  • JOB lists the held jobs as <step-id>#<attempt>, or - when idle.
  • STATE reads ready (online, undrained), stopped (said goodbye), draining (drain in force with jobs still finishing) or quiesced (drained and idle) — the drain's scope is appended as (group) or (runner+group) when a group drain is involved — and - for an offline, undrained runner.

Exit codes​

0 listed; 1 the request failed (network, HTTP error, rejected token); 2 usage.

Named errors​

  • a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' (exit 2)
  • 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 (exit 1)

See also​

  • opschain docs cli/admin-runner-show — one runner in full, including host inventory.
  • opschain docs cli/admin-runner-group-list — the groups the GROUP column names.
  • opschain docs fleet-queue — how group, attributes, drain and liveness decide what this fleet is offered.
  • opschain learn 6.1 — the runners-and-fleet walkthrough.