Buildkite CLI configuration

The Buildkite CLI uses both the REST and GraphQL APIs to interact with Buildkite, and therefore, requires the configuration of an API access token.

Authenticate using OAuth

You can authenticate the Buildkite CLI using OAuth with the bk auth login command, which opens your browser to complete the authentication flow.

By default, bk auth login requests all available REST API scopes. The Buildkite platform enforces server-side restrictions. The issued token only grants permissions that your Buildkite user account actually has. The graphql scope is excluded from this process due to its unscoped nature.

To restrict the scopes requested during OAuth login, use the --scopes flag. For example, --scopes "read_only" requests only read access. You can also combine scope groups with individual scopes, such as --scopes "read_only write_builds". Learn more about available scopes in Token scopes.

Restricting CLI token scopes

For organizations that enforce the principle of least privilege, use --scopes to issue CLI tokens with only the minimum scopes required. Without --scopes, the token is issued with all scopes that your account has permission for.

Create an API access token for the Buildkite CLI

To create a new API access token:

Select your user profile icon > Personal Settings in the global navigation.
Select API Access Tokens to access your API Access Tokens page.
Select New API Access Token to open the New API Access Token page.
Specify a Description and the Organization Access (that is, the specific Buildkite organization) for this token.
Once you have selected the required REST API Scopes and Enable GraphQL API access for the token, retain a copy of your API access token's value in a secure location.

Note: You can also use the following New API Access Token page links with pre-set fields to create these API access tokens:

New API access token with description—pre-sets the Description field with Buildkite CLI.
New API access token with description and API scopes—pre-sets the Description field with Buildkite CLI, along with all the required REST API Scopes and Enable GraphQL API access options already selected.

If you use one of these links, you must still specify the Buildkite organization (in Organization Access) for this API access token.

Configure the Buildkite CLI with your API access token

Once you have created your API access token, you'll need to configure the Buildkite CLI with this token.

To do this:

Run the following command:
```
bk configure
```
When prompted for Organization slug, specify the slug for your Buildkite organization.
When prompted for API Token, specify the value for your configured API access token.

Note: Upon successfully running this command for the first time, a new file is created at $HOME/.config/bk.yaml, which stores the Buildkite organization and its API access token configuration for your local Buildkite CLI.

Using command flags

You can also run the bk configure command with the command flags, --org and --token, each of which can take either a literal or environment variable for the Buildkite organization slug and API access token, respectively.

For example:

bk configure --org my-buildkite-organization --token $BUILDKITE_API_TOKEN

Command behavior and configuration files

The bk configure command is directory-specific, and running this command also creates a file called .bk.yaml in your current directory, which records the current Buildkite organization that your bk command is configured to work with from this current directory.

Attempting to run this command again in the same directory results in an error (due to the presence of a .bk.yaml file). Instead:

You can configure your Buildkite CLI tool to work with other Buildkite organizations.
If your Buildkite CLI is already configured with multiple organizations, you can choose a different Buildkite organization for it to work with.

If you run this command in a new directory (without a .bk.yaml file), and you specify a different API access token value for a Buildkite organization which has already been configured in $HOME/.config/bk.yaml, then this new API access token replaces the existing one configured in this file for that Buildkite organization.

Configure the Buildkite CLI with multiple organizations

Some users may have access to Buildkite organizations—one for their company, and others for open-source work, personal work, etc.

The Buildkite CLI tool allows you to work with such multiple Buildkite organizations.

To configure the Buildkite CLI tool with another Buildkite organization:

Ensure you have created individual API access tokens for each Buildkite organization to configure in the Buildkite CLI tool.
Run the following command:
```
bk configure add
```
When prompted for Organization slug, specify the slug for the new Buildkite organization to add to the Buildkite CLI.
When prompted for API Token, specify the value for your configured API access token for this organization.

Note: Upon success, a new Buildkite organization and corresponding API access token entry is added to your $HOME/.config/bk.yaml. This file stores all currently configured Buildkite organizations and their respective API access tokens for your local Buildkite CLI.

Select a configured organization

If your Buildkite CLI tool has been configured with multiple Buildkite organizations, you can switch from your current/active Buildkite organization to another. To do this:

Run the following command:
```
bk use
```
Use the cursor select another configured Buildkite organization and make it the current/active one. All subsequent bk commands will operate with the new active organization.

Notes:
- If you already know the slug of the other Buildkite organization you're switching to, you can specify this value immediately after the bk use command, for example, bk use my-other-organization.
- Upon success, the .bk.yaml file in your current directory is updated with your current/active Buildkite organization.