CLI (albuild)
The albuild CLI is a thin, cross-platform command-line face for the ALbuild toolchain: provision (or warm-reuse) a Business Central container, resolve dependencies from your feeds, build, publish and test apps, measure code coverage & test quality, and host/operate the MCP server, all from one stable verb surface.
One engine, no drift
The CLI does not re-implement container/artifact/coverage logic. It runs everything through the businessdev.ALbuild PowerShell module, the same engine behind the Azure DevOps tasks, the VS Code extension and the MCP server. One code path, no second wrapper.
What it's for
- A stable, discoverable command vocabulary so humans, CI and shell-only AI agents don't hand-write
pwshone-liners. - The Mac/Linux developer's entry point, talk to a remote Windows MCP host that runs the containers.
- MCP lifecycle tooling: install, host (HTTP / Windows service), configure clients, list/call tools.
- Uniform
--json/--ndjsonstructured output for CI and agents. - Answering a question about AL without a container:
albuild proberuns one procedure or expression locally in a fraction of a second.
Backends
The CLI is not MCP-only. Each command runs through one of two backends:
| Selection | Backend |
|---|---|
| (default, local) | Direct: the businessdev.ALbuild module via pwsh. No MCP server, no Node. The right path on a local Windows host that can run BC Docker containers. |
--backend mcp | A local stdio MCP server (@365businessdev/albuild-mcp), when you want the server's job model / agent scoping locally. |
--server https://host:5020/mcp | A remote MCP host over Streamable HTTP (token from ALBUILD_MCP_TOKEN), e.g. a Mac driving a Windows MCP host. |
--server <profile> | A saved server profile in ~/.albuild/config.json. |
--server local | Force the local direct backend for one command, even when a default server is configured. |
When you omit --server, the backend is resolved in precedence order: explicit --server → the ALBUILD_SERVER environment variable → the configured default server (albuild mcp default) → local. So a Mac that can't run BC containers locally sets a default once and every command goes remote; a Windows box leaves it unset and runs local by default. See setting a default host.
Compilation is always local
app build (and the build step of run pipeline) always compile on the client, regardless of --server or a configured default, your AL source and compiler stay on your machine. Only container ops (publish, test, unpublish) follow the server; the locally-built .apps travel to a remote host as base64 uploads. This is the macOS flow: compile here, run there.
The direct backend keeps the credentials of containers it creates in ~/.albuild/containers.json (the local equivalent of the server's pool), so a later app test can authenticate. Jobs (job get/cancel) and mcp call require an MCP backend.
Output modes (two audiences)
--output | For | stdout | stderr |
|---|---|---|---|
text (default) | humans | the result (colored) | an AL-themed work-in-progress spinner + log lines + ✓/✗ |
json | agents / CI | one envelope { ok, command, data, warnings, error, schemaVersion } | logs only with --verbose |
ndjson | agents / streaming | one JSON event per line (step / progress / result / error) |
In text mode every command shows a spinner (a braille spinner + the albuild wordmark + elapsed time + the live step) so long operations always show activity. It degrades safely: no animation when stderr isn't a TTY, in CI, or with --no-color / NO_COLOR. json / ndjson never emit decoration, stdout carries only the result, so you can pipe it straight into a parser.
Next steps
- Get started: install the tool and run your first commands.
- Command reference: every command, global options and exit codes.