Command Reference

This page provides a complete reference for all BCCL.EXE command-line parameters. Parameters are organized by category. Each entry includes the long form, short form (if available), description, and default value.

Usage

BCCL.EXE [parameters]

Running BCCL.EXE without any parameters displays the version number and basic usage information.

Connection Parameters

These parameters define how BCCL connects to Business Central.

Parameter	Short	Description	Default
`--wsurl`	`-w`	The complete web service URL of the BCCL codeunit, for example: `https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company>/Codeunit/bccl`. The URL includes the company name segment, so `-w` is also the parameter that selects which company data is read from or written to. To address a different company, change the company segment of the URL.	None (required unless remembered)
`--user`	`-u`	The username for Basic authentication. For BC cloud, this is your BC user name.	None
`--password`	`-p`	The password or Web Service Access Key for Basic authentication. For BC cloud, use a Web Service Access Key rather than your login password.	None

Example

BCCL.EXE -w "https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company>/Codeunit/bccl" -u "admin" -p "webservicekey"

To run the same extraction against several companies of one tenant, run one command per company with a company-specific -w URL (and, for SQL output, a company-specific -o table), and put all parameters on each command line without --remember. See Replicating Multiple Companies.

Authentication Parameters

These parameters control the authentication method and related settings.

Parameter	Short	Description	Default
`--auth`	--	The authentication method. Accepted values: `Basic`, `OAuth`, `S2S`.	`Basic`
`--clientid`	--	The Azure AD App Registration client ID (GUID). Required for OAuth and S2S authentication.	None
`--clientsecret`	--	The Azure AD client secret. Required for S2S authentication.	None
`--tenantid`	--	The Azure AD tenant ID (GUID). Required for OAuth and S2S authentication, and for license registration.	None

Examples

OAuth device code flow:

BCCL.EXE --auth OAuth --clientid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" --tenantid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -w "https://..."

S2S client credentials:

BCCL.EXE --auth S2S --clientid "..." --clientsecret "..." --tenantid "..." -w "https://..."

Task Parameters

These parameters define what operation BCCL performs and on which data.

Parameter	Short	Description	Default
`--task`	`-t`	The task type. Accepted values: `getdata`, `putdata`, `deletedata`, `deleteall`, `massupdate`, `runcodeunit`, `changelog`, `tables`, `mapping`, `tasks`, `download`, `upload`, `postsales`, `postpurchase`, plus any custom task types registered by other extensions (run `-t tasks` to list what your environment offers). Note the spelling `getdata` (a typo such as `getdate` is not a valid task).	None (required)
`--setting`	`-s`	A key=value setting for the task. Can be specified multiple times. Common settings include `table=N` (table number) and `view=WHERE(...)` (filter). System fields are addressed in view strings as `Field<fieldnumber>` (for example `Field2000000003` for `SystemModifiedAt`), and the filter-group form `FieldName=1(<filter>)` is used, where `1` is the filter group.	None

Common Settings

Setting	Description	Example
`table=N`	The Business Central table number.	`-s table=18`
`view=WHERE(...)`	A filter expression in BC syntax.	`-s "view=WHERE(Status=CONST(Open))"`
`view=WHERE(Field2000000003=1({today(-1D)}..))`	Filter on the `SystemModifiedAt` system field (field no. 2000000003) to export only recently changed records. Used for incremental SQL replication from the command line; the lookback must be at least as long as the interval between runs. See Filtering Data.	`-s table=17 "view=WHERE(Field2000000003=1({minutes(-2H)}..))"`
`name=text`	Table name search text (for TABLES task).	`-s name=Customer`
`codeunit=N`	Codeunit number (for RUNCODEUNIT task).	`-s codeunit=50100`

Examples

BCCL.EXE -t getdata -s table=18
BCCL.EXE -t getdata -s table=18 -s "view=WHERE(Country/Region Code=CONST(US))"
BCCL.EXE -t tables -s name=Customer
BCCL.EXE -t runcodeunit -s codeunit=50100

Format Parameters

These parameters control data format and file locations.

