@carllee1983/dbcli 1.45.0 → 1.46.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -229,11 +229,13 @@ dbcli init --system postgresql --host localhost --port 5432 \
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
-# MongoDB — full URI (Atlas / replica sets / authSource)
+# MongoDB — field-by-field (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
 dbcli init --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
-# MongoDB — discrete params (no auth = omit --user/--password)
-dbcli init --system mongodb --host localhost --port 27017 --name mydb
 
 # Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
 dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
@@ -301,10 +303,25 @@ as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `-
 flags; otherwise `init` exits with an error — it never silently falls back to plaintext.
 `--env-file <path>` is the path to the env file, independent of the `$env` key names.
 
+**MongoDB is the exception**: only `--env-host` is required non-interactively.
+`--env-port` / `--env-user` / `--env-password` / `--env-database` are optional — an
+omitted one is written as a literal value (empty string for `user` / `password`, the
+resolved value for `port` / `database`) instead of an `$env` ref, so a field the
+connection never needed doesn't later fail closed on an undefined variable. `init`
+also skips the connection test in this mode regardless of `--skip-test` — the `$env`
+refs have no value to connect with yet.
+
 ### Common gotchas
 
 - **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
   natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
+  these interactively (`authSource` only when a user is set; `replicaSet` /
+  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
+  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
+  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  per-field values, `uri` wins silently — `dbcli doctor` flags this and also
+  warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
   percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
 - **Redis `--name`** — accepts only the logical DB index string; non-numeric

package/.cursor/skills/dbcli/reference.md

@@ -32,10 +32,11 @@ dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
 dbcli init --no-interactive --force                     # Non-interactive mode
 
-# MongoDB
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
+# MongoDB — field-by-field (primary path, same shape as SQL)
+dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
 dbcli init --system redis --host localhost --port 6379
@@ -62,7 +63,7 @@ dbcli --global use --list
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -2025,7 +2026,9 @@ dbcli doctor --format json      # JSON output for AI agents
 - Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
 - Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
 
-> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://` (via a full `uri` or the per-field `srv: true`), `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
+> **MongoDB connection-field warnings:** `doctor` also warns when a config has both `uri` and per-field values (`host` / `user`) present — `uri` silently wins and the per-field values are ignored — and when `srv: true` is combined with a non-default `port`, since SRV records carry their own ports.
 
 **Exit code:** 0 if all pass or warnings only, 1 if any error
 **Options:** `--format <text|json>`, `--remediation`
@@ -2600,7 +2603,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
@@ -2623,7 +2626,10 @@ Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against
 ### MongoDB-specific workflow
 
 ```bash
-# 1. Initialize (URI or individual params)
+# 1. Initialize — field-by-field (primary path)
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
 dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -229,11 +229,13 @@ dbcli init --system postgresql --host localhost --port 5432 \
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
-# MongoDB — full URI (Atlas / replica sets / authSource)
+# MongoDB — field-by-field (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
 dbcli init --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
-# MongoDB — discrete params (no auth = omit --user/--password)
-dbcli init --system mongodb --host localhost --port 27017 --name mydb
 
 # Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
 dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
@@ -301,10 +303,25 @@ as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `-
 flags; otherwise `init` exits with an error — it never silently falls back to plaintext.
 `--env-file <path>` is the path to the env file, independent of the `$env` key names.
 
+**MongoDB is the exception**: only `--env-host` is required non-interactively.
+`--env-port` / `--env-user` / `--env-password` / `--env-database` are optional — an
+omitted one is written as a literal value (empty string for `user` / `password`, the
+resolved value for `port` / `database`) instead of an `$env` ref, so a field the
+connection never needed doesn't later fail closed on an undefined variable. `init`
+also skips the connection test in this mode regardless of `--skip-test` — the `$env`
+refs have no value to connect with yet.
+
 ### Common gotchas
 
 - **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
   natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
+  these interactively (`authSource` only when a user is set; `replicaSet` /
+  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
+  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
+  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  per-field values, `uri` wins silently — `dbcli doctor` flags this and also
+  warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
   percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
 - **Redis `--name`** — accepts only the logical DB index string; non-numeric

package/.github/skills/dbcli/reference.md

@@ -32,10 +32,11 @@ dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
 dbcli init --no-interactive --force                     # Non-interactive mode
 
-# MongoDB
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
+# MongoDB — field-by-field (primary path, same shape as SQL)
+dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
 dbcli init --system redis --host localhost --port 6379
@@ -62,7 +63,7 @@ dbcli --global use --list
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -2025,7 +2026,9 @@ dbcli doctor --format json      # JSON output for AI agents
 - Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
 - Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
 
-> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://` (via a full `uri` or the per-field `srv: true`), `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
+> **MongoDB connection-field warnings:** `doctor` also warns when a config has both `uri` and per-field values (`host` / `user`) present — `uri` silently wins and the per-field values are ignored — and when `srv: true` is combined with a non-default `port`, since SRV records carry their own ports.
 
 **Exit code:** 0 if all pass or warnings only, 1 if any error
 **Options:** `--format <text|json>`, `--remediation`
@@ -2600,7 +2603,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
@@ -2623,7 +2626,10 @@ Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against
 ### MongoDB-specific workflow
 
 ```bash
