bc-cli 0.1.3__tar.gz → 0.2.0__tar.gz

{bc_cli-0.1.3 → bc_cli-0.2.0}/.gitignore

@@ -32,3 +32,4 @@ TRASH-FILES.md
 PRD-*.md
 TODOS.md
 bcapi_cli_prd.md
+.planning/

{bc_cli-0.1.3 → bc_cli-0.2.0}/AGENTS.md

@@ -29,6 +29,47 @@ Use `-e` / `--env` only when the user explicitly asks you to hit a
 Same for `--company` / `-c`: only pass it when switching off the
 profile's default company.
 
+The endpoint **registry** does the same job for the API route. When you
+write `bcli get fixedAssets`, the registry already knows the
+publisher / group / version for `fixedAssets` and builds the URL for
+you. You do **not** need `--publisher … --group … --version …` — those
+are escape hatches for the rare case where an admin hasn't imported the
+endpoint yet, and they're hidden from `--help` for that reason. If
+`bcli get <name>` errors with `RegistryError`, the fix is to import the
+endpoint into the registry, not to pass override flags.
+
+---
+
+## Don't write this — minimal command, please
+
+The single biggest tell that an agent is over-pattern-matching:
+redundant flags that the profile + registry already supply.
+
+```bash
+# ❌ Don't write this:
+bcli -c LLC get fixedAssets --publisher beautech --group finance --version v1.5 --all -f json
+
+# ✅ Write this:
+bcli -c LLC get fixedAssets
+```
+
+Why each flag was wrong:
+
+- `--publisher beautech --group finance --version v1.5` — the
+  registry resolves these automatically. Only pass them if the
+  endpoint isn't in the registry (and even then, prefer importing it).
+- `--all` — pulls **every** page. Most asks need `--top 5` or no
+  pagination flag at all. Use `--all` only when the user explicitly
+  asks for a full export.
+- `-f json` — bcli already auto-detects agents (`CLAUDECODE=1`,
+  `BCLI_AGENT=1`, or non-TTY stdout) and emits markdown. Pass `-f
+  json` only when you actually need to feed the result into `jq` or
+  another tool call.
+
+Rule of thumb: **start with the shortest command that names the
+action** (`bcli get fixedAssets`), then add flags one at a time only
+when the user's question demands them.
+
 ---
 
 ## Endpoint discovery — don't guess names
@@ -120,6 +161,67 @@ user, don't loop.
 
 ---
 
