2. Command Line Interface (CLI)

The Build CLI gives you command-line access to your applications and account. While the dashboard is ideal for visual workflows and one-off tasks, the CLI shines when you need to script deployments, automate configuration changes, or quickly check on your apps without leaving the terminal.

This section covers installing the CLI, authenticating with your account, and a section for miscellaneous useful operations. For a full list of commands, see the CLI Command Reference.

2.1 Installing the Build CLI

Install the CLI with your platform’s package manager.

2.1.1 macOS: Homebrew

$ brew install buildio/cli/bld
$ brew trust buildio/cli

2.1.2 Windows: Scoop

> scoop bucket add buildio https://github.com/buildio/cli
> scoop install bld

2.1.3 Linux: APT

Run the install script. It adds the Build APT repository and its signing key, then installs bld (amd64 only):

$ curl -fsSL https://buildio.github.io/cli/install.sh | sh

After that, sudo apt update && sudo apt upgrade keeps bld up to date.

2.1.4 Check the install

Confirm the CLI is on your path:

$ bld --version

Then log in as described in the next section.

Before you can interact with your Build apps from the command line, you need to authenticate the CLI with your Build account.

Logging In

To authenticate, run the login command:

$ bld login

This opens your default web browser and takes you to the Build login page. After you sign in and authorise the CLI, your credentials are saved locally and you’re ready to start using commands.

You can verify that you’re logged in by checking your current user:

$ bld whoami

you@example.com

If your organisation uses single sign-on (SSO) or you need to authenticate directly with the Build cluster, use the OIDC login command:

$ bld oidc-login

This authenticates using OpenID Connect, which may be required for certain enterprise configurations or when accessing cluster-level resources.

Session Management

Your login session persists until you explicitly log out or your token expires. If you encounter authentication errors after a period of inactivity, simply run bld login again to refresh your credentials.

2.3 Useful Operations

If you’re moving an application from Heroku to Build, you can quickly transfer your environment configuration using both CLI tools.

Importing Config Vars from Heroku

Your Heroku app’s config vars can be exported and imported into Build in two steps.
First, use the Heroku CLI to export your config vars to a file:

$ heroku config -a your-heroku-app -s > env-backup

The -s flag outputs the variables in shell format (KEY=value), one per line, which makes them easy to import.

Then, pipe the file into the Build CLI to set all the variables on your new app:

$ cat env-backup | xargs bld config:set -a your-build-app

This reads each line from the backup file and passes them as arguments to the config:set command, recreating your entire environment configuration in one go.

Verifying the Import

After importing, confirm that your config vars were transferred correctly:

$ bld config:list -a your-build-app

Compare this output against your original Heroku configuration to ensure nothing was missed.

A Note on Secrets

The env-backup file will contain sensitive values like API keys and database credentials. Be sure to delete it after the import is complete, and avoid committing it to version control:

$ rm env-backup