name: bcdev description: This skill should be used when the user wants to "download symbols", "compile AL app", "publish to Business Central", "run BC tests", or is working with Business Central development workflows.

BC Dev CLI

This skill provides instructions for using the BC Dev CLI to download symbols, compile, publish, and test Business Central AL applications.

Binary Location

macOS/Linux: ${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure
Windows: ${CLAUDE_PLUGIN_ROOT}\bin\bcdev-ensure.cmd

The wrapper automatically downloads the correct binary for your platform on first use. The binary is cached at:

macOS/Linux: ~/.bcdev/cli/v{version}/bcdev
Windows: %LOCALAPPDATA%\bcdev\cli\v{version}\bcdev.exe

Platform Notes

The CLI is automatically downloaded for your platform on first invocation.

Supported platforms: macOS (arm64, x64), Linux (x64, arm64), Windows (x64)

macOS: May require quarantine removal on first run: xattr -dr com.apple.quarantine ~/.bcdev/cli/
Linux: Binary is made executable automatically
Windows: Runs natively via batch wrapper

To use a different CLI version:

macOS/Linux: export BCDEV_CLI_VERSION=0.8
Windows: set BCDEV_CLI_VERSION=0.8

Prerequisites

Before using the CLI, ensure you have:

A Business Central environment (SaaS sandbox, hosted, or on-premises)
An app.json file for your AL project
A .vscode/launch.json with at least one configuration

Commands Overview

Command	Purpose
`bcdev symbols`	Download symbol packages for dependencies
`bcdev compile`	Compile AL app (auto-downloads compiler)
`bcdev publish`	Publish .app file to Business Central
`bcdev test`	Run tests against Business Central

Typical Workflow

symbols → compile → publish → test

Command: bcdev symbols

Downloads symbol packages for compilation dependencies. By default, downloads from Microsoft's public NuGet feeds (faster, works offline/CI). Optionally download from a BC server with -fromServer.

NuGet mode (default):

# Download symbols from NuGet feeds (no BC server required)
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure symbols -appJsonPath "/path/to/app.json"

# With country-specific packages (e.g., us, de, dk)
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure symbols -appJsonPath "/path/to/app.json" -country us

Server mode (opt-in):

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure symbols \
  -appJsonPath "/path/to/app.json" \
  -fromServer \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -Username "bcuser" \
  -Password "bcpassword"

Options:

Option	Required	Description
`-appJsonPath`	Yes	Path to app.json file
`-packageCachePath`	No	Output folder (defaults to .alpackages next to app.json)
`-country`	No	Country code for localized symbols (e.g., us, de, dk). Default `w1` uses country-less packages
`-fromServer`	No	Download from BC server instead of NuGet feeds
`-launchJsonPath`	No*	Path to launch.json (*required with `-fromServer`)
`-launchJsonName`	No*	Configuration name (*required with `-fromServer`)
`-Username`	No**	For UserPassword auth (**required for UserPassword auth with `-fromServer`)
`-Password`	No**	For UserPassword auth (**required for UserPassword auth with `-fromServer`)

Command: bcdev compile

Compiles an AL application. The compiler is automatically downloaded based on the platform version in app.json.

Usage:

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure compile \
  -appJsonPath "/path/to/app.json"

Options:

Option	Required	Description
`-appJsonPath`	Yes	Path to app.json file
`-packageCachePath`	No	Path to .alpackages folder (defaults to .alpackages in app folder)
`-suppressWarnings`	No	Suppress compiler warnings from output
`-generateReportLayout`	No	Generate report layouts (default: false)
`-parallel`	No	Enable parallel compilation (default: true)
`-maxDegreeOfParallelism`	No	Maximum parallel threads (default: 4)
`-continueBuildOnError`	No	Continue compilation even when errors occur (default: true)

Example with custom parallelism:

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure compile \
  -appJsonPath "/path/to/app.json" \
  -maxDegreeOfParallelism 8

Output: Creates a .app file in the same directory as app.json.

Command: bcdev publish

Publishes an AL application to Business Central.

Usage (pre-compiled .app):

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure publish \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -appPath "/path/to/MyApp.app" \
  -Username "bcuser" \
  -Password "bcpassword"

Compile-then-publish workflow:

# Step 1: Compile
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure compile \
  -appJsonPath "/path/to/app.json"

# Step 2: Publish the compiled .app
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure publish \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -appPath "/path/to/MyApp.app" \
  -Username "bcuser" \
  -Password "bcpassword"

Options:

Option	Required	Description
`-launchJsonPath`	Yes	Path to launch.json
`-launchJsonName`	Yes	Configuration name
`-appPath`	Yes	Path to .app file
`-Username`	No	For UserPassword auth
`-Password`	No	For UserPassword auth

Command: bcdev test

Runs tests against Business Central.

Usage (run all tests):

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure test \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -all \
  -Username "bcuser" \
  -Password "bcpassword"

Usage (run specific test):

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure test \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -CodeunitId 50100 \
  -MethodName "TestSomething" \
  -Username "bcuser" \
  -Password "bcpassword"

Options:

Option	Required	Description
`-launchJsonPath`	Yes	Path to launch.json
`-launchJsonName`	Yes	Configuration name
`-Username`	No	For UserPassword auth
`-Password`	No	For UserPassword auth
`-CodeunitId`	No	Specific test codeunit ID
`-MethodName`	No	Specific test method name
`-all`	No	Run all test codeunits (default: false)
`-testSuite`	No	Test suite name (default: "DEFAULT")
`-timeoutMinutes`	No	Timeout in minutes (default: 30)

Authentication

Two authentication methods are supported:

UserPassword (NavUserPassword)

Pass credentials via command-line options:

-Username "your-bc-user" -Password "your-bc-password"

Azure AD (Microsoft Entra ID)

When -Username and -Password are not provided, the CLI uses device code flow:

A URL and code are displayed
Open the URL in a browser
Enter the code to authenticate
The CLI receives the token and proceeds

Note: Tokens are cached, so you won't need to re-authenticate every time.

Test Iteration Workflow

When iterating on tests:

If test app code is modified → Compile and publish the test app before running tests
If primary app code is modified → Compile and publish the primary app before running tests. If your test app needs to be recompiled for the latest primary app changes, remember to copy the fresh primary .app file to the .alpackages/ folder of the test project before recompiling the test app.
Run tests → Only after all dependent apps are published:

${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure test \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Your Configuration Name" \
  -all \
  -Username "bcuser" \
  -Password "bcpassword"

Complete workflow example (primary app change + test):

# 1. Compile primary app
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure compile -appJsonPath "/path/to/primary/app.json"

# 2. Publish primary app
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure publish \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Dev" \
  -appPath "/path/to/primary/MyApp.app"

# 3. Copy fresh .app to test project's dependencies
cp /path/to/primary/MyApp.app /path/to/test/.alpackages/

# 4. Recompile test app with updated dependency
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure compile -appJsonPath "/path/to/test/app.json"

# 5. Publish test app
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure publish \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Dev" \
  -appPath "/path/to/test/TestApp.app"

# 6. Run tests
${CLAUDE_PLUGIN_ROOT}/bin/bcdev-ensure test \
  -launchJsonPath "/path/to/.vscode/launch.json" \
  -launchJsonName "Dev" \
  -all

Finding launch.json Configurations

To find available configuration names, read .vscode/launch.json and look for objects in the configurations array. The name field is what you pass to -launchJsonName.

Example launch.json:

{
  "configurations": [
    {
      "name": "My Dev Environment",
      "type": "al",
      "server": "https://businesscentral.dynamics.com",
      ...
    }
  ]
}

Use: -launchJsonName "My Dev Environment"

Error Handling

Common issues and solutions:

Error	Solution
Authentication failed	Check credentials or re-authenticate via device code
Symbols not found	Ensure launch.json points to a valid BC environment
Compilation failed	Check for AL syntax errors; ensure symbols are downloaded
Publish failed	Verify app dependencies are satisfied; check BC permissions
Test timeout	Increase `-timeoutMinutes` or check for infinite loops

Name	bcdev
Description	This skill should be used when the user wants to "download symbols", "compile AL app", "publish to Business Central", "run BC tests", or is working with Business Central development workflows.

bcdev

SKILL.md

name: bcdev description: This skill should be used when the user wants to "download symbols", "compile AL app", "publish to Business Central", "run BC tests", or is working with Business Central development workflows.

BC Dev CLI

Binary Location

Platform Notes

Prerequisites

Commands Overview

Typical Workflow

Command: bcdev symbols

Command: bcdev compile

Command: bcdev publish

Command: bcdev test

Authentication

UserPassword (NavUserPassword)

Azure AD (Microsoft Entra ID)

Test Iteration Workflow

Finding launch.json Configurations

Error Handling