@carllee1983/dbcli 9.1.2 → 10.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "9.1.2",
+  "version": "10.0.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": "9.1.2",
+  "version": "10.0.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -328,9 +328,10 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 
 ### Decision tree (ask before writing)
 
-1. **One DB or many environments?** One → v1 (single connection). Multiple
-   environments / tenants / replicas → v2 (`--conn-name <name>`, optionally
-   `--env-file <path>` per connection).
+1. **What is the connection name?** Every new connection uses named v2, even
+   for one DB. Confirm a nonblank `--conn-name <name>` (optionally an
+   `--env-file <path>` per connection). `--name` means the database, not the
+   connection. Existing v1 configs remain readable and support named v2 import.
 2. **Where do credentials live?**
    - Already in a `.env` (`DATABASE_URL` or `DB_HOST` / `DB_PORT` / `DB_USER` /
      `DB_PASSWORD` / `DB_NAME` | `DB_DATABASE`) → `init` parses it automatically.
@@ -347,31 +348,41 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
    blacklist summary, no creds) and `dbcli doctor --format json` (env, config
    shape, connectivity, schema-cache age, Mongo SRV path).
 
+`init` asks for a connection name in an interactive TTY when `--conn-name` is
+omitted, without suggesting `default`. Blank prompt answers are explained and
+re-prompted; cancellation/end of input stops before testing or writing. An explicit
+nonblank name skips this prompt; `--conn-name default` is valid. An explicitly
+blank `--conn-name` is an error in every mode before testing or writing. Non-TTY, `--no-interactive`,
+and complete `--use-env-refs`/`--env-*` automatic noninteractive mode require an
+explicit nonblank `--conn-name` or fail before database access or config/credential
+writes. Plain `init` and explicit `--config` paths both create named v2, never new
+unnamed v1. `--remove` and `--rename` do not prompt for a new connection name.
+
 ### Per-engine essentials
 
 ```bash
-# PostgreSQL / MySQL / MariaDB (v1, plain values)
-dbcli init --system postgresql --host localhost --port 5432 \
+# PostgreSQL / MySQL / MariaDB (named v2, plain values)
+dbcli init --conn-name local --system postgresql --host localhost --port 5432 \
   --user app --password '<secret>' --name appdb --permission query-only
 
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
 # 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 \
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --conn-name local --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 \
+dbcli init --conn-name local --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
 
 # 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
+dbcli init --conn-name local --system redis --host localhost --port 6379 --password '<secret>' --name 0
 
 # Elasticsearch — basic auth, Cloud ID, or API key
-dbcli init --system elasticsearch --host localhost --port 9200 \
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200 \
   --user elastic --password '<secret>'
-dbcli init --system elasticsearch \
+dbcli init --conn-name local --system elasticsearch \
   --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
 # Multi-node / custom CA / self-signed: edit `.dbcli` directly to add
 # `nodes: [...]`, `protocol: https`, `caPath`, `rejectUnauthorized: false`.
@@ -384,13 +395,37 @@ dbcli init --conn-name staging --env-file .env.staging --permission query-only
 dbcli init --conn-name prod    --env-file .env.production --use-env-refs --skip-test
 dbcli use --list --format json            # safe identity inventory: name/env/permission/server/database
 dbcli use prod                            # switch default (persists — avoid for one-off queries)
-dbcli query --use staging "SELECT 1"      # one-shot override on any subcommand
+dbcli use --unset                         # clear the saved default (v2 only; approved config mutation)
+dbcli --use staging query "SELECT 1"      # root-level one-shot selector before any subcommand
 DBCLI_CONNECTION=staging dbcli query "SELECT 1"   # one-shot via env; parallel-safe
 dbcli --use staging,prod query "SELECT count(*) FROM users"   # read-only fan-out
 dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+V2 may omit `default`; if present, it must be a nonempty existing connection
+name, never `null` or `""`. Without a default, connection-dependent commands
+require `--use` or `DBCLI_CONNECTION` and fail before database access with an
+available-name list, never endpoints or credentials. Do not pick the first name
+to bypass that choice. Priority remains `--use` > `DBCLI_CONNECTION` > saved
+default; conflicting root/command selectors and blank CLI selectors are errors,
+while a blank environment selector is absent. Unknown-name and production
+selection protections still apply.
+
+`use --unset` removes only the saved default, reports it cleared, and succeeds
+when already absent without changing connections. It rejects a name, `--list`,
+`--confirm-production`, or `--format json` without writing, and never converts or
+overwrites v1. This is an approved, integrity-protected config mutation, blocked
+in agent mode. `use` describes no default; text inventory has no default marker
+and JSON has `isDefault: false` throughout. `doctor` accepts this v2 shape; select
+a connection explicitly for its connection checks (`dbcli --use staging doctor`).
+Removing the default with `init --remove` clears it and reports that change,
+without choosing a replacement. Other removals preserve the current default or
+its absence; the last connection cannot be deleted. Renaming preserves no
+default, or updates the default name when appropriate. The first explicitly named
+connection defaults a new registry; additions preserve an existing default or
+no-default state. Existing v1 imports and production confirmation rules are unchanged.
+
 Rotating one connection's password — nothing else in the config moves:
 
 ```bash
