Introducing BCCL – Business Central Command Line Tool

BCCL is a command-line interface for getting data in and out of Business Central. All tables are available, including data from apps and customizations. The client is cross-platform and works on Windows, macOS and Linux against Business Central versions 14-17 on-premises and in the cloud.

https://youtu.be/5zLtG_S8CmI

Typically BCCL will be used for data migration during implementation, go-live, ad-hoc integration, or automation after go-live.

Many industry-standard file formats are supported, from classics like CSV and Excel to XML and JSON.

BCCL is designed to work with “any” file without the need for manipulating the source file. A field mapping method makes it easy to automate data integrations.

Excellent performance is at the core of BCCL. Imports and exports are fast and stay fast independently of data size.

We recognize that not all users are comfortable using the command-line and BCCL has a Request Builder tool that can generate a ready-to-run script.

BCCL understands the inner workings of Business Central, and all table and field validation rules can be triggered. It can correctly handle dimension sets and ensure that related tables are updated with stub records to avoid imports failing with data integrity issues.

Additional tasks, such as posting transactions, are also available through BCCL. Keeping with the spirit of Business Central, developers can extend BCCL with new capabilities and customize the inner working through extensions.

BCCL commercial licenses are available for end-users and partners. A free educational version, not for use on production data, is also available.

More information at www.hougaard.com/bccl

In this video, Erik introduces BCCL (BC Command Line), a cross-platform command-line tool he created together with his wife for interacting with Dynamics 365 Business Central. The video walks through installation, configuration, data export/import, mapping files, filtering, Excel support, and the various licensing options available.

What is BCCL?

BCCL — short for “BC Command Line” — is a tool designed to operate Business Central from the command line. It grew out of the need to quickly get data in and out of Business Central and perform operations without relying on the graphical interface. In the on-premises days, developers could interact directly with SQL Server for many tasks, but those capabilities are largely gone in the cloud era. BCCL fills that gap.

The tool runs on Windows, Mac, and Linux, so it works regardless of your preferred operating system.

Architecture: Two Components

BCCL consists of two parts:

  • A Business Central extension — installed inside your BC environment
  • A command-line executable — the client application you run on your machine

The idea is that all operations — getting data, putting data, deleting data, and more — are initiated from the command line, with the BC extension handling the server-side logic.

The Request Builder

Recognizing that not everyone is as fond of the command line as Erik is, the team added a feature called the Request Builder inside Business Central. You can find it by searching for “BCCL” within BC. The Request Builder helps you construct commands visually, showing valid parameter combinations and even suggesting the first three commands you should run.

It color-codes commands: green means the combination is valid, red means something is missing or incorrect.

Getting Started: Registration and Connection

The first step after acquiring BCCL is to register the product:

bccl -register <your-registration-key>

Next, you need to connect the command line to your Business Central instance. The key parameters are:

  • URL — the web service URL for your Business Central
  • User — your credential
  • Password — your password

BCCL supports a -remember parameter that saves these connection details so you don’t have to type them for every subsequent call:

bccl -sw <url> -user <username> -password <password> -remember

When you’re done with your session, you can clear the stored credentials with:

bccl -forget

Getting Data Out of Business Central

Basic Data Retrieval

To retrieve data, you use the get data task and specify a table number. For example, to get all payment terms (table 3):

bccl -t "get data" -table 3

By default, the output is displayed on screen in JSON format, which is the native language of BCCL. All output is designed to be machine-readable so other programs can consume it.

Output to Files

You can redirect output to a file using the -o parameter:

bccl -t "get data" -table 3 -o pterm.json

BCCL automatically determines the file format based on the extension. If you prefer CSV:

bccl -t "get data" -table 3 -o pterm.csv

The supported output formats are:

  • JSON (default)
  • CSV
  • XML
  • Excel (read-only in this version — for output, use CSV which opens fine in Excel)

If the file extension doesn’t indicate the format (e.g., .txt), you can explicitly specify it. The default is JSON if unspecified:

bccl -t "get data" -table 3 -o somefile.txt -format csv

Filtering with Views

You can apply filters using the view parameter. For example, to get only payment terms with “days” in the code:

bccl -t "get data" -table 3 -view "sorting(Code) where(Code=filter(*days*))" -o somept.txt -format csv

The view parameter uses Business Central’s standard table view string syntax, specifying sorting and filters.

CSV Configuration

By default, CSV files use a comma as the delimiter, but you can change it to a tab character (\t) to produce tab-separated files (TSV) if that’s your preference.

Mapping Files: Controlling Which Fields to Export or Import

The customer table (table 18) has 181 fields — you probably don’t want all of them. BCCL uses the concept of a mapping file to control which fields are included and how they map between your file and Business Central.

A mapping file is a JSON file that specifies the columns you want. For example, to export only five fields from the customer table:

bccl -t "get data" -table 18 -o demo.csv -mapping demo_mapping.json

Without the mapping file, you get all fields. With it, you get only the columns specified in the mapping.

Putting Data Into Business Central

Basic Import

BCCL can import data using the put data task. Given a CSV file with customer data and a corresponding mapping file:

bccl -t "put data" -table 18 -input customer.csv -mapping customer_mapping.json

The response tells you exactly what happened — how many records were inserted, modified, and whether related records were created in other tables.

Mapping File Features