-# 1. Initialize (URI or individual params)
+# 1. Initialize — field-by-field (primary path)
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
 dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.46.0] - 2026-08-04 - MongoDB 逐欄連線設定
+
+決策記錄：`docs/adr/0002-mongodb-connection-field-first-config.md`；規格：`docs/specs/2026-08-04-mongodb-field-first-connection.md`。
+
+### Changed
+
+- **⚠️ BREAKING（互動流程）：`dbcli init` 對 MongoDB 改為先問「連線設定方式」。** 過去第一個提問是 MongoDB URI，留空才退回逐欄詢問 —— 於是逐欄路徑事實上沒人走，所有文件也只教「整條 URI 貼進去」。現在預設是「逐欄填寫」，貼 URI 降為明示的進階選項。**設定檔格式向下相容**，既有含 `uri` 的設定不需修改；`--uri`、`--no-interactive` 等非互動用法行為完全不變，只有互動提問的順序改變。
+- **逐欄模式在有帳號時會明確寫出 `authSource`。** 過去只有帶 `--auth-source` 才會（而且寫了也會被 schema 丟掉），現在未指定時會寫入 `admin`。連線結果與過去等價（adapter 本來就以 `admin` 為預設），但設定檔內容會多這一行 —— 包含 `--no-interactive` 的既有腳本。
+- **`uri` 與逐欄欄位仍是 `uri` 優先，但不再靜默。** 兩者同時存在時 `dbcli doctor` 會發出 warning 指出逐欄值被忽略；`srv: true` 又指定非預設 `port` 也會 warning。這兩種設定過去都是「改了欄位卻沒生效」而無從診斷。
+
+### Added
+
+- **MongoDB 連線設定新增 `authSource` / `replicaSet` / `tls` / `srv` 四個欄位。** 過去這些選項只能塞進 `uri` 的 query string —— 這正是逐欄路徑不堪用的根因。其中 `authSource` 更微妙：runtime 型別與 `init --auth-source` flag 都存在，但 zod schema 沒有此鍵，`z.object` 會 strip 掉未知欄位，於是它落盤即遺失，只有 init 當下那次連線測試吃得到，等同一個死 flag。`srv: true` 會組出 `mongodb+srv://` 並沿用既有的 DNS SRV 展開（含 DoH fallback），讓 Atlas 這類最常見的雲端場景也能逐欄設定。`authSource` 與 `replicaSet` 支援 `{"$env": "..."}` 參照。
+- **MongoDB 逐欄分支支援 `--use-env-refs`。** 過去 mongo 在 init 的 early-return 發生在 env-ref 分支之前，想用環境變數參照只能手改 `config.json`。現在五個 `--env-*` 旗標對 mongo 全部生效，密碼不必明文落盤。與 SQL 路徑的差異：mongo 只要求 `--env-host`，其餘留空即寫入字面值而不產生 `$env` —— 因為未定義的 `$env` 會讓之後每一個指令 fail closed，對無認證連線而言那是壞掉的設定。env-ref 模式同樣跳過連線測試（參照此時還沒有值可連），與 SQL 路徑一致。
+- **連線失敗訊息按成因分類。** 認證失敗提示檢查 `authSource`（並說明 Atlas 與多數自架環境為 `admin`）、DNS/SRV 解析失敗提示 `srv` 設定與網路 DNS、TLS 握手失敗提示 `tls` 欄位與自簽憑證情境。原本三種情況共用同兩條泛用訊息。
+
+### Fixed
+
+- **逐欄模式的連線字串跳脫不完整。** `buildUri()` 原本只對 `password` 做 `encodeURIComponent`，`user` 與 `database` 直接字串拼接 —— 帳號含 `@`、資料庫名含 `/` 都會讓 driver 把 authority 切在錯的位置。現在三者一致跳脫，`host` 則改為驗證不含 `/@?#` 並在違反時明確報錯。
+- **`host` 為空字串或含埠號、空白時會產出壞掉的連線字串。** `mongodb://:27017/db` 與 `mongodb://h:1234:27017/db` 過去都會被送進 driver，換來一個難懂的錯誤。現在在組字串前就擋下並說明埠號該填在 `port` 欄位。IPv6 位址需加方括號（`[::1]`），與 driver 的要求一致 —— 未加方括號的 `::1` 過去會組出 `mongodb://::1:27017/db`。同理 `authSource` 為空字串時會退回 `admin`，不再送出 `authSource=`。
+- **連線失敗分類會被連線字串本身誤導。** driver 的錯誤訊息經常回吐原始 URI，而 `mongodb+srv://` 與這次新增的 `?tls=true` 正好含有 `SRV` 與 `TLS` 字樣 —— 用裸字串比對會讓一個單純的連線被拒歸類成 DNS 或 TLS 問題。改為優先讀 driver 的結構化 error code，訊息比對則收斂成 driver 實際會產生的片語。
+- **只填 `user` 沒填 `password` 會靜默降級成無認證連線。** 原本的 `if (user && password)` 在密碼缺漏時直接落到無認證分支，錯誤會延後到伺服器端才浮現、且看起來像是權限問題。現在直接拋 `ConnectionError`，訊息說明補上密碼或一併清空 `user`。
+
+## [1.45.1] - 2026-08-04 - Windows 上的 agent mode 修復
+
+### Fixed
+
+- **agent mode 在 Windows 上拒讀自己寫出來的 config。** `assertAgentReadableFile` 以 `(mode & 0o022) !== 0` 判斷 group/world-writable，但 Windows 的 `stat()` 回的是合成 mode —— 一般可寫檔一律 `0o666`，設了 read-only 位元才 `0o444`，低位元沒有 group/world 語意，`chmod` 也只能切換 read-only。結果 `DBCLI_AGENT_MODE=1` 時，Windows 上連 dbcli 剛寫入的 config 都被拒絕，agent 模式實際不可用（1.45.0 已含此問題）。同檔的 `bestEffortSecureMode` 註解早已寫明「Windows 沒有 POSIX mode bits，靠 content hash 保護」，這次把 assert 端對齊該立場：mode 檢查抽成 `refusesGroupOrWorldWritable(mode, platform)`，win32 放行，POSIX 行為不變。竄改偵測比對的是寫入時記錄的 content hash，與 mode 無關，因此安全性不受影響。連帶修好 2 個 config-binding tampering 測試 —— 同一根因：binding 讀取前先過這道閘門，拋出的是 writable 錯誤而非預期的 tampering 錯誤。
+
+### Changed
+
+- **移除 schema loader 的牆鐘時間斷言。** `initialize` 的 `loadTime < 200ms` 跑在阻擋性的 `bun test` 裡，但共用 CI runner 不是量測儀器（Windows 冷啟動 270ms 就紅，程式本身無異常）。改為斷言合約（有量到並回報 loadTime），時間預算歸 `tests/perf/*.bench.ts` —— CI 對該套件本來就設 `continue-on-error`，正因為 timing 依環境而定。
+- **`docs/security-threat-model.md` 補上平台差異。** POSIX 用 `0o700`/`0o600` 保護設定，Windows 沒有等價 mode bits，機密性靠 profile ACL；竄改偵測兩邊一致。
+- 這兩項修復讓 `windows-latest` CI job 自 v1.40.0 以來首次通過（6 個 matrix job + docs-parity 全綠）。
+
 ## [1.45.0] - 2026-08-04 - root-level `--global`：跨專案共用的 user-global registry
 
 ### Added

