@carllee1983/dbcli 1.42.0 → 1.43.0

package/.claude-plugin/plugin.json

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

package/.cursor/rules/dbcli.mdc

@@ -239,8 +239,10 @@ dbcli init --system elasticsearch \
 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                          # show all, * marks default
-dbcli use prod                            # switch default
+dbcli use prod                            # switch default (persists — avoid for one-off queries)
 dbcli query --use staging "SELECT 1"      # one-shot override on 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
 ```
@@ -296,7 +298,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
-| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
+| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. `--fields` (projection), `--truncate` (cell width), `-f/--query-file` (read query from file or stdin), `--use a,b` (read-only fan-out). Supports `--recovery`. See **Query workflow flags**. |
 | `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
 | `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
@@ -304,7 +306,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
 | `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. Supports `--recovery`. |
 | `delete` | data-admin+ | SQL or MongoDB; Redis has a basic implementation (see Redis section). `--where` required; `--dry-run` first. Supports `--recovery`. |
-| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
+| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. **Fails closed rather than truncating silently**: if the auto-limit would drop rows, the export errors out and you must pass `--no-limit` or `--limit N`. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
 | `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`, `--ignore <globs>`, `--format json\|table\|markdown`. Drizzle: point at `drizzle/meta/<NNNN>_snapshot.json` (run `drizzle-kit generate` first; `.ts` sources are rejected with a hint). TypeORM/Sequelize: feed tool-generated DDL (`schema:log` / a schema-only dump); source files are rejected with the exact generation command to run. |
@@ -325,8 +327,9 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
-`--use <name>` on any subcommand (including `status` / `doctor`) targets a v2 connection
-without changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
+Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,
+`export`, and `check` also accept command-level `--use`. Both target a v2 connection without
+changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
 `delete`, `export`, `schema`, `inspect`, `lint`, and `diff --against-orm` (see **On failure** above).
 
 **Write & query flag semantics** (SQL/Mongo `insert`/`update`):
@@ -344,6 +347,27 @@ without changing the default. `--recovery` is honoured by `query`, `q`, `insert`
 - `--recovery` is recommended for automated agent pipelines (enables `dbcli recover --apply`
   after a failure); optional for one-off manual writes.
 
+## Query workflow flags
+
+These exist so you do not have to pipe output through `head` / `jq` / `python3`
+to make it usable. Reach for them instead of post-processing.
+
+| Need | Flag | Notes |
+|------|------|-------|
+| Only some columns | `--fields sn,bet,created_at` | SQL and MongoDB. Mongo pushes a real `projection` / `$project` to the driver; `_id` is dropped unless you ask for it. A field the result lacks comes back as `null`, so verify spellings with `schema` before reading meaning into an all-null column. |
+| Everything except a huge column | `--fields=-raw_response` | Exclusion form. Include and exclude cannot be mixed. |
+| One field is a giant JSON blob | `--truncate 120` | Table output truncates cells at 120 chars **by default** and marks them `…(+3412 chars)`. `--no-truncate` disables it. Explicit truncation flags are rejected on JSON, CSV, HTML, and `--ui` output. |
+| Query has quotes / newlines / `$regex` | `-f pipeline.json` or `-f -` | Reads the query from a file or stdin; use a heredoc for Mongo pipelines. Passing both a file and positional query text is an error, never a silent pick. `-f -` needs piped input — it refuses an interactive terminal rather than hanging. |
+| Same query across connections | `--use hub-prod,site-a` | Read-only fan-out. Per-connection results, one failure does not cancel the others. Exit `0` all-ok, `2` mixed, `1` all-failed. Rejects writes, `--recovery`, `--ui`, CSV/HTML. |
+| Pick a connection for one call | `DBCLI_CONNECTION=hub-prod dbcli query …` | Env var, or `--use` on the subcommand. Priority: `--use` > `DBCLI_CONNECTION` > saved default. Neither writes the default back to disk, so parallel shells never fight. Requires a v2 config — a single-connection (v1) project rejects both rather than silently running its only connection. **Do not** use `dbcli use <name>` just to switch for one query. |
+
+**Truncation is reported, never implied.** When the query-only auto-limit trims a
+result, the table footer reads `Rows: 1000 (truncated; limit 1000)`, `--format json`
+carries `metadata.truncated` / `metadata.limit_applied`, and CSV appends a `#`
+comment. `Rows: 1000` with no marker means exactly 1000 rows exist — do not infer
+truncation from a round number. This applies to `query` and to `q` snippets
+(whose own 1000-row guard reports the same way). `export` refuses to truncate at all. Redis replies trimmed by the size guard report the same way, and each size-guard warning is printed on stderr.
+
 ## Permission levels
 
 | Level | Allowed |

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