The mapping file is powerful. In addition to column-to-field mappings, it supports:

  • Create related records — If a customer posting group referenced in your file doesn’t exist, BCCL can automatically create it in the related table (e.g., table 92) instead of breaking the import
  • Field validation control — You can specify per-field whether validation triggers should fire, just as if the value were typed manually. For example, validating the Name field populates the Search Name automatically, while skipping postcode validation avoids triggering address lookups
  • Insert/Modify control — You can control whether the import should insert new records, modify existing ones, or both
  • Dimension handling — You can translate dimension columns in your file to proper dimension set IDs in Business Central, enabling import of transactions with dimensions

Import Without Primary Key

An interesting behavior: if you remove the customer number mapping from the mapping file, the import still works. Since the customer number field is left blank, Business Central’s number series kicks in and assigns numbers automatically. This demonstrates the flexibility of the mapping concept — even though the data is in your file, you can exclude fields from the mapping to let BC handle them natively.

Insert Patterns

BCCL supports two insert patterns:

  1. Default (proper) pattern — Fill out primary key fields, insert the record, then fill remaining columns and modify. This mimics the behavior of typing data manually.
  2. Delayed insert pattern — Fill out the entire record first, then insert. This is ideal for raw data migration from one BC environment to another, where you’d set all validations to false and just copy data directly.

Note that the delayed insert pattern doesn’t work on tables with auto-increment fields, as those have their own constraints.

Deleting Data

Beta testers quickly asked: “Can we delete records too?” The answer is yes. Simply change the task from put data to delete data using the same input and mapping files:

bccl -t "delete data" -table 18 -input customer.csv -mapping customer_mapping.json

This performs a bulk delete of the records identified in your file — extremely useful when you’ve imported test data and need to clean it up.

Importing from Excel

BCCL can read Excel files directly. When importing from Excel, you need to provide two additional parameters:

  • Sheet name — which sheet in the workbook to read from
  • Cell range — the range of cells to import (using .. instead of : as the range separator, since colons are problematic on the command line)
bccl -t "put data" -table 18 -input customers.xlsx -mapping excel_mapping.json -x "Sheet Name" -y "A2..D11"

The mapping file’s map name values correspond to the column letters in the Excel sheet (A, B, C, D). This approach lets you import from any Excel sheet as long as the data is tabulated — you just tell BCCL which columns to use.

Important note: The Excel file cannot be open in Excel when BCCL tries to read it.

Additional Features

Erik briefly mentioned several other capabilities:

  • Mass Update — A search-and-replace function for bulk changing field values. For example, changing the posting group on a thousand customers can be done by creating a mapping file pointing to a single-record data file and applying a view filter to target specific records.
  • Post Documents — BCCL can post sales and purchase documents from the command line.
  • Run Codeunit — If you have custom codeunits that need to run as part of a process, BCCL can execute them.
  • Search Functions — Look up table numbers and metadata without opening Business Central. For example: bccl -tables -name vendor returns that the Vendor table is number 23.
  • Paging — BCCL handles large datasets efficiently with built-in paging support, even for gigabytes of data.
  • Binary Fields — Blob and media fields are excluded by default but can be included. When included, they’re Base64 MIME encoded in the output.

The Source Code Repository

The associated repository (BCALToolbox) contains the Business Central extension component. The workspace is structured with separate folders for the app, tests, scripts, and CI/CD pipelines:

{
    "folders": [
        { "path": "app" },
        { "path": "test" },
        { "path": "scripts" },
        { "path": ".github" },
        { "path": ".azureDevOps" }
    ],
    "settings": {
        "CRS.ObjectNameSuffix": "TBHLG",
        "CRS.OnSaveAlFileAction": "Rename",
        "al.compilationOptions": { "parallel": true },
        "al.enableCodeAnalysis": true,
        "al.codeAnalyzers": ["${CodeCop}", "${UICop}", "${PerTenantExtensionCop}"]
    }
}

The Azure DevOps pipeline compiles against multiple targets to ensure compatibility:

strategy:
  matrix:
    'Compile Against W1 - Current Version':
      artifactCountry: 'w1'
      artifactVersion: 'Current'
    'Compile Against W1 - Next Minor':
      artifactCountry: 'w1'
      artifactVersion: 'NextMinor'
    'Compile Against W1 - Next Major':
      artifactCountry: 'w1'
      artifactVersion: 'NextMajor'
    'Compile Against United States - Current Version':
      artifactCountry: 'us'
      artifactVersion: 'Current'
    'Compile Against United States - Next Minor':
      artifactCountry: 'us'
      artifactVersion: 'NextMinor'
    'Compile Against United States - Next Major':
      artifactCountry: 'us'
      artifactVersion: 'NextMajor'

This ensures the extension stays compatible with current and upcoming versions of Business Central across different localizations.

Licensing

BCCL offers three licensing tiers:

  1. Educational License (Free) — Full functionality for testing and learning purposes. A warning displays at the end of every call indicating it’s not for production use.
  2. Commercial License — Grants the right to use BCCL against one Business Central environment (cloud or on-premises) for production data.
  3. Enterprise / Partner License — Designed for Business Central partners. All employees of the partner can use BCCL on their customers’ environments for onboarding, migration, and support. Customers who want to use BCCL themselves still need their own commercial license.

Summary

BCCL is a versatile command-line tool that brings powerful data operations to Business Central. Whether you need to export filtered datasets, bulk import from CSV or Excel, delete test data, mass-update field values, post documents, or run custom codeunits, BCCL provides a scriptable, cross-platform interface to get the job done. The mapping file concept gives you granular control over field selection, validation, and related record creation — making it suitable for everything from quick data lookups to full-scale data migrations between environments.

Picture of hougaard

hougaard