Buildkite CLI agent command
The bk agent command allows you to manage Buildkite agents from the command line.
Commands
| Command | Description |
|---|---|
bk agent install |
Install the buildkite-agent binary locally. |
bk agent run |
Run an ephemeral buildkite-agent locally. |
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. |
Install agent
Install the buildkite-agent binary locally.
By default, this also creates an agent token on the Default cluster and writes a minimal config file so the agent is ready to start.
bk agent install [flags]
Flags
| Flag | Description |
|---|---|
--cluster-uuid=STRING |
Cluster UUID to create the agent token on (default: the "Default" cluster) |
--config-path=STRING |
Path to write the agent config file |
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--dest=STRING |
Destination directory for the binary |
--no-token |
Skip creating an agent token and config file |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
--version="latest" |
Specify an agent version to install |
Examples
Install the latest version of the agent:
bk agent install
Install a specific version:
bk agent install --version "3.112.0"
Install to a custom location:
bk agent install --dest ~/.local/bin
Install without creating a token/config:
bk agent install --no-token
Run agent
Run an ephemeral buildkite-agent locally.
Downloads the agent binary, creates a cluster token, and starts the agent. All temporary files are cleaned up when the agent is stopped with Ctrl+C.
bk agent run [flags]
Flags
| Flag | Description |
|---|---|
--cluster-uuid=STRING |
Cluster UUID to create the agent token on (default: the "Default" cluster) |
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
--queue="default" |
Queue for the agent to listen on |
--version="latest" |
Specify an agent version to run |
Examples
Run the latest agent on the Default cluster:
bk agent run
Run a specific version:
bk agent run --version "3.112.0"
Run on a specific cluster:
bk agent run --cluster-uuid "01234567-89ab-cdef-0123-456789abcdef"
Run on a specific queue:
bk agent run --queue "deploy"
Pause an agent
Pause a Buildkite agent.
When an agent is paused, it will stop accepting new jobs but will continue running any jobs it has already started. You can optionally provide a note explaining why the agent is being paused and set a timeout for automatic resumption.
The timeout must be between 1 and 1440 minutes (24 hours). If no timeout is specified, the agent will pause for 5 minutes by default.
bk agent pause <agent-id> [flags]
Arguments
| Argument | Description |
|---|---|
<agent-id> |
Agent ID to pause |
Flags
| Flag | Description |
|---|---|
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--note=STRING |
A descriptive note to record why the agent is paused |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
--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.
By default, shows up to 100 agents. Use filters to narrow results, or increase the number of agents displayed with --limit.
bk agent list [flags]
Flags
| Flag | Description |
|---|---|
-o, --output=""
|
Output format. One of: json, yaml, text |
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--hostname=STRING |
Filter agents by their hostname |
--json |
Output as JSON |
--limit=100 |
Maximum number of agents to return |
--name=STRING |
Filter agents by their name |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
--per-page=30 |
Number of agents per page |
--state=STRING |
Filter agents by state (running, idle, paused) |
--tags=TAGS,... |
Filter agents by tags |
--text |
Output as text |
--version=STRING |
Filter agents by their version |
--yaml |
Output as YAML |
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.
Resume a paused Buildkite agent.
When an agent is resumed, it will start accepting new jobs again.
bk agent resume <agent-id>
Arguments
| Argument | Description |
|---|---|
<agent-id> |
Agent ID to resume |
Flags
| Flag | Description |
|---|---|
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
Examples
Resume an agent:
bk agent resume 0198d108-a532-4a62-9bd7-b2e744bf5c45
Stop agents
Stop Buildkite agents.
Instruct one or more agents to stop accepting new build jobs and shut itself down. Agents can be supplied as positional arguments or from STDIN, one per line.
If the "ORGANIZATION_SLUG/" portion of the "ORGANIZATION_SLUG/UUID" agent
argument is omitted, it uses the currently selected organization.
The --force flag applies to all agents that are stopped.
bk agent stop [<agents> ...] [flags]
Flags
| Flag | Description |
|---|---|
-l, --limit=5
|
Limit parallel API requests |
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--force |
Force stop the agent. Terminating any jobs in progress |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
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.
If the "ORGANIZATION_SLUG/" portion of the "ORGANIZATION_SLUG/UUID" agent
argument is omitted, it uses the currently selected organization.
bk agent view <agent> [flags]
Arguments
| Argument | Description |
|---|---|
<agent> |
Agent ID to view |
Flags
| Flag | Description |
|---|---|
-o, --output=""
|
Output format. One of: json, yaml, text |
-w, --web
|
Open agent in a browser |
--debug |
Log HTTP API traffic to stderr; bodies may contain sensitive data |
--json |
Output as JSON |
--org=STRING |
Organization slug for this invocation (overrides environment and configuration) |
--text |
Output as text |
--yaml |
Output as YAML |
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