CLI commands

mq-bridge-app is a single headless binary with three modes: config mode (the default — run a long-lived bridge, optionally serving the browser UI), the copy subcommand (an ad-hoc one-route job), and the mcp subcommand (expose the bridge as MCP tools).

mq-bridge-app [OPTIONS]            # config mode
mq-bridge-app copy [COPY OPTIONS]  # one-route ad-hoc job
mq-bridge-app mcp  [MCP OPTIONS]   # MCP server

Config mode (default)

Run with no subcommand to load a config and run a bridge; with no config at all it starts empty and serves the UI so you can build one interactively.

mq-bridge-app --config config.yml
mq-bridge-app --config config.yml --init-config dev/config/file-to-http.yml
mq-bridge-app                      # start empty, define config.yml in the UI

Config is hierarchical (files + environment variables) — see Configuration grammar. In config mode the CLI also serves the browser UI (the same UI as the desktop app) on the configured port.

copy — ad-hoc one-route job

Builds a single route from two endpoint URIs and runs it headlessly (no web UI). The scheme selects the endpoint and query parameters set its config.

# DB → DB, drain the source table then exit (exit code 0 on success)
mq-bridge-app copy \
  --from 'postgres://user:pass@localhost/db?table=src' \
  --to   'postgres://user:pass@localhost/db?table=dst' \
  --drain

# Queue → DB as a continuous bridge (runs until Ctrl-C; omit --drain)
mq-bridge-app copy \
  --from 'nats://localhost:4222?subject=orders' \
  --to   'postgres://user:pass@localhost/db?table=orders'

Note: copy’s defaults (--concurrency 4, --batch-size 1024) are higher than the library’s route defaults (concurrency: 1, batch_size: 1), because copy is built for bulk throughput. See Performance tuning.

URI grammar

scheme://…?param=a&next=b: the scheme selects the endpoint and query parameters set its config. Any query key that matches a field of that endpoint’s config becomes endpoint config; every other query param stays on the connection URL, so driver params pass through unchanged (e.g. postgres://…/db?table=src&sslmode=disable).

• Schemes: postgres / postgresql / mysql / mariadb / sqlite → sqlx, nats → NATS, mongodb → MongoDB, redis → Redis streams, file → file, and the rest by name.
• Common config params: table, insert_query (URL-encoded; supports ${metadata:<key>} / ${payload:<field>} token mapping), delete_after_read, subject, stream, collection, database, format, … — anything on the endpoint’s config struct.
• For nats, the dominant target field can be given as the URL path (nats://localhost:4222/orders ≡ ?subject=orders); the query form wins if both are given. A redis path is the connection’s database number, so a redis stream target must use ?stream=….
• MongoDB sources are non-destructive by default: copy defaults consume to capture_all. Pass ?consume=consumer to opt into the destructive queue-drain mode (capture_* use change streams, which require a replica set).

Middlewares in the URI

Append |-separated middlewares to either URI to wrap that endpoint. They apply in the order written, and each takes its own config struct’s fields as query params:

mq-bridge-app copy \
  --from 'postgres://user:pass@localhost/db?table=src|retry?max_attempts=5&initial_interval_ms=200' \
  --to   'kafka://broker:9092?topic=orders|buffer?max_messages=500&max_delay_ms=50|metrics' \
  --drain

• Names: retry, metrics, dlq, deduplication, delay, limiter, buffer, weak_join, cookie_jar, random_panic, custom (- is accepted for _).
• A middleware with no params needs no ? — |metrics.
• dlq’s endpoint is itself a URL-encoded endpoint URI: |dlq?endpoint=file%3A%2F%2F%2Ftmp%2Ffailed.jsonl.
• Object/array fields take a JSON literal: |weak-join?group_by=cid&expected_count=2&timeout_ms=1000&required=["a","b"].
• A literal | inside the URI (e.g. in a password) must be written percent-encoded as %7C.

Escape hatch: full connection strings

Any query parameter that isn’t a recognised config field (e.g. sslmode, replicaSet) stays on the connection URL, so driver options just work — including object-typed fields like tls. If you already have a complete connection string, pass it verbatim with ?url=<url-encoded>:

mq-bridge-app copy \
  --from 'mongodb://_/?url=mongodb%3A%2F%2Fuser%3Apass%40host%2Fdb%3Ftls%3Dtrue&collection=orders' \
  --to null:

See the Quick start for complete, working copy commands.

mcp — MCP server

mq-bridge-app mcp                                    # stdio (local clients)
mq-bridge-app mcp --transport http --bind 127.0.0.1:9092   # streamable HTTP

mcp install / uninstall / status

Register the running binary with local MCP clients so you don’t write the config by hand:

mq-bridge-app mcp install                         # every detected client
mq-bridge-app mcp install --client cursor --local  # one client, project-scoped
mq-bridge-app mcp install --report-to-ui           # bake --report-to-ui into the entry
mq-bridge-app mcp status
mq-bridge-app mcp uninstall

--print-config prints the JSON snippet for a client not written directly. Full tool and message reference is in MCP server.