package/assets/SKILL.md

@@ -229,11 +229,13 @@ dbcli init --system postgresql --host localhost --port 5432 \
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
-# MongoDB — full URI (Atlas / replica sets / authSource)
+# MongoDB — field-by-field (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
 dbcli init --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
-# MongoDB — discrete params (no auth = omit --user/--password)
-dbcli init --system mongodb --host localhost --port 27017 --name mydb
 
 # Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
 dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
@@ -301,10 +303,25 @@ as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `-
 flags; otherwise `init` exits with an error — it never silently falls back to plaintext.
 `--env-file <path>` is the path to the env file, independent of the `$env` key names.
 
+**MongoDB is the exception**: only `--env-host` is required non-interactively.
+`--env-port` / `--env-user` / `--env-password` / `--env-database` are optional — an
+omitted one is written as a literal value (empty string for `user` / `password`, the
+resolved value for `port` / `database`) instead of an `$env` ref, so a field the
+connection never needed doesn't later fail closed on an undefined variable. `init`
+also skips the connection test in this mode regardless of `--skip-test` — the `$env`
+refs have no value to connect with yet.
+
 ### Common gotchas
 
 - **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
   natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
+  these interactively (`authSource` only when a user is set; `replicaSet` /
+  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
+  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
+  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  per-field values, `uri` wins silently — `dbcli doctor` flags this and also
+  warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
   percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
 - **Redis `--name`** — accepts only the logical DB index string; non-numeric

package/assets/reference.md

@@ -32,10 +32,11 @@ dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
 dbcli init --no-interactive --force                     # Non-interactive mode
 
-# MongoDB
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
+# MongoDB — field-by-field (primary path, same shape as SQL)
+dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
 dbcli init --system redis --host localhost --port 6379
@@ -62,7 +63,7 @@ dbcli --global use --list
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -2025,7 +2026,9 @@ dbcli doctor --format json      # JSON output for AI agents
 - Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
 - Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
 
-> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://` (via a full `uri` or the per-field `srv: true`), `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
+> **MongoDB connection-field warnings:** `doctor` also warns when a config has both `uri` and per-field values (`host` / `user`) present — `uri` silently wins and the per-field values are ignored — and when `srv: true` is combined with a non-default `port`, since SRV records carry their own ports.
 
 **Exit code:** 0 if all pass or warnings only, 1 if any error
 **Options:** `--format <text|json>`, `--remediation`
@@ -2600,7 +2603,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
@@ -2623,7 +2626,10 @@ Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against
 ### MongoDB-specific workflow
 
 ```bash
-# 1. Initialize (URI or individual params)
+# 1. Initialize — field-by-field (primary path)
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
 dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections