golem-list-and-filter-agents

name	golem-list-and-filter-agents
description	Listing and querying agents with filters. Use when listing all agents, filtering agents by name, status, revision, creation time, or environment variables, or paginating through agent results.

Listing and Filtering Agents

Both golem and golem-cli can be used — all commands below work with either binary.

agent list — List All Agents

golem agent list

Lists all agents across all deployed components in the current application. The output includes each agent's name, component, status, and revision.

Filtering by Agent Type

Pass an agent type name as a positional argument to list only agents of that type:

golem agent list CounterAgent

Filtering by Component

Use --component-name to list agents belonging to a specific component:

golem agent list --component-name my-component

Note: --component-name and the agent type name positional argument are mutually exclusive.

Property-Based Filters (--filter)

Use --filter to filter agents by metadata properties. Each filter has the format property comparator value. Multiple --filter flags are combined with AND logic.

Filterable Properties

Property	Comparators	Example
name	=, !=, like, notlike, startswith	--filter "name = CounterAgent(\"c1\")"
status	=, !=, >, >=, <, <=	--filter "status = Running"
revision	=, !=, >, >=, <, <=	--filter "revision >= 2"
created_at	=, !=, >, >=, <, <=	--filter "created_at > 2025-01-01T00:00:00Z"
env.<VAR>	=, !=, like, notlike, startswith	--filter "env.MODE = production"

Agent Status Values

Valid status values: Running, Idle, Suspended, Interrupted, Retrying, Failed, Exited.

String Comparators

Comparator	Aliases	Description
=	==, equal, eq	Exact match
!=	notequal, ne	Not equal
like	—	Contains substring
notlike	—	Does not contain substring
startswith	—	Starts with prefix

Numeric/Ordinal Comparators (for status, revision, created_at)

Comparator	Aliases	Description
=	==, equal, eq	Equal
!=	notequal, ne	Not equal
>	greater, gt	Greater than
>=	greaterequal, ge	Greater than or equal
<	less, lt	Less than
<=	lessequal, le	Less than or equal

Combining Filters

Multiple --filter flags are combined with AND:

golem agent list --filter "status = Running" --filter "name like counter"

Pagination

Use --max-count to limit the number of results and --scan-cursor to paginate:

golem agent list --max-count 10
golem agent list --max-count 10 --scan-cursor 0/5

The cursor is returned in the output when there are more results. Use it in the next call to get the next page.

Note: --scan-cursor requires a single component to be selected (either via --component-name or by being in a single-component application directory).

Precise Mode

Use --precise to query the most up-to-date status for each agent (slightly slower):

golem agent list --precise

Watch Mode (--refresh)

Use --refresh to continuously refresh the agent list on screen. Refresh mode is interactive and only supports text output.

golem agent list --refresh           # Default 400ms interval
golem agent list --refresh=1000      # Custom 1-second interval

Note: --refresh conflicts with --scan-cursor and cannot be combined with structured formats such as --format json, --format yaml, or --format toon.

Examples

List all agents:

golem agent list

List only running agents:

golem agent list --filter "status = Running"

List agents of a specific type:

golem agent list CounterAgent

Find agents by name pattern:

golem agent list --filter "name like test"

List agents with a specific environment variable value:

golem agent list --filter "env.MODE = production"

Combine filters (AND logic):

golem agent list --filter "status = Idle" --filter "revision >= 2"