docs: README 补充 delete 批量删除与 --dry-run 示例

Made-with: Cursor
feat: delete 命令支持批量删除，--name 改为可选
2026-03-19 16:32:20 +08:00 · 2026-03-19 16:31:18 +08:00 · 2026-03-19 16:08:27 +08:00 · 2026-03-19 15:46:57 +08:00
24 changed files with 634 additions and 358 deletions
--- a/.gitea/workflows/secrets.yml
+++ b/.gitea/workflows/secrets.yml
@@ -17,6 +17,7 @@ permissions:

 env:
  BINARY_NAME: secrets
+  SECRETS_UPGRADE_URL: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/latest
  CARGO_INCREMENTAL: 0
  CARGO_NET_RETRY: 10
  CARGO_TERM_COLOR: always
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -142,7 +142,7 @@
    {
      "label": "test: add with file secret",
      "type": "shell",
-      "command": "echo '--- add key from file ---' && ./target/debug/secrets add -n test --kind key --name test-key --tag test -s content=@./refining/keys/Vultr && echo '--- verify metadata ---' && ./target/debug/secrets search -n test --kind key && echo '--- verify inject ---' && ./target/debug/secrets inject -n test --kind key --name test-key && echo '--- cleanup ---' && ./target/debug/secrets delete -n test --kind key --name test-key",
+      "command": "echo '--- add key from file ---' && ./target/debug/secrets add -n test --kind key --name test-key --tag test -s content=@./test-fixtures/example-key.pem && echo '--- verify metadata ---' && ./target/debug/secrets search -n test --kind key && echo '--- verify inject ---' && ./target/debug/secrets inject -n test --kind key --name test-key && echo '--- cleanup ---' && ./target/debug/secrets delete -n test --kind key --name test-key",
      "dependsOn": "build"
    }
  ]
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,8 @@ secrets/
      search.rs          # search 命令：多条件查询，展示 secrets 字段 schema（无需 master_key）
      delete.rs          # delete 命令：事务化，CASCADE 删除 secrets，含历史快照
      update.rs          # update 命令：增量更新，secrets 行级 UPSERT/DELETE，CAS 并发保护
-      rollback.rs        # rollback / history 命令：按 entry_version 恢复 entry + secrets
+      rollback.rs        # rollback 命令：按 entry_version 恢复 entry + secrets
+      history.rs         # history 命令：查看 entry 变更历史列表
      run.rs             # inject / run 命令：逐字段解密 + key_ref 引用解析
      upgrade.rs         # upgrade 命令：检查、校验摘要并下载最新版本，自动替换二进制
      export_cmd.rs      # export 命令：批量导出记录，支持 JSON/TOML/YAML，含解密明文
