> ## 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 supports three configuration methods with the following priority order:

1. **Command-line arguments** (highest priority)
2. **TOML configuration file** (if `--config` is provided or `./dbhub.toml` exists)
3. **Environment variables**
4. **`.env` files** (`.env.local` in development, `.env` in production)

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

Command-line flags are passed when starting DBHub. These have the highest priority and override all other configuration methods.

### --transport

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

  **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.

  | 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.

  ```bash theme={null}
  npx @bytebase/dbhub@latest --transport http --port 3000 --dsn "..."
  ```
</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`

  <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
      ```
    </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).

  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" default="./dbhub.toml">
  Path to TOML configuration file for managing multiple database connections and advanced configurations.

  Automatically loads `./dbhub.toml` if it exists in the current directory.

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

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

  <Warning>
    **`--config` (TOML) is mutually exclusive with:**

    * `--dsn` - TOML configuration defines database connections directly
    * `--id` - TOML configuration defines source IDs directly in the file

    If using TOML config, remove these flags. If you need `--id` or `--dsn`, use command-line/environment configuration instead.
  </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.
  * 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`)                   |
| `--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                                                           |