> ## Documentation Index
> Fetch the complete documentation index at: https://dbhub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-Line Options

DBHub connects to your database in one of two ways:

* **A DSN** — one connection string for a single database.
* **A [TOML file](/config/toml)** — passed with `--config`, for one or more databases plus per-source and per-tool settings.

Choose one. A TOML file defines its sources itself, so `--config` and `--dsn` cannot be combined.

Environment variables are a different matter: `DSN` and `DB_*` stay available to a TOML file through [`${VAR}` interpolation](/config/toml#environment-variable-interpolation), which is the recommended way to keep credentials out of the file.

When you use a DSN, DBHub takes it from the first of:

1. `--dsn` flag
2. `DSN` environment variable
3. `DB_*` environment variables
4. `.env` file (`.env.local` in development, `.env` in production)

Every other option — transport, port, host, and so on — is set by flag or environment variable, in the same order:

1. Command-line flag
2. Environment variable
3. `.env` file
4. Built-in default

This page covers command-line flags and environment variables. For TOML configuration, see [TOML Configuration](/config/toml).

### --transport

<ParamField path="--transport" type="string" env="TRANSPORT" default="stdio">
  Transport protocol for [MCP communication](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports). Env: `TRANSPORT`.

  **Options:**

  * `stdio` - For desktop tools (Claude Desktop, Claude Code, Cursor). Pure MCP-over-stdio with no HTTP server.
  * `http` - For browser and network clients. Starts HTTP server with MCP endpoint, workbench, and API.

  Both transports serve the stateless **2026-07-28** MCP protocol revision natively and fall back to the 2025-era protocol for older clients on the same endpoint — no configuration needed. On `http`, 2026-era clients send the standard `Mcp-Method` / `Mcp-Name` headers with every request, so a fronting gateway or WAF can route and rate-limit individual tools without parsing request bodies.

  | Feature            |       `stdio`       |          `http`          |
  | ------------------ | :-----------------: | :----------------------: |
  | MCP communication  |     stdin/stdout    |     HTTP POST `/mcp`     |
  | Workbench          |          ❌          |   ✅ `http://host:port/`  |
  | Health check       |          ❌          |       ✅ `/healthz`       |
  | API                |          ❌          |       ✅ `/api/xxx`       |
  | Multiple instances | ✅ No port conflicts | Requires different ports |

  ```bash theme={null}
  # stdio (default) - for Claude Desktop, Claude Code, Cursor
  # No HTTP server started
  npx @bytebase/dbhub@latest --transport stdio --dsn "..."

  # http - for web clients, workbench, and remote access
  npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "..."
  ```
</ParamField>

### --port

<ParamField path="--port" type="number" env="PORT" default="8080">
  HTTP server port. Only used when `--transport=http`. Ignored for stdio transport. Env: `PORT`.

  ```bash theme={null}
  npx @bytebase/dbhub@latest --transport http --port 3000 --dsn "..."
  ```
</ParamField>

### --host

<ParamField path="--host" type="string" env="DBHUB_HOST" default="0.0.0.0">
  HTTP bind address. Only used when `--transport=http`. Ignored for stdio transport. Env: `DBHUB_HOST`.

  ```bash theme={null}
  # Restrict to loopback (recommended for production)
  npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --dsn "..."

  # Bind to a specific interface
  npx @bytebase/dbhub@latest --transport http --host 10.0.0.5 --port 8080 --dsn "..."

  # IPv6 loopback
  npx @bytebase/dbhub@latest --transport http --host ::1 --port 8080 --dsn "..."
  ```

  <Warning>
    The default `0.0.0.0` exposes DBHub on every network interface. For production, set `--host 127.0.0.1` and place DBHub behind a reverse proxy (nginx/Caddy) or restrict with a firewall, or configure `--auth-token` (see below) to require a bearer token on every request.
  </Warning>
</ParamField>

### --allowed-hosts

<ParamField path="--allowed-hosts" type="string" env="DBHUB_ALLOWED_HOSTS" default="(loopback + this machine)">
  Comma-separated list of additional hostnames the HTTP transport accepts in the
  `Host` (and `Origin`) headers. This is DBHub's **DNS-rebinding protection**:
  requests whose `Host` is not on the list are rejected with `403`, so a
  malicious web page cannot rebind a hostname to your DBHub instance and drive
  its MCP tools from the victim's browser. Only used when `--transport=http`. Env: `DBHUB_ALLOWED_HOSTS`.

  The list always includes loopback (`localhost`, `127.0.0.1`, `[::1]`). When
  bound to a wildcard address (the default `0.0.0.0` / `::`), this machine's own
  hostname and external IP addresses are added automatically, so reaching DBHub
  by IP or machine name works without any extra configuration. You only need
  this flag for **other** names that resolve to DBHub — most commonly a
  reverse-proxy or public DNS name.

  ```bash theme={null}
  # Serve behind a public/reverse-proxy hostname
  npx @bytebase/dbhub@latest --transport http --allowed-hosts "dbhub.example.com" --dsn "..."

  # Multiple hostnames
  npx @bytebase/dbhub@latest --transport http --allowed-hosts "dbhub.example.com,db.internal" --dsn "..."

  # Disable the check entirely (only when fronted by your own auth/proxy)
  npx @bytebase/dbhub@latest --transport http --allowed-hosts "*" --dsn "..."
  ```

  <Note>
    A port in an entry is ignored — only the hostname is matched. IPv6 literals
    must be bracketed, e.g. `[2001:db8::1]`. The active allow-list is printed at
    startup. If a legitimate client gets a `403` "Host ... is not allowed", add
    its hostname here.
  </Note>

  <Warning>
    `--allowed-hosts "*"` turns off DNS-rebinding protection. Use it only when
    DBHub sits behind your own authentication and/or proxy.
  </Warning>
</ParamField>

### --auth-token

<ParamField path="--auth-token" type="string" env="DBHUB_AUTH_TOKEN">
  Comma-separated list of bearer tokens required on every HTTP request. Only used when `--transport=http`. Unset by default — auth is off unless you configure this. Env: `DBHUB_AUTH_TOKEN`.

  Clients must send a matching token as `Authorization: Bearer <token>`; requests without one get `401 Unauthorized` with a `WWW-Authenticate: Bearer` header. `/healthz` is exempt so uptime monitors don't need a token.

  ```bash theme={null}
  # Single token
  npx @bytebase/dbhub@latest --transport http --auth-token "s3cr3t-token" --dsn "..."

  # Multiple tokens (rotate without downtime, or issue one per client)
  npx @bytebase/dbhub@latest --transport http --auth-token "token-for-ci,token-for-agent" --dsn "..."
  ```

  Client request (`/api/sources` is a plain `GET`; the MCP endpoint itself
  requires a JSON-RPC POST body, so it's not a copy-pasteable example):

  ```bash theme={null}
  curl -H "Authorization: Bearer s3cr3t-token" http://localhost:8080/api/sources
  ```

  <Note>
    Configuring a token *is* the opt-in — there's no separate "require auth" flag to remember. A comma-separated list lets you rotate a leaked or expiring token by adding the new one, redeploying, and then removing the old one, and lets you hand different tokens to different clients so one can be revoked without affecting the others.
  </Note>

  <Warning>
    This is a flat shared-secret check, not OAuth — it answers "does this request have the secret," not "who is this user" (no per-user scopes or audit trail). If you need real identity-based authorization, front DBHub with your own OAuth-aware proxy or IdP-integrated gateway instead.
  </Warning>
</ParamField>

### --dsn

<ParamField path="--dsn" type="string" env="DSN">
  Database connection string (Data Source Name). Format: `database_type://username:password@host:port/database_name?options`. Env: `DSN` (see the resolution order at the top of this page).

  <Tabs>
    <Tab title="PostgreSQL">
      ```bash theme={null}
      # Format: postgres://[user]:[password]@[host]:[port]/[database]?[options]
      postgres://myuser:mypassword@localhost:5432/mydb
      ```
    </Tab>

    <Tab title="MySQL">
      ```bash theme={null}
      # Format: mysql://[user]:[password]@[host]:[port]/[database]?[options]
      mysql://root:password@localhost:3306/mydb
      ```
    </Tab>

    <Tab title="MariaDB">
      ```bash theme={null}
      # Format: mariadb://[user]:[password]@[host]:[port]/[database]?[options]
      mariadb://root:password@localhost:3306/mydb
      ```
    </Tab>

    <Tab title="SQL Server">
      ```bash theme={null}
      # Format: sqlserver://[user]:[password]@[host]:[port]/[database]?[options]
      sqlserver://sa:YourPassword123@localhost:1433/mydb

      # Named instance (e.g., ENV1, ENV2, ENV3)
      sqlserver://sa:YourPassword123@localhost:1433/mydb?instanceName=ENV1

      # Windows/NTLM authentication
      sqlserver://jsmith:secret@sqlserver.corp.local:1433/mydb?authentication=ntlm&domain=CORP

      # Azure AD authentication (password optional/empty)
      sqlserver://username@localhost:1433/mydb?authentication=azure-active-directory-access-token
      ```

      <Note>
        Integrated security (a trusted connection using the logged-in
        Windows user, with no username/password in the DSN) is **not
        supported**. DBHub uses the pure-JS `tedious` driver, which has no
        SSPI/Kerberos support. Note that `authentication=ntlm` still
        requires an explicit username and password in the DSN, so it is not
        a trusted connection. Use SQL authentication or, for Azure SQL,
        Azure AD instead.
      </Note>
    </Tab>

    <Tab title="SQLite">
      ```bash theme={null}
      # Format: sqlite:///[path/to/database.db] or sqlite:///:memory:

      # Unix/Linux/macOS
      sqlite:///var/lib/data/mydb.db

      # Windows
      sqlite:///C:/Users/YourName/data/database.db

      # In-memory
      sqlite:///:memory:
      ```
    </Tab>
  </Tabs>

  **DSN Query Parameters:**

  | Parameter        | Databases                              | Description                                                 | Example                      |
  | ---------------- | -------------------------------------- | ----------------------------------------------------------- | ---------------------------- |
  | `sslmode`        | PostgreSQL, MySQL, MariaDB, SQL Server | SSL mode: `disable`, `require`, `verify-ca`, `verify-full`  | `?sslmode=require`           |
  | `sslrootcert`    | PostgreSQL                             | CA certificate path (requires `verify-ca` or `verify-full`) | `?sslrootcert=~/.ssl/ca.pem` |
  | `instanceName`   | SQL Server                             | Named instance                                              | `?instanceName=SQLEXPRESS`   |
  | `authentication` | SQL Server                             | Auth method: `ntlm`, `azure-active-directory-access-token`  | `?authentication=ntlm`       |
  | `domain`         | SQL Server                             | Windows domain (with `authentication=ntlm`)                 | `?domain=CORP`               |

  **SSL/TLS Options:**

  | Database   | `disable` | `require` | `verify-ca` | `verify-full` |          Default         |
  | ---------- | :-------: | :-------: | :---------: | :-----------: | :----------------------: |
  | PostgreSQL |     ✅     |     ✅     |      ✅      |       ✅       | Certificate verification |
  | MySQL      |     ✅     |     ✅     |      ❌      |       ❌       | Certificate verification |
  | MariaDB    |     ✅     |     ✅     |      ❌      |       ❌       | Certificate verification |
  | SQL Server |     ✅     |     ✅     |      ❌      |       ❌       | Certificate verification |
  | SQLite     |     ❌     |     ❌     |      ❌      |       ❌       |     N/A (file-based)     |

  * `sslmode=disable`: All SSL/TLS encryption is turned off. Data is transmitted in plaintext.
  * `sslmode=require`: Connection is encrypted, but the server's certificate is not verified.
  * `sslmode=verify-ca`: SSL with CA certificate verification, but no hostname check. **PostgreSQL only.** Use `sslrootcert` to specify the CA certificate path.
  * `sslmode=verify-full`: SSL with CA certificate and hostname verification. **PostgreSQL only.** Use `sslrootcert` to specify the CA certificate path.

  ```bash theme={null}
  # Examples
  postgres://user:password@localhost:5432/dbname?sslmode=disable
  postgres://user:password@localhost:5432/dbname?sslmode=require
  postgres://user:password@rds-host:5432/dbname?sslmode=verify-ca&sslrootcert=~/.ssl/rds-ca.pem
  sqlserver://jsmith:secret@localhost:1433/mydb?authentication=ntlm&domain=CORP
  ```
</ParamField>

**Environment Variables (Alternative to --dsn)**

<ParamField path="DB_*" type="environment">
  Recommended for databases with complex passwords containing special characters:

  | Variable      | Type   | Description                                                                                     |
  | ------------- | ------ | ----------------------------------------------------------------------------------------------- |
  | `DB_TYPE`     | string | Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite`                            |
  | `DB_HOST`     | string | Database server hostname (not needed for SQLite)                                                |
  | `DB_PORT`     | number | Database server port. Default: PostgreSQL (`5432`), MySQL/MariaDB (`3306`), SQL Server (`1433`) |
  | `DB_USER`     | string | Database username (not needed for SQLite)                                                       |
  | `DB_PASSWORD` | string | Database password (not needed for SQLite). Supports special characters without URL encoding.    |
  | `DB_NAME`     | string | Database name or SQLite file path                                                               |

  ```bash theme={null}
  export DB_TYPE=postgres
  export DB_HOST=localhost
  export DB_PORT=5432
  export DB_USER=myuser
  export DB_PASSWORD='p@ss:word#123'
  export DB_NAME=mydb
  npx @bytebase/dbhub@latest
  ```
</ParamField>

### --id

<ParamField path="--id" type="string" env="ID">
  Instance identifier to suffix tool names. Useful when running multiple DBHub instances (e.g., in Cursor). Env: `ID`.

  Tools will be named `execute_sql_{id}` for each instance.

  ```bash theme={null}
  npx @bytebase/dbhub@latest --id prod --dsn "postgres://user:pass@prod-host:5432/db"
  npx @bytebase/dbhub@latest --id staging --dsn "postgres://user:pass@staging-host:5432/db"
  ```

  Result: `execute_sql_prod` and `execute_sql_staging` tools

  <Warning>
    Cannot be used with `--config` (TOML configuration). TOML config defines source IDs directly in the configuration file. Use command-line DSN configuration instead if you need the `--id` flag.
  </Warning>
</ParamField>

### --demo

<ParamField path="--demo" type="boolean" default="false">
  Run DBHub with a bundled SQLite sample "employee" database for testing.

  ```bash theme={null}
  npx @bytebase/dbhub@latest --demo --transport http --port 8080
  ```
</ParamField>

### --config

<ParamField path="--config" type="string">
  Path to a TOML configuration file, for managing multiple database connections and advanced configurations.

  ```bash theme={null}
  npx @bytebase/dbhub@latest --config ./dbhub.toml --transport http --port 8080
  ```

  See [TOML Configuration](/config/toml) for the complete reference, including source options, tool options, SSH tunnels, and custom tools.

  <Warning>
    A TOML file defines its own sources and source IDs, so `--config` is mutually exclusive with `--dsn` and `--id`. Use either a TOML file or command-line/environment configuration.
  </Warning>
</ParamField>

### SSH Tunnel Options

SSH tunnel configuration for connecting to databases through bastion/jump hosts.

| Option             | Env              | Type   | Description                                                                                                                             |
| ------------------ | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--ssh-host`       | `SSH_HOST`       | string | SSH server hostname or alias from `~/.ssh/config`                                                                                       |
| `--ssh-port`       | `SSH_PORT`       | number | SSH server port (default: `22`)                                                                                                         |
| `--ssh-user`       | `SSH_USER`       | string | SSH username                                                                                                                            |
| `--ssh-password`   | `SSH_PASSWORD`   | string | SSH password (for password auth)                                                                                                        |
| `--ssh-key`        | `SSH_KEY`        | string | Path to SSH private key file, or a base64-encoded private key. Auto-detects `~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, etc. if not specified |
| `--ssh-passphrase` | `SSH_PASSPHRASE` | string | Passphrase for encrypted SSH key                                                                                                        |
| `--ssh-proxy-jump` | `SSH_PROXY_JUMP` | string | ProxyJump hosts for multi-hop SSH. Format: `[user@]host[:port]` (comma-separated for chains)                                            |

**Examples:**

```bash theme={null}
# Password auth
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu --ssh-password mypassword

# Key-based auth
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu --ssh-key ~/.ssh/id_rsa

# ProxyJump (single hop)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host target.internal --ssh-proxy-jump bastion.example.com

# ProxyJump (multi-hop: bastion1 → bastion2 → target)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host target.internal --ssh-proxy-jump "bastion1.com,admin@bastion2:2222"

# SSH config alias (resolves host, user, key, and ProxyJump from ~/.ssh/config)
npx @bytebase/dbhub@latest --dsn "..." --ssh-host mybastion

# Base64-encoded private key (useful in containerized/cloud environments)
export SSH_KEY=$(base64 < ~/.ssh/id_rsa)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu
```

<Note>
  * `--ssh-key` / `SSH_KEY` accepts either a file path or a base64-encoded private key. DBHub automatically detects the format: it first tries to read the value as a file path, and if that fails, decodes it as base64.
  * When `--ssh-host` is a plain alias (no dots, not an IP address), DBHub automatically resolves it from `~/.ssh/config`, reading the `HostName`, `User`, `IdentityFile`, and `ProxyJump` directives. Explicit flags always override values from the config file.
  * `ProxyJump` hops that are themselves `~/.ssh/config` aliases are resolved recursively — each hop uses its own `HostName`/`User`/`Port`/`IdentityFile` (and its own nested `ProxyJump`), matching how `ssh` connects. Cyclic `ProxyJump` chains are rejected with an error.
  * ProxyCommand is not supported (requires shell execution). Use ProxyJump instead.
  * Path expansion for `~/` is supported in file paths.
</Note>

## Quick Reference

| CLI Option         | Env                   | Type    | Description                                                                                             |
| ------------------ | --------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `--transport`      | `TRANSPORT`           | string  | Transport mode: stdio or http (default: `stdio`)                                                        |
| `--port`           | `PORT`                | number  | HTTP server port (http transport only, default: `8080`)                                                 |
| `--host`           | `DBHUB_HOST`          | string  | HTTP bind address (http transport only, default: `0.0.0.0`)                                             |
| `--allowed-hosts`  | `DBHUB_ALLOWED_HOSTS` | string  | Extra hostnames accepted in Host/Origin headers (http transport only, default: loopback + this machine) |
| `--auth-token`     | `DBHUB_AUTH_TOKEN`    | string  | Comma-separated bearer token(s) required on requests (http transport only, default: auth disabled)      |
| `--demo`           | -                     | boolean | Use sample employee database                                                                            |
| `--id`             | `ID`                  | string  | Instance identifier for tool names                                                                      |
| `--config`         | -                     | string  | Path to TOML config file (default: `./dbhub.toml`)                                                      |
| `--dsn`            | `DSN`                 | string  | Database connection string (required unless using `--demo` or `--config`)                               |
| -                  | `DB_TYPE`             | string  | Database type                                                                                           |
| -                  | `DB_HOST`             | string  | Database hostname                                                                                       |
| -                  | `DB_PORT`             | number  | Database port (varies by type)                                                                          |
| -                  | `DB_USER`             | string  | Database username                                                                                       |
| -                  | `DB_PASSWORD`         | string  | Database password                                                                                       |
| -                  | `DB_NAME`             | string  | Database name or SQLite file path                                                                       |
| `--ssh-host`       | `SSH_HOST`            | string  | SSH server hostname                                                                                     |
| `--ssh-port`       | `SSH_PORT`            | number  | SSH server port (default: `22`)                                                                         |
| `--ssh-user`       | `SSH_USER`            | string  | SSH username                                                                                            |
| `--ssh-password`   | `SSH_PASSWORD`        | string  | SSH password                                                                                            |
| `--ssh-key`        | `SSH_KEY`             | string  | Path to SSH private key or base64-encoded key                                                           |
| `--ssh-passphrase` | `SSH_PASSPHRASE`      | string  | SSH key passphrase                                                                                      |
| `--ssh-proxy-jump` | `SSH_PROXY_JUMP`      | string  | ProxyJump hosts                                                                                         |