Parameter	Short	Description	Default
`--format`	`-f`	The data format. Accepted values: `json`, `csv`, `xml`, `xlsx`, `sql`. If not specified, BCCL auto-detects from the file extension.	Auto-detect
`--outputdata`	`-o`	The output file path for export operations (GETDATA). If omitted, data is written to standard output (console). With `-f sql`, `-o` is the name of the SQL table BCCL writes into, not a file name, and it is mandatory: if `-o` is omitted with `-f sql`, BCCL writes nothing to the database and simply prints the data as JSON on the console without an error. The mapping file does not determine the SQL target table.	Console (stdout)
`--inputdata`	`-i`	The input file path for import operations (PUTDATA, DELETEDATA) or a SQL SELECT statement when importing from SQL.	None
`--mapping`	`-m`	The path to a mapping.json file that defines field selection, renaming, and validation rules.	None

Examples

BCCL.EXE -t getdata -s table=18 -f csv -o "C:\Data\customers.csv"
BCCL.EXE -t putdata -s table=18 -i "C:\Data\new_customers.json" -m "mapping.json"
BCCL.EXE -t getdata -s table=18 -f sql --sqlconnect "Server=myserver;Database=mydb;Trusted_Connection=True;"

CSV Parameters

These parameters apply when working with CSV formatted data.

Parameter	Short	Description	Default
`--delimiter`	`-l`	The character used to separate fields in CSV data. Common values: `,` (comma), `;` (semicolon), `\t` (tab).	`,`
`--quotechar`	`-c`	The character used to quote field values that contain the delimiter or newlines.	`"`
`--ignorequotes`	`-q`	When set, quote characters in CSV data are treated as literal characters rather than field enclosures. Useful for data that contains quotation marks but does not use them for quoting.	`false`
`--header`	`-h`	Whether to include a header row containing column names in CSV output. When importing CSV, this controls whether the first row is treated as a header.	`true`

Examples

BCCL.EXE -t getdata -s table=18 -f csv -o data.csv -l ";" -h true
BCCL.EXE -t putdata -s table=18 -f csv -i data.csv -l "\t" -q

Excel Parameters

These parameters apply when working with Excel (.xlsx) formatted data.