@@ -112,7 +112,7 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 ### query
 
-Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
+Execute a SQL statement, MongoDB filter/pipeline, allow-listed Redis command, or Elasticsearch DSL/Lucene query.
 
 ```bash
 # SQL databases
@@ -143,13 +143,84 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Field projection (`--fields`)
+
+```bash
+dbcli query "SELECT * FROM bet_log" --fields sn,currency,bet
+dbcli query "SELECT * FROM bet_log" --fields=-raw_response,-created_at   # exclusion
+dbcli query '{"station_code":"cmg9998"}' --collection raw_bet_log --fields sn,bet
+```
+
+Include and exclude forms cannot be mixed. Dotted paths (`user.email`) are supported.
+On MongoDB the selection becomes a driver-level `projection` (find) or a trailing
+`$project` stage (aggregate), so the omitted fields never leave the server; `_id` is
+excluded unless listed explicitly. On SQL the rows are projected after fetch — write
+an explicit column list in the `SELECT` when you also want to cut transfer cost.
+Blacklisted columns stay blacklisted: naming one in `--fields` yields no value and the
+result still carries the blacklist `securityNotification`. A requested field that does
+not exist in the result comes back as `null`.
+
+#### Cell truncation (`--truncate`)
+
+```bash
+dbcli query "SELECT sn, raw_response FROM bet_log"                 # table: 120-char default
+dbcli query "SELECT sn, raw_response FROM bet_log" --truncate 40
+dbcli query "SELECT sn, raw_response FROM bet_log" --no-truncate
+```
+
+Table output truncates each serialized cell at 120 Unicode code points by default and
+appends `…(+N chars)`; counting by code point keeps multi-byte characters and emoji
+intact. `--truncate <n>` sets the width, `--no-truncate` disables it. Explicit truncation
+flags are rejected with JSON, CSV, HTML, and `--ui` output.
+
+#### Query from a file or stdin (`-f`)
+
+```bash
+dbcli query -f report.sql
+dbcli query --collection raw_bet_log -f - <<'EOF'
+[{"$match": {"sn": {"$regex": "^SN0000"}}}, {"$group": {"_id": "$currency", "n": {"$sum": 1}}}]
+EOF
+```
+
+Avoids shell quoting entirely — the usual reason a Mongo pipeline containing `$regex`
+or nested date objects fails. Supplying both `--query-file` and positional query text
+is an error rather than a silent choice, and an empty file or empty stdin is refused.
+`-f -` requires piped input: on an interactive terminal dbcli refuses immediately
+instead of waiting silently for input that is never coming.
+
+#### One-shot connection selection and read-only fan-out
+
+Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the saved default.
+`query`, `schema`, `list`, `export`, and `check` accept command-level `--use`; for other
+commands use root-level `dbcli --use <name> <command>`. One-shot selectors never update the
+saved default and require a v2 config. A legacy v1 single-connection config rejects them
+instead of silently running its only connection.
+
+An explicit comma-separated `--use primary,staging` fans one query out to several named
+connections. `DBCLI_CONNECTION` always names one literal connection and never enables
+fan-out. SQL permits `SELECT`, `SHOW`, `DESCRIBE`, and `EXPLAIN`; MongoDB permits filters and
+read-only pipelines without top-level `$out` / `$merge`; Elasticsearch permits searches.
+Redis, writes, `--recovery`, `--ui`, CSV, and HTML are rejected before execution. Each
+connection keeps its own blacklist, limit metadata, audit entry, and error. Aggregate exit
+codes are `0` when all succeed, `2` for mixed outcomes, and `1` when all fail or preflight
+rejects the request.
+
+#### Truncation is stated, not implied
+
+When the query-only auto-limit trims the result, the table footer reads
+`Rows: 1000 (truncated; limit 1000)`, `--format json` carries
+`metadata.truncated` and `metadata.limit_applied`, and CSV appends a `#` comment line.
+dbcli fetches one row past the cap to decide this, so a result of exactly 1000 rows is
+reported as `truncated: false` — never infer truncation from a round row count.
+
 > **MongoDB notes:**
 > - SQL syntax is rejected — use JSON object (filter) or JSON array (pipeline)
 > - `--collection <name>` is required
