Buildkite CLI agent command

The bk agent command allows you to manage Buildkite agents from the command line.

Commands

Command	Description
`bk agent pause`	Pause a Buildkite agent.
`bk agent list`	List agents.
`bk agent resume`	Resume a Buildkite agent.
`bk agent stop`	Stop Buildkite agents.
`bk agent view`	View details of an agent.

Pause an agent

Pause a Buildkite agent.

bk agent pause <agent-id> [flags]

Arguments

Argument	Description
`<agent-id>`	Agent ID to pause

Flags

Flag	Description
`--debug`	Enable debug output for REST API calls
`--note=STRING`	A descriptive note to record why the agent is paused
`--timeout-in-minutes=5`	Timeout after which the agent is automatically resumed, in minutes

Examples

Pause an agent for 5 minutes (default):

bk agent pause 0198d108-a532-4a62-9bd7-b2e744bf5c45

Pause an agent with a note:

bk agent pause 0198d108-a532-4a62-9bd7-b2e744bf5c45 --note "Maintenance scheduled"

Pause an agent with a note and 60 minute timeout:

bk agent pause 0198d108-a532-4a62-9bd7-b2e744bf5c45 --note "too many llamas" --timeout-in-minutes 60

Pause for a short time (15 minutes) during deployment:

bk agent pause 0198d108-a532-4a62-9bd7-b2e744bf5c45 --note "Deploy in progress" --timeout-in-minutes 15

List agents

List agents.

bk agent list [flags]

Flags

Flag	Description
`--debug`	Enable debug output for REST API calls
`--hostname=STRING`	Filter agents by their hostname
`--limit=100`	Maximum number of agents to return
`-o, --output=""`	Output format. One of: json, yaml, text
`--name=STRING`	Filter agents by their name
`--per-page=30`	Number of agents per page
`--state=STRING`	Filter agents by state (running, idle, paused)
`--tags=TAGS,...`	Filter agents by tags
`--version=STRING`	Filter agents by their version

Examples

List all agents:

bk agent list

List agents with JSON output:

bk agent list --output json

List only running agents (currently executing jobs):

bk agent list --state running

List only idle agents (connected but not running jobs):

bk agent list --state idle

List only paused agents:

bk agent list --state paused

Filter agents by hostname:

bk agent list --hostname my-server-01

Combine state and hostname filters:

bk agent list --state idle --hostname my-server-01

Filter agents by tags:

bk agent list --tags queue=default

Filter agents by multiple tags (all must match):

bk agent list --tags queue=default --tags os=linux

Multiple filters with output format:

bk agent list --state running --version 3.107.2 --output json

Resume an agent

Resume a Buildkite agent.

bk agent resume <agent-id>

Arguments

Argument	Description
`<agent-id>`	Agent ID to resume

Flags

Flag	Description
`--debug`	Enable debug output for REST API calls

Examples

Resume an agent:

bk agent resume 0198d108-a532-4a62-9bd7-b2e744bf5c45

Stop agents

Stop Buildkite agents.

bk agent stop [<agents> ...] [flags]

Flags

Flag	Description
`-l`, `--limit=5`	Limit parallel API requests
`--debug`	Enable debug output for REST API calls
`--force`	Force stop the agent. Terminating any jobs in progress

Examples

Stop a single agent:

bk agent stop 0198d108-a532-4a62-9bd7-b2e744bf5c45

Stop multiple agents:

bk agent stop agent-1 agent-2 agent-3

Force stop an agent:

bk agent stop 0198d108-a532-4a62-9bd7-b2e744bf5c45 --force

Stop agents from STDIN:

cat agent-ids.txt | bk agent stop

View an agent

View details of an agent.

bk agent view <agent> [flags]

Arguments

Argument	Description
`<agent>`	Agent ID to view

Flags

Flag	Description
`-w`, `--web`	Open agent in a browser
`-o, --output=""`	Output format. One of: json, yaml, text
`--debug`	Enable debug output for REST API calls

Examples

View an agent:

bk agent view 0198d108-a532-4a62-9bd7-b2e744bf5c45

View an agent with organization slug:

bk agent view my-org/0198d108-a532-4a62-9bd7-b2e744bf5c45

Open agent in browser:

bk agent view 0198d108-a532-4a62-9bd7-b2e744bf5c45 --web

View agent as JSON:

bk agent view 0198d108-a532-4a62-9bd7-b2e744bf5c45 --output json