Connecting the Bridge to the CLI

The extension runs standalone, but seven features — flow-deploy, flow-version-manager, ai-assistant, org-health, drift-check, metadata-scan, and org-compare — call your local sfdt CLI through the bridge. The bridge is a localhost-only channel; nothing it carries ever leaves your machine. (flow-quality used to need the bridge but now runs @sfdt/flow-core in-browser — no bridge required.)

For a conceptual deep-dive shared with the VS Code extension, see Guides → The bridge.

HTTP transport (recommended)

The CLI’s sfdt ui command starts a local server that also mounts the bridge.

Install and initialise the CLI


npm install -g @sfdt/cli
cd your-salesforce-project
sfdt init        # one-time .sfdt/ setup

Start the local server


sfdt ui          # starts http://localhost:7654 + the bridge

Pair the extension

Open the extension’s options page.
Paste the bridge token from ~/.sfdt/bridge-token.
Click Test connection.

The token file is created on the first request to the running server, with 0600 permissions. Treat it like a password — it authorises commands against your orgs.

Native-messaging fallback

If you can’t keep sfdt ui running, the extension can talk to the CLI through Chrome’s native messaging instead. Install the native host once per browser:


sfdt extension install-host --extension-id <your-extension-id>
sfdt extension status     # verify which browsers have the host

The host (com.sfdt.host) ships with the CLI and supports Chrome, Edge, Brave, Chromium, and Vivaldi on macOS, Linux, and Windows. Set the preferred transport in the options page (auto, localhost, or native).

The host answers the read-only bridge kinds directly — quality (in-process via @sfdt/flow-core), plus scan, compare, drift, and org-health. Mutating kinds (deploy, rollback, ai) stay bridge-only and need sfdt ui running. Because Chrome launches the host outside any project, install-host records the project root in ~/.config/sfdt-host.json; pass --project-root <path> to override the auto-detected project, or set SFDT_PROJECT_ROOT.

The extension’s built manifest requests storage, clipboardWrite, and cookies plus localhost host permissions. The native-messaging transport is provided by the CLI-installed host; if your browser prompts for additional permission when enabling it, that is expected.

Versioned wire protocol

The bridge speaks a versioned contract (currently v1.3, defined in packages/flow-core/src/bridge-contract.ts):

Minor mismatch (e.g. 1.2 vs 1.3) — the extension warns but continues; the protocol is additive and backward-compatible.
Major mismatch (e.g. 1.x vs 2.0) — the extension refuses to send requests.

Request kinds include ping, version, deploy, rollback, quality, ai, scan, compare, drift, org-health, telemetry.snapshot, manifest.discover, and manifest.render.

Verifying the connection


sfdt doctor --extension

This checks the bridge, the native host, the kill-switch file, and the telemetry snapshot. See Troubleshooting.