Buildless CLI

Command-line access and management of build caches

The Buildless CLI offers command-line access to your build cache, and control over various features. See below for use guides and references.


The CLI is awesome and free forever.

We highly recommend it, if only because the near-cache functionality accelerates builds significantly, and allows graceful recovery through connectivity blips and other transient issues.

Our CLI and agent service are free, forever, for unlimited users. You only need to pay for Buildless if you consume cloud resources.

About the CLI

Things it can do

  • Integrate your build caching with Git
  • Near-caching, with or without cloud backhaul
  • Install, start/stop, and manage your local build agent service (optional)
  • Show your effective configuration, or your logged-in account
  • Join the Discord, access support/help

Where it can be used

  • On developer machines, to accelerate day-to-day builds
  • On CI systems, to accelerate and measure automated builds


*nix only at this time

The CLI is new and currently only available for macOS and Linux. We are working hard to finish our Windows version. If you need Windows support, please file an issue and we can add you to our beta program.

Getting Started

To use the CLI, you must install it on your machine, and, optionally, log in using your Buildless account.


There are several ways to install the CLI:


This part is easy. Authorizing the CLI is optional, but you must perform this step to share caches via the Buildless cloud service:

buildless login

The flow continues in your browser. After confirming authorization in your browser, the CLI completes the flow on its own. For environments without a browser see buildless login --help.


The CLI is designed to resolve configuration from known places on-disk, and from environment variables. Your "effective" Buildless configuration may depend on a number of factors, including your current working directory, and any active "project" within your working directory.

Override precedence

Buildless supports loading multiple configurations. All configurations exist within a given "scope" from the list below, expressed in reverse priority order (with earlier entries winning):

  • Environment variable overrides
  • Project-level configurations
  • User-level configurations
  • Machine-global configurations
  • Built-in defaults, hard-coded configurations

Config location & format

Buildless supports several formats for configuration: YAML, JSON, TOML, and Properties. See below for a table of example settings in each format.

FormatExtensionsExample keyFormatted key
YAMLyml, yaml

The following configuration paths are supported by default:

Environment variables

  • BUILDLESS_APIKEY: Overrides authorization with the current user's API key

Project configuration

  • package.json: Block with key buildless
  • (Coming soon)

User-level configuration

  • ~/.config/buildless.yml
  • (Coming soon)

Machine-global configuration

  • /etc/buildless/buildless.yml
  • (Coming soon)


Once you have the CLI installed, you can do:

buildless --help

Output of `buildless --help`

Output of buildless --help

Available Sub-commands

To see available commands. Any command can be run with --help for further info. Commands include:

buildless accountShow active account info, if any
buildless agentManage, install, uninstall local agent service
buildless discordJoin the Discord
buildless loginAuthorize the CLI with your Buildless account
buildless logoutDe-authorize the CLI, remove any active account
buildless showShow active configuration, account, and status
buildless statusShow cache status for the current directory (curtailed show)
buildless supportAccess support resources for Buildless

Up next

Next, setup your local agent service to enable near-caching