Command reference
All commands accept the global options below and honour --output text|json|ndjson.
Diagnostics & setup
| Command | What it does |
|---|---|
doctor | Host readiness: PowerShell + businessdev.ALbuild module + Docker. |
setup | Guided setup: check host, module and albuild.json; print next steps. |
update | Update the module + MCP server in one go (and self-update the CLI via dotnet tool update). |
module install | update | status | Manage the businessdev.ALbuild PowerShell module. |
init | Scaffold an albuild.json in the workspace. |
feeds add | list | remove | Manage the package feeds in albuild.json. |
agents list | add | remove | token | Manage MCP agents and their access tokens (centralized config). |
whoami | Says whether you are local or remote to the container host, and which argument form to use. Paths resolve on the host, so a host-local --project is meaningless from another box. |
configure docker | Move Docker's data-root (and report free space) — a full agent disk is the most common cause of "failed to start service". |
After albuild init, add the package feeds the dependency resolver should use. A private feed's key stays out of the file, --api-key-env records the name of the environment variable that holds it, resolved at run time:
Code
--kind is apps (default), symbols or runtime.
Build & test loop
| Command | What it does |
|---|---|
artifact find | Resolve a BC artifact URL. |
container list | inspect | new | restart | remove | Provision / inspect / manage BC containers. |
deps plan | check | install | Dependency resolution against your feeds. deps plan accepts --bc-version to pin the target application/platform; deps check reconciles app.json against the container + feeds. |
After container new provisions a local container it prints how to connect: the web client URL (https://<name>/BC/), the container IP (with a hosts-file hint), and the admin username + generated password, so you can sign in right away (the same fields are in the --json result). When you pass --project, it then installs the app's dependency closure as a separate step; if that fails, it offers to remove the container it just created (auto with --yes, a prompt when interactive) so a failed run doesn't leave an orphan behind.
| app build | Compile the app(s) fresh — artifact symbols + resolved feed deps → alc. Always runs locally. |
| app publish | Publish a built .app into a container (--file <path>, syncs + installs). |
| app deploy | Ensure the test toolkit, publish clean (--apps uploads deps → app → test) and run the tests. |
| app test | Run the tests against an already-deployed app (--coverage to capture code coverage). |
| app unpublish | Uninstall + unpublish app(s) from a container: --name "<a;b>" (--no-uninstall to only unpublish). Destructive. |
| app results | Fetch the last test run's results (read-only). |
| app diagnose | Report a container's actual app state before acting: published versions, install/sync state, tenant data version, BC Server event-log tail, and named blockers with remedies. |
| project order | Multi-project build order (read-only). |
| run pipeline | Full loop: build → publish → test. The build always runs locally (compilation is a client op); publish/test follow --server, so the locally-built .apps are uploaded to a remote host when one is targeted. |
| job get | cancel | attach | Inspect/cancel async jobs, or re-attach to one after a dropped connection (MCP backend only). |
Probing AL (no container)
albuild probe runs one AL procedure or a few AL statements locally, in roughly 10 ms, with no
container and no publish. See Probing AL for the full picture.
| Command | What it does |
|---|---|
probe scope | List what is probeable here — objects, procedure signatures, symbol packages, and any source file that could not be read. Run this first. |
probe call | Run one procedure: --target '"<object>"::<proc>' --args '<json>'. Arguments are converted to each parameter's declared AL type. |
probe eval | Evaluate AL statements: --vars '<decls>' --code '<al>'. Every variable is reported with its value and type. |
probe batch | Run many probes from one JSON file in a single process. Exits non-zero if any failed. |
Flags: --set '<json>' seeds the in-memory tables (they start empty), --trace records every
assignment with its value and source line, --today / --work-date / --user / --company pin the
stand-ins so a probe is reproducible.
Translations
See Check Translations for the CI gate. The translation verbs run locally against the PowerShell module.
| Command | What it does |
|---|---|
translation sync | Sync the XLIFF files from the generated .g.xlf, honouring the translation memory. |
translation new | Create a new target-language XLIFF from the generated base. |
translation list | List translation units (read-only), e.g. to inspect what is missing. |
translation set | Set a single translation unit's target text. |
translation test | Gate on missing / needs-work translations. |
Code coverage & test quality
See the Code coverage & test quality concept for the full picture.
| Command | What it does |
|---|---|
coverage convert | Raw BC coverage (.dat) → ALbuild JSON / Cobertura / Markdown (honest denominator). |
coverage summary | Print a coverage summary (read-only). |
coverage threshold | Gate on coverage; exit code 1 when below --min (--no-fail to soften). |
coverage delta | Patch coverage of git-changed lines (--baseline <ref>). |
coverage merge | Merge coverage from several runs (--paths "a;b" --out merged.dat). |
quality | Assess AL test quality (assertions / empty / score). |
Coverage flags on the test loop: --coverage, --coverage-tracking <Disabled\|PerRun\|PerCodeunit\|PerTest>, --coverage-map, --coverage-formats, --coverage-path, --denominator <Auto\|Source\|CoveredOnly>.
MCP server
| Command | What it does |
|---|---|
mcp install | Install the MCP server (npm i -g @365businessdev/albuild-mcp). |
mcp doctor | Host readiness check (alias of doctor). |
mcp serve | Host an MCP server (HTTP by default) with configured tokens/agents. |
mcp service | Install/uninstall the MCP HTTP server as a Windows service (NSSM). |
mcp status | list-tools | call | configure | logs | Inspect the server, list/call tools, write an mcp.json / save a server profile, tail the server log. |
mcp default | Show/set/clear the default server used when --server is omitted (mcp default <name> | --unset). |
Global options
Code
Exit codes
| Code | Meaning |
|---|---|
0 | ok |
1 | failure (the operation ran and did not succeed — a failed job, failing tests) |
2 | usage error |
3 | precondition failed (host not ready) |
4 | not found |
5 | approval required (e.g. removing a shared container) |
6 | transport lost — the connection to the MCP server dropped while the work continued on the host; the printed jobId lets you re-attach with albuild job attach <id> |
124 | timeout |
Branch on the error.code in the JSON envelope for the cause, and on the exit code only for the
severity.
json / ndjson put only the result on stdout (logs and the spinner go to stderr), so agents and CI can pipe stdout straight into a JSON parser.
Hands-on walkthroughs
A: Local Windows box (everything local)
A Windows host with Docker runs compile and the container, all on the direct backend, no --server:
Code
B: macOS / Linux (compile local, run on a remote host)
You can't run a BC container on a Mac, but you can still compile. Configure a remote host once, then every
command goes there, except the build, which always stays local and uploads the .app:
Code
C: AI agent (structured output, dry-run first)
Agents add --json (or --ndjson) and can preview any call with --dry-run:
Code
D: Clean redeploy of an already-published app
run pipeline is idempotent (it unpublishes in reverse build order first), but you can also do it by hand:
Code