Build Lightbuild projects from the command line

The Lightbuild CLI is the official command-line tool for Lightbuild. Use the lightbuild command to build and test your project, find its build targets, and resolve its dependencies. Your AI agents can run the same commands. Projects that you create from a Lightbuild template include an AGENTS.md file that tells AI agents how to work with Lightbuild and the Lightbuild CLI.

For more information about the Lightbuild CLI's commands and options, see the Lightbuild CLI reference.

Install the Lightbuild CLI

The Lightbuild CLI is distributed as an Android SDK package that you install with Android CLI. You can install and set it up with a single command, or install it manually.

Install and set up in one step

To install the Lightbuild CLI, run the command for your operating system. The command installs the Lightbuild CLI package in your Android SDK, and then runs the package's setup script, which copies the Lightbuild CLI to ~/.local/bin on macOS and Linux, or to $HOME\AppData\LightbuildCLI on Windows, and makes sure that directory is in your PATH:

  • macOS and Linux:

    android sdk install build/lightbuild/0.0.30 && bash "$(android info sdk)/build/lightbuild/0.0.30/cli/install.sh"

  • Windows (PowerShell):

    android sdk install build/lightbuild/0.0.30; if ($LASTEXITCODE -eq 0) { & "$(android info sdk)\build\lightbuild\0.0.30\cli\install.cmd" }; if ($LASTEXITCODE -eq 0) { $env:Path += ";$HOME\AppData\LightbuildCLI"; setx LIGHTBUILD_REFRESH 1 | Out-Null; reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f | Out-Null }

  • Windows (Command Prompt):

    android sdk install build/lightbuild/0.0.30 && for /f "delims=" %p in ('android info sdk') do call "%p\build\lightbuild\0.0.30\cli\install.cmd" && setx LIGHTBUILD_REFRESH 1 >nul && reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f >nul

After the command finishes, verify the installation.

Install manually

Alternatively, to install the Lightbuild CLI and add it to your PATH yourself, follow these steps:

  1. If you don't have Android CLI, install it.

  2. Install the Lightbuild package:

    android sdk install build/lightbuild/0.0.30

  3. Copy the Lightbuild CLI to a directory in your PATH, so that you can run lightbuild from any directory. You can copy it to any directory that's already in your PATH, or use the same directory that the setup script uses:

    • macOS and Linux: Copy the lightbuild file to ~/.local/bin:

      mkdir -p ~/.local/bin
cp "$(android info sdk)/build/lightbuild/0.0.30/cli/lightbuild" ~/.local/bin/

      If ~/.local/bin isn't in your PATH, add the following line to your shell's startup file, such as ~/.zshrc or ~/.bashrc:

      export PATH="$PATH:$HOME/.local/bin"

    • Windows: Run the following commands in PowerShell. They copy lightbuild.exe to $HOME\AppData\LightbuildCLI, add that directory to your user Path if it isn't already there, and then make the change take effect in your current session and in terminals that you open later:

      $dir = "$HOME\AppData\LightbuildCLI"
New-Item -ItemType Directory -Force $dir | Out-Null
Copy-Item "$(android info sdk)\build\lightbuild\0.0.30\cli\lightbuild.exe" $dir
$userPath = (Get-ItemProperty HKCU:\Environment).Path
if (($userPath -split ";") -notcontains $dir) { Set-ItemProperty HKCU:\Environment Path "$userPath;$dir" -Type ExpandString }
setx LIGHTBUILD_REFRESH 1 | Out-Null; reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f | Out-Null
$env:Path += ";$dir"

  4. Verify the installation

Verify the installation

To verify that the Lightbuild CLI is installed, check its version:

lightbuild --version

If your terminal can't find the lightbuild command, open a new terminal window so that your PATH changes take effect.

Find your project's build targets

Lightbuild CLI commands take a target, which identifies the part of your project to build, test, or inspect. A target can be a module's name, such as app, or something more specific, such as app:app-debug.apk. To match all the targets in a module, use the module's name followed by /..., such as app/.... To match all the targets in your project, use ....

To list all the targets in your project, query them from your project's root directory:

lightbuild query ...

To list the files that a target produces, add --output=files. For example, for the app target, run:

lightbuild query app --output=files

To list the commands that are available for your project, run lightbuild help.

Build your app

To build a target, run lightbuild build with the target. For example, to build the app module, run:

lightbuild build app

To build all the targets in your project, run:

lightbuild build

To build a signed release app bundle that you can upload to Google Play, see Publish your Lightbuild app.

To remove your project's build output and caches, run:

lightbuild clean

Run your app

The Lightbuild CLI builds your app, but doesn't install or run it. To run your app on a connected device or a running emulator, build the app, and then run it with the android run command in Android CLI:

lightbuild build app
android run --apks=app/build/app-debug.apk

To see where each of a module's targets writes its output, run lightbuild query app/... --output=files. The locations are relative to the module's directory.

Run tests

To run all the tests in your project, run:

lightbuild test

This command runs your local tests, which run on your development machine, and your instrumented tests, which run on a connected device or a running emulator.

To run the tests in one module, add the module's target, such as app-core. To run only one type of test, add :hostTest for local tests or :deviceTest for instrumented tests to the module's target. For example:

lightbuild test app-core:hostTest
lightbuild test app-core:deviceTest

Resolve dependencies

Each module records its resolved dependencies in a resolved.deps file. To generate the resolved.deps file for a module, run lightbuild resolve with the module's target. For example, for the app module, run:

lightbuild resolve app

To resolve all the targets in your project, run:

lightbuild resolve

For more information, see Resolved dependencies.