@@ -440,11 +475,12 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 
 In an **interactive terminal**, omitting the `--env-*` flags prompts for each key name
 (defaults above) — you can type a non-default name like `PROD_DB_PASSWORD` and it is stored
-as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `--env-*`
+as a `$env` ref. In a **non-interactive / CI** run you **must** pass `--conn-name` and all five `--env-*`
 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.
+**MongoDB has fewer required env-reference flags**: besides `--conn-name`, 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
@@ -469,8 +505,10 @@ refs have no value to connect with yet.
   values are rejected.
 - **Elasticsearch TLS** — `caPath` and `rejectUnauthorized` are not exposed as
   flags; edit `.dbcli` after `init` to add them.
-- **Re-running `init`** — refuses to overwrite without `--force`; never use
-  `--force` to "fix" a config full of `{ "$env": "..." }` refs.
+- **Re-running `init` with the same name** — requires interactive overwrite
+  confirmation or `--force`; a noninteractive duplicate without `--force` or a
+  declined confirmation leaves files untouched. Never use `--force` to "fix"
+  a config full of `{ "$env": "..." }` refs or choose a name for the user.
 
 Full flags and edge cases: see [reference.md](../skills/dbcli/reference.md#init).
 
@@ -478,7 +516,7 @@ Full flags and edge cases: see [reference.md](../skills/dbcli/reference.md#init)
 
 | Command | Min permission | Summary |
 |---------|-----------------|---------|
-| `init` | n/a | Create `.dbcli` (v1 single or v2 multi via `--conn-name` / `--env-file`). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
+| `init` | n/a | Create a named v2 connection (`--conn-name` required outside an interactive TTY). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `capabilities` | n/a | Static capability catalog + `check --require <ids>` requirement gate. No database connection. `--format text\|json\|markdown` (`check` is `text\|json`). Exit `0`/`1`/`2`. |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |

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

@@ -119,24 +119,24 @@ dbcli query '{}' --collection events --format json 2>/dev/null | jq '.rows | len
 Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
 
 ```bash
-dbcli init                                              # Single connection (v1 format)
-dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
+dbcli init                                              # Prompt for a name; create named v2
+dbcli init --conn-name local --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
+dbcli init --conn-name local --no-interactive --force    # Non-interactive; credentials from environment
 
 # 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
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
+dbcli init --conn-name local --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"
+dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
-dbcli init --system redis --host localhost --port 6379
-dbcli init --system redis --host localhost --port 6379 --password secret --name 0
+dbcli init --conn-name local --system redis --host localhost --port 6379
+dbcli init --conn-name local --system redis --host localhost --port 6379 --password secret --name 0
 
 # Elasticsearch
-dbcli init --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
-dbcli init --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
+dbcli init --conn-name local --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
 
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
@@ -151,6 +151,12 @@ dbcli --global init --conn-name shared --system postgresql --host db.example.com
 dbcli --global use --list
 ```
 
+Every new or additional connection needs a nonblank connection name. Pass `--conn-name <name>`, or run `dbcli init` in an interactive terminal to be asked for one. The name prompt has no suggested `default`; empty or whitespace-only answers explain the requirement and prompt again. Cancelling or ending the name prompt stops before any connection test or configuration/credential write. An explicit nonblank `--conn-name` skips this prompt, and `--conn-name default` is valid. An explicitly blank `--conn-name` is an error in every mode, before connection tests or writes. `--name` still means the database name (the logical DB index for Redis), never the connection name.
+
+Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `--env-*` options automatically disables interaction, a missing or blank `--conn-name` fails with guidance to supply it, before database access or configuration/credential writes. Complete credentials, `--name`, `--env-file`, and `--force` do not supply a connection name.
+
+New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
+
 **Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
@@ -161,7 +167,27 @@ dbcli --global use --list
 
 **Redis note:** the `database` (or `--name`) field is the logical DB index (`"0"` … `"15"`), not a database name.
 
-**Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
+**Multi-connection:** Every newly created connection uses v2 with an explicitly supplied or interactively entered name. Each connection can have its own env file and permission level; `--env-file` does not replace the name requirement. Existing v1 configs are automatically imported as the `default` connection when upgrading.
+
+V2 may omit the top-level `default` field; if supplied, it must be a nonempty
+string naming an existing connection. `null`, `""`, and nonexistent names are
+invalid. The first explicitly named connection defaults a new registry; adding
+another preserves the existing default or no-default state. Existing v1 reads
+and named v1 imports remain supported; neither configuration version changes.
+
+Legacy project configuration compatibility: adding a connection cannot import a
+direct-project v2 registry when an existing connection uses an `envFile` other
+than `.env.local`. `init` refuses before writing and retains the existing config
+and env files. An administrator must migrate the registry and custom env files
+to supported home storage before retrying. Bound/home-storage v2 configs and
+direct-project v2 configs with no `envFile` or only `.env.local` remain supported.
+
+`init --remove <name>` clears `default` and reports that change when removing its
+connection; it never chooses another connection. Removing a non-default keeps
+the saved default, and removing a connection from a no-default config keeps that
+state. The public `removeConnection` helper follows the same rules. Deleting
+the last connection is rejected without changing the config. Renaming preserves
+the no-default state, or updates the default name when renaming that connection.
 
 Use root-level `--global` with `init`, `use`, `status`, `query`, or any other command to read or mutate the user-global v2 registry at `~/.config/dbcli/config.json`. Without it, the current project binding remains the source of truth. The global registry uses the same private file mode and integrity record as project home storage.
 
@@ -169,11 +195,12 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 ### use
 
-Switch or display the default database connection (v2 multi-connection config).
+Set, clear, or display the default database connection (v2 multi-connection config).
 
 ```bash
-dbcli use                   # Show current default connection
+dbcli use                   # Show the current default, or describe no default
 dbcli use staging           # Switch default to 'staging'
+dbcli use --unset            # Clear the saved default; connections are unchanged
 dbcli use --list            # List all connections (* marks default)
 dbcli use --list --format json # Credential-free connection identity inventory
 ```
@@ -188,17 +215,43 @@ Cloud ID-only Elasticsearch connections also return `null` instead of default
 placeholders. It deliberately excludes user names, passwords, URIs, Cloud IDs,
 API keys, and env variable names.
 Misspelled selectors suggest nearby configured connection names.
+Without a default, text inventory marks no connection as default and every JSON
+item has `isDefault: false`. Inventory remains usable, and `doctor` accepts an
+omitted default as valid v2 configuration. Its connection checks still require
+an explicit selector, for example `dbcli --use staging doctor`.
 
-Any command can also use `--use <name>` to temporarily select a connection without changing the default:
+Any command can also use root-level `--use <name>` before the command to
+temporarily select a connection without changing the default. `query`, `schema`,
+`list`, `export`, and `check` also accept it after the command:
 
 ```bash
 dbcli query --use staging "SELECT * FROM users LIMIT 10"
 dbcli list --use prod
 ```
 
+Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the
+saved default. Conflicting root-level and command-level selectors are an error;
+blank CLI selectors are invalid, while a blank environment selector is ignored.
+Without a default, connection-dependent commands require an explicit `--use` or
+`DBCLI_CONNECTION` selection. Otherwise they fail before database access with
+an error naming both selectors and listing available connection names, never
+endpoints or credentials. No caller selects the first connection automatically.
+Unknown names and production targets retain their validation and explicit
+selection safeguards.
+
+`use --unset` removes only the persisted v2 `default` field and reports that it
+was cleared. It also succeeds when the field is already absent without changing
+connections. It rejects a connection name, `--list`, `--confirm-production`, or
+`--format json` in the same invocation before writing, and never converts or
+overwrites v1. It uses the existing approved, integrity-protected configuration
+write path and is blocked under `DBCLI_AGENT_MODE=1`. To set a default again, use
+`dbcli use <name>`; production defaults still require the exact name repeated in
+`--confirm-production <name>`, and production database access still requires an
+explicit selector even if that connection is the saved default.
+
 **Requires v2 config** (created with `dbcli init --conn-name`).
 
-**Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
+**Options:** `--list`, `--unset`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
 
 ### password
 
@@ -3591,7 +3644,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.
 
-`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>`.
+`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 non-interactive path via `--uri` (with the required `--conn-name`). 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>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 
@@ -3617,10 +3670,10 @@ The 5000ms default server-selection timeout is often too tight for a connection
 
 ```bash
 # 1. Initialize — field-by-field (primary path)
-dbcli init --system mongodb --host localhost --port 27017 \
+dbcli init --conn-name local --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"
+dbcli init --conn-name local --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections
 dbcli list --format json

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": "9.1.2",
+  "version": "10.0.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

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

@@ -328,9 +328,10 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 
 ### Decision tree (ask before writing)
 
-1. **One DB or many environments?** One → v1 (single connection). Multiple
-   environments / tenants / replicas → v2 (`--conn-name <name>`, optionally
-   `--env-file <path>` per connection).
+1. **What is the connection name?** Every new connection uses named v2, even
+   for one DB. Confirm a nonblank `--conn-name <name>` (optionally an
+   `--env-file <path>` per connection). `--name` means the database, not the
+   connection. Existing v1 configs remain readable and support named v2 import.
 2. **Where do credentials live?**
    - Already in a `.env` (`DATABASE_URL` or `DB_HOST` / `DB_PORT` / `DB_USER` /
      `DB_PASSWORD` / `DB_NAME` | `DB_DATABASE`) → `init` parses it automatically.
@@ -347,31 +348,41 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
    blacklist summary, no creds) and `dbcli doctor --format json` (env, config
    shape, connectivity, schema-cache age, Mongo SRV path).
 
+`init` asks for a connection name in an interactive TTY when `--conn-name` is
+omitted, without suggesting `default`. Blank prompt answers are explained and
+re-prompted; cancellation/end of input stops before testing or writing. An explicit
+nonblank name skips this prompt; `--conn-name default` is valid. An explicitly
+blank `--conn-name` is an error in every mode before testing or writing. Non-TTY, `--no-interactive`,
+and complete `--use-env-refs`/`--env-*` automatic noninteractive mode require an
+explicit nonblank `--conn-name` or fail before database access or config/credential
+writes. Plain `init` and explicit `--config` paths both create named v2, never new
+unnamed v1. `--remove` and `--rename` do not prompt for a new connection name.
+
 ### Per-engine essentials
 
 ```bash
-# PostgreSQL / MySQL / MariaDB (v1, plain values)
-dbcli init --system postgresql --host localhost --port 5432 \
+# PostgreSQL / MySQL / MariaDB (named v2, plain values)
+dbcli init --conn-name local --system postgresql --host localhost --port 5432 \
   --user app --password '<secret>' --name appdb --permission query-only
 
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
 # 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 \
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --conn-name local --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 \
+dbcli init --conn-name local --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
 
 # 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
+dbcli init --conn-name local --system redis --host localhost --port 6379 --password '<secret>' --name 0
 
 # Elasticsearch — basic auth, Cloud ID, or API key
-dbcli init --system elasticsearch --host localhost --port 9200 \
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200 \
   --user elastic --password '<secret>'
-dbcli init --system elasticsearch \
+dbcli init --conn-name local --system elasticsearch \
   --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
 # Multi-node / custom CA / self-signed: edit `.dbcli` directly to add
 # `nodes: [...]`, `protocol: https`, `caPath`, `rejectUnauthorized: false`.
@@ -384,13 +395,37 @@ dbcli init --conn-name staging --env-file .env.staging --permission query-only
 dbcli init --conn-name prod    --env-file .env.production --use-env-refs --skip-test
 dbcli use --list --format json            # safe identity inventory: name/env/permission/server/database
 dbcli use prod                            # switch default (persists — avoid for one-off queries)
-dbcli query --use staging "SELECT 1"      # one-shot override on any subcommand
+dbcli use --unset                         # clear the saved default (v2 only; approved config mutation)
+dbcli --use staging query "SELECT 1"      # root-level one-shot selector before any subcommand
 DBCLI_CONNECTION=staging dbcli query "SELECT 1"   # one-shot via env; parallel-safe
 dbcli --use staging,prod query "SELECT count(*) FROM users"   # read-only fan-out
 dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+V2 may omit `default`; if present, it must be a nonempty existing connection
+name, never `null` or `""`. Without a default, connection-dependent commands
+require `--use` or `DBCLI_CONNECTION` and fail before database access with an
+available-name list, never endpoints or credentials. Do not pick the first name
+to bypass that choice. Priority remains `--use` > `DBCLI_CONNECTION` > saved
+default; conflicting root/command selectors and blank CLI selectors are errors,
+while a blank environment selector is absent. Unknown-name and production
+selection protections still apply.
+
+`use --unset` removes only the saved default, reports it cleared, and succeeds
+when already absent without changing connections. It rejects a name, `--list`,
+`--confirm-production`, or `--format json` without writing, and never converts or
+overwrites v1. This is an approved, integrity-protected config mutation, blocked
+in agent mode. `use` describes no default; text inventory has no default marker
+and JSON has `isDefault: false` throughout. `doctor` accepts this v2 shape; select
+a connection explicitly for its connection checks (`dbcli --use staging doctor`).
+Removing the default with `init --remove` clears it and reports that change,
+without choosing a replacement. Other removals preserve the current default or
+its absence; the last connection cannot be deleted. Renaming preserves no
+default, or updates the default name when appropriate. The first explicitly named
+connection defaults a new registry; additions preserve an existing default or
+no-default state. Existing v1 imports and production confirmation rules are unchanged.
+
 Rotating one connection's password — nothing else in the config moves:
 
 ```bash
@@ -440,11 +475,12 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 
 In an **interactive terminal**, omitting the `--env-*` flags prompts for each key name
 (defaults above) — you can type a non-default name like `PROD_DB_PASSWORD` and it is stored
-as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `--env-*`
+as a `$env` ref. In a **non-interactive / CI** run you **must** pass `--conn-name` and all five `--env-*`
 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.
+**MongoDB has fewer required env-reference flags**: besides `--conn-name`, 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
@@ -469,8 +505,10 @@ refs have no value to connect with yet.
   values are rejected.
 - **Elasticsearch TLS** — `caPath` and `rejectUnauthorized` are not exposed as
   flags; edit `.dbcli` after `init` to add them.
-- **Re-running `init`** — refuses to overwrite without `--force`; never use
-  `--force` to "fix" a config full of `{ "$env": "..." }` refs.
+- **Re-running `init` with the same name** — requires interactive overwrite
+  confirmation or `--force`; a noninteractive duplicate without `--force` or a
+  declined confirmation leaves files untouched. Never use `--force` to "fix"
+  a config full of `{ "$env": "..." }` refs or choose a name for the user.
 
 Full flags and edge cases: see [reference.md](reference.md#init).
 
@@ -478,7 +516,7 @@ Full flags and edge cases: see [reference.md](reference.md#init).
 
 | Command | Min permission | Summary |
 |---------|-----------------|---------|
-| `init` | n/a | Create `.dbcli` (v1 single or v2 multi via `--conn-name` / `--env-file`). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
+| `init` | n/a | Create a named v2 connection (`--conn-name` required outside an interactive TTY). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `capabilities` | n/a | Static capability catalog + `check --require <ids>` requirement gate. No database connection. `--format text\|json\|markdown` (`check` is `text\|json`). Exit `0`/`1`/`2`. |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |