support@build.io
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, a reference for all available commands and a section for miscellaneous useful operations.
2.1 Installing the Build CLI
The preferred way of installing the CLI is to use the Crystal version (the ruby gem is no longer being updated).
2.1.1 Mac
You can install with Homebrew:
$ brew install buildio/cli/bld
2.1.2 Linux
Homebrew
You can install with Homebrew even on Linux.
For Ubuntu, first install this dependency:
$ apt install libpcre3-dev
$ brew install buildio/cli/bld
Manual Install
Install Crystal (lang) and Shards (package manager) using the package manager of the distribution that you are using.
Fedora/RHEL/CentOS
For Fedora, you can use dnf:
$ sudo dnf install crystal
$ sudo dnf install libssh2-devel
Ubuntu/Debian
For Ubuntu, you can use apt:
$ sudo apt install crystal
$ sudo dnf install shards
Generic Linux Install
There is also a generic Linux install that will figure out your package manager for you.
You'll need crystal 1.16. Available from the PPA:
https://crystal-lang.org/install/
If you inspect the script first:
https://crystal-lang.org/install.sh
Then this adds to your sources:
$ curl -fsSL https://crystal-lang.org/install.sh | sudo bash
2.1.3 Build the CLI
Once you have Crystal installed, you can downloaded the Crystal CLI directly from the (public) GitHub account with:
$ git clone git@github.com:buildio/cli.git
$ cd cli/ && shards build
2.2 Authentication and login
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
OIDC Login
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 Command reference
The Build CLI organises commands into groups based on the resource they manage. Below is a summary of all available commands.
Global Options
These options can be used with any command:
Getting Help
To see help for any command, use the --help flag:
$ bld apps:create --help
Or use the help command:
$ bld help apps:create
General Commands
Apps
Config Vars
Processes
Namespaces
Teams
Pipelines
2.4 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