@carllee1983/dbcli 1.45.0 → 1.46.0

package/dist/core.d.ts

@@ -29,6 +29,12 @@ export interface ConnectionOptions {
 	uri?: string;
 	/** MongoDB auth database — used when building URI from host/port/user/password (default: 'admin') */
 	authSource?: string;
+	/** MongoDB replica set name (optional, field-based config) */
+	replicaSet?: string;
+	/** MongoDB TLS switch (optional, field-based config; implied true when srv) */
+	tls?: boolean;
+	/** MongoDB SRV lookup — build a mongodb+srv:// URI from host (optional, field-based config) */
+	srv?: boolean;
 	/** Connection timeout in milliseconds (default: 5000) */
 	timeout?: number;
 	/** Elasticsearch protocol (http or https) */
@@ -430,6 +436,16 @@ interface MongoDBConnectionConfig {
 	database: string | {
 		$env: string;
 	};
+	/** Auth database; defaults to 'admin' when credentials are present */
+	authSource?: string | {
+		$env: string;
+	};
+	replicaSet?: string | {
+		$env: string;
+	};
+	tls?: boolean;
+	/** Build a mongodb+srv:// URI from host and expand it via DNS SRV lookup */
+	srv?: boolean;
 }
 interface RedisConnectionConfig {
 	system: "redis";
@@ -804,6 +820,28 @@ declare const DbcliConfigSchema: z.ZodObject<{
 					$env: string;
 				}>
 			]>>>;
+			authSource: z.ZodOptional<z.ZodUnion<[
+				z.ZodString,
+				z.ZodObject<{
+					$env: z.ZodString;
+				}, "strict", z.ZodTypeAny, {
+					$env: string;
+				}, {
+					$env: string;
+				}>
+			]>>;
+			replicaSet: z.ZodOptional<z.ZodUnion<[
+				z.ZodString,
+				z.ZodObject<{
+					$env: z.ZodString;
+				}, "strict", z.ZodTypeAny, {
+					$env: string;
+				}, {
+					$env: string;
+				}>
+			]>>;
+			tls: z.ZodOptional<z.ZodBoolean>;
+			srv: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 		}, "strip", z.ZodTypeAny, {
 			password: string | {
 				$env: string;
@@ -821,6 +859,14 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			database: string | {
 				$env: string;
 			};
+			srv: boolean;
+			authSource?: string | {
+				$env: string;
+			} | undefined;
+			replicaSet?: string | {
+				$env: string;
+			} | undefined;
+			tls?: boolean | undefined;
 			uri?: string | {
 				$env: string;
 			} | undefined;
@@ -841,6 +887,14 @@ declare const DbcliConfigSchema: z.ZodObject<{
 			database?: string | {
 				$env: string;
 			} | undefined;
+			authSource?: string | {
+				$env: string;
+			} | undefined;
+			replicaSet?: string | {
+				$env: string;
+			} | undefined;
+			tls?: boolean | undefined;
+			srv?: boolean | undefined;
 			uri?: string | {
 				$env: string;
 			} | undefined;
@@ -1183,6 +1237,14 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		database: string | {
 			$env: string;
 		};
+		srv: boolean;
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -1273,6 +1335,14 @@ declare const DbcliConfigSchema: z.ZodObject<{
 		database?: string | {
 			$env: string;
 		} | undefined;
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
+		srv?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -1540,6 +1610,28 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 					$env: string;
 				}>
 			]>>>;
+			authSource: z.ZodOptional<z.ZodUnion<[
+				z.ZodString,
+				z.ZodObject<{
+					$env: z.ZodString;
+				}, "strict", z.ZodTypeAny, {
+					$env: string;
+				}, {
+					$env: string;
+				}>
+			]>>;
+			replicaSet: z.ZodOptional<z.ZodUnion<[
+				z.ZodString,
+				z.ZodObject<{
+					$env: z.ZodString;
+				}, "strict", z.ZodTypeAny, {
+					$env: string;
+				}, {
+					$env: string;
+				}>
+			]>>;
+			tls: z.ZodOptional<z.ZodBoolean>;
+			srv: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 		} & {
 			permission: z.ZodDefault<z.ZodEnum<[
 				"query-only",
@@ -1566,7 +1658,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			database: string | {
 				$env: string;
 			};
+			srv: boolean;
 			permission: "admin" | "query-only" | "read-write" | "data-admin";
+			authSource?: string | {
+				$env: string;
+			} | undefined;
+			replicaSet?: string | {
+				$env: string;
+			} | undefined;
+			tls?: boolean | undefined;
 			uri?: string | {
 				$env: string;
 			} | undefined;
@@ -1589,6 +1689,14 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 			database?: string | {
 				$env: string;
 			} | undefined;
+			authSource?: string | {
+				$env: string;
+			} | undefined;
+			replicaSet?: string | {
+				$env: string;
+			} | undefined;
+			tls?: boolean | undefined;
+			srv?: boolean | undefined;
 			uri?: string | {
 				$env: string;
 			} | undefined;
@@ -1884,7 +1992,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database: string | {
 			$env: string;
 		};
+		srv: boolean;
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -1977,6 +2093,14 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database?: string | {
 			$env: string;
 		} | undefined;
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
+		srv?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -2167,7 +2291,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database: string | {
 			$env: string;
 		};
+		srv: boolean;
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -2271,6 +2403,14 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database?: string | {
 			$env: string;
 		} | undefined;
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
+		srv?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -2411,7 +2551,15 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database: string | {
 			$env: string;
 		};
+		srv: boolean;
 		permission: "admin" | "query-only" | "read-write" | "data-admin";
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;
@@ -2515,6 +2663,14 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 		database?: string | {
 			$env: string;
 		} | undefined;
+		authSource?: string | {
+			$env: string;
+		} | undefined;
+		replicaSet?: string | {
+			$env: string;
+		} | undefined;
+		tls?: boolean | undefined;
+		srv?: boolean | undefined;
 		uri?: string | {
 			$env: string;
 		} | undefined;

package/dist/core.mjs

@@ -15022,12 +15022,40 @@ class MongoDBAdapter {
   buildUri() {
     if (this.options.uri)
       return this.options.uri;
-    const { user, password, host, port, database, authSource } = this.options;
-    if (user && password) {
-      const auth = authSource ?? "admin";
-      return `mongodb://${user}:${encodeURIComponent(password)}@${host}:${port}/${database}?authSource=${auth}`;
+    const { user, password, host, port, database, authSource, replicaSet, tls, srv } = this.options;
+    if (!host) {
+      throw new ConnectionError("UNKNOWN", "MongoDB host \u672A\u8A2D\u5B9A", [
+        "\u8ACB\u586B\u5BEB host\uFF0C\u6216\u6539\u7528 uri \u6B04\u4F4D\u6307\u5B9A\u5B8C\u6574\u9023\u7DDA\u5B57\u4E32"
+      ]);
+    }
+    const isBracketedIpv6 = /^\[[0-9a-f:]+\]$/i.test(host);
+    if (!isBracketedIpv6 && /[/@?#:\s\\]/.test(host)) {
+      throw new ConnectionError("UNKNOWN", `MongoDB host \u542B\u6709\u975E\u6CD5\u5B57\u5143: ${host}`, [
+        "host \u53EA\u61C9\u5305\u542B\u4E3B\u6A5F\u540D\u7A31\u6216 IP\uFF0C\u4E0D\u8981\u542B /\u3001@\u3001?\u3001#\u3001: \u6216\u7A7A\u767D",
+        "\u57E0\u865F\u8ACB\u586B\u5728 port \u6B04\u4F4D\uFF0C\u4E0D\u8981\u4F75\u9032 host",
+        "IPv6 \u4F4D\u5740\u8ACB\u52A0\u65B9\u62EC\u865F\uFF0C\u4F8B\u5982 [::1]",
+        "\u82E5\u8981\u6307\u5B9A\u5B8C\u6574\u9023\u7DDA\u5B57\u4E32\uFF0C\u8ACB\u6539\u7528 uri \u6B04\u4F4D"
+      ]);
+    }
+    if (user && !password) {
+      throw new ConnectionError("UNKNOWN", "\u5DF2\u6307\u5B9A user \u4F46\u672A\u63D0\u4F9B password", [
+        '\u8ACB\u88DC\u4E0A password\uFF0C\u6216\u6539\u7528\u74B0\u5883\u8B8A\u6578\u53C3\u7167 {"$env": "..."}',
+        "\u82E5\u78BA\u5B9A\u8981\u4EE5\u7121\u8A8D\u8B49\u65B9\u5F0F\u9023\u7DDA\uFF0C\u8ACB\u4E00\u4F75\u6E05\u7A7A user"
+      ]);
     }
-    return `mongodb://${host}:${port}/${database}`;
+    const userInfo = user ? `${encodeURIComponent(user)}:${encodeURIComponent(password)}@` : "";
+    const scheme = srv ? "mongodb+srv://" : "mongodb://";
+    const authority = srv ? host : `${host}:${port}`;
+    const path = database ? `/${encodeURIComponent(database)}` : "/";
+    const query = new URLSearchParams;
+    if (user)
+      query.set("authSource", authSource || "admin");
+    if (replicaSet)
+      query.set("replicaSet", replicaSet);
+    if (tls !== undefined)
+      query.set("tls", String(tls));
+    const search = query.toString();
+    return `${scheme}${userInfo}${authority}${path}${search ? `?${search}` : ""}`;
   }
   parseTxtRecords(records) {
     const combined = records.flat().map((record) => record.replace(/^"|"$/g, "")).join("&");
@@ -15089,13 +15117,11 @@ class MongoDBAdapter {
     return this.parseTxtRecords(payload.Answer.map((answer) => [answer.data]));
   }
   async buildResolvedUri() {
-    if (!this.options.uri) {
-      return this.buildUri();
-    }
-    if (!this.options.uri.startsWith("mongodb+srv://")) {
-      return this.options.uri;
+    const canonical = this.buildUri();
+    if (!canonical.startsWith("mongodb+srv://")) {
+      return canonical;
     }
-    const url = new URL(this.options.uri);
+    const url = new URL(canonical);
     const hosts = await this.resolveSrvHosts(url.hostname);
     const txtOptions = await this.resolveTxtOptions(url.hostname);
     const query = new URLSearchParams(url.searchParams);
@@ -15115,6 +15141,37 @@ class MongoDBAdapter {
     const search = query.toString();
     return `mongodb://${userInfo}${hosts.join(",")}${path}${search ? `?${search}` : ""}`;
   }
+  connectionHints(error, message) {
+    const AUTH_HINTS = [
+      "\u8A8D\u8B49\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D user / password \u6B63\u78BA",
+      "\u8ACB\u78BA\u8A8D authSource \u6307\u5411\u5B58\u653E\u8A72\u5E33\u865F\u7684\u8CC7\u6599\u5EAB\uFF08Atlas \u8207\u591A\u6578\u81EA\u67B6\u74B0\u5883\u70BA admin\uFF09"
+    ];
+    const DNS_HINTS = [
+      "DNS/SRV \u89E3\u6790\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D host \u70BA SRV \u7DB2\u57DF\uFF0C\u4E14 srv \u8A2D\u5B9A\u8207\u5B83\u4E00\u81F4",
+      "\u82E5\u8A72\u4E3B\u6A5F\u4E0D\u662F SRV \u7DB2\u57DF\uFF0C\u8ACB\u95DC\u9589 srv \u4E26\u6539\u586B host \u8207 port",
+      "\u8ACB\u78BA\u8A8D\u672C\u6A5F DNS \u6216\u7DB2\u8DEF\uFF08VPN\u3001\u516C\u53F8\u7DB2\u8DEF\uFF09\u5141\u8A31 SRV \u67E5\u8A62"
+    ];
+    const TLS_HINTS = [
+      "TLS \u63E1\u624B\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D tls \u6B04\u4F4D\u8A2D\u5B9A\u8207\u4F3A\u670D\u5668\u4E00\u81F4",
+      "\u81EA\u7C3D\u6191\u8B49\u74B0\u5883\u9700\u8981\u5728\u4F3A\u670D\u5668\u7AEF\u6216\u7CFB\u7D71\u4FE1\u4EFB\u93C8\u4E2D\u5B89\u88DD CA \u6191\u8B49"
+    ];
+    const err = error;
+    const causeCode = String(err?.cause?.code ?? err?.code ?? "");
+    if (err?.code === 18 || err?.codeName === "AuthenticationFailed")
+      return AUTH_HINTS;
+    if (["ENOTFOUND", "EAI_AGAIN"].includes(causeCode))
+      return DNS_HINTS;
+    if (causeCode.startsWith("ERR_TLS") || causeCode.startsWith("SELF_SIGNED"))
+      return TLS_HINTS;
+    if (/authentication failed|not authorized|bad auth/i.test(message))
+      return AUTH_HINTS;
+    if (/querySrv|getaddrinfo (ENOTFOUND|EAI_AGAIN)/i.test(message))
+      return DNS_HINTS;
+    if (/unable to verify the first certificate|self.signed certificate|certificate has expired|ERR_TLS/i.test(message)) {
+      return TLS_HINTS;
+    }
+    return ["\u8ACB\u78BA\u8A8D MongoDB \u670D\u52D9\u6B63\u5728\u57F7\u884C", "\u8ACB\u78BA\u8A8D\u9023\u7DDA\u8A2D\u5B9A\uFF08URI \u6216 host/port\uFF09\u6B63\u78BA"];
+  }
   getDatabase() {
     if (!this.client) {
       throw new ConnectionError("UNKNOWN", "\u5C1A\u672A\u9023\u7DDA\uFF0C\u8ACB\u5148\u547C\u53EB connect()", []);
@@ -15130,10 +15187,7 @@ class MongoDBAdapter {
     } catch (err) {
       const message = err.message ?? "Unknown error";
       const code = message.includes("ECONNREFUSED") ? "ECONNREFUSED" : message.includes("ETIMEDOUT") ? "ETIMEDOUT" : "UNKNOWN";
-      throw new ConnectionError(code, `MongoDB \u9023\u7DDA\u5931\u6557: ${message}`, [
-        "\u8ACB\u78BA\u8A8D MongoDB \u670D\u52D9\u6B63\u5728\u57F7\u884C",
-        "\u8ACB\u78BA\u8A8D\u9023\u7DDA\u8A2D\u5B9A\uFF08URI \u6216 host/port\uFF09\u6B63\u78BA"
-      ]);
+      throw new ConnectionError(code, `MongoDB \u9023\u7DDA\u5931\u6557: ${message}`, this.connectionHints(err, message));
     }
   }
   async disconnect() {
@@ -17598,6 +17652,11 @@ async function bestEffortSecureMode(path, mode) {
     await chmod(path, mode);
   } catch {}
 }
+function refusesGroupOrWorldWritable(mode, platform = process.platform) {
+  if (platform === "win32")
+    return false;
+  return (mode & 18) !== 0;
+}
 async function assertAgentReadableFile(path, description = "config") {
   if (process.env.DBCLI_AGENT_MODE !== "1")
     return;
@@ -17606,7 +17665,7 @@ async function assertAgentReadableFile(path, description = "config") {
     if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
       throw new ConfigError(`Agent mode refuses a non-regular ${description} file: ${path}. Run the human/admin setup workflow to provision it.`);
     }
-    if ((fileStat.mode & 18) !== 0) {
+    if (refusesGroupOrWorldWritable(fileStat.mode)) {
       throw new ConfigError(`Agent mode refuses a group/world-writable config: ${path}. Run the human/admin setup workflow to secure it.`);
     }
   } catch (error) {
@@ -21799,7 +21858,11 @@ var MongoDBConnectionConfigSchema = exports_external.object({
   port: OptNumberOrEnvRef,
   user: OptStringOrEnvRef,
   password: OptStringOrEnvRef,
-  database: OptStringOrEnvRef
+  database: OptStringOrEnvRef,
+  authSource: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
+  replicaSet: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
+  tls: exports_external.boolean().optional(),
+  srv: exports_external.boolean().optional().default(false)
 });
 var SqlConnectionConfigSchema = exports_external.object({
   system: exports_external.enum(["postgresql", "mysql", "mariadb"]),

package/gemini-extension.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.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.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/plugins/dbcli-agent/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/plugins/dbcli-agent/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/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/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