Commands

Bridge is a CLI-first product, so the command surface is the product surface. This page documents the commands Bridge exposes today, what they do, and how they behave at runtime.

Command map

Bridge currently exposes these subcommands:

Command	Purpose
`init`	Create a `bridge.yaml` file in the current directory
`connect`	Add or update a named provider in `bridge.yaml`
`remove`	Remove a named provider from `bridge.yaml`
`status`	Check the health of configured providers
`ls`	List entries from a provider
`read`	Read structured context from a provider
`completions`	Generate shell completion scripts

Command conventions

Most Bridge commands follow the same runtime pattern:

load bridge.yaml from the current directory
resolve a named provider if the command needs one
perform a provider operation inside the configured timeout
print structured JSON on success

That means the CLI is predictable for both humans and agents:

successful commands print JSON to stdout
failures print JSON to stderr
failures exit with a non-zero status code

Example error output:

{
  "error": {
    "code": "config_not_found",
    "message": "bridge.yaml not found. Run `bridge init` to create one."
  }
}

Bridge currently uses:

exit code 1 for most validation and provider errors
exit code 2 for I/O, database, and timeout failures

Global options

All commands support the global --timeout flag:

bridge --timeout 60 status
bridge --timeout 10 read README.md --from files

Flag	Default	Meaning
`--timeout <seconds>`	`30`	Timeout for provider operations

Bridge also supports the standard top-level help and version flags:

bridge --help
bridge --version

Typical workflow

Most teams use the commands in this order:

bridge init
bridge connect file://./docs --as files
bridge status
bridge ls --from files
bridge read README.md --from files

If you are connecting a database, the flow stays the same:

bridge connect postgres://localhost:5432/mydb --as db
bridge status
bridge ls --from db
bridge read users --from db --limit 25

For a safer setup that keeps the real connection string out of bridge.yaml, connect with an environment variable name instead:

bridge connect DATABASE_URL --type postgres --as db
export DATABASE_URL=postgres://user:pass@localhost:5432/mydb
bridge status

`bridge init`

Create a new bridge.yaml in the current directory.

Usage

bridge init

What it does

creates bridge.yaml if it does not already exist
uses the current directory name as the default project name
initializes providers as an empty map

Success output

On first run:

{
  "status": "created",
  "path": "bridge.yaml",
  "name": "my-project"
}

If the file already exists, Bridge does not overwrite it:

{
  "status": "already_exists",
  "path": "bridge.yaml"
}

Typical use

mkdir my-agent-project
cd my-agent-project
bridge init

`bridge connect`

Add a named provider connection to bridge.yaml.

Usage

bridge connect <target> --as <NAME> [--type <provider>]

<target> can be:

a literal URI such as file://./docs or postgres://localhost:5432/mydb
a bare environment variable name such as DATABASE_URL

Examples

bridge connect file://./docs --as files
bridge connect postgres://localhost:5432/mydb --as db
bridge connect DATABASE_URL --type postgres --as db

What it does

loads the current bridge.yaml
interprets <target> as either a literal URI or an environment variable name
infers the provider type from a literal URI scheme when possible
inserts the provider under the given name
saves the updated config back to disk

If a provider with the same name already exists, Bridge overwrites it with the new value. When <target> is an environment variable name, bridge connect writes it into bridge.yaml as ${TARGET} and requires --type <provider>. bridge connect validates the target format and supported provider type, but it does not verify that the backend is reachable before writing the config. The actual connection check happens later when you run bridge status, bridge ls, or bridge read.

Success output

{
  "status": "connected",
  "name": "files",
  "type": "filesystem",
  "uri": "file://./docs"
}

Supported URI schemes

Current built-in inference supports:

file://... → filesystem
postgres://... → postgres
postgresql://... → postgres

Unsupported or malformed URIs fail with invalid_uri.

Environment-variable targets

When you pass a bare environment variable name such as DATABASE_URL, Bridge:

requires --type
stores uri: ${DATABASE_URL} in bridge.yaml
resolves the actual value later from the process environment when you run status, ls, or read

Bridge does not automatically load a .env file.

Common failure cases

bridge.yaml is missing
<target> is neither a supported URI nor a valid environment variable name
--type is missing for an environment-variable target
an environment variable referenced by bridge.yaml is not set later at runtime

`bridge remove`

Remove a named provider connection from bridge.yaml.

Usage

bridge remove <NAME>

Example

bridge remove files

Success output

{
  "status": "removed",
  "name": "files"
}

Failure behavior

If the provider name does not exist, Bridge returns a provider_not_found error and includes the currently available provider names.

`bridge status`

Check the health of all configured providers.

Usage

bridge status

What it does

For each provider in bridge.yaml, Bridge:

expands environment variables in the URI
creates the provider
connects to it
runs that provider’s health check

Success output

{
  "providers": {
    "files": {
      "connected": true,
      "latency_ms": 0,
      "message": "Directory: /path/to/docs"
    },
    "db": {
      "connected": true,
      "latency_ms": 12,
      "message": "Connected to postgres://user:***@localhost:5432/mydb"
    }
  }
}

Notes

the filesystem provider reports a directory status
the Postgres provider runs a lightweight health query
URIs are redacted in status messages so passwords are not exposed
provider status is reported per entry, so one broken provider does not stop Bridge from checking the others

