Commands

​

Command map

​

Command conventions

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

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

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

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

​

Global options

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

• bridge --help
• bridge --version

​

Typical workflow

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

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

bridge connect sqlite://./local.db?mode=rwc --as localdb
bridge status
bridge ls --from localdb
bridge read users --from localdb --limit 25

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

​

bridge init

​

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

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

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

​

Typical use

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

​

bridge connect

​

Usage

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

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

​

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 DATABASE_URL --type postgres --as db
bridge connect SQLITE_DATABASE_URL --type sqlite --as localdb
bridge connect DATABASE_URL --type postgres --as db --force
bridge connect postgres://localhost:5432/mydb --as db --no-verify

​

Flags

• --type <provider> is required when <target> is an environment variable name
• --force replaces an existing provider with the same name
• --no-verify saves the provider without checking connectivity first

​

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
• refuses to overwrite an existing provider name unless you pass --force
• verifies the provider connection and health by default
• saves the updated config back to disk after successful verification

​

Success output

{
  "latency_ms": 3,
  "name": "db",
  "status": "connected",
  "type": "postgres",
  "uri": "${DATABASE_URL}",
  "verified": true
}

{
  "message": "Verification skipped (--no-verify).",
  "name": "db",
  "status": "saved_unverified",
  "type": "postgres",
  "uri": "postgres://localhost:5432/mydb",
  "verified": false
}

​

Supported URI schemes

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

​

Environment-variable targets

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

​

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
• a provider with the same name already exists and you did not pass --force
• the backend cannot be reached or fails its health check during verification
• an environment variable referenced by bridge.yaml is not set later at runtime

​

bridge remove

​

Usage

bridge remove <NAME>

​

Example

bridge remove files

​

Success output

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

​

Failure behavior

​

bridge status

​

Usage

bridge status

​

What it does

1. expands environment variables in the URI
2. creates the provider
3. connects to it
4. runs that provider’s health check

​

Success output

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

​

Notes

• the filesystem provider reports a directory status
• the SQLite provider runs a lightweight health query
• 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

​

Usage

bridge ls --from <NAME>

​

Examples

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

​

Success output

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

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

​

Important runtime note

​

Typical use

​

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

​

Usage

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

​

Examples

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

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

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

​

Output

• data
• metadata

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

​

Current path shapes

​

--limit

• default: 100
• applies to whole-table Postgres and SQLite reads
• is ignored for single-row Postgres and SQLite reads
• if omitted, Bridge falls back to 100

​

Path semantics depend on the provider

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

​

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 generate mcp

​

Usage

bridge generate mcp --from openapi <SPEC> --name <NAME> --out <FILE> [options]
bridge generate mcp --from db --connection <NAME> --name <NAME> --out <FILE> [options]

​

Flags

​

What it does

​

Success output

{
  "status": "generated",
  "manifest": "my-api.mcp.yaml",
  "name": "my-api",
  "tools": ["list_users", "get_user_by_id"],
  "skipped": [],
  "client_snippet": {
    "mcpServers": {
      "my-api": {
        "command": "/usr/local/bin/bridge",
        "args": ["mcp", "serve", "/absolute/path/to/my-api.mcp.yaml"]
      }
    }
  }
}

​

Examples

# From an OpenAPI spec with auth
bridge generate mcp \
  --from openapi ./openapi.yaml \
  --name petstore \
  --base-url-env PETSTORE_URL \
  --bearer-env PETSTORE_TOKEN \
  --out petstore.mcp.yaml

# From a Postgres or SQLite connection
bridge generate mcp \
  --from db \
  --connection db \
  --name myapp-db \
  --out myapp-db.mcp.yaml

# From a non-default schema, overwriting an existing manifest
bridge generate mcp \
  --from db \
  --connection db \
  --schema analytics \
  --name analytics \
  --out analytics.mcp.yaml \
  --force

​

Limitations

• Only GET operations are supported from OpenAPI specs
• Only Postgres and SQLite are supported as database sources
• bridge.yaml must exist and the named connection must be reachable when using --from db

​

bridge mcp serve

​

Usage

bridge mcp serve <MANIFEST>

​

What it does

• reads and validates the manifest at the given path
• resolves any environment variables referenced in the manifest
• starts a JSON-RPC 2.0 MCP server on stdin/stdout
• handles tools/list and tools/call requests from MCP clients
• for OpenAPI-backed tools: forwards calls as HTTP requests to the backend API
• for database-backed tools: executes parameterized SQL SELECTs against the configured database provider

​

Example

bridge mcp serve ./petstore.mcp.yaml

​

Configuration

​

Wiring into Claude Desktop

{
  "mcpServers": {
    "petstore": {
      "command": "/usr/local/bin/bridge",
      "args": ["mcp", "serve", "/absolute/path/to/petstore.mcp.yaml"]
    }
  }
}

​

bridge mcp serve-http

​

Usage

bridge mcp serve-http <MANIFEST> [options]

​

Flags

​

Endpoints

​

CORS and origin policy

​

Examples

# Default: bind to localhost:8080
bridge mcp serve-http ./petstore.mcp.yaml

# Bind on all interfaces, port 9000
bridge mcp serve-http ./petstore.mcp.yaml --bind 0.0.0.0:9000

# With public URL and a browser-friendly origin
bridge mcp serve-http ./petstore.mcp.yaml \
  --bind 0.0.0.0:9000 \
  --public-url https://mcp.example.com \
  --allow-origin https://app.example.com

​

Graceful shutdown

​

bridge update

​

Usage

bridge update [--check]

​

Flags

​

What it does

​

Example

# Install the latest version
bridge update

# Just check — don't install
bridge update --check

​

bridge completions

​

Usage

bridge completions <SHELL>

• bash
• elvish
• fish
• powershell
• zsh

​

Examples

bridge completions zsh
bridge completions fish
bridge completions powershell

​

What it outputs

​

Common error codes

• config_not_found
• invalid_uri
• env_var_not_set
• provider_not_found
• provider_error
• timeout
• path_traversal
• invalid_identifier

​

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 generate mcp when you want to expose a backend as an MCP server
• Use mcp serve to run an MCP server locally for Claude Desktop or Cursor
• Use mcp serve-http to run an MCP server over HTTP for remote clients
• Use update to keep the CLI current
• Use completions when improving your shell workflow

​

Related pages