Bridge Docs — One CLI for all your agent context

bridge.yaml is the project-local configuration file for Bridge. It tells the CLI what your project is called and which named providers an agent can read from. Bridge keeps the config intentionally small:

one file
one project name
one map of named providers

Where Bridge looks for configuration

Bridge reads bridge.yaml from the current working directory. That means:

bridge init creates bridge.yaml in the directory where you run it
bridge read, bridge ls, bridge status, and bridge connect expect the file to exist in the current directory
Bridge does not currently search parent directories for a config file

If bridge.yaml is missing, Bridge returns config_not_found and tells you to run bridge init.

Minimal configuration

Running bridge init creates a minimal config like this:

version: "1"
name: my-project
providers: {}

bridge init uses the current directory name as the default project name. If bridge.yaml already exists, the command does not overwrite it.

A real example

Most projects will start with one local provider and one database provider:

version: "1"
name: my-agent-project
providers:
  files:
    type: filesystem
    uri: file://./docs
  localdb:
    type: sqlite
    uri: sqlite://./local.db?mode=rwc
  db:
    type: postgres
    uri: ${DATABASE_URL}

In this example:

files is a filesystem provider rooted at ./docs
localdb is a SQLite provider backed by a local file and allowed to create it on first use
db is a Postgres provider whose connection string comes from an environment variable

Top-level fields

Field	Type	Required	What it does
`version`	string	yes	Configuration format version. Bridge currently writes `"1"`.
`name`	string	yes	Project name. `bridge init` defaults this to the current directory name.
`providers`	map	yes	Named provider definitions keyed by provider alias such as `files` or `db`.

Provider entries

Each entry under providers is keyed by the name you want agents and humans to use at the command line.

providers:
  files:
    type: filesystem
    uri: file://./docs

The provider name:

is chosen by you
is what you pass to --from
should be short and memorable

Each provider object currently supports these fields:

Field	Type	Required	What it does
`type`	string	yes	Provider type such as `filesystem`, `sqlite`, or `postgres`
`uri`	string	yes	Connection target for that provider

For provider-specific behavior and limitations, see Providers.

Supported provider types today

Bridge currently recognizes these provider types:

Type	Accepted URI forms	Notes
`filesystem`	`file://./path`, `file:///absolute/path`	Must point to an existing directory
`sqlite`	`sqlite://./local.db`, `sqlite:///absolute/path.db`, `sqlite://:memory:`	Used for listing tables and reading rows from a local SQLite database
`postgres`	`postgres://...`, `postgresql://...`	Used for listing tables and reading rows

If you use bridge connect with a literal URI, Bridge infers the type from the URI scheme automatically. Examples:

bridge connect file://./docs --as files
bridge connect sqlite://./local.db?mode=rwc --as localdb
bridge connect postgres://localhost:5432/mydb --as db
bridge connect postgresql://localhost:5432/mydb --as db

If you use bridge connect with an environment variable name, Bridge requires --type and writes the placeholder into bridge.yaml for you:

bridge connect DATABASE_URL --type postgres --as db
bridge connect SQLITE_DATABASE_URL --type sqlite --as localdb

By default, bridge connect also verifies the provider before it saves the config. Use --no-verify if you want to keep a provider definition before the backend is reachable, and use --force if you want to replace an existing provider name.

Filesystem URIs

Filesystem providers use file:// URIs.

Relative paths

providers:
  files:
    type: filesystem
    uri: file://./docs

Relative paths are resolved from the current directory when Bridge connects the provider. In normal usage, that means they are relative to the project root where your bridge.yaml lives.

Absolute paths

providers:
  files:
    type: filesystem
    uri: file:///Users/alice/project/docs

Bridge expects a filesystem provider to point to an existing directory. If the path does not exist, or if it points to a file instead of a directory, connection will fail.

Postgres URIs

Postgres providers use standard connection strings:

providers:
  db:
    type: postgres
    uri: postgres://localhost:5432/mydb

Or:

providers:
  db:
    type: postgres
    uri: postgresql://localhost:5432/mydb

For local development, it is usually better to keep credentials out of the file and load them from the environment:

providers:
  db:
    type: postgres
    uri: ${DATABASE_URL}

You can write that shape manually, or ask Bridge to generate it with:

bridge connect DATABASE_URL --type postgres --as db

SQLite URIs

SQLite providers use sqlite:// URIs.

Relative paths

providers:
  localdb:
    type: sqlite
    uri: sqlite://./local.db

Absolute paths

providers:
  localdb:
    type: sqlite
    uri: sqlite:///Users/alice/project/local.db

