Configuring the Bitrise CLI

The Bitrise CLI reads default values from config files, so you don't have to pass the same flags to every command. For example, you can save the project a repository belongs to, or make every command print JSON.

Bitrise CLI 3.0.0 or newer

The bitrise config commands and the config keys on this page need Bitrise CLI 3.0.0 or newer. To update, run bitrise update.

Configuration file locations

The CLI reads configuration from up to three files, in order of precedence from highest to lowest:

1. The legacy config file, ~/.bitrise/config.json. See The legacy config file.
2. A per-directory config file, .bitrise-cli.yml. The CLI looks for it in the current directory, then in each parent directory, and uses the first one it finds.
3. The global config file, ~/.config/bitrise/cli/config.yml. Set $XDG_CONFIG_HOME to read it from somewhere other than ~/.config. Run bitrise config path to print its location.

If none of the files set a value, the CLI falls back to its built-in default.

Flags and Environment Variables override every config file. For example, the CLI picks the project for a command in this order:

1. The --app flag.
2. The BITRISE_APP_ID Environment Variable, then BITRISE_APP_SLUG.
3. The app_id key in a .bitrise-cli.yml file.
4. The app_id key in the global config file.

Make sure ~/.config (or $XDG_CONFIG_HOME, if you set it) is writable. Otherwise, bitrise local setup and plugin commands can fail.

Config keys

Key	What it sets	Environment Variable	Default
app_id	The project that commands act on when you don't pass --app.	BITRISE_APP_ID, BITRISE_APP_SLUG	None
default_workspace_id	The Workspace that commands act on when you don't pass --workspace.	BITRISE_WORKSPACE_ID	Your only Workspace, if you have one
output	The output format: raw, json, or yml.	BITRISE_OUTPUT	raw
theme	The color theme: auto, dark, light, or none.	BITRISE_CLI_THEME	auto
api_base_url	The Bitrise API host.	BITRISE_API_BASE_URL	https://api.bitrise.io/v0.1
web_base_url	The Bitrise website host, used for logging in with your email and password, and for opening a project with bitrise app view --web.	BITRISE_WEB_BASE_URL	https://app.bitrise.io
rde_api_base_url	The Remote Dev Environment API host.	BITRISE_RDE_API_BASE_URL	https://api.bitrise.io/rde

Inside a Bitrise build, BITRISE_APP_SLUG and BITRISE_WORKSPACE_ID are always set, so commands act on the build's own project and Workspace unless you pass a flag.

Your access token isn't a config key: it's saved to a separate file. See Authenticating with the Bitrise CLI.

Base URLs

There are three exceptions to the configuration order: only the glocal configuration file can set the keys that define base URLs. The CLI ignores these keys in a .bitrise-cli.yml file:

• api_base_url
• web_base_url
• rde_api_base_url

Their corresponding Environment Variables override even the global config file:

• BITRISE_API_BASE_URL
• BITRISE_WEB_BASE_URL
• BITRISE_RDE_API_BASE_URL

All three set a host that the CLI sends your credentials to, and the CLI reads a .bitrise-cli.yml from any parent directory without asking you first. If it read these keys from there, a repository you only cloned could redirect your login to a server you don't control.

Managing the global config file

Use the bitrise config commands to read and write the global config file:

Command	What it does
bitrise config set KEY VALUE	Set a key.
bitrise config get KEY	Print the value of a key.
bitrise config unset KEY	Remove a key.
bitrise config list	Print every key saved in the file. Takes --format json or --format yml.
bitrise config path	Print the location of the file.

For example, to make my-app-id the default project:

bitrise config set app_id my-app-id

注記

bitrise app create also saves the ID of the new project as app_id.

bitrise config list only shows what's saved in the global config file. When a command runs, flags, Environment Variables, and a .bitrise-cli.yml file can override those values.

Pinning a repository to a project

Add a .bitrise-cli.yml file to the root of a repository to set the project and workspace for every command you run inside it. The bitrise config commands don't write this file, so create it by hand:

app_id: my-app-id
default_workspace_id: my-workspace-id

Now bitrise build list or bitrise yml get, run anywhere in the repository, act on my-app-id without the --app flag.

Besides app_id and default_workspace_id, the file can set output and theme. It can't set the base URLs.

The legacy config file

Bitrise CLI versions before 3.0.0 saved their settings to ~/.bitrise/config.json. The file only contains internal state: the version of the last bitrise local setup and when the CLI last checked for updates of itself and its plugins. You don't have to edit it.

If the file exists, the CLI keeps reading it and its values take precedence. When the CLI updates one of these values, it writes both config.json and config.yml. A new installation doesn't create config.json.