CLI Reference

Command-line reference for the spectral-bridge package. For a guided walkthrough, see the Quickstart.

Installation

Example

pip install spectral-bridge
# or, with extra dependencies for built-in adapters:
pip install "spectral-bridge[pass-through]"

Authentication

All commands require the SPECTRAL_BRIDGE_API_KEY environment variable:

Example

export SPECTRAL_BRIDGE_API_KEY=<your-api-key>

Relay URL

From spectral-bridge 0.4.0, the relay URL defaults to Spectral's relay (wss://bridge.spectral.principled.app/connect). To connect to a different platform's relay server, pass --relay-url wss://relay.example.com/connect or set the SPECTRAL_BRIDGE_RELAY_URL environment variable (the flag wins over the variable). On earlier versions, --relay-url is required.

Commands

spectral-bridge start

Starts both the relay client and a passthrough adapter. The bundled pass-through adapter serves both /v1/chat/completions and /v1/responses; each request is routed to whichever endpoint your target exposes, so there is no protocol flag to set.

Example

spectral-bridge start \
  --adapter  pass-through \             # built-in adapter to spawn
  --target   http://internal-host:8080  # base URL of your AI system

Optional flags:

Flag	Default	Description
--relay-url	Spectral relay	Relay server WebSocket URL (see Relay URL).
--port	8840	Local port for the adapter.
--request-timeout	600	Max seconds to wait for the adapter to return a completion. The default is matched to the Spectral relay; on another platform keep it at or above that relay's server-side timeout.
--max-ws-message-bytes	16777216 (16 MiB)	Maximum incoming WebSocket message size from the relay.
--insecure-relay	off	Allow ws:// instead of wss:// (development only).

spectral-bridge start-relay

Starts only the relay client, connecting it to an adapter you are already running.

Example

spectral-bridge start-relay \
  --adapter-url  http://localhost:8000  # URL of your running adapter

Optional flags:

Flag	Default	Description
--relay-url	Spectral relay	Relay server WebSocket URL (see Relay URL).
--request-timeout	600	Max seconds to wait for the adapter to return a completion. The default is matched to the Spectral relay; on another platform keep it at or above that relay's server-side timeout.
--max-ws-message-bytes	16777216 (16 MiB)	Maximum incoming WebSocket message size from the relay.
--insecure-relay	off	Allow ws:// instead of wss:// (development only).
--insecure-adapter	off	Allow a non-loopback adapter URL (development only; the adapter is normally reached over localhost).