import { Callout } from "zudoku/ui/Callout";

# Command reference

All commands accept the [global options](#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:

```bash
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

| 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 `.app`s 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](./probe) 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](../devops-extension/build-tasks#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 &amp; test quality

See the [Code coverage &amp; test quality](../concepts/code-coverage) 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

```text
--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

| 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**.

<Callout type="note">
`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.
</Callout>

## 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`:

```bash
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`:

```bash
# 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`:

```bash
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:

```bash
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
```