opschain admin agents list

packs:agents

opschain admin agents list [--project <code>] [--server <url>] [--auth-token <token>]

Lists the registered agents (v2 AgentService.ListAgents), sorted by project then code — the agent half of the unified fleet view. The default rendering is a table; -o json or -o yaml prints the raw rows (which carry more fields than the table shows, e.g. spec and agent versions, capabilities and halt metadata).

PROJECT  CODE  NAME       ID          GROUP    ONLINE  LAST SEEN             CHANNEL  STATE  RELEASE      LANE    PROVIDER
/demo    sre   sre-agent  01999a7e-…  default  ✓       2026-10-14T03:12:09Z  stream   ready  sre@2.0.0    stable  demo-anthropic
/demo    sre   sre-agent  01999a81-…  default  ✓       2026-10-14T03:12:11Z  stream   ready  sre@2.1.0    shadow  demo-anthropic

One row per instance: an agent with several running processes lists one row each, grouped under the code by release then lane.

• ONLINE — ✓ when the agent was seen within the liveness window (3 minutes) and has not said goodbye; - otherwise.
• CHANNEL — the live carriage on this replica: stream, poll, or -.
• STATE — halted (optionally (group)) wins, then stopped, then quiesced for a drain (with (group) or (agent+group) scope — an agent holds no jobs, so a drain always reads quiesced), then ready when online, else - (never seen).
• RELEASE / LANE — the release the instance enrolled from (name@version; - without one) and the lane it serves (stable, shadow, canary or a label); the JSON rows add instance_id and release_stage. opschain admin agent instances <agent> is the per-agent view.
• PROVIDER — the model-provider catalog code the agent's manifest binds its model calls to (exactly one entry, by code — never resolved by kind, so with several anthropic entries this names the one in use); - when the agent brokers through none. --filter provider=<code> lists one provider's agents. The JSON rows add the entry's model_provider_kind and live model_provider_state (ok / disabled / missing); opschain admin agent show renders them on its MODEL PROVIDER row. Not the disclosed model vendor — that is the detail's MODEL row.

The ID column is the <agent-id> every opschain admin agent verb takes.

Flags

Flag	Meaning
--project <code>	Only list agents of this project.
--server <url>	Server base URL. Default: the active context, then 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 for that server.
--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; --project narrows server-side. Grammar: opschain docs cli.

Exit codes

Code	Meaning
0	The fleet was printed (an empty fleet prints just the header).
1	The server refused or failed the request (including a rejected admin token).
2	Usage — unexpected arguments, or no server / admin token resolvable.

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-agent-show — one agent in full.
• opschain docs cli/admin-agent — the per-agent lifecycle verbs.
• opschain docs cli/admin-agent-token-create — enrol a new agent.