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 agents across all deployed components in the current application. The output includes each agent’s name, component, status, and revision.

By default only durable agents are listed. Use --mode ephemeral or --mode all to include ephemeral agents (--mode is ignored when a mode filter is passed via --filter).

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"`
`mode`	`=`, `!=`	`--filter "mode = ephemeral"`
`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 '<cursor-from-previous-output>'

The cursor is an opaque value returned in the output when there are more results. Pass it back unchanged 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"