-> - Auto-limit does not apply; use `$limit` in your pipeline if needed
+> - Query-only auto-limit applies to filters and to pipelines without their own
+>   `$limit`; the applied cap and truncation are reported in the result metadata
 
 > **Redis notes:**
 > - The first token must be an allow-listed command (`GET`/`SET`/`HGET`/`HSET`/`DEL`/...). Unknown commands are refused.
@@ -661,9 +732,13 @@ dbcli export orders --no-limit --format jsonl             # scroll the whole ind
 **Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
+If the query-only auto-limit would omit rows, export fails closed with exit code `1` and
+writes no partial file. Re-run with `--no-limit` to export everything, or `--limit N` to
+accept a bounded export explicitly. This applies to SQL, MongoDB, and Elasticsearch.
+
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
 
-> **Elasticsearch export (v1.22):** pass a search DSL with `--index <index>` to export the hits, or pass an index name as the query to scroll the whole index via `match_all`. Default cap is 1000 rows; `--no-limit` streams the full index via scroll in batches. Index-level blacklist is checked before export and an audit record is written.
+> **Elasticsearch export (v1.22):** pass a search DSL with `--index <index>` to export the hits, or pass an index name as the query to scroll the whole index via `match_all`. Default cap is 1000 rows; reaching it fails closed unless the caller explicitly uses `--limit N`, while `--no-limit` streams the full index via scroll in batches. Index-level blacklist is checked before export and an audit record is written.
 
 ### blacklist
 

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

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

@@ -239,8 +239,10 @@ dbcli init --system elasticsearch \
 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                          # show all, * marks default
-dbcli use prod                            # switch default
+dbcli use prod                            # switch default (persists — avoid for one-off queries)
 dbcli query --use staging "SELECT 1"      # one-shot override on 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
 ```
@@ -296,7 +298,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `use` | n/a | Show/switch default named connection (v2 only). |
 | `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
-| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
+| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. `--fields` (projection), `--truncate` (cell width), `-f/--query-file` (read query from file or stdin), `--use a,b` (read-only fan-out). Supports `--recovery`. See **Query workflow flags**. |
 | `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
 | `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
@@ -304,7 +306,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
 | `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. Supports `--recovery`. |
 | `delete` | data-admin+ | SQL or MongoDB; Redis has a basic implementation (see Redis section). `--where` required; `--dry-run` first. Supports `--recovery`. |
-| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
+| `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. **Fails closed rather than truncating silently**: if the auto-limit would drop rows, the export errors out and you must pass `--no-limit` or `--limit N`. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
 | `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`, `--ignore <globs>`, `--format json\|table\|markdown`. Drizzle: point at `drizzle/meta/<NNNN>_snapshot.json` (run `drizzle-kit generate` first; `.ts` sources are rejected with a hint). TypeORM/Sequelize: feed tool-generated DDL (`schema:log` / a schema-only dump); source files are rejected with the exact generation command to run. |
@@ -325,8 +327,9 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
-`--use <name>` on any subcommand (including `status` / `doctor`) targets a v2 connection
-without changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
+Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,
+`export`, and `check` also accept command-level `--use`. Both target a v2 connection without
+changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
 `delete`, `export`, `schema`, `inspect`, `lint`, and `diff --against-orm` (see **On failure** above).
 
 **Write & query flag semantics** (SQL/Mongo `insert`/`update`):
@@ -344,6 +347,27 @@ without changing the default. `--recovery` is honoured by `query`, `q`, `insert`
 - `--recovery` is recommended for automated agent pipelines (enables `dbcli recover --apply`
   after a failure); optional for one-off manual writes.
 
+## Query workflow flags
+
+These exist so you do not have to pipe output through `head` / `jq` / `python3`
+to make it usable. Reach for them instead of post-processing.
+
+| Need | Flag | Notes |
+|------|------|-------|
+| Only some columns | `--fields sn,bet,created_at` | SQL and MongoDB. Mongo pushes a real `projection` / `$project` to the driver; `_id` is dropped unless you ask for it. A field the result lacks comes back as `null`, so verify spellings with `schema` before reading meaning into an all-null column. |
+| Everything except a huge column | `--fields=-raw_response` | Exclusion form. Include and exclude cannot be mixed. |
+| One field is a giant JSON blob | `--truncate 120` | Table output truncates cells at 120 chars **by default** and marks them `…(+3412 chars)`. `--no-truncate` disables it. Explicit truncation flags are rejected on JSON, CSV, HTML, and `--ui` output. |
+| Query has quotes / newlines / `$regex` | `-f pipeline.json` or `-f -` | Reads the query from a file or stdin; use a heredoc for Mongo pipelines. Passing both a file and positional query text is an error, never a silent pick. `-f -` needs piped input — it refuses an interactive terminal rather than hanging. |
+| Same query across connections | `--use hub-prod,site-a` | Read-only fan-out. Per-connection results, one failure does not cancel the others. Exit `0` all-ok, `2` mixed, `1` all-failed. Rejects writes, `--recovery`, `--ui`, CSV/HTML. |
+| Pick a connection for one call | `DBCLI_CONNECTION=hub-prod dbcli query …` | Env var, or `--use` on the subcommand. Priority: `--use` > `DBCLI_CONNECTION` > saved default. Neither writes the default back to disk, so parallel shells never fight. Requires a v2 config — a single-connection (v1) project rejects both rather than silently running its only connection. **Do not** use `dbcli use <name>` just to switch for one query. |
+
+**Truncation is reported, never implied.** When the query-only auto-limit trims a
+result, the table footer reads `Rows: 1000 (truncated; limit 1000)`, `--format json`
+carries `metadata.truncated` / `metadata.limit_applied`, and CSV appends a `#`
+comment. `Rows: 1000` with no marker means exactly 1000 rows exist — do not infer
+truncation from a round number. This applies to `query` and to `q` snippets
+(whose own 1000-row guard reports the same way). `export` refuses to truncate at all. Redis replies trimmed by the size guard report the same way, and each size-guard warning is printed on stderr.
+
 ## Permission levels
 
 | Level | Allowed |

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

@@ -112,7 +112,7 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 ### query
 
-Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
+Execute a SQL statement, MongoDB filter/pipeline, allow-listed Redis command, or Elasticsearch DSL/Lucene query.
 
 ```bash
 # SQL databases
@@ -143,13 +143,84 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Field projection (`--fields`)
+
+```bash
+dbcli query "SELECT * FROM bet_log" --fields sn,currency,bet
+dbcli query "SELECT * FROM bet_log" --fields=-raw_response,-created_at   # exclusion
+dbcli query '{"station_code":"cmg9998"}' --collection raw_bet_log --fields sn,bet
+```
+
+Include and exclude forms cannot be mixed. Dotted paths (`user.email`) are supported.
+On MongoDB the selection becomes a driver-level `projection` (find) or a trailing
+`$project` stage (aggregate), so the omitted fields never leave the server; `_id` is
+excluded unless listed explicitly. On SQL the rows are projected after fetch — write
+an explicit column list in the `SELECT` when you also want to cut transfer cost.
+Blacklisted columns stay blacklisted: naming one in `--fields` yields no value and the
+result still carries the blacklist `securityNotification`. A requested field that does
+not exist in the result comes back as `null`.
+
+#### Cell truncation (`--truncate`)
+
+```bash
+dbcli query "SELECT sn, raw_response FROM bet_log"                 # table: 120-char default
+dbcli query "SELECT sn, raw_response FROM bet_log" --truncate 40
+dbcli query "SELECT sn, raw_response FROM bet_log" --no-truncate
+```
+
+Table output truncates each serialized cell at 120 Unicode code points by default and
+appends `…(+N chars)`; counting by code point keeps multi-byte characters and emoji
+intact. `--truncate <n>` sets the width, `--no-truncate` disables it. Explicit truncation
+flags are rejected with JSON, CSV, HTML, and `--ui` output.
+
+#### Query from a file or stdin (`-f`)
+
+```bash
+dbcli query -f report.sql
+dbcli query --collection raw_bet_log -f - <<'EOF'
+[{"$match": {"sn": {"$regex": "^SN0000"}}}, {"$group": {"_id": "$currency", "n": {"$sum": 1}}}]
+EOF
+```
+
+Avoids shell quoting entirely — the usual reason a Mongo pipeline containing `$regex`
+or nested date objects fails. Supplying both `--query-file` and positional query text
+is an error rather than a silent choice, and an empty file or empty stdin is refused.
+`-f -` requires piped input: on an interactive terminal dbcli refuses immediately
+instead of waiting silently for input that is never coming.
+
+#### One-shot connection selection and read-only fan-out
+
+Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the saved default.
+`query`, `schema`, `list`, `export`, and `check` accept command-level `--use`; for other
+commands use root-level `dbcli --use <name> <command>`. One-shot selectors never update the
+saved default and require a v2 config. A legacy v1 single-connection config rejects them
+instead of silently running its only connection.
+
+An explicit comma-separated `--use primary,staging` fans one query out to several named
+connections. `DBCLI_CONNECTION` always names one literal connection and never enables
+fan-out. SQL permits `SELECT`, `SHOW`, `DESCRIBE`, and `EXPLAIN`; MongoDB permits filters and
+read-only pipelines without top-level `$out` / `$merge`; Elasticsearch permits searches.
+Redis, writes, `--recovery`, `--ui`, CSV, and HTML are rejected before execution. Each
+connection keeps its own blacklist, limit metadata, audit entry, and error. Aggregate exit
+codes are `0` when all succeed, `2` for mixed outcomes, and `1` when all fail or preflight
+rejects the request.
+
+#### Truncation is stated, not implied
+
+When the query-only auto-limit trims the result, the table footer reads
+`Rows: 1000 (truncated; limit 1000)`, `--format json` carries
+`metadata.truncated` and `metadata.limit_applied`, and CSV appends a `#` comment line.
+dbcli fetches one row past the cap to decide this, so a result of exactly 1000 rows is
+reported as `truncated: false` — never infer truncation from a round row count.
+
 > **MongoDB notes:**
 > - SQL syntax is rejected — use JSON object (filter) or JSON array (pipeline)
 > - `--collection <name>` is required
-> - Auto-limit does not apply; use `$limit` in your pipeline if needed
+> - Query-only auto-limit applies to filters and to pipelines without their own
+>   `$limit`; the applied cap and truncation are reported in the result metadata
 
 > **Redis notes:**
 > - The first token must be an allow-listed command (`GET`/`SET`/`HGET`/`HSET`/`DEL`/...). Unknown commands are refused.
@@ -661,9 +732,13 @@ dbcli export orders --no-limit --format jsonl             # scroll the whole ind
 **Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
+If the query-only auto-limit would omit rows, export fails closed with exit code `1` and
+writes no partial file. Re-run with `--no-limit` to export everything, or `--limit N` to
+accept a bounded export explicitly. This applies to SQL, MongoDB, and Elasticsearch.
+
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
 
