Copy page

CLI

Command reference

All commands accept the global options below and honour --output text|json|ndjson.

Diagnostics & setup

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
albuild init --country de --bc-version 28.2
albuild feeds add https://pkgs.dev.azure.com/acme/_packaging/bc/nuget/v3/index.json
albuild feeds add https://pkgs.dev.azure.com/acme/_packaging/rt/nuget/v3/index.json \
  --name acme-runtime --kind runtime --api-key-env ACME_PAT
albuild feeds list

--kind is apps (default), symbols or runtime.

Build & test loop

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.

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.

Code coverage & test quality

See the Code coverage & test quality concept for the full picture.

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

---

Global options

Code
--output <mode>      text (humans, default) | json (one envelope) | ndjson (event stream)
--json               alias for --output json
--no-color           disable ANSI colors (also honours NO_COLOR / CI / non-TTY)
--verbose, -v        stream diagnostics/logs to stderr
--dry-run            validate + show the plan; no side effects
--yes, -y            skip confirmation for destructive commands
--backend <b>        direct | mcp
--server <name|url>  target MCP server (profile name or http(s) URL). Omit to use
                     ALBUILD_SERVER, then the configured default (mcp default), else local.
                     Use --server local to force local for a one-off.
--container <name>   target container
--project <path>     app folder (app.json)
--workspace <path>   repo root (albuild.json)
--license <path|url> ALbuild license (or ${env:NAME} placeholder)
--timeout <sec>      cap long operations

Exit codes

Branch on the error.code in the JSON envelope for the cause, and on the exit code only for the severity.

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
albuild doctor                                   # PowerShell + module + Docker all green?
albuild init --country de --bc-version 28.2      # scaffold albuild.json in the workspace
albuild feeds add https://pkgs.dev.azure.com/acme/_packaging/bc/nuget/v3/index.json
albuild container new --project ./app --workspace .   # provision a BC 28.2 container
albuild deps install --project ./app --workspace .    # resolve + restore .alpackages
albuild run pipeline --workspace . --container <name>  # build → publish → test, locally
albuild coverage threshold --path ./CodeCoverage --workspace ./app --min 80   # gate (exit 1 if below)

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
# one-time: point at the shared Windows MCP host and make it the default
albuild mcp configure --server prod --url http://winsrv:5020/mcp --default
export ALBUILD_MCP_TOKEN='<your bearer token from the host>'

albuild app build --workspace . --project ./app   # compiles on your Mac (server is ignored for build)
albuild run pipeline --workspace . --container <name>   # build local → publish/test on 'prod' (apps uploaded)
albuild app test --container <name> --coverage           # tests run on the remote container
albuild mcp status --server local                        # force a one-off local command, ignoring the default

C: AI agent (structured output, dry-run first)

Agents add --json (or --ndjson) and can preview any call with --dry-run:

Code
albuild deps check --project ./app --workspace . --json      # reconcile app.json vs container + feeds
albuild app build --workspace . --json                       # { ok, command, data:{ projects:[…] }, … }
albuild run pipeline --workspace . --container <name> --json --dry-run   # show the plan, do nothing
albuild mcp call run-tests --args '{"containerName":"x","testExtensionId":"…"}'

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
albuild app unpublish --container <name> --name "My Test App;My App" --yes   # uninstall+unpublish (dependents first)
albuild app publish  --container <name> --file ./app/output/Publisher_MyApp_1.0.0.0.app