bridge-cli

bridge-cli is the terminal client for Bridge, the all-in-one personal agent app. It opens an interactive TUI, authenticates against a Bridge backend, streams agent sessions over SSE, and registers the current checkout as a local connector environment over WebSocket so the remote agent can inspect files, edit files, and run approved shell commands on the user's machine.

The CLI is intended for local development workflows where an agent needs both a chat surface and controlled access to a repository on disk.

Features

• Interactive terminal chat UI built with Ratatui and Crossterm.
• Email code login flow with locally stored JWT auth state.
• Session creation, resuming, listing, renaming, cancellation, and compaction.
• Live response streaming, reasoning summaries, tool status, and transcript view.
• Local connector runtime for file reads, writes, stats, listing, glob, grep, streamed file transfer, and shell execution.
• Approval prompts for shell commands and writes outside the current directory.
• Read-only shell command auto-approval for a constrained allowlist.
• Automatic connector reconnection and session stream reconnection.

Related Projects

• Bridge product repository: contains the Go backend that serves the /v1/user/agent/* HTTP, SSE, and WebSocket APIs used by bridge-cli, plus the macOS app, web surfaces, and evaluation tooling.
• unbox: the distributed multi-agent runtime used by the broader Bridge system. It provides agent execution infrastructure, remote environment access, and bridge integrations that complement the local connector exposed by this CLI.

Requirements

• Rust toolchain with edition 2024 support.
• A running Bridge backend. By default the CLI talks to http://localhost:8080.
• A terminal that supports alternate-screen TUI applications.

Installation

For a released binary:

curl -fsSL https://github.com/AFK-surf/bridge-cli/releases/latest/download/install.sh | sh

For local development:

cargo build
cargo run -- chat

Quick Start

Start or point at a Bridge backend, then log in:

export BRIDGE_BASE_URL=http://localhost:8080
cargo run -- login

The login flow prompts for an email address, requests a six-digit verification code from the backend, then stores the returned JWT locally.

Start the TUI:

cargo run

or:

cargo run -- chat

When the TUI starts, bridge-cli:

1. ensures the user is authenticated;
2. checks the backend agent config;
3. detects the nearest Git repository root from the current directory;
4. connects that root as a Bridge connector environment;
5. opens or creates an agent session when the first message is sent.

CLI Commands

bridge-cli [--log-file <path>] [command]

If no command is provided, bridge-cli starts chat.

Command	Description
chat [--session <id>]	Open the interactive TUI, optionally resuming a specific session.
login	Force the email code login flow and store fresh auth state.
logout	Clear stored auth state.
sessions	Print recent sessions for the current account.
new [title]	Start the TUI with a new draft session title.
connector status	Print the computed local connector name, alias, root, and backend URL.

Use --log-file <path> to write tracing output to a file. Without this flag, tracing is initialized with a sink writer.

TUI Commands

Inside the chat composer, slash commands control the active session and UI:

Command	Description
/new [title]	Create a fresh draft session.
/resume [id]	Resume a session by id, or open the recent-session chooser.
/sessions	Open the recent-session chooser.
/permissions	Inspect pending approval requests.
/transcript	Toggle between chat and transcript displays.
/search	Search the transcript.
/rename <title>	Rename the current or draft session.
/cancel	Cancel the active run.
/compact	Request backend context compaction for the current session.
/status	Show connector, session, run, and approval state.
/help	Open in-app help.
/quit	Exit the TUI.

Useful key bindings:

Key	Action
Enter	Send the current message.
Ctrl+Enter, Alt+Enter, or Shift+Enter	Insert a newline.
Ctrl+T	Toggle chat/transcript display.
PgUp / PgDn	Scroll transcript content.
Mouse wheel	Scroll transcript content.
Esc	Close overlays.
Ctrl+C	Quit.

In the permissions overlay, use a to approve, r to reject, Tab to enter feedback, and Up/Down or j/k to switch requests.

Configuration

Config and auth files are stored via the platform config directory resolved by the directories crate for bridge-cli.

The store contains:

• config.toml
  • base_url: backend URL. Defaults to BRIDGE_BASE_URL, then http://localhost:8080.
  • machine_id: generated 12-character machine id used in connector aliases.
  • last_session_id: reserved session state field.
• auth.json
  • jwt: bearer token returned by login verification.
  • email: login email address.

To switch backends, either set BRIDGE_BASE_URL before the first run or edit config.toml.

Connector Behavior

The connector runtime registers over:

/v1/user/agent/connect

using a WebSocket URL derived from base_url. The local environment alias is computed from the machine id and a short hash of the detected repository root:

local-cli-<machine_id>-<path_hash>

The connector exposes methods for:

• read, write, delete, stat, and list;
• glob and grep;
• read_stream and write_stream;
• exec;
• request_permission.

Paths are resolved under the detected root. The CLI detects the nearest parent directory containing .git; if none is found, it uses the current directory.

Shell execution runs through /bin/bash -lc in the requested working directory. Known read-only commands are auto-approved. Other commands trigger an in-TUI approval prompt before execution. Writes inside the current directory are allowed by default; writes outside the current directory but still under the connector root require approval.

Development

Common commands:

cargo check
cargo build
cargo build --release
cargo fmt --all
cargo fmt --all -- --check
cargo clippy --lib -p bridge-cli --message-format=short

Run tests:

cargo test

From the Bridge product repository root, start the local Bridge backend:

docker compose -f backend/.docker/dev/compose.yml up -d
cd backend
cp config.example.json config.json
make run CONFIG_PATH=./config.json

Then, from this repository:

export BRIDGE_BASE_URL=http://localhost:8080
cargo run -- login
cargo run -- chat

Source Layout

src/
|-- main.rs                  # Tokio entry point
|-- lib.rs                   # crate exports
|-- cli.rs                   # Clap command definitions and top-level dispatch
|-- config.rs                # config/auth store
|-- auth.rs                  # email-code login and JWT extraction
|-- api/                     # Bridge REST and SSE client
|-- session.rs               # session service and stream handling
|-- events.rs                # UI event bus types
|-- terminal.rs              # plain terminal helpers
|-- ui.rs                    # Ratatui TUI rendering and input handling
`-- connector/
    |-- mod.rs               # WebSocket connector runtime
    |-- protocol.rs          # connector protocol message types
    |-- handlers.rs          # file/search/exec request handlers
    |-- approvals.rs         # approval broker
    `-- shell_safety.rs      # read-only command analysis