Parameter	Short	Description	Default
`--excelsheet`	`-x`	The name of the Excel worksheet to read from or write to. Must match exactly, including case and spaces.	None
`--datarange`	`-y`	The cell range containing data. Uses two-dot notation (not Excel's colon notation). For example: `A1..H100`.	None (entire sheet)

Important: BCCL uses two dots (..) to separate range boundaries, not the colon (:) used in Excel formulas. Write A1..H100, not A1:H100.

Examples

BCCL.EXE -t getdata -s table=18 -f xlsx -o report.xlsx -x "Sheet1"
BCCL.EXE -t putdata -s table=18 -f xlsx -i data.xlsx -x "Import Data" -y "A1..F500"

XML Parameters

These parameters apply when working with XML formatted data.

Parameter	Short	Description	Default
`--record`	`-r`	The XML element path that identifies individual record nodes. BCCL uses this to locate the repeating element in the XML document that represents each data record.	None

Example

BCCL.EXE -t putdata -s table=18 -f xml -i data.xml -r "/root/customers/customer"

Data Parameters

These parameters control how data is processed during transfer.

Parameter	Short	Description	Default
`--pagesize`	`-z`	The number of records to transfer in each web service request. Smaller values reduce memory usage; larger values reduce the number of HTTP requests.	`1000`
`--delayedinsert`	`-d`	Enables the delayed insert pattern for PUTDATA. By default BCCL assigns the primary key fields, inserts the record, and then assigns the remaining fields. With `-d`, BCCL assigns all mapped fields first and delays the `Insert()` until the record is complete. Designed for the case where the target table's `OnInsert` trigger requires a non-primary-key field to be filled (errors such as `<Field> must have a value in <Table> ... It cannot be zero or empty.` for a field that is present in the payload). Corresponds to `"DelayedInsert": true` in the verbose settings output. `-d` changes when the record is inserted, not whether validation runs; it is independent of per-field `Validate` and of `ValidateOnInsert`/`ValidateOnModify`. See Import (PUTDATA) Errors.	`false`
`--binary`	`-b`	Includes binary (BLOB) fields such as images and attachments in the data transfer. Disabled by default because binary fields can be very large.	`false`
`--language`	`-a`	A language ID that controls locale-specific formatting of dates, numbers, and other values. Use `0` for the default BC language.	`0`

Examples

BCCL.EXE -t getdata -s table=18 -f json -o data.json -z 500 -b
BCCL.EXE -t putdata -s table=18 -i data.csv -d -a 1033

SQL Parameters

These parameters apply when using SQL Server as a data source or destination.

Parameter	Short	Description	Default
`--sqlconnect`	--	A SQL Server connection string. Used with `-f sql` to stream data directly to/from a SQL Server database.	None
`--sqlprecommand`	--	A SQL statement that BCCL executes on the SQL connection before it starts working with the data. Commonly used to truncate a staging table before loading new data, or to set session options on the connection, for example `--sqlprecommand "SET ANSI_WARNINGS OFF"`. When `--remember` is used, the value is persisted under the key `SqlPreCommand`. Run with `-v` to confirm that the pre-command is processed (`SQL PreCommand Result=...`). See SQL Output Issues.	None
`--sqlzerodate`	--	The date value to substitute for BC's empty date (0D). SQL Server does not support BC's zero date, so BCCL replaces it with this value.	`1900-01-01`

Examples

BCCL.EXE -t getdata -s table=18 -f sql --sqlconnect "Server=myserver;Database=mydb;Trusted_Connection=True;"
BCCL.EXE -t getdata -s table=18 -f sql --sqlconnect "..." --sqlprecommand "TRUNCATE TABLE dbo.Customers" --sqlzerodate "1753-01-01"

File Storage Parameters

These parameters control where files are read from and written to when using remote file storage.

Parameter	Short	Description	Default
`--filestorage`	--	The file storage transport. Accepted values: `LocalFile`, `FTP`, `SFTP`, `FTPS`.	`LocalFile`
`--filestoragesettings`	--	Connection settings for the remote file storage, including server address, port, username, password, and remote path. Format depends on the storage type.	None

Example

BCCL.EXE -t getdata -s table=18 -f csv -o "/exports/customers.csv" --filestorage SFTP --filestoragesettings "server=ftp.example.com;user=myuser;password=mypass;port=22"

Registration Parameters

These parameters manage BCCL licensing and credential storage.

Parameter	Short	Description	Default
`--register`	--	Registers BCCL with a license key (GUID format). Must be combined with `--tenantid`, which is the Business Central / Entra tenant ID (GUID) the license becomes locked to. Supplying the wrong tenant ID requires a support-side reset, so verify the tenant ID before running the command. Each machine (and each Windows user profile) that runs BCCL must be registered. See License and Registration Issues.	None
`--check`	--	Displays the current registration status, including license type, expiration, and tenant ID.	None
`--remember`	--	Saves the connection and authentication settings given on that one command line to Isolated Storage. Subsequent runs use these saved settings without needing them on the command line. See the rules below.	None
`--forget`	--	Deletes all saved settings, credentials, and tokens from Isolated Storage. This clears local settings only; it does not affect the tenant binding of the license held on the hougaard.com license server.	None

Examples

BCCL.EXE --register "00000000-0000-0000-0000-000000000000" --tenantid "00000000-0000-0000-0000-000000000000"
BCCL.EXE --check
BCCL.EXE --remember -w "https://..." -u "admin" -p "key"
BCCL.EXE --forget

Rules for `--remember`

Everything on one line. --remember persists only the parameters supplied on the same command line. Settings spread across several BCCL invocations do not accumulate. All parameters that must be remembered (-w, --auth, --clientid, --clientsecret, --tenantid, --sqlconnect, ...) must be on a single command line together with --remember. A script must never contain two or more separate --remember lines; combine them into one. Splitting the endpoint (-w ... --remember) and the authentication (--auth S2S ...) onto separate lines is not supported and makes later getdata calls fail with Cannot continue without a user for Business Central (-u --user) or authenticated with --auth.
Not for parallel or multi-company runs. --remember stores connection information inside the prompt session on the machine. Remembered values from one session can overwrite those used by another, so the wrong company or connection may be used. When running BCCL for several companies, or any concurrent invocations, do not use --remember; put all parameters, including -w and authentication, on each individual command line. See Replicating Multiple Companies.
Not for long transfers. For long-running exports and SQL replication, put every parameter on the single command that runs the task instead of a --remember command followed by a task-only command, so BCCL can re-authenticate during the run. See Running Long or Unattended Transfers Reliably.
Per machine and per user. Remembered parameters are stored locally on the machine where the command was run. A new server needs its own --remember run as well as its own --register.

Batch File Rules

One command per line. The entire BCCL --remember ... command, from BCCL through the last parameter value, must be on one single, unbroken line. Windows executes each line of a .bat/.cmd file separately. If a long command is wrapped, the continuation fragments are executed as commands and Windows reports '"<fragment>"' is not recognized as an internal or external command, operable program or batch file. (typically for the client secret or the SQL connection string), and every following BCCL -t getdata ... line fails with An error has occurred: Cannot continue without a URL for Business Central (-w --wsurl). Open the file in a plain text editor and join the command back onto one line; editors, e-mail, and word processors that soft-wrap long lines are a common source of this problem. Explicit line continuation characters (^ in batch files) are the exception, because the shell joins those lines before running the command.
Quote values with special characters. Values containing spaces, semicolons, or other special characters (client secret, SQL connection string, web service URL with a company name containing spaces) must be enclosed in double quotes.
Register first. Put BCCL --register <license-key> --tenantid <tenant-id> as the first line of the batch file so that every run verifies that the instance it is running on is registered.

A single-line remember command using placeholders only:

BCCL --remember --auth S2S --clientid <client-id> --clientsecret "<client-secret>" --tenantid <tenant-id> -f sql --sqlconnect "Server=<server>;Database=<database>;User ID=<user>;Password=<password>" -w "https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company name>/Codeunit/bccl"

Other Parameters

Parameter	Short	Description	Default
`--verbose`	`-v`	Enables verbose output: the license verification result, the complete JSON request sent to Business Central (including the mapping), whether the SQL pre-command is processed, token requests and call durations, SQL errors with the per-row SQL parameter values and sizes, and a per-table summary line. Add `-v` to the same command line as the other parameters. It is the recommended first step whenever a command fails, errors intermittently, or behaves unexpectedly, and support normally asks for the complete `-v` output. See Diagnosing with Verbose Mode and Export Performance and Intermittent Export Errors.	`false`
`--agentid`	--	Specifies the agent ID when running BCCL as a service agent. The agent ID links this BCCL instance to a specific agent registration in Business Central.	None

Example

BCCL.EXE -v -t getdata -s table=18 -f json -o data.json

Parameter Precedence

BCCL resolves parameters in the following order of precedence (highest to lowest):

Command-line arguments -- explicitly provided on the current command line.
Remembered settings -- saved with --remember.
Service configuration -- from bccl_service.json (service mode only).
Defaults -- built-in default values.

Command-line arguments always override remembered settings, which in turn override service configuration values. This precedence does not make --remember suitable for multi-company or parallel runs; for those, put all parameters on each command line (see "Rules for --remember" above).

Exit Codes

BCCL returns the following exit codes:

Code	Meaning
`0`	Success. The operation completed without errors.
Non-zero	Failure. The operation encountered an error. Check console output or verbose mode for details.

You can check the exit code in scripts to determine whether the operation succeeded:

Windows batch: %ERRORLEVEL%
PowerShell: $LASTEXITCODE
Bash: $?

Command Reference

Usage

Connection Parameters

Example

Authentication Parameters

Examples

Task Parameters

Common Settings

Examples

Format Parameters

Examples

CSV Parameters

Examples

Excel Parameters

Examples

XML Parameters

Example

Data Parameters

Examples

SQL Parameters

Examples

File Storage Parameters

Example

Registration Parameters

Examples

Rules for --remember

Batch File Rules

Other Parameters

Example

Parameter Precedence

Exit Codes

Related Topics

Send Feedback

Rules for `--remember`