bcli

A Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs, with agent-friendly endpoint discovery, browser auth, custom API registries, and a built-in dlt source for ETL backup pipelines.

Status: Alpha (0.1.x). Public surface may change before 1.0. Track CHANGELOG.md for breaking changes. Independent project by @igor-ctrl — not affiliated with Microsoft.

SDK Quick Start

from bcli import AsyncBCClient

# Programmatic auth — no config files needed
async with AsyncBCClient(
    tenant_id="your-tenant-id",
    client_id="your-app-id",
    client_secret="your-secret",
    environment="Sandbox",
    company_id="your-company-id",
) as client:
    # Query with fluent OData builder
    customers = await client.query("customers").filter("city eq 'Chicago'").top(10).get()

    # Write with safety gate
    async with client.safe_write("Sandbox", "your-company-id") as sw:
        await sw.post("salesInvoices", body={"customerNumber": "10000"}, domain="finance")

Or use TOML profiles for the CLI and repeated SDK use:

from bcli import AsyncBCClient

async with AsyncBCClient(profile="production") as client:
    vendors = await client.query("vendors").select("displayName", "balance").get()

CLI Quick Start

# Install (PyPI distribution name is "bc-cli"; the binary is "bcli")
pip install bc-cli
# or
uv tool install bc-cli

# Configure with browser auth (no client secret)
bcli config init

# Query standard APIs immediately
bcli get customers --top 5
bcli get vendors --filter "displayName eq 'Fabrikam'" --format json
bcli get salesInvoices --select number,totalAmountIncludingTax --top 10

# Import custom APIs from a Postman collection
bcli registry import --from-postman ./my_collection.json

# Query custom endpoints (route auto-resolved)
bcli get myCustomEntities --top 5

Features

• Works out of the box — 79 standard BC v2.0 entities (customers, vendors, items, GL entries, ...) with zero configuration beyond auth
• Custom API support — Import your custom API pages from Postman collections, JSON, or live $metadata
• Three-tier endpoint resolution — Custom registry -> standard v2.0 -> fuzzy suggestions
• Multi-company — Assign aliases to companies and query across all entities
• OData query builder — --filter, --select, --expand, --orderby, --top, --skip on every query
• Multiple output formats — table, JSON, CSV, NDJSON for pipeline use
• Secure auth — Browser PKCE by default, OS keychain support for automation secrets, token caching, client credentials + device code fallback
• Write safety — SafeContext gate prevents wrong-environment writes, enforces draft status on financial documents
• Programmatic auth — Pass credentials directly for MCP servers, Airflow DAGs, and containers (no config files required)
• Batch operations — Execute sequences of API calls from YAML files
• ETL pipeline — Built-in dlt source for incremental backup to Parquet / DuckDB / Iceberg / Postgres
• Structured logging — JSON request logs with correlation IDs for observability

ETL Pipeline (dlt source)

Sync BC data incrementally to any dlt-supported destination — useful as a Fivetran backup, a warehouse backfill tool, or a standalone ETL runner.

Standalone (any BC tenant, no bcli config required):

import dlt
from bcli.etl import business_central, EntityDef, fivetran_stamper

source = business_central(
    tenant_id="...", client_id="...", client_secret="...",
    environment="Production",
    entities=[
        EntityDef(name="customers"),
        EntityDef(name="vendors"),
    ],
    multi_company=True,             # iterate all BC companies
    stampers=[fivetran_stamper()],  # add _fivetran_synced / _fivetran_deleted
)

pipeline = dlt.pipeline(destination="duckdb", dataset_name="bc_raw")
pipeline.run(source)

Or use the bcli bridge (reuses your profile and custom-API registry):

# List entities the pipeline will sync
bcli --profile prod etl entities

# Incremental sync (uses systemModifiedAt cursor)
bcli --profile prod etl sync --destination filesystem

# Full refresh
bcli --profile prod etl sync --destination filesystem --full-refresh

# Schedule via cron (every 10 min incremental, nightly full refresh)
*/10 * * * * bcli --profile prod etl sync --destination filesystem
0 0 * * *    bcli --profile prod etl sync --destination filesystem --full-refresh

Installation

Requires Python 3.11+.

Heads-up on the package name. The PyPI name is bc-cli, not bcli. An unrelated 2018-era package squats on the bcli name (an "EC2 Cluster Creator" with no relation to this project) — pip install bcli will install that, not this. Always pip install bc-cli. Once installed, the import name (import bcli) and the CLI binary (bcli) work as documented.

# CLI + SDK
pip install bc-cli

# SDK + ETL (dlt source for backup pipelines)
pip install "bc-cli[etl]"

# Everything
pip install "bc-cli[etl,mcp,telemetry]"

# Via uv (recommended)
uv tool install bc-cli

# From source
git clone https://github.com/igor-ctrl/bcli.git
cd bcli
pip install -e ".[dev,etl]"

Documentation

License

Licensed under the Apache License, Version 2.0. See the NOTICE file for attribution requirements.