opschain agents posture

packs:agents

opschain agents posture [--project <code>] [--tier none|advise|supervised|autonomous] [--type service|ai]
                        [--stale] [--departed-owner] [-o json|yaml|csv] [--server <url>] [--auth-token <token>]

Lists every agent enrolled in this estate with its posture (v2 AgentPostureService.ListAgentPosture): one row per agent, not per instance — the effective tier from the compiled trust snapshot, the owning principal and whether the identity catalog still holds it, the assigned subtree, the release and its stage, the instances enrolled and connected, the last governed action with its correlation chain, the token caps and the spend against them, the transcript and data-handling markers, the manifest disclosures, health, and whether the agent is stale (no governed action within agents.stale_after, 168h by default). It is not discovery: the list is what is enrolled, nothing else (opschain docs agent-posture).

Without --project the whole estate is read, which needs read on the root; with it, read on the project (a project you may not read is reported as unknown).

Flags

Flag	Meaning
--project <code>	Project code to read. Default: the whole estate.
--tier <tier>	Keep only agents at this effective tier: none, advise, supervised or autonomous.
--type <type>	Keep only agents declaring this type: service or ai.
--stale	Keep only stale agents — no governed action within agents.stale_after, never-acted agents included.
--departed-owner	Keep only agents whose owning principal has departed: an owner is set but the identity catalog no longer holds an enabled user or a known group by that name.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output

The table lists one row per agent: AGENT (project/code), TYPE, TIER, OWNER (the stored reference, marked (departed) when the catalog no longer holds it), RELEASE (name@version stage), INSTANCES (connected/enrolled), LAST ACTION (instant, kind, outcome), SPEND (window used/cap per token-cap window), HEALTH and STALE, followed by a totals line — agents enrolled, stale, over a token cap, with a departed owner, without an owner.

-o json / -o yaml carry computed_at, stale_after, summary (total, by_tier, stale, over_cap, owner_departed, without_owner) and rows — every field of the posture row (opschain docs resources/agent_posture).

-o csv prints one row per agent the way an external inventory keys on it: agent_id and release_digest in every row, the owner as owner_principal_id only — never a username or an email leaves the estate in this export. Columns: agent_id, principal_id, project_path, code, name, type, group, owner_principal_id, owner_departed, tier, assigned_scopes (space-separated), release_id, release_name, release_version, release_stage, release_digest, instances, instances_connected, last_action_at, last_action_kind, last_action_outcome, last_action_correlation_id, token_windows (window=used/cap, space-separated), over_cap, transcripts_captured, model_provider, data_handling_approved, health, last_seen_at, stale.

Exit codes

Code	Meaning
0	The inventory was printed (an empty one included).
1	The server refused or failed the request (an unreadable project, an unknown tier or type, a rejected credential).
2	Usage — no server / credential resolvable.

Named errors

• filter.tier must be none, advise, supervised or autonomous / filter.agent_type must be service or ai — the server's field violations, exit 1.
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
• the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.

Examples

Every agent enrolled in a project:

opschain agents posture --project limebank

The estate's stale AI agents, and the agents whose owner has left:

opschain agents posture --type ai --stale
opschain agents posture --departed-owner

The inventory a CAIO pastes into their own register:

opschain agents posture -o csv > agents.csv

Related settings

• agents.stale_after — the staleness threshold (168h by default).
• agents.assignment_floor — whether an assignment alone confers advise.

See also

• opschain docs agent-posture — the component page.
• opschain docs cli/agents-usage — the token telemetry behind the spend column.
• opschain docs cli/admin-agent-trust-review — one agent's grants, caps and timeline.
• opschain docs cli/admin-agent-owner — reassigning a departed owner.