@@ -144,9 +145,9 @@ secrets_history (
 |------|--------|------|
 | `namespace` | 项目/团队隔离 | `refining`, `ricnsmart` |
 | `kind` | 记录类型 | `server`, `service`, `key` |
-| `name` | 唯一标识名 | `i-uf63f2uookgs5uxmrdyc`, `gitea` |
+| `name` | 唯一标识名 | `i-example0abcd1234efgh`, `gitea` |
 | `tags` | 多维分类标签 | `["aliyun","hongkong","ricn"]` |
-| `metadata` | 明文非敏感信息 | `{"ip":"47.243.154.187","desc":"Grafana","key_ref":"ricn-hk-260127"}` |
+| `metadata` | 明文非敏感信息 | `{"ip":"192.0.2.1","desc":"Grafana","key_ref":"my-shared-key"}` |
 | `secrets.field_name` | 加密字段名（明文） | `"username"`, `"token"`, `"ssh_key"` |
 | `secrets.field_type` | 值类型（明文） | `"string"`, `"number"`, `"boolean"`, `"json"` |
 | `secrets.value_len` | 原始值字符数（明文） | `4`（root），`40`（token），`4096`（PEM） |
@@ -158,17 +159,17 @@ secrets_history (

 ```bash
 # 1. 存共享 PEM
-secrets add -n refining --kind key --name ricn-hk-260127 \
+secrets add -n refining --kind key --name my-shared-key \
  --tag aliyun --tag hongkong \
-  -s content=@./keys/ricn-hk-260127.pem
+  -s content=@./keys/my-shared-key.pem

 # 2. 服务器通过 metadata.key_ref 引用（inject/run 时自动合并 key 的 secrets）
-secrets add -n refining --kind server --name i-j6c39dmtkr26vztii0ox \
-  -m ip=47.243.154.187 -m key_ref=ricn-hk-260127 \
+secrets add -n refining --kind server --name i-example0xyz789 \
+  -m ip=192.0.2.1 -m key_ref=my-shared-key \
  -s username=ecs-user

 # 3. 轮换只需更新 key 记录，所有引用服务器自动生效
-secrets update -n refining --kind key --name ricn-hk-260127 \
+secrets update -n refining --kind key --name my-shared-key \
  -s content=@./keys/new-key.pem
 ```

@@ -230,7 +231,7 @@ secrets init
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
-#   --name             gitea | i-uf63f2uookgs5uxmrdyc | mqtt
+#   --name             gitea | i-example0abcd1234efgh | mqtt
 #   --tag              aliyun | hongkong | production
 #   -q / --query       mqtt | grafana | gitea   （模糊匹配 name/namespace/kind/tags/metadata）
 #   secrets schema  search 默认展示 secrets 字段名、类型与长度（无需 master_key）
@@ -248,7 +249,7 @@ secrets search --sort updated --limit 10 --summary

 # 精确定位单条记录
 secrets search -n refining --kind service --name gitea
-secrets search -n refining --kind server --name i-uf63f2uookgs5uxmrdyc
+secrets search -n refining --kind server --name i-example0abcd1234efgh

 # 精确定位并获取完整内容（secrets 保持加密占位）
 secrets search -n refining --kind service --name gitea -o json
@@ -265,7 +266,7 @@ secrets run -n refining --kind service --name gitea -- printenv
 # 模糊关键词搜索
 secrets search -q mqtt
 secrets search -q grafana
-secrets search -q 47.117
+secrets search -q 192.0.2

 # 按条件过滤
 secrets search -n refining --kind service
@@ -289,31 +290,31 @@ secrets search -n refining --kind service | jq '.[].name'
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
-#   --name             gitea | i-uf63f2uookgs5uxmrdyc
+#   --name             gitea | i-example0abcd1234efgh
 #   --tag              aliyun | hongkong（可重复）
-#   -m / --meta        ip=47.117.131.22 | desc="Aliyun ECS" | url=https://... | tls:cert@./cert.pem（可重复）
+#   -m / --meta        ip=10.0.0.1 | desc="ECS" | url=https://... | tls:cert@./cert.pem（可重复）
 #   -s / --secret      token=<value> | ssh_key=@./key.pem | password=secret123 | credentials:content@./key.pem（可重复）

 # 添加服务器
-secrets add -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
+secrets add -n refining --kind server --name i-example0abcd1234efgh \
  --tag aliyun --tag shanghai \
-  -m ip=47.117.131.22 -m desc="Aliyun Shanghai ECS" \
-  -s username=root -s ssh_key=@./keys/voson_shanghai_e.pem
+  -m ip=10.0.0.1 -m desc="Aliyun Shanghai ECS" \
+  -s username=root -s ssh_key=@./keys/deploy-key.pem

 # 添加服务凭据
 secrets add -n refining --kind service --name gitea \
  --tag gitea \
-  -m url=https://gitea.refining.dev -m default_org=refining -m username=voson \
+  -m url=https://code.example.com -m default_org=refining -m username=voson \
  -s token=<token> -s runner_token=<runner_token>

 # 从文件读取 token
 secrets add -n ricnsmart --kind service --name mqtt \
-  -m host=mqtt.ricnsmart.com -m port=1883 \
+  -m host=mqtt.example.com -m port=1883 \
  -s password=@./mqtt_password.txt

 # 多行文件直接写入嵌套 secret 字段
-secrets add -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
-  -s credentials:content@./keys/voson_shanghai_e.pem
+secrets add -n refining --kind server --name i-example0abcd1234efgh \
+  -s credentials:content@./keys/deploy-key.pem

 # 使用类型化值（key:=<json>）存储非字符串类型
 secrets add -n refining --kind service --name prometheus \
@@ -333,7 +334,7 @@ secrets add -n refining --kind service --name prometheus \
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
-#   --name             gitea | i-uf63f2uookgs5uxmrdyc
+#   --name             gitea | i-example0abcd1234efgh
 #   --add-tag          production | backup（不影响已有 tag，可重复）
 #   --remove-tag       staging | deprecated（可重复）
 #   -m / --meta        ip=10.0.0.1 | desc="新描述" | credentials:username=root（新增或覆盖，可重复）
@@ -342,7 +343,7 @@ secrets add -n refining --kind service --name prometheus \
 #   --remove-secret    old_password | deprecated_key | credentials:content（删除 secret 字段，可重复）

 # 更新单个 metadata 字段
-secrets update -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
+secrets update -n refining --kind server --name i-example0abcd1234efgh \
  -m ip=10.0.0.1

 # 轮换 token
@@ -359,11 +360,11 @@ secrets update -n refining --kind service --name mqtt \
  --remove-meta old_port --remove-secret old_password

 # 从文件更新嵌套 secret 字段
-secrets update -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
-  -s credentials:content@./keys/voson_shanghai_e.pem
+secrets update -n refining --kind server --name i-example0abcd1234efgh \
+  -s credentials:content@./keys/deploy-key.pem

 # 删除嵌套字段
-secrets update -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
+secrets update -n refining --kind server --name i-example0abcd1234efgh \
  --remove-secret credentials:content

 # 移除 tag
@@ -372,19 +373,34 @@ secrets update -n refining --kind service --name gitea --remove-tag staging

 ---

-### delete — 删除记录
+### delete — 删除记录（支持单条精确删除与批量删除）
+
+删除时会自动将 entry 与所有关联 secret 字段快照到历史表，并写入审计日志，可通过 `rollback` 命令恢复。

 ```bash
 # 参数说明（带典型值）
-#   -n / --namespace   refining | ricnsmart
-#   --kind             server | service
-#   --name             gitea | i-uf63f2uookgs5uxmrdyc（必须精确匹配）
+#   -n / --namespace   refining | ricnsmart（必填）
+#   --kind             server | service（指定 --name 时必填；批量时可选）
+#   --name             gitea | i-example0abcd1234efgh（精确匹配；省略则批量删除）
+#   --dry-run          预览将删除的记录，不实际写入（仅批量模式有效）
+#   -o / --output      text | json | json-compact

-# 删除服务凭据
+# 精确删除单条记录（--kind 必填）
 secrets delete -n refining --kind service --name legacy-mqtt
-
-# 删除服务器记录
 secrets delete -n ricnsmart --kind server --name i-old-server-id
+
+# 预览批量删除（不写入数据库）
+secrets delete -n refining --dry-run
+secrets delete -n ricnsmart --kind server --dry-run
+
+# 批量删除整个 namespace 的所有记录
+secrets delete -n ricnsmart
+
+# 批量删除 namespace 下指定 kind 的所有记录
+secrets delete -n ricnsmart --kind server
+
+# JSON 输出
+secrets delete -n refining --kind service -o json
 ```

 ---
@@ -483,7 +499,9 @@ secrets run -n refining --kind service --name gitea -- printenv

 ### upgrade — 自动更新 CLI 二进制

-从 Gitea Release 下载最新版本，校验对应 `.sha256` 摘要后替换当前二进制，无需数据库连接或主密钥。
+从 Release 服务器下载最新版本，校验对应 `.sha256` 摘要后替换当前二进制，无需数据库连接或主密钥。
+
+**配置方式**：`SECRETS_UPGRADE_URL` 必填。优先用**构建时**：`SECRETS_UPGRADE_URL=https://... cargo build`，CI 已自动注入。或**运行时**：写在 `.env` 或 `export` 后执行。

 ```bash
 # 检查是否有新版本（不下载）
@@ -503,7 +521,7 @@ secrets upgrade
 # 参数说明
 # -n / --namespace refining | ricnsmart
 # --kind server | service
-# --name gitea | i-uf63f2uookgs5uxmrdyc
+# --name gitea | i-example0abcd1234efgh
 # --tag aliyun | production（可重复）
 # -q / --query 模糊关键词
 # --file <path>   输出文件路径，格式由扩展名推断（.json / .toml / .yaml / .yml）
@@ -663,5 +681,6 @@ cargo fmt -- --check && cargo clippy -- -D warnings && cargo test
 |------|------|
 | `RUST_LOG` | 日志级别，如 `secrets=debug`、`secrets=trace`（默认 warn） |
 | `USER` | 审计日志 actor 字段来源，Shell 自动设置，通常无需手动配置 |
+| `SECRETS_UPGRADE_URL` | upgrade 的 Release API 地址。构建时（cargo build）或运行时（.env/export） |

 数据库连接通过 `secrets config set-db` 持久化到 `~/.config/secrets/config.toml`，不支持环境变量。
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1836,7 +1836,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"

 [[package]]
 name = "secrets"
-version = "0.9.0"
+version = "0.9.3"
 dependencies = [
 "aes-gcm",
 "anyhow",
@@ -1844,6 +1844,7 @@ dependencies = [
 "chrono",
 "clap",
 "dirs",
+ "dotenvy",
 "flate2",
 "keyring",
 "rand 0.10.0",
@@ -2448,7 +2449,6 @@ dependencies = [
 "bytes",
 "libc",
 "mio",
- "parking_lot",
 "pin-project-lite",
 "signal-hook-registry",
 "socket2",
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,32 +1,33 @@
 [package]
 name = "secrets"
-version = "0.9.0"
+version = "0.9.3"
 edition = "2024"

 [dependencies]
-aes-gcm = "0.10.3"
-anyhow = "1.0.102"
-argon2 = { version = "0.5.3", features = ["std"] }
-chrono = { version = "0.4.44", features = ["serde"] }
-clap = { version = "4.6.0", features = ["derive"] }
-dirs = "6.0.0"
-flate2 = "1.1.9"
-keyring = { version = "3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
-rand = "0.10.0"
-reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
-rpassword = "7.4.0"
-self-replace = "1.5.0"
-semver = "1.0.27"
-serde = { version = "1.0.228", features = ["derive"] }
-serde_json = "1.0.149"
-serde_yaml = "0.9"
-sha2 = "0.10.9"
-sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
-tar = "0.4.44"
-tempfile = "3.19"
-tokio = { version = "1.50.0", features = ["full"] }
-toml = "1.0.7"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-uuid = { version = "1.22.0", features = ["serde"] }
-zip = { version = "8.2.0", default-features = false, features = ["deflate"] }
+aes-gcm = "^0.10.3"
+anyhow = "^1.0.102"
+argon2 = { version = "^0.5.3", features = ["std"] }
+chrono = { version = "^0.4.44", features = ["serde"] }
+clap = { version = "^4.6.0", features = ["derive"] }
+dirs = "^6.0.0"
+dotenvy = "^0.15"
+flate2 = "^1.1.9"
+keyring = { version = "^3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
+rand = "^0.10.0"
+reqwest = { version = "^0.12", default-features = false, features = ["rustls-tls", "json"] }
+rpassword = "^7.4.0"
+self-replace = "^1.5.0"
+semver = "^1.0.27"
+serde = { version = "^1.0.228", features = ["derive"] }
+serde_json = "^1.0.149"
+serde_yaml = "^0.9"
+sha2 = "^0.10.9"
+sqlx = { version = "^0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
+tar = "^0.4.44"
+tempfile = "^3.19"
+tokio = { version = "^1.50.0", features = ["rt-multi-thread", "macros", "fs", "io-util", "process", "signal"] }
+toml = "^1.0.7"
+tracing = "^0.1"
+tracing-subscriber = { version = "^0.3", features = ["env-filter"] }
+uuid = { version = "^1.22.0", features = ["serde"] }
+zip = { version = "^8.2.0", default-features = false, features = ["deflate"] }
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ secrets search -n refining --summary --limit 10 --offset 10  # 翻页
 # ── add ──────────────────────────────────────────────────────────────────────
 secrets add -n refining --kind server --name my-server \
  --tag aliyun --tag shanghai \
-  -m ip=47.117.131.22 -m desc="Aliyun Shanghai ECS" \
+  -m ip=10.0.0.1 -m desc="Example ECS" \
  -s username=root -s ssh_key=@./keys/server.pem

 # 多行文件直接写入嵌套 secret 字段
@@ -136,7 +136,7 @@ secrets add -n refining --kind service --name deploy-bot \

 secrets add -n refining --kind service --name gitea \
  --tag gitea \
-  -m url=https://gitea.refining.dev -m default_org=refining \
+  -m url=https://code.example.com -m default_org=myorg \
  -s token=<token>

 # ── update ───────────────────────────────────────────────────────────────────
@@ -146,7 +146,10 @@ secrets update -n refining --kind service --name mqtt --remove-meta old_port --r
 secrets update -n refining --kind server --name my-server --remove-secret credentials:content

 # ── delete ───────────────────────────────────────────────────────────────────
-secrets delete -n refining --kind service --name legacy-mqtt
+secrets delete -n refining --kind service --name legacy-mqtt   # 精确删除单条（--kind 必填）
+secrets delete -n refining --dry-run                          # 预览批量删除（不写入）
+secrets delete -n ricnsmart                                    # 批量删除整个 namespace
+secrets delete -n ricnsmart --kind server                      # 批量删除指定 kind

 # ── init ─────────────────────────────────────────────────────────────────────
 secrets init              # 主密钥初始化（每台设备一次，主密码至少 8 位，派生后存钥匙串）
@@ -158,7 +161,7 @@ secrets config path    # 打印配置文件路径

 # ── upgrade ──────────────────────────────────────────────────────────────────
 secrets upgrade --check   # 仅检查是否有新版本
-secrets upgrade           # 下载、校验 SHA-256 并安装最新版（从 Gitea Release）
+secrets upgrade           # 下载、校验 SHA-256 并安装最新版（可通过 SECRETS_UPGRADE_URL 自托管）

 # ── export ────────────────────────────────────────────────────────────────────
 secrets export --file backup.json                        # 全量导出到 JSON
@@ -203,12 +206,12 @@ RUST_LOG=secrets=trace secrets search

 | 目标值 | 写法示例 | 实际存入 |
 |------|------|------|
-| 普通字符串 | `-m url=https://gitea.refining.dev` | `"https://gitea.refining.dev"` |
+| 普通字符串 | `-m url=https://code.example.com` | `"https://code.example.com"` |
 | 文件内容字符串 | `-m notes=@./service-notes.txt` | `"..."` |
 | 布尔值 | `-m enabled:=true` | `true` |
 | 数字 | `-m port:=3000` | `3000` |
 | `null` | `-m deprecated_at:=null` | `null` |
-| 数组 | `-m domains:='["gitea.refining.dev","git.refining.dev"]'` | `["gitea.refining.dev","git.refining.dev"]` |
+| 数组 | `-m domains:='["code.example.com","git.example.com"]'` | `["code.example.com","git.example.com"]` |
 | 对象 | `-m tls:='{"enabled":true,"redirect_http":true}'` | `{"enabled":true,"redirect_http":true}` |
 | 嵌套路径 + JSON | `-m deploy:strategy:='{"type":"rolling","batch":2}'` | `{"deploy":{"strategy":{"type":"rolling","batch":2}}}` |

@@ -223,10 +226,10 @@ RUST_LOG=secrets=trace secrets search

 ```bash
 secrets add -n refining --kind service --name gitea \
-  -m url=https://gitea.refining.dev \
+  -m url=https://code.example.com \
  -m port:=3000 \
  -m enabled:=true \
-  -m domains:='["gitea.refining.dev","git.refining.dev"]' \
+  -m domains:='["code.example.com","git.example.com"]' \
  -m tls:='{"enabled":true,"redirect_http":true}'
 ```

--- a/src/audit.rs
+++ b/src/audit.rs
@@ -1,6 +1,11 @@
 use serde_json::Value;
 use sqlx::{Postgres, Transaction};

+/// Return the current OS user as the audit actor (falls back to empty string).
+pub fn current_actor() -> String {
+    std::env::var("USER").unwrap_or_default()
+}
+
 /// Write an audit entry within an existing transaction.
 pub async fn log_tx(
    tx: &mut Transaction<'_, Postgres>,
@@ -10,7 +15,7 @@ pub async fn log_tx(
    name: &str,
    detail: Value,
 ) {
-    let actor = std::env::var("USER").unwrap_or_default();
+    let actor = current_actor();
    let result: Result<_, sqlx::Error> = sqlx::query(
        "INSERT INTO audit_log (action, namespace, kind, name, detail, actor) \
         VALUES ($1, $2, $3, $4, $5, $6)",
--- a/src/commands/add.rs
+++ b/src/commands/add.rs
@@ -5,7 +5,8 @@ use std::fs;

 use crate::crypto;
 use crate::db;
-use crate::output::OutputMode;
+use crate::models::EntryRow;
+use crate::output::{OutputMode, print_json};

 // ── Key/value parsing helpers (shared with update.rs) ───────────────────────

@@ -228,13 +229,6 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
    let mut tx = pool.begin().await?;

    // Upsert the entry row (tags + metadata).
-    #[derive(sqlx::FromRow)]
-    struct EntryRow {
-        id: uuid::Uuid,
-        version: i64,
-        tags: Vec<String>,
-        metadata: Value,
-    }
    let existing: Option<EntryRow> = sqlx::query_as(
        "SELECT id, version, tags, metadata FROM entries \
         WHERE namespace = $1 AND kind = $2 AND name = $3",
@@ -383,11 +377,8 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
    });

    match args.output {
-        OutputMode::Json => {
-            println!("{}", serde_json::to_string_pretty(&result_json)?);
-        }
-        OutputMode::JsonCompact => {
-            println!("{}", serde_json::to_string(&result_json)?);
+        OutputMode::Json | OutputMode::JsonCompact => {
+            print_json(&result_json, &args.output)?;
        }
        _ => {
            println!("Added: [{}/{}] {}", args.namespace, args.kind, args.name);
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -15,7 +15,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
                database_url: Some(url.clone()),
            };
            config::save_config(&cfg)?;
-            println!("Database URL saved to: {}", config_path().display());
+            println!("Database URL saved to: {}", config_path()?.display());
            println!("  {}", mask_password(&url));
        }
        crate::ConfigAction::Show => {
@@ -23,7 +23,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
            match cfg.database_url {
                Some(url) => {
                    println!("database_url = {}", mask_password(&url));
-                    println!("config file:  {}", config_path().display());
+                    println!("config file:  {}", config_path()?.display());
                }
                None => {
                    println!("Database URL not configured.");
@@ -32,7 +32,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
            }
        }
        crate::ConfigAction::Path => {
-            println!("{}", config_path().display());
+            println!("{}", config_path()?.display());
        }
    }
    Ok(())
--- a/src/commands/delete.rs
+++ b/src/commands/delete.rs
@@ -1,29 +1,52 @@
 use anyhow::Result;
-use serde_json::{Value, json};
-use sqlx::{FromRow, PgPool};
+use serde_json::json;
+use sqlx::PgPool;
 use uuid::Uuid;

 use crate::db;
-use crate::output::OutputMode;
+use crate::models::{EntryRow, SecretFieldRow};
+use crate::output::{OutputMode, print_json};

-#[derive(FromRow)]
-struct EntryRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
+pub struct DeleteArgs<'a> {
+    pub namespace: &'a str,
+    /// Kind filter. Required when --name is given; optional for bulk deletes.
+    pub kind: Option<&'a str>,
+    /// Exact record name. When None, bulk-delete all matching records.
+    pub name: Option<&'a str>,
+    /// Preview without writing to the database (bulk mode only).
+    pub dry_run: bool,
+    pub output: OutputMode,
 }

-#[derive(FromRow)]
-struct SecretFieldRow {
-    id: Uuid,
-    field_name: String,
-    field_type: String,
-    value_len: i32,
-    encrypted: Vec<u8>,
+// ── Internal row type used for bulk queries ────────────────────────────────
+
+#[derive(Debug, sqlx::FromRow)]
+struct FullEntryRow {
+    pub id: Uuid,
+    pub version: i64,
+    pub kind: String,
+    pub name: String,
+    pub metadata: serde_json::Value,
+    pub tags: Vec<String>,
 }

-pub async fn run(
+// ── Entry point ────────────────────────────────────────────────────────────
+
+pub async fn run(pool: &PgPool, args: DeleteArgs<'_>) -> Result<()> {
+    match args.name {
+        Some(name) => {
+            let kind = args
+                .kind
+                .ok_or_else(|| anyhow::anyhow!("--kind is required when --name is specified"))?;
+            delete_one(pool, args.namespace, kind, name, args.output).await
+        }
+        None => delete_bulk(pool, args.namespace, args.kind, args.dry_run, args.output).await,
+    }
+}
+
+// ── Single-record delete (original behaviour) ─────────────────────────────
+
+async fn delete_one(
    pool: &PgPool,
    namespace: &str,
    kind: &str,
@@ -48,27 +71,175 @@ pub async fn run(
    let Some(row) = row else {
        tx.rollback().await?;
        tracing::warn!(namespace, kind, name, "entry not found for deletion");
+        let v = json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name});
        match output {
-            OutputMode::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(
-                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
-                )?
-            ),
-            OutputMode::JsonCompact => println!(
-                "{}",
-                serde_json::to_string(
-                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
-                )?
-            ),
-            _ => println!("Not found: [{}/{}] {}", namespace, kind, name),
+            OutputMode::Text => println!("Not found: [{}/{}] {}", namespace, kind, name),
+            ref mode => print_json(&v, mode)?,
        }
        return Ok(());
    };

-    // Snapshot entry history before deleting.
+    snapshot_and_delete(&mut tx, namespace, kind, name, &row).await?;
+
+    crate::audit::log_tx(&mut tx, "delete", namespace, kind, name, json!({})).await;
+    tx.commit().await?;
+
+    let v = json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name});
+    match output {
+        OutputMode::Text => println!("Deleted: [{}/{}] {}", namespace, kind, name),
+        ref mode => print_json(&v, mode)?,
+    }
+    Ok(())
+}
+
+// ── Bulk delete by namespace (+ optional kind filter) ─────────────────────
+
+async fn delete_bulk(
+    pool: &PgPool,
+    namespace: &str,
+    kind: Option<&str>,
+    dry_run: bool,
+    output: OutputMode,
+) -> Result<()> {
+    tracing::debug!(namespace, ?kind, dry_run, "bulk-deleting entries");
+
+    let rows: Vec<FullEntryRow> = if let Some(k) = kind {
+        sqlx::query_as(
+            "SELECT id, version, kind, name, metadata, tags FROM entries \
+             WHERE namespace = $1 AND kind = $2 \
+             ORDER BY name",
+        )
+        .bind(namespace)
+        .bind(k)
+        .fetch_all(pool)
+        .await?
+    } else {
+        sqlx::query_as(
+            "SELECT id, version, kind, name, metadata, tags FROM entries \
+             WHERE namespace = $1 \
+             ORDER BY kind, name",
+        )
+        .bind(namespace)
+        .fetch_all(pool)
+        .await?
+    };
+
+    if rows.is_empty() {
+        let v = json!({
+            "action": "noop",
+            "namespace": namespace,
+            "kind": kind,
+            "deleted": 0,
+            "dry_run": dry_run
+        });
+        match output {
+            OutputMode::Text => println!(
+                "No records found in namespace \"{}\"{}.",
+                namespace,
+                kind.map(|k| format!(" with kind \"{}\"", k))
+                    .unwrap_or_default()
+            ),
+            ref mode => print_json(&v, mode)?,
+        }
+        return Ok(());
+    }
+
+    if dry_run {
+        let count = rows.len();
+        match output {
+            OutputMode::Text => {
+                println!(
+                    "dry-run: would delete {} record(s) in namespace \"{}\":",
+                    count, namespace
+                );
+                for r in &rows {
+                    println!("  [{}/{}] {}", namespace, r.kind, r.name);
+                }
+            }
+            ref mode => {
+                let items: Vec<_> = rows
+                    .iter()
+                    .map(|r| json!({"namespace": namespace, "kind": r.kind, "name": r.name}))
+                    .collect();
+                print_json(
+                    &json!({
+                        "action": "dry_run",
+                        "namespace": namespace,
+                        "kind": kind,
+                        "would_delete": count,
+                        "entries": items
+                    }),
+                    mode,
+                )?;
+            }
+        }
+        return Ok(());
+    }
+
+    let mut deleted = Vec::with_capacity(rows.len());
+
+    for row in &rows {
+        let entry_row = EntryRow {
+            id: row.id,
+            version: row.version,
+            tags: row.tags.clone(),
+            metadata: row.metadata.clone(),
+        };
+        let mut tx = pool.begin().await?;
+        snapshot_and_delete(&mut tx, namespace, &row.kind, &row.name, &entry_row).await?;
+        crate::audit::log_tx(
+            &mut tx,
+            "delete",
+            namespace,
+            &row.kind,
+            &row.name,
+            json!({"bulk": true}),
+        )
+        .await;
+        tx.commit().await?;
+
+        deleted.push(json!({"namespace": namespace, "kind": row.kind, "name": row.name}));
+        tracing::info!(namespace, kind = %row.kind, name = %row.name, "bulk deleted");
+    }
+
+    let count = deleted.len();
+    match output {
+        OutputMode::Text => {
+            for item in &deleted {
+                println!(
+                    "Deleted: [{}/{}] {}",
+                    item["namespace"].as_str().unwrap_or(""),
+                    item["kind"].as_str().unwrap_or(""),
+                    item["name"].as_str().unwrap_or("")
+                );
+            }
+            println!("Total: {} record(s) deleted.", count);
+        }
+        ref mode => print_json(
+            &json!({
+                "action": "deleted",
+                "namespace": namespace,
+                "kind": kind,
+                "deleted": count,
+                "entries": deleted
+            }),
+            mode,
+        )?,
+    }
+    Ok(())
+}
+
+// ── Shared helper: snapshot history then DELETE ────────────────────────────
+
+async fn snapshot_and_delete(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    namespace: &str,
+    kind: &str,
+    name: &str,
+    row: &EntryRow,
+) -> Result<()> {
    if let Err(e) = db::snapshot_entry_history(
-        &mut tx,
+        tx,
        db::EntrySnapshotParams {
            entry_id: row.id,
            namespace,
@@ -85,18 +256,17 @@ pub async fn run(
        tracing::warn!(error = %e, "failed to snapshot entry history before delete");
    }

-    // Snapshot all secret fields before cascade delete.
    let fields: Vec<SecretFieldRow> = sqlx::query_as(
        "SELECT id, field_name, field_type, value_len, encrypted \
         FROM secrets WHERE entry_id = $1",
    )
    .bind(row.id)
-    .fetch_all(&mut *tx)
+    .fetch_all(&mut **tx)
    .await?;

    for f in &fields {
        if let Err(e) = db::snapshot_secret_history(
-            &mut tx,
+            tx,
            db::SecretSnapshotParams {
                entry_id: row.id,
                secret_id: f.id,
@@ -110,35 +280,14 @@ pub async fn run(
        )
        .await
        {
-            tracing::warn!(error = %e, "failed to snapshot secret field history before delete");
+            tracing::warn!(error = %e, "failed to snapshot secret history before delete");
        }
    }

-    // Delete the entry — secrets rows are removed via ON DELETE CASCADE.
    sqlx::query("DELETE FROM entries WHERE id = $1")
        .bind(row.id)
-        .execute(&mut *tx)
+        .execute(&mut **tx)
        .await?;

-    crate::audit::log_tx(&mut tx, "delete", namespace, kind, name, json!({})).await;
-
-    tx.commit().await?;
-
-    match output {
-        OutputMode::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(
-                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
-            )?
-        ),
-        OutputMode::JsonCompact => println!(
-            "{}",
-            serde_json::to_string(
-                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
-            )?
-        ),
-        _ => println!("Deleted: [{}/{}] {}", namespace, kind, name),
-    }
-
    Ok(())
 }
--- a/src/commands/history.rs
+++ b/src/commands/history.rs
@@ -0,0 +1,78 @@
+use anyhow::Result;
+use serde_json::{Value, json};
+use sqlx::{FromRow, PgPool};
+
+use crate::output::{OutputMode, format_local_time, print_json};
+
+pub struct HistoryArgs<'a> {
+    pub namespace: &'a str,
+    pub kind: &'a str,
+    pub name: &'a str,
+    pub limit: u32,
+    pub output: OutputMode,
+}
+
+/// List history entries for an entry.
+pub async fn run(pool: &PgPool, args: HistoryArgs<'_>) -> Result<()> {
+    #[derive(FromRow)]
+    struct HistorySummary {
+        version: i64,
+        action: String,
+        actor: String,
+        created_at: chrono::DateTime<chrono::Utc>,
+    }
+
+    let rows: Vec<HistorySummary> = sqlx::query_as(
+        "SELECT version, action, actor, created_at FROM entries_history \
+         WHERE namespace = $1 AND kind = $2 AND name = $3 \
+         ORDER BY id DESC LIMIT $4",
+    )
+    .bind(args.namespace)
+    .bind(args.kind)
+    .bind(args.name)
+    .bind(args.limit as i64)
+    .fetch_all(pool)
+    .await?;
+
+    match args.output {
+        OutputMode::Json | OutputMode::JsonCompact => {
+            let arr: Vec<Value> = rows
+                .iter()
+                .map(|r| {
+                    json!({
+                        "version": r.version,
+                        "action": r.action,
+                        "actor": r.actor,
+                        "created_at": r.created_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+                    })
+                })
+                .collect();
+            print_json(&Value::Array(arr), &args.output)?;
+        }
+        _ => {
+            if rows.is_empty() {
+                println!(
+                    "No history found for [{}/{}] {}.",
+                    args.namespace, args.kind, args.name
+                );
+                return Ok(());
+            }
+            println!(
+                "History for [{}/{}] {}:",
+                args.namespace, args.kind, args.name
+            );
+            for r in &rows {
+                println!(
+                    "  v{:<4}  {:8}  {}  {}",
+                    r.version,
+                    r.action,
+                    r.actor,
+                    format_local_time(r.created_at)
+                );
+            }
+            println!("  (use `secrets rollback --to-version <N>` to restore)");
+        }
+    }
+
+    Ok(())
+}
--- a/src/commands/import_cmd.rs
+++ b/src/commands/import_cmd.rs
@@ -5,11 +5,13 @@ use std::collections::BTreeMap;

 use crate::commands::add::{self, AddArgs};
 use crate::models::ExportFormat;
-use crate::output::OutputMode;
+use crate::output::{OutputMode, print_json};

 pub struct ImportArgs<'a> {
    pub file: &'a str,
    /// Overwrite existing records when there is a conflict (upsert).
+    /// Without this flag, the import aborts on the first conflict.
+    /// A future `--skip` flag could allow silently skipping conflicts and continuing.
    pub force: bool,
    /// Check and preview operations without writing to the database.
    pub dry_run: bool,
@@ -48,26 +50,29 @@ pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) ->
        .unwrap_or(false);

        if exists && !args.force {
-            let msg = format!(
-                "[{}/{}/{}] conflict — record already exists (use --force to overwrite)",
-                entry.namespace, entry.kind, entry.name
-            );
+            let v = serde_json::json!({
+                "action": "conflict",
+                "namespace": entry.namespace,
+                "kind": entry.kind,
+                "name": entry.name,
+            });
            match args.output {
-                OutputMode::Json | OutputMode::JsonCompact => {
-                    let v = serde_json::json!({
-                        "action": "conflict",
-                        "namespace": entry.namespace,
-                        "kind": entry.kind,
-                        "name": entry.name,
-                    });
-                    let s = if args.output == OutputMode::Json {
-                        serde_json::to_string_pretty(&v)?
-                    } else {
-                        serde_json::to_string(&v)?
-                    };
-                    eprintln!("{}", s);
+                OutputMode::Text => eprintln!(
+                    "[{}/{}/{}] conflict — record already exists (use --force to overwrite)",
+                    entry.namespace, entry.kind, entry.name
+                ),
+                ref mode => {
+                    // Write conflict notice to stderr so it does not mix with summary JSON.
+                    eprint!(
+                        "{}",
+                        if *mode == OutputMode::Json {
+                            serde_json::to_string_pretty(&v)?
+                        } else {
+                            serde_json::to_string(&v)?
+                        }
+                    );
+                    eprintln!();
                }
-                _ => eprintln!("{}", msg),
            }
            return Err(anyhow::anyhow!(
                "Import aborted: conflict on [{}/{}/{}]",
@@ -80,26 +85,19 @@ pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) ->
        let action = if exists { "upsert" } else { "insert" };

        if args.dry_run {
+            let v = serde_json::json!({
+                "action": action,
+                "namespace": entry.namespace,
+                "kind": entry.kind,
+                "name": entry.name,
+                "dry_run": true,
+            });
            match args.output {
-                OutputMode::Json | OutputMode::JsonCompact => {
-                    let v = serde_json::json!({
-                        "action": action,
-                        "namespace": entry.namespace,
-                        "kind": entry.kind,
-                        "name": entry.name,
-                        "dry_run": true,
-                    });
-                    let s = if args.output == OutputMode::Json {
-                        serde_json::to_string_pretty(&v)?
-                    } else {
-                        serde_json::to_string(&v)?
-                    };
-                    println!("{}", s);
-                }
-                _ => println!(
+                OutputMode::Text => println!(
                    "[dry-run] {} [{}/{}/{}]",
                    action, entry.namespace, entry.kind, entry.name
                ),
+                ref mode => print_json(&v, mode)?,
            }
            if exists {
                skipped += 1;
@@ -131,25 +129,18 @@ pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) ->
        .await
        {
            Ok(()) => {
+                let v = serde_json::json!({
+                    "action": action,
+                    "namespace": entry.namespace,
+                    "kind": entry.kind,
+                    "name": entry.name,
+                });
                match args.output {
-                    OutputMode::Json | OutputMode::JsonCompact => {
-                        let v = serde_json::json!({
-                            "action": action,
-                            "namespace": entry.namespace,
-                            "kind": entry.kind,
-                            "name": entry.name,
-                        });
-                        let s = if args.output == OutputMode::Json {
-                            serde_json::to_string_pretty(&v)?
-                        } else {
-                            serde_json::to_string(&v)?
-                        };
-                        println!("{}", s);
-                    }
-                    _ => println!(
+                    OutputMode::Text => println!(
                        "Imported [{}/{}/{}]",
                        entry.namespace, entry.kind, entry.name
                    ),
+                    ref mode => print_json(&v, mode)?,
                }
                inserted += 1;
            }
@@ -163,23 +154,15 @@ pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) ->
        }
    }

+    let summary = serde_json::json!({
+        "total": total,
+        "inserted": inserted,
+        "skipped": skipped,
+        "failed": failed,
+        "dry_run": args.dry_run,
+    });
    match args.output {
-        OutputMode::Json | OutputMode::JsonCompact => {
-            let v = serde_json::json!({
-                "total": total,
-                "inserted": inserted,
-                "skipped": skipped,
-                "failed": failed,
-                "dry_run": args.dry_run,
-            });
-            let s = if args.output == OutputMode::Json {
-                serde_json::to_string_pretty(&v)?
-            } else {
-                serde_json::to_string(&v)?
-            };
-            println!("{}", s);
-        }
-        _ => {
+        OutputMode::Text => {
            if args.dry_run {
                println!(
                    "\n[dry-run] {} total: {} would insert, {} would skip, {} would fail",
@@ -192,6 +175,7 @@ pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) ->
                );
            }
        }
+        ref mode => print_json(&summary, mode)?,
    }

    if failed > 0 {
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -2,6 +2,7 @@ pub mod add;
 pub mod config;
 pub mod delete;
 pub mod export_cmd;
+pub mod history;
 pub mod import_cmd;
 pub mod init;
 pub mod rollback;
--- a/src/commands/rollback.rs
+++ b/src/commands/rollback.rs
@@ -5,7 +5,7 @@ use uuid::Uuid;

 use crate::crypto;
 use crate::db;
-use crate::output::{OutputMode, format_local_time};
+use crate::output::{OutputMode, print_json};

 pub struct RollbackArgs<'a> {
    pub namespace: &'a str,
@@ -255,83 +255,11 @@ pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -
    });

    match args.output {
-        OutputMode::Json => println!("{}", serde_json::to_string_pretty(&result_json)?),
-        OutputMode::JsonCompact => println!("{}", serde_json::to_string(&result_json)?),
-        _ => println!(
+        OutputMode::Text => println!(
            "Rolled back: [{}/{}] {} → version {}",
            args.namespace, args.kind, args.name, snap.version
        ),
-    }
-
-    Ok(())
-}
-
-/// List history entries for an entry.
-pub async fn list_history(
-    pool: &PgPool,
-    namespace: &str,
-    kind: &str,
-    name: &str,
-    limit: u32,
-    output: OutputMode,
-) -> Result<()> {
-    #[derive(FromRow)]
-    struct HistorySummary {
-        version: i64,
-        action: String,
-        actor: String,
-        created_at: chrono::DateTime<chrono::Utc>,
-    }
-
-    let rows: Vec<HistorySummary> = sqlx::query_as(
-        "SELECT version, action, actor, created_at FROM entries_history \
-         WHERE namespace = $1 AND kind = $2 AND name = $3 \
-         ORDER BY id DESC LIMIT $4",
-    )
-    .bind(namespace)
-    .bind(kind)
-    .bind(name)
-    .bind(limit as i64)
-    .fetch_all(pool)
-    .await?;
-
-    match output {
-        OutputMode::Json | OutputMode::JsonCompact => {
-            let arr: Vec<Value> = rows
-                .iter()
-                .map(|r| {
-                    json!({
-                        "version": r.version,
-                        "action": r.action,
-                        "actor": r.actor,
-                        "created_at": r.created_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
-                    })
-                })
-                .collect();
-            let out = if output == OutputMode::Json {
-                serde_json::to_string_pretty(&arr)?
-            } else {
-                serde_json::to_string(&arr)?
-            };
-            println!("{}", out);
-        }
-        _ => {
-            if rows.is_empty() {
-                println!("No history found for [{}/{}] {}.", namespace, kind, name);
-                return Ok(());
-            }
-            println!("History for [{}/{}] {}:", namespace, kind, name);
-            for r in &rows {
-                println!(
-                    "  v{:<4}  {:8}  {}  {}",
-                    r.version,
-                    r.action,
-                    r.actor,
-                    format_local_time(r.created_at)
-                );
-            }
-            println!("  (use `secrets rollback --to-version <N>` to restore)");
-        }
+        ref mode => print_json(&result_json, mode)?,
    }

    Ok(())
--- a/src/commands/search.rs
+++ b/src/commands/search.rs
@@ -121,7 +121,12 @@ struct PagedFetchArgs<'a> {
    offset: u32,
 }

+/// A very large limit used when callers need all matching records (export, inject, run).
+/// Postgres will stop scanning when this many rows are found; adjust if needed.
+pub const FETCH_ALL_LIMIT: u32 = 100_000;
+
 /// Fetch entries matching the given filters (used by search, inject, run).
+/// `limit` caps the result set; pass `FETCH_ALL_LIMIT` when you need all matching records.
 pub async fn fetch_entries(
    pool: &PgPool,
    namespace: Option<&str>,
@@ -129,6 +134,19 @@ pub async fn fetch_entries(
    name: Option<&str>,
    tags: &[String],
    query: Option<&str>,
+) -> Result<Vec<Entry>> {
+    fetch_entries_with_limit(pool, namespace, kind, name, tags, query, FETCH_ALL_LIMIT).await
+}
+
+/// Like `fetch_entries` but with an explicit limit. Used internally by `search`.
+pub(crate) async fn fetch_entries_with_limit(
+    pool: &PgPool,
+    namespace: Option<&str>,
+    kind: Option<&str>,
+    name: Option<&str>,
+    tags: &[String],
+    query: Option<&str>,
+    limit: u32,
 ) -> Result<Vec<Entry>> {
    fetch_entries_paged(
        pool,
@@ -139,7 +157,7 @@ pub async fn fetch_entries(
            tags,
            query,
            sort: "name",
-            limit: 200,
+            limit,
            offset: 0,
        },
    )
@@ -524,7 +542,7 @@ mod tests {
            kind: "service".to_string(),
            name: "gitea.main".to_string(),
            tags: vec!["prod".to_string()],
-            metadata: json!({"url": "https://gitea.refining.dev", "enabled": true}),
+            metadata: json!({"url": "https://code.example.com", "enabled": true}),
            version: 1,
            created_at: Utc::now(),
            updated_at: Utc::now(),
@@ -561,7 +579,7 @@ mod tests {

        assert_eq!(
            map.get("GITEA_MAIN_URL").map(String::as_str),
-            Some("https://gitea.refining.dev")
+            Some("https://code.example.com")
        );
        assert_eq!(
            map.get("GITEA_MAIN_ENABLED").map(String::as_str),
--- a/src/commands/update.rs
+++ b/src/commands/update.rs
@@ -1,6 +1,6 @@
 use anyhow::Result;
 use serde_json::{Map, Value, json};
-use sqlx::{FromRow, PgPool};
+use sqlx::PgPool;
 use uuid::Uuid;

 use super::add::{
@@ -9,15 +9,8 @@ use super::add::{
 };
 use crate::crypto;
 use crate::db;
-use crate::output::OutputMode;
-
-#[derive(FromRow)]
-struct EntryRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
-}
+use crate::models::EntryRow;
+use crate::output::{OutputMode, print_json};

 pub struct UpdateArgs<'a> {
    pub namespace: &'a str,
@@ -284,11 +277,8 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
    });

    match args.output {
-        OutputMode::Json => {
-            println!("{}", serde_json::to_string_pretty(&result_json)?);
-        }
-        OutputMode::JsonCompact => {
-            println!("{}", serde_json::to_string(&result_json)?);
+        OutputMode::Json | OutputMode::JsonCompact => {
+            print_json(&result_json, &args.output)?;
        }
        _ => {
            println!("Updated: [{}/{}] {}", args.namespace, args.kind, args.name);
--- a/src/commands/upgrade.rs
+++ b/src/commands/upgrade.rs
@@ -5,10 +5,26 @@ use sha2::{Digest, Sha256};
 use std::io::{Cursor, Read, Write};
 use std::time::Duration;

-const GITEA_API: &str = "https://gitea.refining.dev/api/v1/repos/refining/secrets/releases/latest";
-
 const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");

+/// Build-time config via `option_env!("SECRETS_UPGRADE_URL")`. Set during `cargo build`, e.g.:
+///   SECRETS_UPGRADE_URL=https://... cargo build --release
+const BUILD_UPGRADE_URL: Option<&'static str> = option_env!("SECRETS_UPGRADE_URL");
+
+fn upgrade_api_url() -> Result<String> {
+    if let Some(url) = BUILD_UPGRADE_URL.filter(|s| !s.trim().is_empty()) {
+        return Ok(url.to_string());
+    }
+    let url = std::env::var("SECRETS_UPGRADE_URL").context(
+        "SECRETS_UPGRADE_URL is not set at build or runtime. Set it when building: \
+         SECRETS_UPGRADE_URL=https://... cargo build, or export before running secrets upgrade.",
+    )?;
+    if url.trim().is_empty() {
+        anyhow::bail!("SECRETS_UPGRADE_URL is empty.");
+    }
+    Ok(url)
+}
+
 #[derive(Debug, Deserialize)]
 struct Release {
    tag_name: String,
@@ -186,13 +202,14 @@ pub async fn run(check_only: bool) -> Result<()> {
        .build()
        .context("failed to build HTTP client")?;

+    let api_url = upgrade_api_url()?;
    let release: Release = client
-        .get(GITEA_API)
+        .get(&api_url)
        .send()
        .await
-        .context("failed to fetch release info from Gitea")?
+        .context("failed to fetch release info")?
        .error_for_status()
-        .context("Gitea API returned an error")?
+        .context("release API returned an error")?
        .json()
        .await
        .context("failed to parse release JSON")?;
--- a/src/config.rs
+++ b/src/config.rs
@@ -8,19 +8,23 @@ pub struct Config {
    pub database_url: Option<String>,
 }

-pub fn config_dir() -> PathBuf {
-    dirs::config_dir()
+pub fn config_dir() -> Result<PathBuf> {
+    let dir = dirs::config_dir()
        .or_else(|| dirs::home_dir().map(|h| h.join(".config")))
-        .unwrap_or_else(|| PathBuf::from(".config"))
-        .join("secrets")
+        .context(
+            "Cannot determine config directory: \
+             neither XDG_CONFIG_HOME nor HOME is set",
+        )?
+        .join("secrets");
+    Ok(dir)
 }

-pub fn config_path() -> PathBuf {
-    config_dir().join("config.toml")
+pub fn config_path() -> Result<PathBuf> {
+    Ok(config_dir()?.join("config.toml"))
 }

 pub fn load_config() -> Result<Config> {
-    let path = config_path();
+    let path = config_path()?;
    if !path.exists() {
        return Ok(Config::default());
    }
@@ -32,11 +36,11 @@ pub fn load_config() -> Result<Config> {
 }

 pub fn save_config(config: &Config) -> Result<()> {
-    let dir = config_dir();
+    let dir = config_dir()?;
    fs::create_dir_all(&dir)
        .with_context(|| format!("failed to create config dir: {}", dir.display()))?;

-    let path = config_path();
+    let path = dir.join("config.toml");
    let content = toml::to_string_pretty(config).context("failed to serialize config")?;
    fs::write(&path, &content)
        .with_context(|| format!("failed to write config file: {}", path.display()))?;
--- a/src/crypto.rs
+++ b/src/crypto.rs
@@ -10,12 +10,24 @@ const KEYRING_SERVICE: &str = "secrets-cli";
 const KEYRING_USER: &str = "master-key";
 const NONCE_LEN: usize = 12;

+// Argon2id parameters — OWASP recommended (m=64 MiB, t=3 iterations, p=4 threads, key=32 B)
+const ARGON2_M_COST: u32 = 65_536;
+const ARGON2_T_COST: u32 = 3;
+const ARGON2_P_COST: u32 = 4;
+const ARGON2_KEY_LEN: usize = 32;
+
 // ─── Argon2id key derivation ─────────────────────────────────────────────────

 /// Derive a 32-byte Master Key from a password and salt using Argon2id.
 /// Parameters: m=65536 KiB (64 MB), t=3, p=4 — OWASP recommended.
 pub fn derive_master_key(password: &str, salt: &[u8]) -> Result<[u8; 32]> {
-    let params = Params::new(65536, 3, 4, Some(32)).context("invalid Argon2id params")?;
+    let params = Params::new(
+        ARGON2_M_COST,
+        ARGON2_T_COST,
+        ARGON2_P_COST,
+        Some(ARGON2_KEY_LEN),
+    )
+    .context("invalid Argon2id params")?;
    let argon2 = Argon2::new(argon2::Algorithm::Argon2id, Version::V0x13, params);
    let mut key = [0u8; 32];
    argon2
--- a/src/db.rs
+++ b/src/db.rs
@@ -3,6 +3,8 @@ use serde_json::Value;
 use sqlx::PgPool;
 use sqlx::postgres::PgPoolOptions;

+use crate::audit::current_actor;
+
 pub async fn create_pool(database_url: &str) -> Result<PgPool> {
    tracing::debug!("connecting to database");
    let pool = PgPoolOptions::new()
@@ -139,7 +141,7 @@ pub async fn snapshot_entry_history(
    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
    p: EntrySnapshotParams<'_>,
 ) -> Result<()> {
-    let actor = std::env::var("USER").unwrap_or_default();
+    let actor = current_actor();
    sqlx::query(
        "INSERT INTO entries_history \
         (entry_id, namespace, kind, name, version, action, tags, metadata, actor) \
@@ -177,7 +179,7 @@ pub async fn snapshot_secret_history(
    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
    p: SecretSnapshotParams<'_>,
 ) -> Result<()> {
-    let actor = std::env::var("USER").unwrap_or_default();
+    let actor = current_actor();
    sqlx::query(
        "INSERT INTO secrets_history \
         (entry_id, secret_id, entry_version, field_name, field_type, value_len, encrypted, action, actor) \
--- a/src/main.rs
+++ b/src/main.rs
@@ -7,6 +7,11 @@ mod models;
 mod output;

 use anyhow::Result;
+
+/// Load .env from current or parent directories (best-effort, no error if missing).
+fn load_dotenv() {
+    let _ = dotenvy::dotenv();
+}
 use clap::{Parser, Subcommand};
 use tracing_subscriber::EnvFilter;

@@ -76,25 +81,25 @@ EXAMPLES:
  # Add a server
  secrets add -n refining --kind server --name my-server \\
    --tag aliyun --tag shanghai \\
-    -m ip=47.117.131.22 -m desc=\"Aliyun Shanghai ECS\" \\
+    -m ip=10.0.0.1 -m desc=\"Example ECS\" \\
    -s username=root -s ssh_key=@./keys/server.pem

  # Add a service credential
  secrets add -n refining --kind service --name gitea \\
    --tag gitea \\
-    -m url=https://gitea.refining.dev -m default_org=refining \\
+    -m url=https://code.example.com -m default_org=myorg \\
    -s token=<token>

  # Add typed JSON metadata
  secrets add -n refining --kind service --name gitea \\
    -m port:=3000 \\
    -m enabled:=true \\
-    -m domains:='[\"gitea.refining.dev\",\"git.refining.dev\"]' \\
+    -m domains:='[\"code.example.com\",\"git.example.com\"]' \\
    -m tls:='{\"enabled\":true,\"redirect_http\":true}'

  # Add with token read from a file
  secrets add -n ricnsmart --kind service --name mqtt \\
-    -m host=mqtt.ricnsmart.com -m port=1883 \\
+    -m host=mqtt.example.com -m port=1883 \\
    -s password=@./mqtt_password.txt

  # Add typed JSON secrets
@@ -114,7 +119,7 @@ EXAMPLES:
        /// Kind of record: server, service, key, ...
        #[arg(long)]
        kind: String,
-        /// Human-readable unique name, e.g. gitea, i-uf63f2uookgs5uxmrdyc
+        /// Human-readable unique name, e.g. gitea, i-example0abcd1234efgh
        #[arg(long)]
        name: String,
        /// Tag for categorization (repeatable), e.g. --tag aliyun --tag hongkong
@@ -177,7 +182,7 @@ EXAMPLES:
        /// Filter by kind, e.g. server, service
        #[arg(long)]
        kind: Option<String>,
-        /// Exact name filter, e.g. gitea, i-uf63f2uookgs5uxmrdyc
+        /// Exact name filter, e.g. gitea, i-example0abcd1234efgh
        #[arg(long)]
        name: Option<String>,
        /// Filter by tag, e.g. --tag aliyun (repeatable for AND intersection)
@@ -206,23 +211,39 @@ EXAMPLES:
        output: Option<String>,
    },

-    /// Delete a record permanently. Requires exact namespace + kind + name.
+    /// Delete one record precisely, or bulk-delete by namespace.
+    ///
+    /// With --name: deletes exactly that record (--kind also required).
+    /// Without --name: bulk-deletes all records matching namespace + optional --kind.
+    /// Use --dry-run to preview bulk deletes before committing.
    #[command(after_help = "EXAMPLES:
-  # Delete a service credential
+  # Delete a single record (exact match)
  secrets delete -n refining --kind service --name legacy-mqtt

-  # Delete a server record
-  secrets delete -n ricnsmart --kind server --name i-old-server-id")]
+  # Preview what a bulk delete would remove (no writes)
+  secrets delete -n refining --dry-run
+
+  # Bulk-delete all records in a namespace
+  secrets delete -n ricnsmart
+
+  # Bulk-delete only server records in a namespace
+  secrets delete -n ricnsmart --kind server
+
+  # JSON output
+  secrets delete -n refining --kind service -o json")]
    Delete {
        /// Namespace, e.g. refining
        #[arg(short, long)]
        namespace: String,
-        /// Kind, e.g. server, service
+        /// Kind filter, e.g. server, service (required with --name; optional for bulk)
        #[arg(long)]
-        kind: String,
-        /// Exact name of the record to delete
+        kind: Option<String>,
+        /// Exact name of the record to delete (omit for bulk delete)
        #[arg(long)]
-        name: String,
+        name: Option<String>,
+        /// Preview what would be deleted without making any changes (bulk mode only)
+        #[arg(long)]
+        dry_run: bool,
        /// Output format: text (default on TTY), json, json-compact
        #[arg(short, long = "output")]
        output: Option<String>,
@@ -423,8 +444,8 @@ EXAMPLES:

    /// Check for a newer version and update the binary in-place.
    ///
-    /// Downloads the latest release from Gitea and replaces the current binary.
-    /// No database connection or master key required.
+    /// Downloads the latest release and replaces the current binary. No database connection or master key required.
+    /// Release URL defaults to the upstream server; override via SECRETS_UPGRADE_URL for self-hosted or fork.
    #[command(after_help = "EXAMPLES:
  # Check for updates only (no download)
  secrets upgrade --check
@@ -530,6 +551,7 @@ enum ConfigAction {

 #[tokio::main]
 async fn main() -> Result<()> {
+    load_dotenv();
    let cli = Cli::parse();

    let filter = if cli.verbose {
@@ -634,12 +656,23 @@ async fn main() -> Result<()> {
            namespace,
            kind,
            name,
+            dry_run,
            output,
        } => {
            let _span =
-                tracing::info_span!("cmd", command = "delete", %namespace, %kind, %name).entered();
+                tracing::info_span!("cmd", command = "delete", %namespace, ?kind, ?name).entered();
            let out = resolve_output_mode(output.as_deref())?;
-            commands::delete::run(&pool, &namespace, &kind, &name, out).await?;
+            commands::delete::run(
+                &pool,
+                commands::delete::DeleteArgs {
+                    namespace: &namespace,
+                    kind: kind.as_deref(),
+                    name: name.as_deref(),
+                    dry_run,
+                    output: out,
+                },
+            )
+            .await?;
        }

        Commands::Update {
@@ -685,7 +718,17 @@ async fn main() -> Result<()> {
            output,
        } => {
            let out = resolve_output_mode(output.as_deref())?;
-            commands::rollback::list_history(&pool, &namespace, &kind, &name, limit, out).await?;
+            commands::history::run(
+                &pool,
+                commands::history::HistoryArgs {
+                    namespace: &namespace,
+                    kind: &kind,
+                    name: &name,
+                    limit,
+                    output: out,
+                },
+            )
+            .await?;
        }

        Commands::Rollback {
--- a/src/models.rs
+++ b/src/models.rs
@@ -38,6 +38,27 @@ pub struct SecretField {
    pub updated_at: DateTime<Utc>,
 }

+// ── Internal query row types (shared across commands) ─────────────────────────
+
+/// Minimal entry row fetched for write operations (add / update / delete / rollback).
+#[derive(Debug, sqlx::FromRow)]
+pub struct EntryRow {
+    pub id: Uuid,
+    pub version: i64,
+    pub tags: Vec<String>,
+    pub metadata: Value,
+}
+
+/// Minimal secret field row fetched before snapshots or cascade deletes.
+#[derive(Debug, sqlx::FromRow)]
+pub struct SecretFieldRow {
+    pub id: Uuid,
+    pub field_name: String,
+    pub field_type: String,
+    pub value_len: i32,
+    pub encrypted: Vec<u8>,
+}
+
 // ── Export / Import types ──────────────────────────────────────────────────────

 /// Supported file formats for export/import.
@@ -52,15 +73,12 @@ impl ExportFormat {
    /// Infer format from file extension (.json / .toml / .yaml / .yml).
    pub fn from_extension(path: &str) -> anyhow::Result<Self> {
        let ext = path.rsplit('.').next().unwrap_or("").to_lowercase();
-        match ext.as_str() {
-            "json" => Ok(Self::Json),
-            "toml" => Ok(Self::Toml),
-            "yaml" | "yml" => Ok(Self::Yaml),
-            other => anyhow::bail!(
+        Self::from_str(&ext).map_err(|_| {
+            anyhow::anyhow!(
                "Cannot infer format from extension '.{}'. Use --format json|toml|yaml",
-                other
-            ),
-        }
+                ext
+            )
+        })
    }

    /// Parse from --format CLI value.
@@ -146,16 +164,12 @@ pub fn json_to_toml_value(v: &Value) -> anyhow::Result<toml::Value> {
        }
        Value::String(s) => Ok(toml::Value::String(s.clone())),
        Value::Array(arr) => {
-            // Check for uniform scalar type (TOML requires homogeneous arrays at the value level,
-            // though arrays of tables are handled separately via TOML's [[table]] syntax).
-            // For simplicity we convert each element; if types are mixed, toml crate will
-            // handle it gracefully or we fall back to a JSON string.
            let items: anyhow::Result<Vec<toml::Value>> =
                arr.iter().map(json_to_toml_value).collect();
            match items {
                Ok(vals) => Ok(toml::Value::Array(vals)),
-                Err(_) => {
-                    // Fallback: serialise as JSON string
+                Err(e) => {
+                    tracing::debug!(error = %e, "mixed-type array; falling back to JSON string");
                    Ok(toml::Value::String(serde_json::to_string(v)?))
                }
            }
@@ -171,8 +185,8 @@ pub fn json_to_toml_value(v: &Value) -> anyhow::Result<toml::Value> {
                    Ok(tv) => {
                        toml_map.insert(k.clone(), tv);
                    }
-                    Err(_) => {
-                        // Fallback: serialise as JSON string
+                    Err(e) => {
+                        tracing::debug!(key = %k, error = %e, "field not representable in TOML; falling back to JSON string");
                        toml_map
                            .insert(k.clone(), toml::Value::String(serde_json::to_string(val)?));
                    }
--- a/src/output.rs
+++ b/src/output.rs
@@ -50,3 +50,16 @@ pub fn format_local_time(dt: DateTime<Utc>) -> String {
        .format("%Y-%m-%d %H:%M:%S %:z")
        .to_string()
 }
+
+/// Print a JSON value to stdout in the requested output mode.
+/// - `Json`        → pretty-printed
+/// - `JsonCompact` → single line
+/// - `Text`        → no-op (caller is responsible for the text branch)
+pub fn print_json(value: &serde_json::Value, mode: &OutputMode) -> anyhow::Result<()> {
+    match mode {
+        OutputMode::Json => println!("{}", serde_json::to_string_pretty(value)?),
+        OutputMode::JsonCompact => println!("{}", serde_json::to_string(value)?),
+        OutputMode::Text => {}
+    }
+    Ok(())
+}
--- a/test-fixtures/example-key.pem
+++ b/test-fixtures/example-key.pem
@@ -0,0 +1,3 @@
+-----BEGIN EXAMPLE KEY PLACEHOLDER-----
+This file is for local dev/testing. Replace with a real key when needed.
+-----END EXAMPLE KEY PLACEHOLDER-----
Author	SHA1	Message	Date
voson	62a1df316b	docs: README 补充 delete 批量删除与 --dry-run 示例 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 3s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 2m30s Details Secrets CLI - Build & Release / Build (macOS aarch64 + x86_64) (push) Successful in 1m1s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m17s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Has been cancelled Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details Made-with: Cursor	2026-03-19 16:32:20 +08:00
voson	d0796e9c9a	feat: delete 命令支持批量删除，--name 改为可选省略 --name 时按 namespace（+ 可选 --kind）批量删除所有匹配记录；支持 --dry-run 预览；删除前自动快照历史并写入审计日志。移除独立的 delete-ns 子命令，合并为统一的 delete 入口。更新 AGENTS.md 文档，版本 bump 至 0.9.3。 Made-with: Cursor	2026-03-19 16:31:18 +08:00
voson	66b6417faa	feat: 开源准备与 upgrade URL 构建时配置 - upgrade: SECRETS_UPGRADE_URL 改为构建时优先（option_env!），CI 自动注入 - upgrade: 支持运行时回退（.env/export），添加 dotenvy 加载 .env - 泛化示例：IP/实例 ID/域名/密钥名改为示例值（10.0.0.1、example.com 等） - tasks.json: 文件 secret 测试改用 test-fixtures/example-key.pem - 文档更新：AGENTS.md、README.md Made-with: Cursor	2026-03-19 16:08:27 +08:00
voson	56a28e8cf7	refactor: 消除冗余、统一设计，bump 0.9.1 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 3s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 2m46s Details Secrets CLI - Build & Release / Build (macOS aarch64 + x86_64) (push) Successful in 1m27s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 2m0s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Has been cancelled Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 提取 EntryRow/SecretFieldRow 到 models.rs - 提取 current_actor()、print_json() 公共函数 - ExportFormat::from_extension 复用 from_str - fetch_entries 默认 limit 100k（export/inject/run 不再截断） - history 独立为 history.rs 模块 - delete 改用 DeleteArgs 结构体 - config_dir 改为 Result，Argon2id 参数提取常量 - Cargo 依赖 ^ 前缀、tokio 精简 features - 更新 AGENTS.md 项目结构 Made-with: Cursor	2026-03-19 15:46:57 +08:00