Modes

providers:
  localdb:
    type: sqlite
    uri: sqlite://./local.db?mode=ro

Common patterns:

use ?mode=ro to open an existing database in read-only mode
use ?mode=rwc to allow SQLite to create the database file on first connection
use sqlite://:memory: for an in-memory database

Unless you use a creation or memory mode, the database file must already exist when Bridge connects the provider.

Environment variable expansion

Bridge expands environment variables inside strings using the exact ${VAR_NAME} syntax. Bridge writes that ${VAR_NAME} form automatically when you connect with a bare env var name such as DATABASE_URL. Example:

providers:
  db:
    type: postgres
    uri: postgres://${PGHOST}:${PGPORT}/mydb

This supports:

a single variable in a full string like ${DATABASE_URL}
multiple variables inside one URI

If a referenced variable is not set, runtime commands such as bridge status, bridge ls, and bridge read fail with env_var_not_set. bridge connect is slightly different: when it cannot verify because a required variable is missing in your current shell, it saves the placeholder and marks the provider as unverified.

Use environment variables for secrets and credentials. Keep bridge.yaml safe to commit by avoiding raw passwords in the file when possible.

How Bridge updates the file

`bridge init`

creates bridge.yaml if it does not exist
uses the current directory name as name
initializes providers as an empty map
returns "already_exists" instead of overwriting an existing file

`bridge connect`

loads the existing config
accepts either a literal URI or a bare environment variable name as <target>
infers the provider type from a literal URI scheme when possible
requires --type when <target> is an environment variable name
refuses to overwrite an existing provider name unless you pass --force
verifies the target by default before saving
writes the updated bridge.yaml back to disk after successful verification
can save an unverified provider if you pass --no-verify, or if a placeholder variable is not set in the current shell during verification

If you connect the same name twice, Bridge returns provider_already_exists unless you pass --force.

`bridge remove`

deletes the named provider from providers
writes the updated file back to disk

Common mistakes

Missing config file

If you run a Bridge command in a directory without bridge.yaml, Bridge returns config_not_found. Run bridge init first, or change into the project directory that already contains the config file.

Invalid or unsupported URI

Bridge currently understands file://, sqlite://, postgres://, and postgresql:// schemes. A value like redis://localhost will fail with invalid_uri.

Invalid connect target

A bridge connect target must be either a full URI such as postgres://localhost:5432/mydb or a bare environment variable name such as DATABASE_URL. Placeholder syntax like ${DATABASE_URL} is for bridge.yaml, not for the CLI input.

Missing environment variable

If your config references ${DATABASE_URL} and that variable is not set, runtime commands fail fast with env_var_not_set rather than guessing or continuing with a partial value. During bridge connect, Bridge can still save the placeholder as unverified if it cannot verify in the current shell.

Duplicate provider name

If you try to connect db twice, Bridge now returns provider_already_exists instead of silently replacing the existing provider. Re-run with --force when you intend to overwrite it.

Filesystem path points to the wrong thing

A filesystem provider must point to an existing directory. If the directory does not exist, bridge connect fails verification unless you pass --no-verify. If the path resolves outside the configured root during reads, Bridge returns a provider error.

Configuration philosophy

Bridge keeps configuration intentionally narrow:

one project-local file
explicit named providers
URI-based backend selection
environment variables for secrets

The goal is to keep agent integrations stable even when your storage setup changes. A provider can move from one URI to another without changing the command shape the agent uses.

Next steps

Providers

Learn exactly how each provider behaves at runtime.

Quickstart

Start with the minimal Bridge workflow and connect your first provider.

CLI interface

See how Bridge turns configuration into structured JSON commands and output.

​Where Bridge looks for configuration

​Minimal configuration

​A real example

​Top-level fields

​Provider entries

​Supported provider types today

​Filesystem URIs

​Relative paths

​Absolute paths

​Postgres URIs

​SQLite URIs

​Relative paths

​Absolute paths

​Modes

​Environment variable expansion

​How Bridge updates the file

​bridge init

​bridge connect

​bridge remove

​Common mistakes

​Configuration philosophy

​Next steps

Providers

Quickstart

CLI interface

Where Bridge looks for configuration

Minimal configuration

A real example

Top-level fields

Provider entries

Supported provider types today

Filesystem URIs

Relative paths

Absolute paths

Postgres URIs

SQLite URIs

Relative paths

Absolute paths

Modes

Environment variable expansion

How Bridge updates the file

`bridge init`

`bridge connect`

`bridge remove`

Common mistakes

Configuration philosophy

Next steps