+## Dry-run before writes
+
+Before any `post` / `patch` / `delete` / `attach upload`, run with `--dry-run`
+and `-f json` to get a structured preview the user can sanity-check:
+
+```bash
+bcli --dry-run -f json post customers --data '{"displayName": "Test"}'
+```
+
+The response is a JSON envelope:
+
+```json
+{
+  "dry_run": true,
+  "method": "POST",
+  "endpoint": "customers",
+  "resolved_url": "https://.../api/v2.0/companies(<id>)/customers",
+  "profile": "dev",
+  "environment": "Sandbox",
+  "company_id": "<id>",
+  "body": {"displayName": "Test"}
+}
+```
+
+`PATCH` and `DELETE` envelopes also include `record_id`. The shape is stable —
+field names won't change. Use it to:
+
+* Show the user the resolved URL + body before they approve a real write.
+* Catch typos in the endpoint name before any HTTP call goes out.
+* Verify the right environment / company is targeted.
+
+## Caution levels for write endpoints
+
+Every endpoint exposes a `caution` level (`low` / `medium` / `high`) via
+`bcli endpoint info` and the `list_endpoints` MCP tool. Endpoints whose name
+contains a mutation verb (`post`, `release`, `cancel`, `void`, `reverse`,
+`apply`, `unapply`) are flagged `high` automatically. Treat `high` as: "do
+not write without explicit user confirmation, even if the user previously
+authorised a similar action." Examples:
+
+* `customers` → `low` (CRUD on a master-data record)
+* `salesInvoicePost` → `high` (irreversibly posts an invoice)
+* `customerLedgerEntryApply` → `high` (modifies posted ledger state)
+
+## Audit log location
+
+When the user has `[audit] enabled = true` in `~/.config/bcli/config.toml`,
+every write you trigger appends a JSON line to
+`~/.config/bcli/audit/<profile>.jsonl` (or whatever the user configured).
+Each entry includes `outcome` (`completed` / `failed` / `dry_run`),
+`correlation_id` (BC's `x-ms-correlation-request-id`), `latency_ms`, and the
+redacted request body. Useful for:
+
+* Showing the user "here's what just happened" after a multi-step task.
+* Grepping for the BC correlation ID when debugging a 500 the user reported.
+* Reconciling intent (`dry_run` entries) against actual writes.
+
+You don't need to enable the log yourself — it's the user's choice. If they
+ask "did that POST go through?" the audit log is the canonical answer when it's
+on, and the CLI exit code is the answer when it's off.
+
 ## When you have an MCP server
 
 If the user has mounted `bcli-mcp` (see [`docs/mcp-server.md`](docs/mcp-server.md)),

{bc_cli-0.1.3 → bc_cli-0.2.0}/CHANGELOG.md

@@ -7,8 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-05-06
+
+### Added
+
+- **Structured `--dry-run` output** — write commands (`post`, `patch`,
+  `delete`, `attach upload`) now emit a stable JSON envelope on stdout
+  when `--format json` / `ndjson` / `raw` is selected. Includes
+  `dry_run`, `method`, `endpoint`, `resolved_url`, `profile`,
+  `environment`, `company_id`, `body`, and `record_id` (when applicable).
+  Agents can parse the envelope before deciding whether to proceed. The
+  human format keeps the same yellow rich panel on stderr but is now
+  augmented with the resolved URL and profile context. See
+  `docs/write-operations.md`.
+- **Opt-in audit log** — new `[audit]` config section persists every
+  write to a per-profile JSONL file. Each entry captures the resolved
+  URL, response status, BC `correlation_id`, latency, redacted request
+  body, and outcome (`completed` / `failed` / `dry_run`). Bounded disk
+  usage via single-backup rotation. SDK (`AsyncBCClient`) does NOT
+  auto-emit; this is a CLI-layer ergonomic on top of BC permission sets.
+  See `docs/configuration.md#audit-log`.
+- **Endpoint `caution` flag** — `EndpointMetadata` now carries a
+  `caution: low | medium | high` level. Importers populate it
+  automatically from a verb-name heuristic (entities containing `post`,
+  `release`, `cancel`, `void`, `reverse`, `apply`, `unapply` are flagged
+  `high`). Surfaced in `bcli endpoint info` and the `list_endpoints` MCP
+  tool so agents can require explicit user confirmation before mutating
+  posted/closed records.
+- New `AGENTS.md` recipes for dry-run-first writes, caution-level
+  interpretation, and audit-log location.
+
+## [0.1.5] — 2026-05-05
+
 ### Added
 
+- **Business Central admin setup guide** — new
+  `docs/business-central-admin-setup.md` walks a zero-knowledge user
+  through Entra app registration, localhost redirect setup, delegated BC
+  permissions, admin consent, BC user permission sets, first `bcli
+  config init`, and verification.
 - **`bcli-mcp` preview server** — an MCP (Model Context Protocol) server
   that lets Claude Desktop and other MCP clients drive bcli. Four
   read-only tools: `query`, `list_endpoints`, `describe_endpoint`,
@@ -18,12 +55,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `bcli config init` now defaults to browser PKCE auth for local humans
+  and agents. New `--automation` and `--headless` shortcuts create
+  client-credentials and device-code profiles respectively.
+- CLI runtime dependencies now ship with the base `bc-cli` install, so
+  `pip install bc-cli` and `uv tool install bc-cli` provide a working
+  `bcli` command without requiring an extra.
 - `bcli company list` accepts `--format` (`json`, `markdown`, `csv`,
   `ndjson`, `table`). Stable JSON shape:
   `[{"id", "name", "alias", "is_default"}]`.
 - `bcli endpoint list` and `bcli endpoint info` accept `--format json`.
   Stable JSON shapes documented inline in each command's help text.
 
+### Removed
+
+- Removed WorkOS AuthKit support. Browser PKCE is now the delegated auth
+  path, Business Central remains the permission boundary, and
+  client-credentials profiles cover automation.
+
 ## [0.1.2] — 2026-04-29
 
 Security release. Closes four findings from a strix.ai run against the

{bc_cli-0.1.3 → bc_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bc-cli
-Version: 0.1.3
+Version: 0.2.0
 Summary: Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs
 Project-URL: Homepage, https://github.com/igor-ctrl/bcli
 Project-URL: Repository, https://github.com/igor-ctrl/bcli
@@ -23,35 +23,25 @@ Classifier: Topic :: Office/Business :: Financial :: Accounting
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
 Requires-Dist: msal>=1.28
 Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
 Requires-Dist: tomlkit>=0.13
+Requires-Dist: typer>=0.12
 Provides-Extra: cli
-Requires-Dist: keyring>=25.0; extra == 'cli'
-Requires-Dist: pyyaml>=6.0; extra == 'cli'
-Requires-Dist: rich>=13.0; extra == 'cli'
-Requires-Dist: typer>=0.12; extra == 'cli'
-Requires-Dist: workos>=5.0; extra == 'cli'
 Provides-Extra: dev
-Requires-Dist: keyring>=25.0; extra == 'dev'
+Requires-Dist: dlt[filesystem,parquet,s3]>=1.0; extra == 'dev'
 Requires-Dist: mcp>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: pyyaml>=6.0; extra == 'dev'
-Requires-Dist: rich>=13.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
-Requires-Dist: typer>=0.12; extra == 'dev'
-Requires-Dist: workos>=5.0; extra == 'dev'
 Provides-Extra: etl
 Requires-Dist: dlt[filesystem,parquet,s3]>=1.0; extra == 'etl'
 Provides-Extra: mcp
-Requires-Dist: keyring>=25.0; extra == 'mcp'
 Requires-Dist: mcp>=1.0; extra == 'mcp'
-Requires-Dist: pyyaml>=6.0; extra == 'mcp'
-Requires-Dist: rich>=13.0; extra == 'mcp'
-Requires-Dist: typer>=0.12; extra == 'mcp'
-Requires-Dist: workos>=5.0; extra == 'mcp'
 Provides-Extra: polaris
 Requires-Dist: dlt[filesystem,parquet,s3]>=1.0; extra == 'polaris'
 Requires-Dist: pyarrow>=16.0; extra == 'polaris'
@@ -67,7 +57,9 @@ Description-Content-Type: text/markdown
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
 
-A Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs, with a built-in [dlt](https://dlthub.com) source for ETL backup pipelines.
+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](https://dlthub.com) source for ETL backup pipelines.
 
 > **Status: Alpha (0.1.x).** Public surface may change before 1.0. Track
 > [CHANGELOG.md](CHANGELOG.md) for breaking changes. Independent project
@@ -112,7 +104,7 @@ pip install bc-cli
 # or
 uv tool install bc-cli
 
-# Configure (interactive — discovers companies automatically)
+# Configure with browser auth (no client secret)
 bcli config init
 
 # Query standard APIs immediately
@@ -135,7 +127,7 @@ bcli get myCustomEntities --top 5
 - **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** — OS keychain integration (macOS Keychain, Windows Credential Manager), token caching, client credentials + device code flows
+- **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
@@ -196,17 +188,14 @@ Requires Python 3.11+.
 > documented.
 
 ```bash
-# SDK only (for libraries, MCP servers, Airflow DAGs)
+# CLI + SDK
 pip install bc-cli
 
-# SDK + CLI
-pip install "bc-cli[cli]"
-
 # SDK + ETL (dlt source for backup pipelines)
 pip install "bc-cli[etl]"
 
 # Everything
-pip install "bc-cli[cli,etl]"
+pip install "bc-cli[etl,mcp,telemetry]"
 
 # Via uv (recommended)
 uv tool install bc-cli
@@ -222,8 +211,9 @@ pip install -e ".[dev,etl]"
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](docs/getting-started.md) | First-time setup, authentication, your first query |
+| [Business Central Admin Setup](docs/business-central-admin-setup.md) | Entra app registration and BC permissions from scratch |
 | [Configuration](docs/configuration.md) | Profiles, environments, config file format |
-| [Authentication](docs/authentication.md) | Client credentials, device code, OS keychain |
+| [Authentication](docs/authentication.md) | Browser auth, client credentials, device code fallback |
 | [Querying Data](docs/querying.md) | GET, OData filters, pagination, output formats |
 | [Write Operations](docs/write-operations.md) | POST, PATCH, DELETE |
 | [Custom APIs](docs/custom-apis.md) | Importing from Postman, JSON, or $metadata |

{bc_cli-0.1.3 → bc_cli-0.2.0}/README.md

@@ -5,7 +5,9 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
 
-A Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs, with a built-in [dlt](https://dlthub.com) source for ETL backup pipelines.
+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](https://dlthub.com) source for ETL backup pipelines.
 
 > **Status: Alpha (0.1.x).** Public surface may change before 1.0. Track
 > [CHANGELOG.md](CHANGELOG.md) for breaking changes. Independent project
@@ -50,7 +52,7 @@ pip install bc-cli
 # or
 uv tool install bc-cli
 
-# Configure (interactive — discovers companies automatically)
+# Configure with browser auth (no client secret)
 bcli config init
 
 # Query standard APIs immediately
@@ -73,7 +75,7 @@ bcli get myCustomEntities --top 5
 - **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** — OS keychain integration (macOS Keychain, Windows Credential Manager), token caching, client credentials + device code flows
+- **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
@@ -134,17 +136,14 @@ Requires Python 3.11+.
 > documented.
 
 ```bash
-# SDK only (for libraries, MCP servers, Airflow DAGs)
+# CLI + SDK
 pip install bc-cli
 
-# SDK + CLI
-pip install "bc-cli[cli]"
-
 # SDK + ETL (dlt source for backup pipelines)
 pip install "bc-cli[etl]"
 
 # Everything
-pip install "bc-cli[cli,etl]"
+pip install "bc-cli[etl,mcp,telemetry]"
 
 # Via uv (recommended)
 uv tool install bc-cli
@@ -160,8 +159,9 @@ pip install -e ".[dev,etl]"
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](docs/getting-started.md) | First-time setup, authentication, your first query |
+| [Business Central Admin Setup](docs/business-central-admin-setup.md) | Entra app registration and BC permissions from scratch |
 | [Configuration](docs/configuration.md) | Profiles, environments, config file format |
-| [Authentication](docs/authentication.md) | Client credentials, device code, OS keychain |
+| [Authentication](docs/authentication.md) | Browser auth, client credentials, device code fallback |
 | [Querying Data](docs/querying.md) | GET, OData filters, pagination, output formats |
 | [Write Operations](docs/write-operations.md) | POST, PATCH, DELETE |
 | [Custom APIs](docs/custom-apis.md) | Importing from Postman, JSON, or $metadata |

bc_cli-0.2.0/docs/authentication.md

@@ -0,0 +1,104 @@
+# Authentication
+
+bcli supports three Business Central online authentication methods:
+
+| Method | Flow | Use case |
+|--------|------|----------|
+| `browser` | Authorization code with PKCE | Default for local humans and AI agents |
+| `client_credentials` | App permissions | CI/CD, servers, scheduled jobs |
+| `device_code` | Delegated device code | SSH/headless fallback |
+
+For a full zero-knowledge Entra ID and Business Central setup, start with
+[Business Central Admin Setup](business-central-admin-setup.md).
+
+## Browser Auth (Recommended)
+
+Browser auth is the default for `bcli config init`. It opens the user's browser,
+uses PKCE, needs no client secret, and Business Central enforces the signed-in
+user's permission sets.
+
+```bash
+bcli config init
+bcli auth login
+bcli get customers --top 5
+```
+
+The Entra app registration must be a public/native client with delegated
+Business Central permissions and a localhost redirect URI. See
+[Business Central Admin Setup](business-central-admin-setup.md) for the portal
+steps.
+
+Useful login options:
+
+```bash
+# Fresh browser session, useful when switching accounts
+bcli auth login --method browser --incognito
+
+# Explicit browser profile setup
+bcli config init --auth browser
+```
+
+## Client Credentials
+
+Use client credentials only for automation: CI/CD, background jobs, servers, and
+scheduled exports. This path uses application permissions and a client secret,
+so it should be set up deliberately.
+
+```bash
+bcli config init --automation
+bcli auth store-secret
+bcli get customers --top 5
+```
+
+bcli never stores client secrets in config files. It resolves secrets in this
+order:
+
+1. OS keychain: macOS Keychain, Windows Credential Manager, or equivalent.
+2. The configured `client_secret_env` environment variable.
+3. Generic fallback env vars: `BCLI_SECRET` or `BCLI_CLIENT_SECRET`.
+
+In CI, use environment variables:
+
+```yaml
+env:
+  BCLI_SECRET: ${{ secrets.BC_CLIENT_SECRET }}
+
+steps:
+  - run: bcli get customers --top 1 -f json -q
+```
+
+No `bcli auth login` is required when a valid secret is available; bcli acquires
+tokens automatically.
+
+## Device Code
+
+Device code is a fallback for hosts where a localhost browser callback is not
+practical, such as SSH sessions or locked-down remote machines.
+
+```bash
+bcli config init --headless
+bcli auth login --method device
+```
+
+The terminal prints a URL and code. Open the URL in any browser, enter the code,
+and bcli caches the resulting delegated token.
+
+## Token Cache
+
+After authentication, bcli caches access tokens at
+`~/.config/bcli/tokens.json`. Tokens are reused until shortly before expiry.
+
+```bash
+bcli auth status
+bcli auth logout
+```
+
+## Common Failures
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Redirect URI mismatch | Entra app lacks localhost redirect URI | Add `http://localhost` as a mobile/desktop redirect URI |
+| Consent required | Tenant admin has not granted API consent | Grant admin consent for Business Central delegated permissions |
+| 403 Forbidden | User lacks BC permission set for that page/company | Assign the user the required Business Central permissions |
+| Wrong tenant/account | Browser reused an existing Microsoft session | Re-run with `--incognito` |
+| Secret missing | Automation profile cannot find `BCLI_SECRET` or keychain secret | Run `bcli auth store-secret` or set the env var |

bc_cli-0.2.0/docs/business-central-admin-setup.md

@@ -0,0 +1,121 @@
+# Business Central Admin Setup
+
+This guide is for users who do not already have an Entra app registration or
+Business Central API permissions ready for bcli.
+
+## Recommended Local Setup: Browser Auth
+
+Use this path for humans and local AI agents. It needs no client secret.
+
+### 1. Create An Entra App Registration
+
+1. Open the Microsoft Entra admin center.
+2. Go to **Identity** -> **Applications** -> **App registrations**.
+3. Select **New registration**.
+4. Name it something clear, such as `bcli-local`.
+5. Choose the supported account type for your tenant.
+6. Register the app.
+7. Copy the **Application (client) ID** and **Directory (tenant) ID**.
+
+### 2. Configure Browser Redirect
+
+1. Open the app registration.
+2. Go to **Authentication**.
+3. Add a platform: **Mobile and desktop applications**.
+4. Add redirect URI: `http://localhost`.
+5. Save.
+
+bcli binds an available localhost port at login time. Entra accepts localhost
+redirects for native clients without requiring one fixed port.
+
+### 3. Add Business Central API Permission
+
+1. Open **API permissions**.
+2. Select **Add a permission**.
+3. Choose **Dynamics 365 Business Central**.
+4. Choose **Delegated permissions**.
+5. Add the Business Central delegated permission your tenant requires, commonly
+   `user_impersonation` or `Financials.ReadWrite.All`.
+6. Grant admin consent if your tenant requires it.
+
+### 4. Assign Business Central Permissions
+
+The browser token carries the signed-in user. Business Central still decides
+what that user can see or change.
+
+1. Open Business Central.
+2. Search for **Users**.
+3. Open the user who will run bcli.
+4. Assign the required permission sets for the companies and pages they need.
+5. Start read-only when possible, then add write permissions deliberately.
+
+### 5. Configure bcli
+
+```bash
+bcli config init
+```
+
+Use:
+
+- Tenant ID: the Directory tenant ID from Entra.
+- Environment: `Production`, `Sandbox`, or your BC environment name.
+- Client ID: the Application client ID from Entra.
+- Auth method: browser auth is the default.
+
+When bcli asks to authenticate, accept. It opens a browser, completes Microsoft
+sign-in, discovers companies, and lets you choose a default company.
+
+### 6. Verify
+
+```bash
+bcli test connection
+bcli get customers --top 5
+```
+
+If this fails with `403 Forbidden`, authentication worked but Business Central
+permissions are missing for that user.
+
+## Automation Setup: Client Credentials
+
+Use this path for CI/CD, servers, and scheduled jobs.
+
+### 1. Create Or Reuse A Confidential App
+
+Create an Entra app registration for automation and add Business Central
+**application** permissions. Generate a client secret or certificate according
+to your organization's policy.
+
+### 2. Grant Consent And BC Access
+
+Grant admin consent for the application permission. In Business Central, ensure
+the application identity has the required API access and permission sets for the
+target companies.
+
+### 3. Configure bcli
+
+```bash
+bcli config init --automation
+bcli auth store-secret
+```
+
+For CI, store the secret in your pipeline secret manager and expose it as
+`BCLI_SECRET` or the `client_secret_env` name you chose during setup.
+
+## Headless Fallback: Device Code
+
+Use device code only when browser callback auth cannot work, such as SSH hosts.
+
+```bash
+bcli config init --headless
+bcli auth login --method device
+```
+
+## Troubleshooting
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| Redirect URI mismatch | Entra does not allow the localhost callback | Add `http://localhost` under Mobile and desktop applications |
+| Consent required | Tenant policy blocks unconsented API permissions | Ask an admin to grant consent |
+| 403 Forbidden | BC rejected the user or app authorization | Assign the right BC permission sets and company access |
+| Wrong account | Browser reused another Microsoft login | Run `bcli auth login --incognito` |
+| Secret missing | Automation profile cannot find a secret | Run `bcli auth store-secret` or set the configured env var |

{bc_cli-0.1.3 → bc_cli-0.2.0}/docs/command-reference.md

@@ -26,12 +26,23 @@ bcli [global-options] <command> [command-options]
 
 ### config init
 
-Interactive setup wizard. Discovers companies automatically.
+Interactive setup wizard. Defaults to browser auth and discovers companies
+automatically.
 
 ```bash
 bcli config init
+bcli config init --automation
+bcli config init --headless
 ```
 
+| Option | Description |
+|--------|-------------|
+| `--auth <method>` | `browser`, `client-credentials`, or `device-code` |
+| `--automation` | Shortcut for client credentials |
+| `--headless` | Shortcut for device code |
+| `--scoped` | Hide standard APIs; only imported endpoints are visible |
+| `--import <file>` | Import custom endpoints after profile creation |
+
 ### config show
 
 Print resolved configuration (secrets redacted).
@@ -77,14 +88,12 @@ bcli auth login [--method <method>] [--incognito]
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--method <method>` | `-m` | `workos`, `browser`, `device`, or `client_credentials` (default: profile's `auth_method`) |
+| `--method <method>` | `-m` | `browser`, `device`, or `client_credentials` (default: profile's `auth_method`) |
 | `--incognito` | `-i` | Open the browser in incognito/private mode — useful for logging in as a different user |
 
 Examples:
 ```bash
 bcli auth login                              # uses profile's auth_method
-bcli auth login --method workos              # WorkOS SSO → role-based BC access
-bcli auth login --method workos -i           # incognito — log in as a different user
 bcli auth login --method browser             # browser OAuth (user's BC permissions, PKCE)
 bcli auth login --method device              # device code flow
 bcli auth login --method client_credentials  # service-to-service