CLI usage

The bridgemcp CLI drives agent deployment and endpoint status from the command line. It authenticates against your BridgeMCP instance using the same OAuth authorization server that serves interactive MCP clients, through a browser-based authorization code flow with PKCE.

Installation

The CLI is distributed two ways.

As a .NET tool

Requires the .NET 10 SDK. Install it globally:

dotnet tool install --global BridgeMCP.Cli

The command is exposed as bridgemcp. Update with dotnet tool update --global BridgeMCP.Cli.

As a self-contained binary

Self-contained, single-file binaries (no .NET runtime required) are attached to each BridgeMCP CLI GitHub release. The install scripts detect your platform, download the matching binary, place it on your PATH, and verify it runs.

On Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/kubebridges/bridge-cli/main/scripts/install.sh | sh

On Windows (PowerShell):

irm https://raw.githubusercontent.com/kubebridges/bridge-cli/main/scripts/install.ps1 | iex

Pin a specific version by passing --version <x.y.z> (Linux/macOS) or -Version <x.y.z> (Windows). Only linux-x64, osx-arm64, and win-x64 binaries are published.

To install manually instead, download the archive for your platform from the public CLI releases page, extract it (the binary inside is named bridgemcp-<version>-<rid>), rename it, mark it executable, and place it on your PATH. For example, for 0.1.0 on linux-x64:

tar -xzf bridgemcp-0.1.0-linux-x64.tar.gz
mv bridgemcp-0.1.0-linux-x64 bridgemcp
chmod +x bridgemcp
mv bridgemcp /usr/local/bin/

Authentication

bridgemcp login [--url <url>]

login starts a loopback listener on http://127.0.0.1:<port>/callback, opens your browser to the consent page, and completes the OAuth authorization-code flow with PKCE. On approval it stores the resulting cli-scoped token in a local config file.

  • --url is optional and defaults to https://bridgemcp.net.
  • The browser flow requires an interactive session. Headless and CI authentication is not part of the initial release.
  • The token is valid for 30 days of inactivity; active use keeps it alive (sliding expiry).
bridgemcp logout

logout clears the stored token locally and best-effort revokes it on the server.

Configuration

The CLI resolves its instance URL and token in this order:

  1. A command-line flag (--url).
  2. Environment variables: BRIDGEMCP_URL and BRIDGEMCP_TOKEN.
  3. The stored config file at ~/.bridgemcp/config.json.

The default URL is https://bridgemcp.net. The config file holds the instance URL and token and is written with owner-only permissions (0600) on Unix.

Commands

status

bridgemcp status

Shows a composed view of your Virtual MCPs and connectors: whether each is enabled, whether it is connected, and its per-connector OAuth state.

agents list

bridgemcp agents list

Lists the agents in your organization.

agents deploy

bridgemcp agents deploy <agent-name-or-id> <package.zip>

Uploads an agent package (a .zip archive of skills and configuration) to an agent. The first argument accepts either the agent id or its name; a name is resolved against your agent list (an ambiguous name asks you to use the id instead).

Output and exit codes

Read commands (status, agents list) accept --json for machine-readable output. Commands return a non-zero exit code with a clear error message when an API call fails, so the CLI composes cleanly into scripts.

Next steps