`bridge ls`

List entries from a provider.

Usage

bridge ls --from <NAME>

Examples

bridge ls --from files
bridge ls --from db

Success output

Filesystem example:

[
  { "name": "README.md", "path": "README.md", "entry_type": "file" },
  { "name": "nested", "path": "nested", "entry_type": "directory" }
]

Postgres example:

[
  { "name": "users", "path": "users", "entry_type": "table" },
  { "name": "orders", "path": "orders", "entry_type": "table" }
]

Important runtime note

The current --help text says --from is optional, but the current implementation still requires it. If you omit --from, Bridge returns a provider error asking you to specify a provider name.

Typical use

Use ls to discover valid paths before you call read.

Common failure cases

config_not_found if there is no bridge.yaml in the current directory
provider_not_found if --from names a provider that is not configured
provider_error if the backend cannot connect or the configured root is invalid
timeout if the provider does not respond before the configured timeout

`bridge read`

Read structured context from a provider.

Usage

bridge read <PATH> --from <NAME> [--limit <N>]

Examples

Filesystem:

bridge read README.md --from files
bridge read nested/deep.txt --from files

Postgres:

bridge read users --from db
bridge read users/42 --from db
bridge read users --from db --limit 25

Output

read always returns a structured ContextValue object with:

data
metadata

Example:

{
  "data": {
    "type": "text",
    "content": "# Hello\n\nFile contents here."
  },
  "metadata": {
    "source": "filesystem",
    "path": "README.md",
    "content_type": "text/markdown"
  }
}

Current path shapes

The meaning of <PATH> depends on the provider:

Provider	Path shape	Example
`filesystem`	relative file path under the provider root	`README.md`
`postgres`	table name	`users`
`postgres`	table plus primary key	`users/42`

`--limit`

--limit is relevant for database-backed reads that return multiple rows.

default: 100
applies to whole-table Postgres reads
if omitted, Bridge falls back to 100

Path semantics depend on the provider

Filesystem paths are file paths under the provider root
Postgres paths are either table or table/primary_key

For the provider-specific behavior of read, see Providers.

Common failure cases

provider_not_found if the provider name passed to --from is not configured
path_traversal if a filesystem read escapes the provider root
provider_error if the file, table, or row does not exist
timeout if the provider does not finish the read before the timeout

`bridge completions`

Generate shell completion scripts for supported shells.

Usage

bridge completions <SHELL>

Supported shells today:

bash
elvish
fish
powershell
zsh

Examples

bridge completions zsh
bridge completions fish
bridge completions powershell

What it outputs

bridge completions writes the completion script text to stdout. You can then save or source that output using your shell’s normal setup flow. Unlike provider commands, completions does not need bridge.yaml and does not talk to any backend. See Installation for the current installer behavior, completion file locations, and manual setup examples for each shell.

Common error codes

The most useful error codes to know when scripting Bridge are:

config_not_found
invalid_uri
env_var_not_set
provider_not_found
provider_error
timeout
path_traversal
invalid_identifier

See Security and errors for the full failure model, timeout behavior, and current safety guardrails.

Choosing the right command

Use init once per project
Use connect when adding or updating a backend
Use remove when cleaning up provider aliases
Use status when debugging connectivity
Use ls when discovering valid paths
Use read when you want the actual context payload
Use completions when improving your shell workflow

Installation

See install methods, PATH behavior, and how the official installers set up completions.

Configuration

Learn how bridge.yaml is structured and how commands resolve provider names.

Providers

See what filesystem and postgres actually return for ls, read, and status.

Security and errors

Understand timeout handling, error codes, secret redaction, and Bridge’s current guardrails.

CLI interface

See the higher-level JSON contract that sits behind these commands.

CLI interface

Configuration

Providers

Security and errors

​Command map

​Command conventions

​Global options

​Typical workflow

​bridge init

​Usage

​What it does

​Success output

​Typical use

​bridge connect

​Usage

​Examples

​What it does

​Success output

​Supported URI schemes

​Environment-variable targets

​Common failure cases

​bridge remove

​Usage

​Example

​Success output

​Failure behavior

​bridge status

​Usage

​What it does

​Success output

​Notes

​bridge ls

​Usage

​Examples

​Success output

​Important runtime note

​Typical use

​Common failure cases

​bridge read

​Usage

​Examples

​Output

​Current path shapes

​--limit

​Path semantics depend on the provider

​Common failure cases

​bridge completions

​Usage

​Examples

​What it outputs

​Common error codes

​Choosing the right command

​Related pages

Installation

Configuration

Providers

Security and errors

CLI interface

Command map

Command conventions

Global options

Typical workflow

`bridge init`

Usage

What it does

Success output

Typical use

`bridge connect`

Usage

Examples

What it does

Success output

Supported URI schemes

Environment-variable targets

Common failure cases

`bridge remove`

Usage

Example

Success output

Failure behavior

`bridge status`

Usage

What it does

Success output

Notes

`bridge ls`

Usage

Examples

Success output

Important runtime note

Typical use

Common failure cases

`bridge read`

Usage

Examples

Output

Current path shapes

`--limit`

Path semantics depend on the provider

Common failure cases

`bridge completions`

Usage

Examples

What it outputs

Common error codes

Choosing the right command

Related pages