-> **Elasticsearch export (v1.22):** pass a search DSL with `--index <index>` to export the hits, or pass an index name as the query to scroll the whole index via `match_all`. Default cap is 1000 rows; `--no-limit` streams the full index via scroll in batches. Index-level blacklist is checked before export and an audit record is written.
+> **Elasticsearch export (v1.22):** pass a search DSL with `--index <index>` to export the hits, or pass an index name as the query to scroll the whole index via `match_all`. Default cap is 1000 rows; reaching it fails closed unless the caller explicitly uses `--limit N`, while `--no-limit` streams the full index via scroll in batches. Index-level blacklist is checked before export and an audit record is written.
 
 ### blacklist
 

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.43.0] - 2026-08-02 - Agent Core、查詢完整性與跨平台修復
+
+### Added
+
+- **穩定的 `./agent-core` 子路徑匯出。** 以五個 runtime functions（env 載入、env reference、連線選取、名稱解析、lookahead 截斷）與三個型別形成 agent CLI 共用的 semver interface；`./core` 仍是 dbcli 專用介面。建置同時產出 ESM 與型別宣告，CI purity gate 禁止資料庫、adapter 或 CLI framework 相依滲入。
+- **欄位投影 `--fields`。** SQL 與 MongoDB 通用；`--fields a,b` 取用、`--fields=-raw_response` 排除，兩種形式不可混用。MongoDB 會把 `projection`（find）或 `$project`（aggregate）下推給 driver，未明確指定時不回傳 `_id`。黑名單欄位不會因為被 `--fields` 點名而洩漏。
+- **欄位值截斷 `--truncate`。** table 輸出預設在 120 個 Unicode code point 截斷並標記 `…(+N chars)`，以 code point 計數所以不會切壞中文與 emoji；`--no-truncate` 可關閉。`--format json` / `csv` 會拒絕此旗標而非靜默忽略。
+- **從檔案或 stdin 讀查詢 `-f, --query-file`。** `-f -` 讀 stdin，可用 heredoc 傳含 `$regex`、巢狀日期物件的 MongoDB pipeline，完全避開 shell 引號問題。同時給檔案與位置參數會明確報錯。
+- **單次連線指定。** 新增 `DBCLI_CONNECTION` 環境變數，`query` / `list` / `schema` / `export` / `check` 也接受子指令層級的 `--use`。優先序為 `--use` > `DBCLI_CONNECTION` > 儲存的預設值，兩者都不會改寫 `.dbcli/config.json`，因此平行執行不會互相污染。
+- **唯讀多連線扇出 `--use a,b`。** 同一查詢對多個連線執行，JSON 回傳 `results` 陣列並逐一標示 `ok` / `error`，table 則分段標註連線名。單一連線失敗不會取消其他連線。彙總 exit code：全成功 `0`、部分失敗 `2`、全失敗或執行前拒絕 `1`。寫入語句、`--recovery`、`--ui` 與 CSV/HTML 輸出在扇出下一律拒絕。
+
+### Changed
+
+- **HTML dashboard 明示不完整與遮蔽結果。** `query`、`q` 與 HTML export 會把既有的截斷與 security metadata 傳入 dashboard；在 KPI、圖表與 raw table 之前顯示醒目提示，避免使用不完整資料得出結論。
+- **截斷改為出現在結果本身。** dbcli 擁有的 row cap 會多取一列前瞻，因此能區分「剛好 N 筆」與「被砍到 N 筆」：table footer 顯示 `Rows: N (truncated; limit N)`、`--format json` 帶 `metadata.truncated` 與 `metadata.limit_applied`、CSV 附加 `# truncated; limit N` 註解行。`dbcli q` 的 snippet size guard 同樣依此回報，不再讓整數列數被誤讀為全集。
+- **`dbcli export` 撞到 auto-limit 改為 fail closed。** 匯出檔沒有地方記錄資料被丟掉（jsonl 是一行一筆、MongoDB `--format json` 是裸陣列），stderr 警告又會在重導向後消失，因此改為 exit `1` 且不寫檔，要求以 `--no-limit` 或 `--limit N` 明確表態。Elasticsearch 匯出的 1000 筆上限同此處理。
+- **CLI 錯誤輸出收斂。** 連線類錯誤在所有指令路徑都會被頂層 handler 攔截並格式化，stderr 首行即為人類可讀訊息，不再由 Bun 印出打包後的 code frame 與未解碼的中文跳脫序列。stack 改掛在 `-v` / `-vv` 之下，預設不輸出。
+
+### Fixed
+
+- **MySQL 8 schema introspection 相容預設 `ONLY_FULL_GROUP_BY`。** 外鍵查詢現在完整分組 referenced table，不再讓 `dbcli schema <table>` 在原廠預設設定下失敗。
+- **已分類的連線錯誤不再被巢狀 adapter catch 重包。** `mapError` 直接保留既有 `ConnectionError` 的 identity、code、message 與 hints，消除 `Connection failed: Connection failed:` 重複前綴與分類退化。
+- **stdout 管線與 Windows CI 修復。** redirected stdout 以完整同步寫入避免 64KB 截斷；測試 filesystem 與換行處理改為跨平台實作，Windows matrix 恢復全綠。
+- **發布依賴安全更新。** 將 PostCSS 鎖定至 `8.5.25`、`brace-expansion` 鎖定至 `5.0.9`，清除 release gate 回報的 3 個 high-severity advisories；並統一 Prettier 格式，讓完整 9 階段發布檢查恢復全綠。
+- **`--no-limit` 過去被靜默忽略。** Commander 會把 `--no-limit` 折進 `limit` 屬性（設為 `false`）而不會產生 `noLimit`，但 `query` / `q` / `export` 都讀 `options.noLimit`，導致這個旗標自始無效——`query` 仍套用 1000 筆上限，`q` 仍包 size guard。CLI 邊界現在會把 Commander 的否定形式轉回指令實際讀取的形狀。
+- **`dbcli export` 的 SQL 路徑忽略 `--limit` 與 `--no-limit`。** 該分支未把選項傳給 QueryExecutor，任何 `--limit N` 都不生效。
+- **`-v` / `-vv` 的 stack 開關過去對 `q` / `insert` / `update` / `delete` 無效。** 這四個指令自行輸出在地化訊息、繞過共用的錯誤呈現層，因此 verbose 對它們不會多印任何東西。改為共用同一個呈現函式：措辭維持不變，但 verbose 下會補上 stack。
+- **Redis 的 size-guard warning 在 `query` 被丟棄。** adapter 早已算出 `REDIS_SIZE_TRUNCATE` / `REDIS_SIZE_REWRITE` / `REDIS_BLACKLIST_FILTERED`，但 `query` 分支完全沒讀 `result.warnings`——文件卻聲稱結果會帶 `warnings[]`。現在每則 warning 都會印到 stderr，且被裁切的回覆會回報 `truncated` / `limit_applied`，與其他引擎一致。
+- **`--query-file -` 在互動式終端會無提示空等。** 改為立即拒絕並說明需要 piped input，與 repo 中其他 stdin 消費端（`insert`、`shell`、`audit`）既有的 TTY 檢查一致。
+- **單一連線 (v1) 設定會靜默忽略 `--use` / `DBCLI_CONNECTION`。** v1 沒有具名連線可選，過去卻照樣執行那唯一的連線，讓使用者以為切換成功——正是 issue #7 要避免的情境。現在會明確報錯並指出升級為 v2 的方式。
+- **skill assets 與 reference 補齊。** `assets/SKILL.md`、`SKILL.zh-TW.md` 與 `reference.md` 新增查詢工作流程旗標章節；`reference.md` 原本記載「MongoDB 不套用 auto-limit」與實際行為不符，已更正為套用於 filter 與未自帶 `$limit` 的 pipeline。
+
 ## [1.42.0] - 2026-07-20 - Drizzle Snapshot 與 ORM DDL 工作流擴充
 
 ### Added

package/README.dev.md

@@ -42,7 +42,7 @@ Before running `npm publish`:
    ```bash
    npm pack --dry-run
    ```
-   Expect **`dist/`** (at least `cli.mjs`), **`assets/`** (e.g. `SKILL.md`, `reference.md` for `dbcli skill`), **`README.md`**, **`CHANGELOG.md`**, **`LICENSE`**, and **`package.json`**. There must be **no** `src/`, `tests/`, or `node_modules/`. The listing may also include other root `README*.md` files (npm can still pack them even when `files` is set); dev-only readmes are listed in **`.npmignore`** — re-check with dry-run if you add or remove docs.
+   Expect **`dist/`** (including `cli.mjs`, `core.mjs` / `core.d.ts`, and `agent-core.mjs` / `agent-core.d.ts`), **`assets/`** (e.g. `SKILL.md`, `reference.md` for `dbcli skill`), **`README.md`**, **`CHANGELOG.md`**, **`LICENSE`**, and **`package.json`**. There must be **no** `src/`, `tests/`, or `node_modules/`. The listing may also include other root `README*.md` files (npm can still pack them even when `files` is set); dev-only readmes are listed in **`.npmignore`** — re-check with dry-run if you add or remove docs.
 
 5. **Check package size:**
    ```bash