chore(ci): 精简 publish-release job，移除多余 checkout

Made-with: Cursor

.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
@@ -406,8 +407,6 @@ jobs:
     runs-on: debian
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
-
       - name: 发布草稿
         env:
           RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
@@ -447,7 +446,8 @@ jobs:
 
           tag="${{ needs.version.outputs.tag }}"
           tag_exists="${{ needs.version.outputs.tag_exists }}"
-          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
+          commit="${{ github.event.head_commit.message }}"
+          [ -z "$commit" ] && commit="${{ github.sha }}"
           url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
 
           linux_r="${{ needs.build-linux.result }}"

.vscode/tasks.json

@@ -104,9 +104,9 @@
       "dependsOn": "build"
     },
     {
-      "label": "test: inject service secrets",
+      "label": "test: run service secrets",
       "type": "shell",
-      "command": "./target/debug/secrets inject -n refining --kind service --name gitea",
+      "command": "./target/debug/secrets run -n refining --kind service --name gitea -- printenv",
       "dependsOn": "build"
     },
     {
@@ -118,7 +118,7 @@
     {
       "label": "test: add + delete roundtrip",
       "type": "shell",
-      "command": "echo '--- add ---' && ./target/debug/secrets add -n test --kind demo --name roundtrip-test --tag test -m foo=bar -s password=secret123 && echo '--- search metadata ---' && ./target/debug/secrets search -n test && echo '--- inject secrets ---' && ./target/debug/secrets inject -n test --kind demo --name roundtrip-test && echo '--- delete ---' && ./target/debug/secrets delete -n test --kind demo --name roundtrip-test && echo '--- verify deleted ---' && ./target/debug/secrets search -n test",
+      "command": "echo '--- add ---' && ./target/debug/secrets add -n test --kind demo --name roundtrip-test --tag test -m foo=bar -s password=secret123 && echo '--- search metadata ---' && ./target/debug/secrets search -n test && echo '--- run secrets ---' && ./target/debug/secrets run -n test --kind demo --name roundtrip-test -- printenv && echo '--- delete ---' && ./target/debug/secrets delete -n test --kind demo --name roundtrip-test && echo '--- verify deleted ---' && ./target/debug/secrets search -n test",
       "dependsOn": "build"
     },
     {
@@ -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 run ---' && ./target/debug/secrets run -n test --kind key --name test-key -- printenv && echo '--- cleanup ---' && ./target/debug/secrets delete -n test --kind key --name test-key",
       "dependsOn": "build"
     }
   ]

AGENTS.md

@@ -7,7 +7,7 @@
 3. 若当前版本对应 tag 已存在，必须先 bump `Cargo.toml` 的 `version`，再执行 `cargo build` 同步 `Cargo.lock`，然后才能提交。
 4. 提交前优先运行 `./scripts/release-check.sh`；该脚本会检查重复版本并执行 `cargo fmt -- --check && cargo clippy --locked -- -D warnings && cargo test --locked`。
 
-跨设备密钥与配置管理 CLI 工具，将 refining / ricnsmart 两个项目的服务器信息、服务凭据存储到 PostgreSQL 18，供 AI 工具读取上下文。敏感数据（encrypted 字段）使用 AES-256-GCM 加密，主密钥由 Argon2id 从主密码派生并存入平台安全存储（macOS Keychain / Windows Credential Manager / Linux keyutils）。
+跨设备密钥与配置管理 CLI 工具，将服务器信息、服务凭据等存储到 PostgreSQL 18，供 AI 工具读取上下文。每个加密字段单独行存储（`secrets` 子表），字段名、类型、长度以明文保存，主密钥由 Argon2id 从主密码派生并存入平台安全存储（macOS Keychain / Windows Credential Manager / Linux keyutils）。
 
 ## 项目结构
 
@@ -15,22 +15,25 @@
 secrets/
   src/
     main.rs              # CLI 入口，clap 命令定义，auto-migrate，--verbose 全局参数
-    output.rs            # OutputMode 枚举 + TTY 检测（TTY→text，非 TTY→json-compact）
+    output.rs            # OutputMode 枚举（默认 json，-o text 供人类使用）
     config.rs            # 配置读写：~/.config/secrets/config.toml（database_url）
-    db.rs                # PgPool 创建 + 建表/索引（幂等，含 audit_log + kv_config + secrets_history）
+    db.rs                # PgPool 创建 + 建表/索引（DROP+CREATE，含所有表）
     crypto.rs            # AES-256-GCM 加解密、Argon2id 派生、OS 钥匙串
-    models.rs            # Secret 结构体（sqlx::FromRow + serde，含 version 字段）
-    audit.rs             # 审计写入：log_tx（事务内）/ log（池，保留备用）
+    models.rs            # Entry + SecretField 结构体（sqlx::FromRow + serde）
+    audit.rs             # 审计写入：log_tx（事务内）
     commands/
       init.rs            # init 命令：主密钥初始化（每台设备一次）
-      add.rs             # add 命令：upsert，事务化，含历史快照，支持 key:=json 类型化值与嵌套路径写入
+      add.rs             # add 命令：upsert entries + 逐字段写入 secrets，含历史快照
       config.rs          # config 命令：set-db / show / path（持久化 database_url）
-      search.rs          # search 命令：多条件查询，公开 fetch_rows / build_env_map
-      delete.rs          # delete 命令：事务化，含历史快照
-      update.rs          # update 命令：增量更新，CAS 并发保护，含历史快照
-      rollback.rs        # rollback / history 命令：版本回滚与历史查看
-      run.rs             # inject / run 命令：临时环境变量注入
+      search.rs          # search 命令：多条件查询，展示 secrets 字段 schema（无需 master_key）
+      delete.rs          # delete 命令：事务化，CASCADE 删除 secrets，含历史快照
+      update.rs          # update 命令：增量更新，secrets 行级 UPSERT/DELETE，CAS 并发保护
+      rollback.rs        # rollback 命令：按 entry_version 恢复 entry + secrets
+      history.rs         # history 命令：查看 entry 变更历史列表
+      run.rs             # run 命令：仅 secrets 逐字段解密 + key_ref 引用解析（不含 metadata）
       upgrade.rs         # upgrade 命令：检查、校验摘要并下载最新版本，自动替换二进制
+      export_cmd.rs      # export 命令：批量导出记录，支持 JSON/TOML/YAML，含解密明文
+      import_cmd.rs      # import 命令：批量导入记录，冲突检测，dry-run，重新加密写入
   scripts/
     release-check.sh        # 发版前检查版本号/tag 是否重复，并执行 fmt/clippy/test
     setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
@@ -44,19 +47,18 @@ secrets/
 - **Host**: `<host>:<port>`
 - **Database**: `secrets`
 - **连接串**: `postgres://postgres:<password>@<host>:<port>/secrets`
-- **表**: `secrets`（主表）+ `audit_log`（审计表）+ `kv_config`（Argon2 salt 等），首次连接自动建表（auto-migrate）
+- **表**: `entries`（主表）+ `secrets`（加密字段子表）+ `entries_history` + `secrets_history` + `audit_log` + `kv_config`，首次连接自动建表（auto-migrate）
 
 ### 表结构
 
 ```sql
-secrets (
+entries (
   id          UUID PRIMARY KEY DEFAULT uuidv7(),  -- PG18 时间有序 UUID
   namespace   VARCHAR(64)   NOT NULL,              -- 一级隔离: "refining" | "ricnsmart"
-  kind        VARCHAR(64)   NOT NULL,              -- 类型: "server" | "service"（可扩展）
+  kind        VARCHAR(64)   NOT NULL,              -- 类型: "server" | "service" | "key"（可扩展）
   name        VARCHAR(256)  NOT NULL,              -- 人类可读标识
   tags        TEXT[]        NOT NULL DEFAULT '{}', -- 灵活标签: ["aliyun","hongkong"]
   metadata    JSONB         NOT NULL DEFAULT '{}', -- 明文描述: ip, desc, domains, location...
-  encrypted   BYTEA         NOT NULL DEFAULT '\x', -- AES-256-GCM 密文: nonce(12B)||ciphertext+tag
   version     BIGINT        NOT NULL DEFAULT 1,    -- 乐观锁版本号，每次写操作自增
   created_at  TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
   updated_at  TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
@@ -65,26 +67,22 @@ secrets (
 ```
 
 ```sql
-secrets_history (
-  id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  secret_id   UUID         NOT NULL,   -- 对应 secrets.id
-  namespace   VARCHAR(64)  NOT NULL,
-  kind        VARCHAR(64)  NOT NULL,
-  name        VARCHAR(256) NOT NULL,
-  version     BIGINT       NOT NULL,   -- 被快照时的版本号
-  action      VARCHAR(16)  NOT NULL,   -- 'add' | 'update' | 'delete' | 'rollback'
-  tags        TEXT[]       NOT NULL DEFAULT '{}',
-  metadata    JSONB        NOT NULL DEFAULT '{}',
-  encrypted   BYTEA        NOT NULL DEFAULT '\x', -- 快照时的加密密文
-  actor       VARCHAR(128) NOT NULL DEFAULT '',
-  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+secrets (
+  id          UUID PRIMARY KEY DEFAULT uuidv7(),
+  entry_id    UUID         NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+  field_name  VARCHAR(256) NOT NULL,              -- 明文字段名: "username", "token", "ssh_key"
+  encrypted   BYTEA        NOT NULL DEFAULT '\x', -- 仅加密值本身：nonce(12B)||ciphertext+tag
+  version     BIGINT       NOT NULL DEFAULT 1,
+  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  UNIQUE(entry_id, field_name)
 )
 ```
 
 ```sql
 kv_config (
   key   TEXT PRIMARY KEY,   -- 如 'argon2_salt'
-  value BYTEA NOT NULL        -- Argon2id salt，首台设备 init 时生成
+  value BYTEA NOT NULL      -- Argon2id salt，首台设备 init 时生成
 )
 ```
 
@@ -93,26 +91,81 @@ kv_config (
 ```sql
 audit_log (
   id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  action      VARCHAR(32)   NOT NULL,              -- 'add' | 'update' | 'delete'
+  action      VARCHAR(32)   NOT NULL,              -- 'add' | 'update' | 'delete' | 'rollback'
   namespace   VARCHAR(64)   NOT NULL,
   kind        VARCHAR(64)   NOT NULL,
   name        VARCHAR(256)  NOT NULL,
   detail      JSONB         NOT NULL DEFAULT '{}', -- 变更摘要（tags/meta keys/secret keys，不含 value）
-  actor       VARCHAR(128)  NOT NULL DEFAULT '',    -- 操作者（$USER 环境变量）
+  actor       VARCHAR(128)  NOT NULL DEFAULT '',   -- 操作者（$USER 环境变量）
   created_at  TIMESTAMPTZ   NOT NULL DEFAULT NOW()
 )
 ```
 
+### entries_history 表结构
+
+```sql
+entries_history (
+  id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  entry_id    UUID         NOT NULL,
+  namespace   VARCHAR(64)  NOT NULL,
+  kind        VARCHAR(64)  NOT NULL,
+  name        VARCHAR(256) NOT NULL,
+  version     BIGINT       NOT NULL,   -- 被快照时的版本号
+  action      VARCHAR(16)  NOT NULL,   -- 'add' | 'update' | 'delete' | 'rollback'
+  tags        TEXT[]       NOT NULL DEFAULT '{}',
+  metadata    JSONB        NOT NULL DEFAULT '{}',
+  actor       VARCHAR(128) NOT NULL DEFAULT '',
+  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+)
+```
+
+### secrets_history 表结构
+
+```sql
+secrets_history (
+  id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  entry_id        UUID         NOT NULL,
+  secret_id       UUID         NOT NULL,  -- 对应 secrets.id
+  entry_version   BIGINT       NOT NULL,  -- 关联 entries_history 的版本号
+  field_name      VARCHAR(256) NOT NULL,
+  encrypted       BYTEA        NOT NULL DEFAULT '\x',
+  action          VARCHAR(16)  NOT NULL,   -- 'add' | 'update' | 'delete' | 'rollback'
+  actor           VARCHAR(128) NOT NULL DEFAULT '',
+  created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+)
+```
+
 ### 字段职责划分
 
 | 字段 | 存什么 | 示例 |
 |------|--------|------|
 | `namespace` | 项目/团队隔离 | `refining`, `ricnsmart` |
-| `kind` | 记录类型 | `server`, `service` |
-| `name` | 唯一标识名 | `i-uf63f2uookgs5uxmrdyc`, `gitea` |
+| `kind` | 记录类型 | `server`, `service`, `key` |
+| `name` | 唯一标识名 | `i-example0abcd1234efgh`, `gitea` |
 | `tags` | 多维分类标签 | `["aliyun","hongkong","ricn"]` |
-| `metadata` | 明文非敏感信息 | `{"ip":"47.243.154.187","desc":"Grafana","domains":["..."]}` |
-| `encrypted` | 敏感凭据，AES-256-GCM 加密存储 | 二进制密文，解密后为 `{"ssh_key":"...","password":"..."}` |
+| `metadata` | 明文非敏感信息 | `{"ip":"192.0.2.1","desc":"Grafana","key_ref":"my-shared-key"}` |
+| `secrets.field_name` | 加密字段名（明文） | `"username"`, `"token"`, `"ssh_key"` |
+| `secrets.encrypted` | 仅加密值本身 | AES-256-GCM 密文 |
+
+### PEM 共享机制（key_ref）
+
+同一 PEM 被多台服务器共享时，将 PEM 存为独立的 `kind=key` 记录，服务器通过 `metadata.key_ref` 引用：
+
+```bash
+# 1. 存共享 PEM
+secrets add -n refining --kind key --name my-shared-key \
+  --tag aliyun --tag hongkong \
+  -s content=@./keys/my-shared-key.pem
+
+# 2. 服务器通过 metadata.key_ref 引用（run 时自动合并 key 的 secrets）
+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 my-shared-key \
+  -s content=@./keys/new-key.pem
+```
 
 ## 数据库配置
 
@@ -150,10 +203,9 @@ secrets init   # 提示输入主密码，Argon2id 派生主密钥后存入 OS
 **读取一律用 `search`，写入用 `add` / `update`，避免反复查帮助。**
 
 输出格式规则：
-- TTY（终端直接运行）→ 默认 `text`
-- 非 TTY（管道/重定向/AI 调用）→ 自动 `json-compact`
-- 显式 `-o json` → 美化 JSON
-- 显式 `-o env` → KEY=VALUE（可 source）
+- 默认始终输出 `json`（pretty-printed），无论 TTY 还是管道
+- 显式 `-o json-compact` → 单行 JSON（管道处理时更紧凑）
+- 显式 `-o text` → 人类可读文本格式
 
 ---
 
@@ -173,16 +225,16 @@ 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）
-#   --show-secrets     已弃用；search 不再直接展示 secrets
+#   secrets schema  search 默认展示 secrets 字段名、类型与长度（无需 master_key）
 #   -f / --field       metadata.ip | metadata.url | metadata.default_org
 #   --summary          不带值的 flag，仅返回摘要（name/tags/desc/updated_at）
 #   --limit            20 | 50（默认 50）
 #   --offset           0 | 10 | 20（分页偏移）
 #   --sort             name（默认）| updated | created
-#   -o / --output      text | json | json-compact | env
+#   -o / --output      text | json | json-compact
 
 # 发现概览（起步推荐）
 secrets search --summary --limit 20
@@ -191,7 +243,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
@@ -201,14 +253,13 @@ secrets search -n refining --kind service --name gitea -f metadata.url
 secrets search -n refining --kind service --name gitea \
   -f metadata.url -f metadata.default_org
 
-# 需要 secrets 时，改用 inject / run
-secrets inject -n refining --kind service --name gitea
+# 需要 secrets 时，改用 run
 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
@@ -220,12 +271,8 @@ secrets search --tag aliyun --summary
 secrets search -n refining --summary --limit 10 --offset 0
 secrets search -n refining --summary --limit 10 --offset 10
 
-# 管道 / AI 调用（非 TTY 自动 json-compact）
+# 管道 / AI 调用（默认 json，直接可解析）
 secrets search -n refining --kind service | jq '.[].name'
-
-# 导出 metadata 为 env 文件（单条记录）
-secrets search -n refining --kind service --name gitea -o env \
-  > ~/.config/gitea/config.env
 ```
 
 ---
@@ -236,31 +283,31 @@ secrets search -n refining --kind service --name gitea -o env \
 # 参数说明（带典型值）
 #   -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 \
@@ -280,7 +327,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（新增或覆盖，可重复）
@@ -289,7 +336,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
@@ -306,11 +353,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
@@ -319,19 +366,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
 ```
 
 ---
@@ -375,37 +437,11 @@ secrets rollback -n refining --kind service --name gitea --to-version 3
 
 ---
 
-### inject — 输出临时环境变量
-
-敏感值仅打印到 stdout，不持久化、不写入当前 shell。
-
-```bash
-# 参数说明
-#   -n / --namespace   refining | ricnsmart
-#   --kind             server | service
-#   --name             记录名
-#   --tag              按 tag 过滤（可重复）
-#   --prefix           变量名前缀（留空则以记录 name 作前缀）
-#   -o / --output      text（默认 KEY=VALUE）| json | json-compact
-
-# 打印单条记录的所有变量（KEY=VALUE 格式）
-secrets inject -n refining --kind service --name gitea
-
-# 自定义前缀
-secrets inject -n refining --kind service --name gitea --prefix GITEA
-
-# JSON 格式（适合管道或脚本解析）
-secrets inject -n refining --kind service --name gitea -o json
-
-# eval 注入当前 shell（谨慎使用）
-eval $(secrets inject -n refining --kind service --name gitea)
-```
-
----
-
 ### run — 向子进程注入 secrets 并执行命令
 
-secrets 仅作用于子进程环境，不修改当前 shell，进程退出码透传。
+仅注入 secrets 表中的加密字段（解密后），不含 metadata。secrets 仅作用于子进程环境，不修改当前 shell，进程退出码透传。
+
+使用 `-s/--secret` 指定只注入哪些字段（最小权限原则）；使用 `--dry-run` 预览将注入哪些变量名及来源，不执行命令。
 
 ```bash
 # 参数说明
@@ -413,24 +449,39 @@ secrets 仅作用于子进程环境，不修改当前 shell，进程退出码透
 #   --kind             server | service
 #   --name             记录名
 #   --tag              按 tag 过滤（可重复）
+#   -s / --secret      只注入指定字段名（可重复；省略则注入全部）
 #   --prefix           变量名前缀
-#   -- <command>       执行的命令及参数
+#   --dry-run          预览变量映射，不执行命令
+#   -o / --output      json（默认）| json-compact | text
+#   -- <command>       执行的命令及参数（--dry-run 时可省略）
 
-# 向脚本注入单条记录的 secrets
+# 注入全部 secrets 到脚本
 secrets run -n refining --kind service --name gitea -- ./deploy.sh
 
+# 只注入特定字段（最小化注入范围）
+secrets run -n refining --kind service --name aliyun \
+  -s access_key_id -s access_key_secret -- aliyun ecs DescribeInstances
+
 # 按 tag 批量注入（多条记录合并）
 secrets run --tag production -- env | grep -i token
 
-# 验证注入了哪些变量
-secrets run -n refining --kind service --name gitea -- printenv
+# 预览将注入哪些变量（不执行命令，默认 JSON 输出）
+secrets run -n refining --kind service --name gitea --dry-run
+
+# 配合字段过滤预览
+secrets run -n refining --kind service --name gitea -s token --dry-run
+
+# text 模式预览（人类阅读）
+secrets run -n refining --kind service --name gitea --dry-run -o text
 ```
 
 ---
 
 ### upgrade — 自动更新 CLI 二进制
 
-从 Gitea Release 下载最新版本，校验对应 `.sha256` 摘要后替换当前二进制，无需数据库连接或主密钥。
+从 Release 服务器下载最新版本，校验对应 `.sha256` 摘要后替换当前二进制，无需数据库连接或主密钥。
+
+**配置方式**：`SECRETS_UPGRADE_URL` 必填。优先用**构建时**：`SECRETS_UPGRADE_URL=https://... cargo build`，CI 已自动注入。或**运行时**：写在 `.env` 或 `export` 后执行。
 
 ```bash
 # 检查是否有新版本（不下载）
@@ -442,6 +493,75 @@ secrets upgrade
 
 ---
 
+### export — 批量导出记录
+
+将匹配的记录（含解密后的明文 secrets）导出到文件或 stdout。支持 JSON、TOML、YAML 三种格式，文件格式由扩展名自动推断。使用 `--no-secrets` 时无需主密钥。
+
+```bash
+# 参数说明
+# -n / --namespace refining | ricnsmart
+# --kind server | service
+# --name gitea | i-example0abcd1234efgh
+# --tag aliyun | production（可重复）
+# -q / --query 模糊关键词
+# --file <path>   输出文件路径，格式由扩展名推断（.json / .toml / .yaml / .yml）
+# --format json | toml | yaml   显式指定格式（输出到 stdout 时必须指定）
+# --no-secrets    不导出 secrets，无需主密钥
+
+# 全量导出到 JSON 文件
+secrets export --file backup.json
+
+# 按 namespace 导出为 TOML
+secrets export -n refining --file refining.toml
+
+# 按 kind 导出为 YAML
+secrets export -n refining --kind service --file services.yaml
+
+# 按 tag 过滤导出
+secrets export --tag production --file prod.json
+
+# 模糊关键词导出
+secrets export -q mqtt --file mqtt.json
+
+# 仅导出 schema（不含 secrets，无需主密钥）
+secrets export --no-secrets --file schema.json
+
+# 输出到 stdout（必须指定 --format）
+secrets export -n refining --format yaml
+secrets export --format json | jq '.'
+```
+
+---
+
+### import — 批量导入记录
+
+从导出文件读取记录并写入数据库，自动重新加密 secrets。支持 JSON、TOML、YAML 三种格式，文件格式由扩展名自动推断。
+
+```bash
+# 参数说明
+# <file>        必选，输入文件路径（格式由扩展名推断）
+# --force       冲突时覆盖已有记录（默认：报错并停止）
+# --dry-run     预览将执行的操作，不写入数据库
+# -o / --output text | json | json-compact
+
+# 导入 JSON 文件（遇到已存在记录报错）
+secrets import backup.json
+
+# 导入 TOML 文件，冲突时覆盖
+secrets import --force refining.toml
+
+# 导入 YAML 文件，冲突时覆盖
+secrets import --force services.yaml
+
+# 预览将执行的操作（不写入）
+secrets import --dry-run backup.json
+
+# JSON 格式输出导入摘要
+secrets import backup.json -o json
+```
+
+---
+
 ### config — 配置管理（无需主密钥）
 
 ```bash
@@ -482,7 +602,7 @@ secrets --db-url "postgres://..." search -n refining
 - 日志：用户可见输出用 `println!`；调试/运维信息用 `tracing::debug!`/`info!`/`warn!`/`error!`
 - 审计：`add`/`update`/`delete` 成功后调用 `audit::log_tx`，写入 `audit_log` 表；失败只 warn 不中断
 - 加密：`encrypted` 列存储 AES-256-GCM 密文；`add`/`update`/`search`/`delete` 需主密钥（`secrets init` 后从 OS 钥匙串加载）
-- 输出：读命令通过 `OutputMode` 支持 text/json/json-compact/env；写命令 `add` 同样支持 `-o json`
+- 输出：读命令通过 `OutputMode` 支持 text/json/json-compact；默认始终 `json`（pretty），`-o text` 供人类阅读；写命令 `add` 同样支持 `-o json`
 
 ## 提交前检查（必须全部通过）
 
@@ -541,5 +661,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`，不支持环境变量。

Cargo.lock

@@ -1836,7 +1836,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "secrets"
-version = "0.7.4"
+version = "0.9.6"
 dependencies = [
  "aes-gcm",
  "anyhow",
@@ -1844,6 +1844,7 @@ dependencies = [
  "chrono",
  "clap",
  "dirs",
+ "dotenvy",
  "flate2",
  "keyring",
  "rand 0.10.0",
@@ -1853,6 +1854,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
+ "serde_yaml",
  "sha2",
  "sqlx",
  "tar",
@@ -1982,6 +1984,19 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -2434,7 +2449,6 @@ dependencies = [
  "bytes",
  "libc",
  "mio",
- "parking_lot",
  "pin-project-lite",
  "signal-hook-registry",
  "socket2",
@@ -2681,6 +2695,12 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"

Cargo.toml

@@ -1,31 +1,33 @@
 [package]
 name = "secrets"
-version = "0.7.4"
+version = "0.9.6"
 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"
-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"] }

README.md

@@ -2,7 +2,7 @@
 
 跨设备密钥与配置管理 CLI，基于 Rust + PostgreSQL 18。
 
-将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。敏感数据（`encrypted` 字段）使用 AES-256-GCM 加密存储，主密钥由 Argon2id 从主密码派生并存入系统钥匙串。
+将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。每个敏感字段单独行存储（`secrets` 子表），字段名、类型、长度以明文保存便于 AI 理解，仅值本身使用 AES-256-GCM 加密；主密钥由 Argon2id 从主密码派生并存入系统钥匙串。
 
 ## 安装
 
@@ -54,7 +54,7 @@ secrets search --sort updated --limit 10 --summary
 # 精确定位（namespace + kind + name 三元组）
 secrets search -n refining --kind service --name gitea
 
-# 获取完整记录（secrets 保持加密占位）
+# 获取完整记录（含 secrets 字段名，无需 master_key）
 secrets search -n refining --kind service --name gitea -o json
 
 # 直接提取单个 metadata 字段值（最短路径）
@@ -64,36 +64,35 @@ secrets search -n refining --kind service --name gitea -f metadata.url
 secrets search -n refining --kind service --name gitea \
   -f metadata.url -f metadata.default_org
 
-# 需要 secrets 时，改用 inject / run
-secrets inject -n refining --kind service --name gitea
-secrets run -n refining --kind service --name gitea -- printenv
+# 需要 secrets 时，改用 run（只注入 token 字段到子进程）
+secrets run -n refining --kind service --name gitea -s token -- ./deploy.sh
+
+# 预览 run 会注入哪些变量（不执行命令）
+secrets run -n refining --kind service --name gitea --dry-run
 ```
 
-`search` 只负责发现、定位和读取 metadata，不直接展示 secrets。
+`search` 展示 metadata 与 secrets 的字段名，不展示 secret 值本身；需要 secret 值时用 `run`（仅注入加密字段到子进程，不含 metadata）。用 `-s` 指定只注入特定字段，最小化注入范围。
 
 ### 输出格式
 
 | 场景 | 推荐命令 |
 |------|----------|
-| AI 解析 / 管道处理 | `-o json` 或 `-o json-compact` |
-| 写入 metadata `.env` 文件 | `-o env` |
-| 注入 secrets 到环境变量 | `inject` / `run` |
-| 人类查看 | 默认 `text`（TTY 下自动启用） |
-| 非 TTY（管道/重定向） | 自动 `json-compact` |
+| AI 解析 / 管道处理（默认） | json（pretty-printed） |
+| 管道紧凑格式 | `-o json-compact` |
+| 注入 secrets 到子进程环境 | `run` |
+| 人类查看 | `-o text` |
 
-说明：`text` 输出中的时间会按当前机器本地时区显示；`json/json-compact` 继续使用 UTC（RFC3339 风格）以便脚本和 AI 稳定解析。
+默认始终输出 JSON，无论是 TTY 还是管道。`text` 输出中时间按本地时区显示；`json/json-compact` 使用 UTC（RFC3339）。
 
 ```bash
-# 管道直接 jq 解析（非 TTY 自动 json-compact）
+# 默认 JSON 输出，直接可 jq 解析
 secrets search -n refining --kind service | jq '.[].name'
 
-# 导出 metadata 为可 source 的 env 文件（单条记录）
-secrets search -n refining --kind service --name gitea -o env \
-  > ~/.config/gitea/config.env
+# 需要 secrets 时，使用 run（-s 指定只注入特定字段）
+secrets run -n refining --kind service --name gitea -s token -- ./deploy.sh
 
-# 需要 secrets 时，使用 inject / run
-secrets inject -n refining --kind service --name gitea > ~/.config/gitea/secrets.env
-secrets run -n refining --kind service --name gitea -- ./deploy.sh
+# 预览 run 会注入哪些变量（不执行命令）
+secrets run -n refining --kind service --name gitea --dry-run
 ```
 
 ## 完整命令参考
@@ -108,6 +107,8 @@ secrets update --help
 secrets delete --help
 secrets config --help
 secrets upgrade --help     # 检查并更新 CLI 版本
+secrets export --help      # 批量导出（JSON/TOML/YAML）
+secrets import --help      # 批量导入（JSON/TOML/YAML）
 
 # ── search ──────────────────────────────────────────────────────────────────
 secrets search --summary --limit 20                        # 发现概览
@@ -116,14 +117,14 @@ secrets search -n refining --kind service --name gitea     # 精确查找
 secrets search -q mqtt                                     # 关键词模糊搜索
 secrets search --tag hongkong                              # 按 tag 过滤
 secrets search -n refining --kind service --name gitea -f metadata.url   # 提取 metadata 字段
-secrets search -n refining --kind service --name gitea -o json            # 完整记录（secrets 保持占位）
+secrets search -n refining --kind service --name gitea -o json            # 完整记录（含 secrets schema）
 secrets search --sort updated --limit 10 --summary         # 最近改动
 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 字段
@@ -139,7 +140,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 ───────────────────────────────────────────────────────────────────
@@ -149,7 +150,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 位，派生后存钥匙串）
@@ -161,7 +165,31 @@ 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
+secrets export -n refining --file refining.toml          # 按 namespace 导出为 TOML
+secrets export -n refining --kind service --file svc.yaml   # 按 kind 导出为 YAML
+secrets export --tag production --file prod.json         # 按 tag 过滤
+secrets export -q mqtt --file mqtt.json                   # 模糊搜索导出
+secrets export --no-secrets --file schema.json           # 仅导出 schema（无需主密钥）
+secrets export -n refining --format yaml                  # 输出到 stdout，指定格式
+
+# ── import ────────────────────────────────────────────────────────────────────
+secrets import backup.json                               # 导入（冲突时报错）
+secrets import --force refining.toml                     # 冲突时覆盖已有记录
+secrets import --dry-run backup.yaml                     # 预览将要执行的操作（不写入）
+
+# ── run ───────────────────────────────────────────────────────────────────────
+secrets run -n refining --kind service --name gitea -- ./deploy.sh            # 注入全部 secrets
+secrets run -n refining --kind service --name gitea -s token -- ./deploy.sh   # 只注入 token 字段
+secrets run -n refining --kind service --name aliyun \
+  -s access_key_id -s access_key_secret -- aliyun ecs DescribeInstances       # 只注入指定字段
+secrets run --tag production -- env                                            # 按 tag 批量注入
+secrets run -n refining --kind service --name gitea --dry-run                 # 预览变量映射
+secrets run -n refining --kind service --name gitea -s token --dry-run        # 过滤后预览
+secrets run -n refining --kind service --name gitea --dry-run -o text         # 人类可读预览
 
 # ── 调试 ──────────────────────────────────────────────────────────────────────
 secrets --verbose search -q mqtt
@@ -170,18 +198,21 @@ RUST_LOG=secrets=trace secrets search
 
 ## 数据模型
 
-单张 `secrets` 表，首次连接自动建表；同时自动创建 `audit_log` 表，记录所有写操作。
+主表 `entries`（namespace、kind、name、tags、metadata）+ 子表 `secrets`（每个加密字段一行，含 field_name、encrypted）。首次连接自动建表；同时创建 `audit_log`、`entries_history`、`secrets_history` 等表。
 
-| 字段 | 说明 |
-|------|------|
-| `namespace` | 一级隔离，如 `refining`、`ricnsmart` |
-| `kind` | 记录类型，如 `server`、`service`（可自由扩展） |
-| `name` | 人类可读唯一标识 |
-| `tags` | 多维标签，如 `["aliyun","hongkong"]` |
-| `metadata` | 明文描述信息（ip、desc、domains 等） |
-| `encrypted` | 敏感凭据（ssh_key、password、token 等），AES-256-GCM 加密存储 |
+| 位置 | 字段 | 说明 |
+|------|------|------|
+| entries | namespace | 一级隔离，如 `refining`、`ricnsmart` |
+| entries | kind | 记录类型，如 `server`、`service`、`key`（可自由扩展） |
+| entries | name | 人类可读唯一标识 |
+| entries | tags | 多维标签，如 `["aliyun","hongkong"]` |
+| entries | metadata | 明文描述（ip、desc、domains、key_ref 等） |
+| secrets | field_name | 明文，search 可见，AI 可推断 run 会注入哪些变量 |
+| secrets | encrypted | 仅加密值本身，AES-256-GCM |
 
-`-m` / `--meta` 写入 `metadata`，`-s` / `--secret` 写入 `encrypted`。支持 `key=value`、`key=@file`、`key:=<json>`，也支持 `credentials:content@./key.pem` 这种嵌套字段文件写入语法，避免手动转义多行文本；删除时也支持 `--remove-secret credentials:content` 和 `--remove-meta credentials:content`。加解密使用主密钥（由 `secrets init` 设置）。
+`-m` / `--meta` 写入 `metadata`，`-s` / `--secret` 写入 `secrets` 表的独立行。支持 `key=value`、`key=@file`、`key:=<json>`，也支持 `credentials:content@./key.pem` 这类嵌套字段文件写入；删除时支持 `--remove-secret credentials:content`。加解密使用主密钥（由 `secrets init` 设置）。
+
+**PEM 共享**：同一 PEM 被多台服务器共享时，可存为 `kind=key` 记录，服务器通过 `metadata.key_ref` 引用；轮换只需 update 一条 key 记录，所有引用自动生效。详见 [AGENTS.md](AGENTS.md)。
 
 ### `-m` / `--meta` JSON 语法速查
 
@@ -189,12 +220,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}}}` |
 
@@ -209,10 +240,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}'
 ```
 
@@ -285,18 +316,22 @@ src/
   main.rs          # CLI 入口（clap），含各子命令 after_help 示例
   output.rs        # OutputMode 枚举 + TTY 检测
   config.rs        # 配置读写（~/.config/secrets/config.toml）
-  db.rs            # 连接池 + auto-migrate（secrets + audit_log + kv_config）
+  db.rs            # 连接池 + auto-migrate（entries + secrets + entries_history + secrets_history + audit_log + kv_config）
   crypto.rs        # AES-256-GCM 加解密、Argon2id 派生、OS 钥匙串
-  models.rs        # Secret 结构体
+  models.rs        # Entry + SecretField 结构体
   audit.rs         # 审计日志写入（audit_log 表）
   commands/
     init.rs        # 主密钥初始化（首次/新设备）
-    add.rs         # upsert，支持 -o json
+    add.rs         # upsert entries + secrets 行，支持 -o json
     config.rs      # config set-db/show/path
-    search.rs      # 多条件查询，支持 -f/-o/--summary/--limit/--offset/--sort
-    delete.rs      # 删除
-    update.rs      # 增量更新（合并 tags/metadata/encrypted）
+    search.rs      # 多条件查询，展示 secrets schema（-f/-o/--summary/--limit/--offset/--sort）
+    delete.rs      # 删除（CASCADE 删除 secrets）
+    update.rs      # 增量更新（tags/metadata + secrets 行级 UPSERT/DELETE）
+    rollback.rs    # rollback / history：按 entry_version 恢复
+    run.rs         # run，仅 secrets 逐字段解密 + key_ref 引用解析（不含 metadata）
     upgrade.rs     # 从 Gitea Release 自更新
+    export_cmd.rs  # export：批量导出，支持 JSON/TOML/YAML，含解密明文
+    import_cmd.rs  # import：批量导入，冲突检测，dry-run，重新加密写入
 scripts/
   setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
 ```

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)",

src/commands/add.rs

@@ -5,7 +5,10 @@ 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) ───────────────────────
 
 /// Parse secret / metadata entries into a nested key path and JSON value.
 /// - `key=value`        → stores the literal string `value`
@@ -158,6 +161,30 @@ pub(crate) fn remove_path(map: &mut Map<String, Value>, path: &[String]) -> Resu
     Ok(removed)
 }
 
+/// Flatten a (potentially nested) JSON object into dot-separated field entries.
+/// e.g. `{"credentials": {"type": "ssh", "content": "..."}}` →
+///   `[("credentials.type", "ssh"), ("credentials.content", "...")]`
+/// Top-level non-object values are emitted directly.
+pub(crate) fn flatten_json_fields(prefix: &str, value: &Value) -> Vec<(String, Value)> {
+    match value {
+        Value::Object(map) => {
+            let mut out = Vec::new();
+            for (k, v) in map {
+                let full_key = if prefix.is_empty() {
+                    k.clone()
+                } else {
+                    format!("{}.{}", prefix, k)
+                };
+                out.extend(flatten_json_fields(&full_key, v));
+            }
+            out
+        }
+        other => vec![(prefix.to_string(), other.clone())],
+    }
+}
+
+// ── Add command ──────────────────────────────────────────────────────────────
+
 pub struct AddArgs<'a> {
     pub namespace: &'a str,
     pub kind: &'a str,
@@ -171,26 +198,17 @@ pub struct AddArgs<'a> {
 pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
     let metadata = build_json(args.meta_entries)?;
     let secret_json = build_json(args.secret_entries)?;
-    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
 
-    tracing::debug!(args.namespace, args.kind, args.name, "upserting record");
+    tracing::debug!(args.namespace, args.kind, args.name, "upserting entry");
 
     let meta_keys = collect_key_paths(args.meta_entries)?;
     let secret_keys = collect_key_paths(args.secret_entries)?;
 
     let mut tx = pool.begin().await?;
 
-    // Snapshot existing row into history before overwriting (if it exists).
-    #[derive(sqlx::FromRow)]
-    struct ExistingRow {
-        id: uuid::Uuid,
-        version: i64,
-        tags: Vec<String>,
-        metadata: serde_json::Value,
-        encrypted: Vec<u8>,
-    }
-    let existing: Option<ExistingRow> = sqlx::query_as(
-        "SELECT id, version, tags, metadata, encrypted FROM secrets \
+    // Upsert the entry row (tags + metadata).
+    let existing: Option<EntryRow> = sqlx::query_as(
+        "SELECT id, version, tags, metadata FROM entries \
          WHERE namespace = $1 AND kind = $2 AND name = $3",
     )
     .bind(args.namespace)
@@ -199,11 +217,12 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
     .fetch_optional(&mut *tx)
     .await?;
 
-    if let Some(ex) = existing
-        && let Err(e) = db::snapshot_history(
+    // Snapshot the current entry state before overwriting.
+    if let Some(ref ex) = existing
+        && let Err(e) = db::snapshot_entry_history(
             &mut tx,
-            db::SnapshotParams {
-                secret_id: ex.id,
+            db::EntrySnapshotParams {
+                entry_id: ex.id,
                 namespace: args.namespace,
                 kind: args.kind,
                 name: args.name,
@@ -211,25 +230,24 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
                 action: "add",
                 tags: &ex.tags,
                 metadata: &ex.metadata,
-                encrypted: &ex.encrypted,
             },
         )
         .await
     {
-        tracing::warn!(error = %e, "failed to snapshot history before upsert");
+        tracing::warn!(error = %e, "failed to snapshot entry history before upsert");
     }
 
-    sqlx::query(
+    let entry_id: uuid::Uuid = sqlx::query_scalar(
         r#"
-        INSERT INTO secrets (namespace, kind, name, tags, metadata, encrypted, version, updated_at)
-        VALUES ($1, $2, $3, $4, $5, $6, 1, NOW())
+        INSERT INTO entries (namespace, kind, name, tags, metadata, version, updated_at)
+        VALUES ($1, $2, $3, $4, $5, 1, NOW())
         ON CONFLICT (namespace, kind, name)
         DO UPDATE SET
             tags       = EXCLUDED.tags,
             metadata   = EXCLUDED.metadata,
-            encrypted  = EXCLUDED.encrypted,
-            version    = secrets.version + 1,
+            version    = entries.version + 1,
             updated_at = NOW()
+        RETURNING id
         "#,
     )
     .bind(args.namespace)
@@ -237,10 +255,71 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
     .bind(args.name)
     .bind(args.tags)
     .bind(&metadata)
-    .bind(&encrypted_bytes)
-    .execute(&mut *tx)
+    .fetch_one(&mut *tx)
     .await?;
 
+    let new_entry_version: i64 = sqlx::query_scalar("SELECT version FROM entries WHERE id = $1")
+        .bind(entry_id)
+        .fetch_one(&mut *tx)
+        .await?;
+
+    // Snapshot existing secret fields before replacing.
+    if existing.is_some() {
+        #[derive(sqlx::FromRow)]
+        struct ExistingField {
+            id: uuid::Uuid,
+            field_name: String,
+            encrypted: Vec<u8>,
+        }
+        let existing_fields: Vec<ExistingField> = sqlx::query_as(
+            "SELECT id, field_name, encrypted \
+             FROM secrets WHERE entry_id = $1",
+        )
+        .bind(entry_id)
+        .fetch_all(&mut *tx)
+        .await?;
+
+        for f in &existing_fields {
+            if let Err(e) = db::snapshot_secret_history(
+                &mut tx,
+                db::SecretSnapshotParams {
+                    entry_id,
+                    secret_id: f.id,
+                    entry_version: new_entry_version - 1,
+                    field_name: &f.field_name,
+                    encrypted: &f.encrypted,
+                    action: "add",
+                },
+            )
+            .await
+            {
+                tracing::warn!(error = %e, "failed to snapshot secret field history");
+            }
+        }
+
+        // Delete existing secret fields so we can re-insert the full set.
+        sqlx::query("DELETE FROM secrets WHERE entry_id = $1")
+            .bind(entry_id)
+            .execute(&mut *tx)
+            .await?;
+    }
+
+    // Insert new secret fields.
+    let flat_fields = flatten_json_fields("", &secret_json);
+    for (field_name, field_value) in &flat_fields {
+        let encrypted = crypto::encrypt_json(master_key, field_value)?;
+
+        sqlx::query(
+            "INSERT INTO secrets (entry_id, field_name, encrypted) \
+             VALUES ($1, $2, $3)",
+        )
+        .bind(entry_id)
+        .bind(field_name)
+        .bind(&encrypted)
+        .execute(&mut *tx)
+        .await?;
+    }
+
     crate::audit::log_tx(
         &mut tx,
         "add",
@@ -268,11 +347,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);
@@ -293,7 +369,7 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
 
 #[cfg(test)]
 mod tests {
-    use super::{build_json, key_path_to_string, parse_kv, remove_path};
+    use super::{build_json, flatten_json_fields, key_path_to_string, parse_kv, remove_path};
     use serde_json::Value;
     use std::fs;
     use std::path::PathBuf;
@@ -363,4 +439,21 @@ mod tests {
         assert!(removed);
         assert_eq!(value, serde_json::json!({ "username": "root" }));
     }
+
+    #[test]
+    fn flatten_json_fields_nested() {
+        let v = serde_json::json!({
+            "username": "root",
+            "credentials": {
+                "type": "ssh",
+                "content": "pem-data"
+            }
+        });
+        let mut fields = flatten_json_fields("", &v);
+        fields.sort_by(|a, b| a.0.cmp(&b.0));
+
+        assert_eq!(fields[0].0, "credentials.content");
+        assert_eq!(fields[1].0, "credentials.type");
+        assert_eq!(fields[2].0, "username");
+    }
 }

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(())

src/commands/delete.rs

@@ -1,33 +1,64 @@
 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 DeleteRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
-    encrypted: Vec<u8>,
+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,
 }
 
-pub async fn run(
+// ── 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>,
+}
+
+// ── 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,
     name: &str,
     output: OutputMode,
 ) -> Result<()> {
-    tracing::debug!(namespace, kind, name, "deleting record");
+    tracing::debug!(namespace, kind, name, "deleting entry");
 
     let mut tx = pool.begin().await?;
 
-    let row: Option<DeleteRow> = sqlx::query_as(
-        "SELECT id, version, tags, metadata, encrypted FROM secrets \
+    let row: Option<EntryRow> = sqlx::query_as(
+        "SELECT id, version, tags, metadata FROM entries \
          WHERE namespace = $1 AND kind = $2 AND name = $3 \
          FOR UPDATE",
     )
@@ -39,30 +70,178 @@ pub async fn run(
 
     let Some(row) = row else {
         tx.rollback().await?;
-        tracing::warn!(namespace, kind, name, "record not found for deletion");
+        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 before physical delete so the row can be restored via rollback.
-    if let Err(e) = db::snapshot_history(
-        &mut tx,
-        db::SnapshotParams {
-            secret_id: row.id,
+    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(
+        tx,
+        db::EntrySnapshotParams {
+            entry_id: row.id,
             namespace,
             kind,
             name,
@@ -70,38 +249,43 @@ pub async fn run(
             action: "delete",
             tags: &row.tags,
             metadata: &row.metadata,
-            encrypted: &row.encrypted,
         },
     )
     .await
     {
-        tracing::warn!(error = %e, "failed to snapshot history before delete");
+        tracing::warn!(error = %e, "failed to snapshot entry history before delete");
     }
 
-    sqlx::query("DELETE FROM secrets WHERE id = $1")
+    let fields: Vec<SecretFieldRow> = sqlx::query_as(
+        "SELECT id, field_name, encrypted \
+         FROM secrets WHERE entry_id = $1",
+    )
+    .bind(row.id)
+    .fetch_all(&mut **tx)
+    .await?;
+
+    for f in &fields {
+        if let Err(e) = db::snapshot_secret_history(
+            tx,
+            db::SecretSnapshotParams {
+                entry_id: row.id,
+                secret_id: f.id,
+                entry_version: row.version,
+                field_name: &f.field_name,
+                encrypted: &f.encrypted,
+                action: "delete",
+            },
+        )
+        .await
+        {
+            tracing::warn!(error = %e, "failed to snapshot secret history before delete");
+        }
+    }
+
+    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(())
 }

src/commands/export_cmd.rs

@@ -0,0 +1,109 @@
+use anyhow::Result;
+use sqlx::PgPool;
+use std::collections::BTreeMap;
+use std::io::Write;
+
+use crate::commands::search::{fetch_entries, fetch_secrets_for_entries};
+use crate::crypto;
+use crate::models::{ExportData, ExportEntry, ExportFormat};
+
+pub struct ExportArgs<'a> {
+    pub namespace: Option<&'a str>,
+    pub kind: Option<&'a str>,
+    pub name: Option<&'a str>,
+    pub tags: &'a [String],
+    pub query: Option<&'a str>,
+    /// Output file path. None means write to stdout.
+    pub file: Option<&'a str>,
+    /// Explicit format override (e.g. from --format flag).
+    pub format: Option<&'a str>,
+    /// When true, secrets are omitted and master_key is not used.
+    pub no_secrets: bool,
+}
+
+pub async fn run(pool: &PgPool, args: ExportArgs<'_>, master_key: Option<&[u8; 32]>) -> Result<()> {
+    // Determine output format: --format > file extension > default JSON.
+    let format = if let Some(fmt_str) = args.format {
+        ExportFormat::from_str(fmt_str)?
+    } else if let Some(path) = args.file {
+        ExportFormat::from_extension(path).unwrap_or(ExportFormat::Json)
+    } else {
+        ExportFormat::Json
+    };
+
+    let entries = fetch_entries(
+        pool,
+        args.namespace,
+        args.kind,
+        args.name,
+        args.tags,
+        args.query,
+    )
+    .await?;
+
+    let entry_ids: Vec<uuid::Uuid> = entries.iter().map(|e| e.id).collect();
+
+    let secrets_map = if !args.no_secrets && !entry_ids.is_empty() {
+        fetch_secrets_for_entries(pool, &entry_ids).await?
+    } else {
+        std::collections::HashMap::new()
+    };
+
+    let key = if !args.no_secrets { master_key } else { None };
+
+    let mut export_entries: Vec<ExportEntry> = Vec::with_capacity(entries.len());
+    for entry in &entries {
+        let secrets = if args.no_secrets {
+            None
+        } else {
+            let fields = secrets_map.get(&entry.id).map(Vec::as_slice).unwrap_or(&[]);
+            if fields.is_empty() {
+                Some(BTreeMap::new())
+            } else {
+                let mk =
+                    key.ok_or_else(|| anyhow::anyhow!("master key required to decrypt secrets"))?;
+                let mut map = BTreeMap::new();
+                for f in fields {
+                    let decrypted = crypto::decrypt_json(mk, &f.encrypted)?;
+                    map.insert(f.field_name.clone(), decrypted);
+                }
+                Some(map)
+            }
+        };
+
+        export_entries.push(ExportEntry {
+            namespace: entry.namespace.clone(),
+            kind: entry.kind.clone(),
+            name: entry.name.clone(),
+            tags: entry.tags.clone(),
+            metadata: entry.metadata.clone(),
+            secrets,
+        });
+    }
+
+    let data = ExportData {
+        version: 1,
+        exported_at: chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+        entries: export_entries,
+    };
+
+    let serialized = format.serialize(&data)?;
+
+    if let Some(path) = args.file {
+        std::fs::write(path, &serialized)?;
+        println!(
+            "Exported {} record(s) to {} ({:?})",
+            data.entries.len(),
+            path,
+            format
+        );
+    } else {
+        std::io::stdout().write_all(serialized.as_bytes())?;
+        // Ensure trailing newline on stdout.
+        if !serialized.ends_with('\n') {
+            println!();
+        }
+    }
+
+    Ok(())
+}

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(())
+}

src/commands/import_cmd.rs

@@ -0,0 +1,217 @@
+use anyhow::Result;
+use serde_json::Value;
+use sqlx::PgPool;
+use std::collections::BTreeMap;
+
+use crate::commands::add::{self, AddArgs};
+use crate::models::ExportFormat;
+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,
+    pub output: OutputMode,
+}
+
+pub async fn run(pool: &PgPool, args: ImportArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
+    let format = ExportFormat::from_extension(args.file)?;
+    let content = std::fs::read_to_string(args.file)
+        .map_err(|e| anyhow::anyhow!("Cannot read file '{}': {}", args.file, e))?;
+    let data = format.deserialize(&content)?;
+
+    if data.version != 1 {
+        anyhow::bail!(
+            "Unsupported export version {}. Only version 1 is supported.",
+            data.version
+        );
+    }
+
+    let total = data.entries.len();
+    let mut inserted = 0usize;
+    let mut skipped = 0usize;
+    let mut failed = 0usize;
+
+    for entry in &data.entries {
+        // Check if record already exists.
+        let exists: bool = sqlx::query_scalar(
+            "SELECT EXISTS(SELECT 1 FROM entries \
+             WHERE namespace = $1 AND kind = $2 AND name = $3)",
+        )
+        .bind(&entry.namespace)
+        .bind(&entry.kind)
+        .bind(&entry.name)
+        .fetch_one(pool)
+        .await
+        .unwrap_or(false);
+
+        if exists && !args.force {
+            let v = serde_json::json!({
+                "action": "conflict",
+                "namespace": entry.namespace,
+                "kind": entry.kind,
+                "name": entry.name,
+            });
+            match args.output {
+                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!();
+                }
+            }
+            return Err(anyhow::anyhow!(
+                "Import aborted: conflict on [{}/{}/{}]",
+                entry.namespace,
+                entry.kind,
+                entry.name
+            ));
+        }
+
+        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::Text => println!(
+                    "[dry-run] {} [{}/{}/{}]",
+                    action, entry.namespace, entry.kind, entry.name
+                ),
+                ref mode => print_json(&v, mode)?,
+            }
+            if exists {
+                skipped += 1;
+            } else {
+                inserted += 1;
+            }
+            continue;
+        }
+
+        // Build secret_entries: convert BTreeMap<String, Value> to Vec<String> ("key:=json")
+        let secret_entries = build_secret_entries(entry.secrets.as_ref());
+
+        // Build meta_entries from metadata JSON object.
+        let meta_entries = build_meta_entries(&entry.metadata);
+
+        match add::run(
+            pool,
+            AddArgs {
+                namespace: &entry.namespace,
+                kind: &entry.kind,
+                name: &entry.name,
+                tags: &entry.tags,
+                meta_entries: &meta_entries,
+                secret_entries: &secret_entries,
+                output: OutputMode::Text,
+            },
+            master_key,
+        )
+        .await
+        {
+            Ok(()) => {
+                let v = serde_json::json!({
+                    "action": action,
+                    "namespace": entry.namespace,
+                    "kind": entry.kind,
+                    "name": entry.name,
+                });
+                match args.output {
+                    OutputMode::Text => println!(
+                        "Imported [{}/{}/{}]",
+                        entry.namespace, entry.kind, entry.name
+                    ),
+                    ref mode => print_json(&v, mode)?,
+                }
+                inserted += 1;
+            }
+            Err(e) => {
+                eprintln!(
+                    "Error importing [{}/{}/{}]: {}",
+                    entry.namespace, entry.kind, entry.name, e
+                );
+                failed += 1;
+            }
+        }
+    }
+
+    let summary = serde_json::json!({
+        "total": total,
+        "inserted": inserted,
+        "skipped": skipped,
+        "failed": failed,
+        "dry_run": args.dry_run,
+    });
+    match args.output {
+        OutputMode::Text => {
+            if args.dry_run {
+                println!(
+                    "\n[dry-run] {} total: {} would insert, {} would skip, {} would fail",
+                    total, inserted, skipped, failed
+                );
+            } else {
+                println!(
+                    "\nImport done: {} total — {} inserted, {} skipped, {} failed",
+                    total, inserted, skipped, failed
+                );
+            }
+        }
+        ref mode => print_json(&summary, mode)?,
+    }
+
+    if failed > 0 {
+        anyhow::bail!("{} record(s) failed to import", failed);
+    }
+
+    Ok(())
+}
+
+/// Convert metadata JSON object into Vec<String> of "key:=json_value" entries.
+fn build_meta_entries(metadata: &Value) -> Vec<String> {
+    let mut entries = Vec::new();
+    if let Some(obj) = metadata.as_object() {
+        for (k, v) in obj {
+            entries.push(value_to_kv_entry(k, v));
+        }
+    }
+    entries
+}
+
+/// Convert a BTreeMap<String, Value> (secrets) into Vec<String> of "key:=json_value" entries.
+fn build_secret_entries(secrets: Option<&BTreeMap<String, Value>>) -> Vec<String> {
+    let mut entries = Vec::new();
+    if let Some(map) = secrets {
+        for (k, v) in map {
+            entries.push(value_to_kv_entry(k, v));
+        }
+    }
+    entries
+}
+
+/// Convert a key/value pair to a CLI-style entry string.
+/// Strings use `key=value`; everything else uses `key:=<json>`.
+fn value_to_kv_entry(key: &str, value: &Value) -> String {
+    match value {
+        Value::String(s) => format!("{}={}", key, s),
+        other => format!("{}:={}", key, other),
+    }
+}

src/commands/mod.rs

@@ -1,6 +1,9 @@
 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;
 pub mod run;

src/commands/rollback.rs

@@ -3,32 +3,34 @@ use serde_json::{Value, json};
 use sqlx::{FromRow, PgPool};
 use uuid::Uuid;
 
-use crate::output::{OutputMode, format_local_time};
-
-#[derive(FromRow)]
-struct HistoryRow {
-    secret_id: Uuid,
-    version: i64,
-    action: String,
-    tags: Vec<String>,
-    metadata: Value,
-    encrypted: Vec<u8>,
-}
+use crate::crypto;
+use crate::db;
+use crate::output::{OutputMode, print_json};
 
 pub struct RollbackArgs<'a> {
     pub namespace: &'a str,
     pub kind: &'a str,
     pub name: &'a str,
-    /// Target version to restore. None → restore the most recent history entry.
+    /// Target entry version to restore. None → restore the most recent history entry.
     pub to_version: Option<i64>,
     pub output: OutputMode,
 }
 
 pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
-    let snap: Option<HistoryRow> = if let Some(ver) = args.to_version {
+    // ── Find the target entry history snapshot ────────────────────────────────
+    #[derive(FromRow)]
+    struct EntryHistoryRow {
+        entry_id: Uuid,
+        version: i64,
+        action: String,
+        tags: Vec<String>,
+        metadata: Value,
+    }
+
+    let snap: Option<EntryHistoryRow> = if let Some(ver) = args.to_version {
         sqlx::query_as(
-            "SELECT secret_id, version, action, tags, metadata, encrypted \
-             FROM secrets_history \
+            "SELECT entry_id, version, action, tags, metadata \
+             FROM entries_history \
              WHERE namespace = $1 AND kind = $2 AND name = $3 AND version = $4 \
              ORDER BY id DESC LIMIT 1",
         )
@@ -40,8 +42,8 @@ pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -
         .await?
     } else {
         sqlx::query_as(
-            "SELECT secret_id, version, action, tags, metadata, encrypted \
-             FROM secrets_history \
+            "SELECT entry_id, version, action, tags, metadata \
+             FROM entries_history \
              WHERE namespace = $1 AND kind = $2 AND name = $3 \
              ORDER BY id DESC LIMIT 1",
         )
@@ -64,25 +66,51 @@ pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -
         )
     })?;
 
-    // Validate encrypted blob is non-trivial (re-encrypt guard).
-    if !snap.encrypted.is_empty() {
-        // Probe decrypt to ensure the blob is valid before restoring.
-        crate::crypto::decrypt_json(master_key, &snap.encrypted)?;
+    // ── Find the matching secret field snapshots ──────────────────────────────
+    #[derive(FromRow)]
+    struct SecretHistoryRow {
+        secret_id: Uuid,
+        field_name: String,
+        encrypted: Vec<u8>,
+        action: String,
+    }
+
+    let field_snaps: Vec<SecretHistoryRow> = sqlx::query_as(
+        "SELECT secret_id, field_name, encrypted, action \
+         FROM secrets_history \
+         WHERE entry_id = $1 AND entry_version = $2 \
+         ORDER BY field_name",
+    )
+    .bind(snap.entry_id)
+    .bind(snap.version)
+    .fetch_all(pool)
+    .await?;
+
+    // Validate: try decrypting all encrypted fields before writing anything.
+    for f in &field_snaps {
+        if f.action != "delete" && !f.encrypted.is_empty() {
+            crypto::decrypt_json(master_key, &f.encrypted).map_err(|e| {
+                anyhow::anyhow!(
+                    "Cannot decrypt snapshot for field '{}': {}",
+                    f.field_name,
+                    e
+                )
+            })?;
+        }
     }
 
     let mut tx = pool.begin().await?;
 
-    // Snapshot current live row (if it exists) before overwriting.
+    // ── Snapshot the current live state before overwriting ────────────────────
     #[derive(sqlx::FromRow)]
-    struct LiveRow {
+    struct LiveEntry {
         id: Uuid,
         version: i64,
         tags: Vec<String>,
         metadata: Value,
-        encrypted: Vec<u8>,
     }
-    let live: Option<LiveRow> = sqlx::query_as(
-        "SELECT id, version, tags, metadata, encrypted FROM secrets \
+    let live: Option<LiveEntry> = sqlx::query_as(
+        "SELECT id, version, tags, metadata FROM entries \
          WHERE namespace = $1 AND kind = $2 AND name = $3 FOR UPDATE",
     )
     .bind(args.namespace)
@@ -91,11 +119,11 @@ pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -
     .fetch_optional(&mut *tx)
     .await?;
 
-    if let Some(lr) = live
-        && let Err(e) = crate::db::snapshot_history(
+    if let Some(ref lr) = live {
+        if let Err(e) = db::snapshot_entry_history(
             &mut tx,
-            crate::db::SnapshotParams {
-                secret_id: lr.id,
+            db::EntrySnapshotParams {
+                entry_id: lr.id,
                 namespace: args.namespace,
                 kind: args.kind,
                 name: args.name,
@@ -103,35 +131,96 @@ pub async fn run(pool: &PgPool, args: RollbackArgs<'_>, master_key: &[u8; 32]) -
                 action: "rollback",
                 tags: &lr.tags,
                 metadata: &lr.metadata,
-                encrypted: &lr.encrypted,
             },
         )
         .await
-    {
-        tracing::warn!(error = %e, "failed to snapshot current row before rollback");
+        {
+            tracing::warn!(error = %e, "failed to snapshot entry before rollback");
+        }
+
+        // Snapshot existing secret fields.
+        #[derive(sqlx::FromRow)]
+        struct LiveField {
+            id: Uuid,
+            field_name: String,
+            encrypted: Vec<u8>,
+        }
+        let live_fields: Vec<LiveField> = sqlx::query_as(
+            "SELECT id, field_name, encrypted \
+             FROM secrets WHERE entry_id = $1",
+        )
+        .bind(lr.id)
+        .fetch_all(&mut *tx)
+        .await?;
+
+        for f in &live_fields {
+            if let Err(e) = db::snapshot_secret_history(
+                &mut tx,
+                db::SecretSnapshotParams {
+                    entry_id: lr.id,
+                    secret_id: f.id,
+                    entry_version: lr.version,
+                    field_name: &f.field_name,
+                    encrypted: &f.encrypted,
+                    action: "rollback",
+                },
+            )
+            .await
+            {
+                tracing::warn!(error = %e, "failed to snapshot secret field before rollback");
+            }
+        }
     }
 
+    // ── Restore entry row ─────────────────────────────────────────────────────
     sqlx::query(
-        "INSERT INTO secrets (id, namespace, kind, name, tags, metadata, encrypted, version, updated_at) \
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, NOW()) \
+        "INSERT INTO entries (id, namespace, kind, name, tags, metadata, version, updated_at) \
+         VALUES ($1, $2, $3, $4, $5, $6, $7, NOW()) \
          ON CONFLICT (namespace, kind, name) DO UPDATE SET \
              tags       = EXCLUDED.tags, \
              metadata   = EXCLUDED.metadata, \
-             encrypted  = EXCLUDED.encrypted, \
-             version    = secrets.version + 1, \
+             version    = entries.version + 1, \
              updated_at = NOW()",
     )
-    .bind(snap.secret_id)
+    .bind(snap.entry_id)
     .bind(args.namespace)
     .bind(args.kind)
     .bind(args.name)
     .bind(&snap.tags)
     .bind(&snap.metadata)
-    .bind(&snap.encrypted)
     .bind(snap.version)
     .execute(&mut *tx)
     .await?;
 
+    // ── Restore secret fields ─────────────────────────────────────────────────
+    // Delete all current fields and re-insert from snapshot
+    // (only non-deleted fields from the snapshot are restored).
+    sqlx::query("DELETE FROM secrets WHERE entry_id = $1")
+        .bind(snap.entry_id)
+        .execute(&mut *tx)
+        .await?;
+
+    for f in &field_snaps {
+        if f.action == "delete" {
+            // Field was deleted at this snapshot point — don't restore it.
+            continue;
+        }
+        sqlx::query(
+            "INSERT INTO secrets (id, entry_id, field_name, encrypted) \
+             VALUES ($1, $2, $3, $4) \
+             ON CONFLICT (entry_id, field_name) DO UPDATE SET \
+                 encrypted  = EXCLUDED.encrypted, \
+                 version    = secrets.version + 1, \
+                 updated_at = NOW()",
+        )
+        .bind(f.secret_id)
+        .bind(snap.entry_id)
+        .bind(&f.field_name)
+        .bind(&f.encrypted)
+        .execute(&mut *tx)
+        .await?;
+    }
+
     crate::audit::log_tx(
         &mut tx,
         "rollback",
@@ -156,83 +245,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 a record.
-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 secrets_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(())

src/commands/run.rs

@@ -1,54 +1,78 @@
 use anyhow::Result;
-use serde_json::Value;
+use serde_json::json;
 use sqlx::PgPool;
 use std::collections::HashMap;
 
-use crate::commands::search::build_injected_env_map;
+use crate::commands::search::{build_injected_env_map, fetch_entries, fetch_secrets_for_entries};
 use crate::output::OutputMode;
 
-pub struct InjectArgs<'a> {
-    pub namespace: Option<&'a str>,
-    pub kind: Option<&'a str>,
-    pub name: Option<&'a str>,
-    pub tags: &'a [String],
-    /// Prefix to prepend to every variable name. Empty string means no prefix.
-    pub prefix: &'a str,
-    pub output: OutputMode,
-}
-
 pub struct RunArgs<'a> {
     pub namespace: Option<&'a str>,
     pub kind: Option<&'a str>,
     pub name: Option<&'a str>,
     pub tags: &'a [String],
+    pub secret_fields: &'a [String],
     pub prefix: &'a str,
-    /// The command and its arguments to execute with injected secrets.
+    pub dry_run: bool,
+    pub output: OutputMode,
     pub command: &'a [String],
 }
 
-/// Fetch secrets matching the filter and build a flat env map.
-/// Metadata and secret fields are merged; naming: `<PREFIX_><NAME>_<KEY>` (uppercased).
-pub async fn collect_env_map(
+/// A single environment variable with its origin for dry-run display.
+pub struct EnvMapping {
+    pub var_name: String,
+    pub source: String,
+    pub field: String,
+}
+
+struct CollectArgs<'a> {
+    namespace: Option<&'a str>,
+    kind: Option<&'a str>,
+    name: Option<&'a str>,
+    tags: &'a [String],
+    secret_fields: &'a [String],
+    prefix: &'a str,
+}
+
+/// Fetch entries matching the filter and build a flat env map (decrypted secrets only, no metadata).
+/// If `secret_fields` is non-empty, only those fields are decrypted and included.
+async fn collect_env_map(
     pool: &PgPool,
-    namespace: Option<&str>,
-    kind: Option<&str>,
-    name: Option<&str>,
-    tags: &[String],
-    prefix: &str,
+    args: &CollectArgs<'_>,
     master_key: &[u8; 32],
 ) -> Result<HashMap<String, String>> {
-    if namespace.is_none() && kind.is_none() && name.is_none() && tags.is_empty() {
+    if args.namespace.is_none()
+        && args.kind.is_none()
+        && args.name.is_none()
+        && args.tags.is_empty()
+    {
         anyhow::bail!(
-            "At least one filter (--namespace, --kind, --name, or --tag) is required for inject/run"
+            "At least one filter (--namespace, --kind, --name, or --tag) is required for run"
         );
     }
-    let rows = crate::commands::search::fetch_rows(pool, namespace, kind, name, tags, None).await?;
-    if rows.is_empty() {
+    let entries =
+        fetch_entries(pool, args.namespace, args.kind, args.name, args.tags, None).await?;
+    if entries.is_empty() {
         anyhow::bail!("No records matched the given filters.");
     }
+
+    let entry_ids: Vec<uuid::Uuid> = entries.iter().map(|e| e.id).collect();
+    let fields_map = fetch_secrets_for_entries(pool, &entry_ids).await?;
+
     let mut map = HashMap::new();
-    for row in &rows {
-        let row_map = build_injected_env_map(row, prefix, master_key)?;
+    for entry in &entries {
+        let empty = vec![];
+        let all_fields = fields_map.get(&entry.id).unwrap_or(&empty);
+        let filtered_fields: Vec<_> = if args.secret_fields.is_empty() {
+            all_fields.iter().collect()
+        } else {
+            all_fields
+                .iter()
+                .filter(|f| args.secret_fields.contains(&f.field_name))
+                .collect()
+        };
+        let row_map =
+            build_injected_env_map(pool, entry, args.prefix, master_key, &filtered_fields).await?;
         for (k, v) in row_map {
             map.insert(k, v);
         }
@@ -56,65 +80,152 @@ pub async fn collect_env_map(
     Ok(map)
 }
 
-/// `inject` command: print env vars to stdout (suitable for `eval $(...)` or export).
-pub async fn run_inject(pool: &PgPool, args: InjectArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
-    let env_map = collect_env_map(
-        pool,
-        args.namespace,
-        args.kind,
-        args.name,
-        args.tags,
-        args.prefix,
-        master_key,
-    )
-    .await?;
-
-    match args.output {
-        OutputMode::Json => {
-            let obj: serde_json::Map<String, Value> = env_map
-                .into_iter()
-                .map(|(k, v)| (k, Value::String(v)))
-                .collect();
-            println!("{}", serde_json::to_string_pretty(&Value::Object(obj))?);
-        }
-        OutputMode::JsonCompact => {
-            let obj: serde_json::Map<String, Value> = env_map
-                .into_iter()
-                .map(|(k, v)| (k, Value::String(v)))
-                .collect();
-            println!("{}", serde_json::to_string(&Value::Object(obj))?);
-        }
-        _ => {
-            // Shell-safe KEY=VALUE output, one per line.
-            let mut pairs: Vec<(String, String)> = env_map.into_iter().collect();
-            pairs.sort_by(|a, b| a.0.cmp(&b.0));
-            for (k, v) in pairs {
-                println!("{}={}", k, shell_quote(&v));
-            }
-        }
+/// Like `collect_env_map` but also returns per-variable source info for dry-run display.
+async fn collect_env_map_with_source(
+    pool: &PgPool,
+    args: &CollectArgs<'_>,
+    master_key: &[u8; 32],
+) -> Result<(HashMap<String, String>, Vec<EnvMapping>)> {
+    if args.namespace.is_none()
+        && args.kind.is_none()
+        && args.name.is_none()
+        && args.tags.is_empty()
+    {
+        anyhow::bail!(
+            "At least one filter (--namespace, --kind, --name, or --tag) is required for run"
+        );
+    }
+    let entries =
+        fetch_entries(pool, args.namespace, args.kind, args.name, args.tags, None).await?;
+    if entries.is_empty() {
+        anyhow::bail!("No records matched the given filters.");
     }
 
-    Ok(())
+    let entry_ids: Vec<uuid::Uuid> = entries.iter().map(|e| e.id).collect();
+    let fields_map = fetch_secrets_for_entries(pool, &entry_ids).await?;
+
+    let mut map = HashMap::new();
+    let mut mappings: Vec<EnvMapping> = Vec::new();
+
+    for entry in &entries {
+        let empty = vec![];
+        let all_fields = fields_map.get(&entry.id).unwrap_or(&empty);
+        let filtered_fields: Vec<_> = if args.secret_fields.is_empty() {
+            all_fields.iter().collect()
+        } else {
+            all_fields
+                .iter()
+                .filter(|f| args.secret_fields.contains(&f.field_name))
+                .collect()
+        };
+
+        let row_map =
+            build_injected_env_map(pool, entry, args.prefix, master_key, &filtered_fields).await?;
+
+        let source = format!("{}/{}/{}", entry.namespace, entry.kind, entry.name);
+        for field in &filtered_fields {
+            let var_name = format!(
+                "{}_{}",
+                env_prefix_name(&entry.name, args.prefix),
+                field.field_name.to_uppercase().replace(['-', '.'], "_")
+            );
+            if row_map.contains_key(&var_name) {
+                mappings.push(EnvMapping {
+                    var_name: var_name.clone(),
+                    source: source.clone(),
+                    field: field.field_name.clone(),
+                });
+            }
+        }
+
+        for (k, v) in row_map {
+            map.insert(k, v);
+        }
+    }
+    Ok((map, mappings))
+}
+
+fn env_prefix_name(entry_name: &str, prefix: &str) -> String {
+    let name_part = entry_name.to_uppercase().replace(['-', '.', ' '], "_");
+    if prefix.is_empty() {
+        name_part
+    } else {
+        format!(
+            "{}_{}",
+            prefix.to_uppercase().replace(['-', '.', ' '], "_"),
+            name_part
+        )
+    }
 }
 
 /// `run` command: inject secrets into a child process environment and execute.
+/// With `--dry-run`, prints the variable mapping (names and sources only) without executing.
 pub async fn run_exec(pool: &PgPool, args: RunArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
-    if args.command.is_empty() {
+    if !args.dry_run && args.command.is_empty() {
         anyhow::bail!(
             "No command specified. Usage: secrets run [filter flags] -- <command> [args]"
         );
     }
 
-    let env_map = collect_env_map(
-        pool,
-        args.namespace,
-        args.kind,
-        args.name,
-        args.tags,
-        args.prefix,
-        master_key,
-    )
-    .await?;
+    let collect = CollectArgs {
+        namespace: args.namespace,
+        kind: args.kind,
+        name: args.name,
+        tags: args.tags,
+        secret_fields: args.secret_fields,
+        prefix: args.prefix,
+    };
+
+    if args.dry_run {
+        let (env_map, mappings) = collect_env_map_with_source(pool, &collect, master_key).await?;
+
+        let total_vars = env_map.len();
+        let total_records = {
+            let mut seen = std::collections::HashSet::new();
+            for m in &mappings {
+                seen.insert(&m.source);
+            }
+            seen.len()
+        };
+
+        match args.output {
+            OutputMode::Text => {
+                for m in &mappings {
+                    println!("{:<40} <- {} :: {}", m.var_name, m.source, m.field);
+                }
+                println!("---");
+                println!(
+                    "{} variable(s) from {} record(s).",
+                    total_vars, total_records
+                );
+            }
+            OutputMode::Json | OutputMode::JsonCompact => {
+                let vars: Vec<_> = mappings
+                    .iter()
+                    .map(|m| {
+                        json!({
+                            "name": m.var_name,
+                            "source": m.source,
+                            "field": m.field,
+                        })
+                    })
+                    .collect();
+                let out = json!({
+                    "variables": vars,
+                    "total_vars": total_vars,
+                    "total_records": total_records,
+                });
+                if args.output == OutputMode::Json {
+                    println!("{}", serde_json::to_string_pretty(&out)?);
+                } else {
+                    println!("{}", serde_json::to_string(&out)?);
+                }
+            }
+        }
+        return Ok(());
+    }
+
+    let env_map = collect_env_map(pool, &collect, master_key).await?;
 
     tracing::debug!(
         vars = env_map.len(),
@@ -135,9 +246,3 @@ pub async fn run_exec(pool: &PgPool, args: RunArgs<'_>, master_key: &[u8; 32]) -
 
     Ok(())
 }
-
-/// Quote a value for safe shell output. Wraps the value in single quotes,
-/// escaping any single quotes within the value.
-fn shell_quote(s: &str) -> String {
-    format!("'{}'", s.replace('\'', "'\\''"))
-}

src/commands/search.rs

@@ -4,7 +4,7 @@ use sqlx::PgPool;
 use std::collections::HashMap;
 
 use crate::crypto;
-use crate::models::Secret;
+use crate::models::{Entry, SecretField};
 use crate::output::{OutputMode, format_local_time};
 
 pub struct SearchArgs<'a> {
@@ -13,7 +13,6 @@ pub struct SearchArgs<'a> {
     pub name: Option<&'a str>,
     pub tags: &'a [String],
     pub query: Option<&'a str>,
-    pub show_secrets: bool,
     pub fields: &'a [String],
     pub summary: bool,
     pub limit: u32,
@@ -23,9 +22,9 @@ pub struct SearchArgs<'a> {
 }
 
 pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
-    validate_safe_search_args(args.show_secrets, args.fields)?;
+    validate_safe_search_args(args.fields)?;
 
-    let rows = fetch_rows_paged(
+    let rows = fetch_entries_paged(
         pool,
         PagedFetchArgs {
             namespace: args.namespace,
@@ -40,14 +39,25 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
     )
     .await?;
 
-    // -f/--field: extract specific field values directly
+    // -f/--field: extract specific metadata field values directly
     if !args.fields.is_empty() {
         return print_fields(&rows, args.fields);
     }
 
+    // Fetch secret schemas for all returned entries (no master key needed).
+    let entry_ids: Vec<uuid::Uuid> = rows.iter().map(|r| r.id).collect();
+    let schema_map = if !args.summary && !entry_ids.is_empty() {
+        fetch_secret_schemas(pool, &entry_ids).await?
+    } else {
+        HashMap::new()
+    };
+
     match args.output {
         OutputMode::Json | OutputMode::JsonCompact => {
-            let arr: Vec<Value> = rows.iter().map(|r| to_json(r, args.summary)).collect();
+            let arr: Vec<Value> = rows
+                .iter()
+                .map(|r| to_json(r, args.summary, schema_map.get(&r.id).map(Vec::as_slice)))
+                .collect();
             let out = if args.output == OutputMode::Json {
                 serde_json::to_string_pretty(&arr)?
             } else {
@@ -55,31 +65,17 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
             };
             println!("{}", out);
         }
-        OutputMode::Env => {
-            if rows.len() > 1 {
-                anyhow::bail!(
-                    "env output requires exactly one record; got {}. Add more filters.",
-                    rows.len()
-                );
-            }
-            if let Some(row) = rows.first() {
-                let map = build_metadata_env_map(row, "");
-                let mut pairs: Vec<(String, String)> = map.into_iter().collect();
-                pairs.sort_by(|a, b| a.0.cmp(&b.0));
-                for (k, v) in pairs {
-                    println!("{}={}", k, shell_quote(&v));
-                }
-            } else {
-                eprintln!("No records found.");
-            }
-        }
         OutputMode::Text => {
             if rows.is_empty() {
                 println!("No records found.");
                 return Ok(());
             }
             for row in &rows {
-                print_text(row, args.summary)?;
+                print_text(
+                    row,
+                    args.summary,
+                    schema_map.get(&row.id).map(Vec::as_slice),
+                )?;
             }
             println!("{} record(s) found.", rows.len());
             if rows.len() == args.limit as usize {
@@ -95,20 +91,13 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
     Ok(())
 }
 
-fn validate_safe_search_args(show_secrets: bool, fields: &[String]) -> Result<()> {
-    if show_secrets {
-        anyhow::bail!(
-            "`search` no longer reveals secrets. Use `secrets inject` or `secrets run` instead."
-        );
-    }
-
+fn validate_safe_search_args(fields: &[String]) -> Result<()> {
     if let Some(field) = fields.iter().find(|field| is_secret_field(field)) {
         anyhow::bail!(
-            "Field '{}' is sensitive. `search -f` only supports metadata.* fields; use `secrets inject` or `secrets run` for secrets.",
+            "Field '{}' is sensitive. `search -f` only supports metadata.* fields; use `secrets run` for secrets.",
             field
         );
     }
-
     Ok(())
 }
 
@@ -119,32 +108,8 @@ fn is_secret_field(field: &str) -> bool {
     )
 }
 
-/// Fetch rows with simple equality/tag filters (no pagination). Used by inject/run.
-pub async fn fetch_rows(
-    pool: &PgPool,
-    namespace: Option<&str>,
-    kind: Option<&str>,
-    name: Option<&str>,
-    tags: &[String],
-    query: Option<&str>,
-) -> Result<Vec<Secret>> {
-    fetch_rows_paged(
-        pool,
-        PagedFetchArgs {
-            namespace,
-            kind,
-            name,
-            tags,
-            query,
-            sort: "name",
-            limit: 200,
-            offset: 0,
-        },
-    )
-    .await
-}
+// ── Entry fetching ────────────────────────────────────────────────────────────
 
-/// Arguments for the internal paged fetch. Grouped to avoid too-many-arguments lint.
 struct PagedFetchArgs<'a> {
     namespace: Option<&'a str>,
     kind: Option<&'a str>,
@@ -156,7 +121,50 @@ struct PagedFetchArgs<'a> {
     offset: u32,
 }
 
-async fn fetch_rows_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Secret>> {
+/// A very large limit used when callers need all matching records (export, 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, 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>,
+    kind: Option<&str>,
+    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,
+        PagedFetchArgs {
+            namespace,
+            kind,
+            name,
+            tags,
+            query,
+            sort: "name",
+            limit,
+            offset: 0,
+        },
+    )
+    .await
+}
+
+async fn fetch_entries_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Entry>> {
     let mut conditions: Vec<String> = Vec::new();
     let mut idx: i32 = 1;
 
@@ -205,7 +213,7 @@ async fn fetch_rows_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Se
     };
 
     let sql = format!(
-        "SELECT * FROM secrets {} ORDER BY {} LIMIT ${} OFFSET ${}",
+        "SELECT * FROM entries {} ORDER BY {} LIMIT ${} OFFSET ${}",
         where_clause,
         order,
         idx,
@@ -214,7 +222,7 @@ async fn fetch_rows_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Se
 
     tracing::debug!(sql, "executing search query");
 
-    let mut q = sqlx::query_as::<_, Secret>(&sql);
+    let mut q = sqlx::query_as::<_, Entry>(&sql);
     if let Some(v) = a.namespace {
         q = q.bind(v);
     }
@@ -237,12 +245,62 @@ async fn fetch_rows_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Se
     }
     q = q.bind(a.limit as i64).bind(a.offset as i64);
 
-    let rows = q.fetch_all(pool).await?;
-    Ok(rows)
+    Ok(q.fetch_all(pool).await?)
 }
 
-fn env_prefix(row: &Secret, prefix: &str) -> String {
-    let name_part = row.name.to_uppercase().replace(['-', '.', ' '], "_");
+// ── Secret schema fetching (no master key) ───────────────────────────────────
+
+/// Fetch secret field names for a set of entry ids.
+/// Returns a map from entry_id to list of SecretField.
+async fn fetch_secret_schemas(
+    pool: &PgPool,
+    entry_ids: &[uuid::Uuid],
+) -> Result<HashMap<uuid::Uuid, Vec<SecretField>>> {
+    if entry_ids.is_empty() {
+        return Ok(HashMap::new());
+    }
+
+    let fields: Vec<SecretField> = sqlx::query_as(
+        "SELECT * FROM secrets WHERE entry_id = ANY($1) ORDER BY entry_id, field_name",
+    )
+    .bind(entry_ids)
+    .fetch_all(pool)
+    .await?;
+
+    let mut map: HashMap<uuid::Uuid, Vec<SecretField>> = HashMap::new();
+    for f in fields {
+        map.entry(f.entry_id).or_default().push(f);
+    }
+    Ok(map)
+}
+
+/// Fetch all secret fields (including encrypted bytes) for a set of entry ids.
+pub async fn fetch_secrets_for_entries(
+    pool: &PgPool,
+    entry_ids: &[uuid::Uuid],
+) -> Result<HashMap<uuid::Uuid, Vec<SecretField>>> {
+    if entry_ids.is_empty() {
+        return Ok(HashMap::new());
+    }
+
+    let fields: Vec<SecretField> = sqlx::query_as(
+        "SELECT * FROM secrets WHERE entry_id = ANY($1) ORDER BY entry_id, field_name",
+    )
+    .bind(entry_ids)
+    .fetch_all(pool)
+    .await?;
+
+    let mut map: HashMap<uuid::Uuid, Vec<SecretField>> = HashMap::new();
+    for f in fields {
+        map.entry(f.entry_id).or_default().push(f);
+    }
+    Ok(map)
+}
+
+// ── Display helpers ───────────────────────────────────────────────────────────
+
+fn env_prefix(entry: &Entry, prefix: &str) -> String {
+    let name_part = entry.name.to_uppercase().replace(['-', '.', ' '], "_");
     if prefix.is_empty() {
         name_part
     } else {
@@ -254,61 +312,65 @@ fn env_prefix(row: &Secret, prefix: &str) -> String {
     }
 }
 
-/// Build a flat `KEY=VALUE` map from metadata only.
-/// Variable names: `<PREFIX><NAME>_<FIELD>` (all uppercased, hyphens/dots → underscores).
-/// If `prefix` is empty, the name segment alone is used as the prefix.
-pub fn build_metadata_env_map(row: &Secret, prefix: &str) -> HashMap<String, String> {
-    let effective_prefix = env_prefix(row, prefix);
-
-    let mut map = HashMap::new();
-
-    if let Some(meta) = row.metadata.as_object() {
-        for (k, v) in meta {
-            let key = format!(
-                "{}_{}",
-                effective_prefix,
-                k.to_uppercase().replace(['-', '.'], "_")
-            );
-            map.insert(key, json_value_to_env_string(v));
-        }
-    }
-
-    map
-}
-
-/// Build a flat `KEY=VALUE` map from metadata and decrypted secrets.
-pub fn build_injected_env_map(
-    row: &Secret,
+/// Build a flat KEY=VALUE map from decrypted secret fields only.
+/// Resolves key_ref: if metadata.key_ref is set, merges secret fields from that key entry.
+pub async fn build_injected_env_map(
+    pool: &PgPool,
+    entry: &Entry,
     prefix: &str,
     master_key: &[u8; 32],
+    fields: &[&SecretField],
 ) -> Result<HashMap<String, String>> {
-    let effective_prefix = env_prefix(row, prefix);
-    let mut map = build_metadata_env_map(row, prefix);
+    let effective_prefix = env_prefix(entry, prefix);
+    let mut map = HashMap::new();
 
-    if !row.encrypted.is_empty() {
-        let decrypted = crypto::decrypt_json(master_key, &row.encrypted)?;
-        if let Some(enc) = decrypted.as_object() {
-            for (k, v) in enc {
-                let key = format!(
+    // Decrypt each secret field and add to env map.
+    for f in fields {
+        let decrypted = crypto::decrypt_json(master_key, &f.encrypted)?;
+        let key = format!(
+            "{}_{}",
+            effective_prefix,
+            f.field_name.to_uppercase().replace(['-', '.'], "_")
+        );
+        map.insert(key, json_value_to_env_string(&decrypted));
+    }
+
+    // Resolve key_ref: merge secrets from the referenced key entry.
+    if let Some(key_ref) = entry.metadata.get("key_ref").and_then(|v| v.as_str()) {
+        let key_entries = fetch_entries(
+            pool,
+            Some(&entry.namespace),
+            Some("key"),
+            Some(key_ref),
+            &[],
+            None,
+        )
+        .await?;
+
+        if let Some(key_entry) = key_entries.first() {
+            let key_ids = vec![key_entry.id];
+            let key_fields_map = fetch_secrets_for_entries(pool, &key_ids).await?;
+            let empty = vec![];
+            let key_fields = key_fields_map.get(&key_entry.id).unwrap_or(&empty);
+
+            let key_prefix = env_prefix(key_entry, prefix);
+            for f in key_fields {
+                let decrypted = crypto::decrypt_json(master_key, &f.encrypted)?;
+                let key_var = format!(
                     "{}_{}",
-                    effective_prefix,
-                    k.to_uppercase().replace(['-', '.'], "_")
+                    key_prefix,
+                    f.field_name.to_uppercase().replace(['-', '.'], "_")
                 );
-                map.insert(key, json_value_to_env_string(v));
+                map.insert(key_var, json_value_to_env_string(&decrypted));
             }
+        } else {
+            tracing::warn!(key_ref, "key_ref target not found");
         }
     }
 
     Ok(map)
 }
 
-/// Quote a value for safe shell / env output. Wraps in single quotes,
-/// escaping any single quotes within the value.
-fn shell_quote(s: &str) -> String {
-    format!("'{}'", s.replace('\'', "'\\''"))
-}
-
-/// Convert a JSON value to its string representation suitable for env vars.
 fn json_value_to_env_string(v: &Value) -> String {
     match v {
         Value::String(s) => s.clone(),
@@ -317,81 +379,96 @@ fn json_value_to_env_string(v: &Value) -> String {
     }
 }
 
-fn to_json(row: &Secret, summary: bool) -> Value {
+fn to_json(entry: &Entry, summary: bool, schema: Option<&[SecretField]>) -> Value {
     if summary {
-        let desc = row
+        let desc = entry
             .metadata
             .get("desc")
-            .or_else(|| row.metadata.get("url"))
+            .or_else(|| entry.metadata.get("url"))
             .and_then(|v| v.as_str())
             .unwrap_or("")
             .to_string();
         return json!({
-            "namespace": row.namespace,
-            "kind": row.kind,
-            "name": row.name,
-            "tags": row.tags,
+            "namespace": entry.namespace,
+            "kind": entry.kind,
+            "name": entry.name,
+            "tags": entry.tags,
             "desc": desc,
-            "updated_at": row.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+            "updated_at": entry.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
         });
     }
 
-    let secrets_val = if row.encrypted.is_empty() {
-        Value::Object(Default::default())
-    } else {
-        json!({"_encrypted": true})
+    let secrets_val: Value = match schema {
+        Some(fields) if !fields.is_empty() => {
+            let schema_arr: Vec<Value> = fields
+                .iter()
+                .map(|f| {
+                    json!({
+                        "field_name": f.field_name,
+                    })
+                })
+                .collect();
+            Value::Array(schema_arr)
+        }
+        _ => Value::Array(vec![]),
     };
 
     json!({
-        "id": row.id,
-        "namespace": row.namespace,
-        "kind": row.kind,
-        "name": row.name,
-        "tags": row.tags,
-        "metadata": row.metadata,
+        "id": entry.id,
+        "namespace": entry.namespace,
+        "kind": entry.kind,
+        "name": entry.name,
+        "tags": entry.tags,
+        "metadata": entry.metadata,
         "secrets": secrets_val,
-        "version": row.version,
-        "created_at": row.created_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
-        "updated_at": row.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+        "version": entry.version,
+        "created_at": entry.created_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+        "updated_at": entry.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
     })
 }
 
-fn print_text(row: &Secret, summary: bool) -> Result<()> {
-    println!("[{}/{}] {}", row.namespace, row.kind, row.name);
+fn print_text(entry: &Entry, summary: bool, schema: Option<&[SecretField]>) -> Result<()> {
+    println!("[{}/{}] {}", entry.namespace, entry.kind, entry.name);
     if summary {
-        let desc = row
+        let desc = entry
             .metadata
             .get("desc")
-            .or_else(|| row.metadata.get("url"))
+            .or_else(|| entry.metadata.get("url"))
             .and_then(|v| v.as_str())
             .unwrap_or("-");
-        if !row.tags.is_empty() {
-            println!("  tags:    [{}]", row.tags.join(", "));
+        if !entry.tags.is_empty() {
+            println!("  tags:    [{}]", entry.tags.join(", "));
         }
         println!("  desc:    {}", desc);
-        println!("  updated: {}", format_local_time(row.updated_at));
+        println!("  updated: {}", format_local_time(entry.updated_at));
     } else {
-        println!("  id:       {}", row.id);
-        if !row.tags.is_empty() {
-            println!("  tags:     [{}]", row.tags.join(", "));
+        println!("  id:       {}", entry.id);
+        if !entry.tags.is_empty() {
+            println!("  tags:     [{}]", entry.tags.join(", "));
         }
-        if row.metadata.as_object().is_some_and(|m| !m.is_empty()) {
+        if entry.metadata.as_object().is_some_and(|m| !m.is_empty()) {
             println!(
                 "  metadata: {}",
-                serde_json::to_string_pretty(&row.metadata)?
+                serde_json::to_string_pretty(&entry.metadata)?
             );
         }
-        if !row.encrypted.is_empty() {
-            println!("  secrets:  [encrypted]  (use `secrets inject` or `secrets run`)");
+        match schema {
+            Some(fields) if !fields.is_empty() => {
+                let schema_str: Vec<String> = fields.iter().map(|f| f.field_name.clone()).collect();
+                println!("  secrets:  {}", schema_str.join(", "));
+                println!("            (use `secrets run` to get values)");
+            }
+            _ => {}
         }
-        println!("  created:  {}", format_local_time(row.created_at));
+        println!("  version:  {}", entry.version);
+        println!("  created:  {}", format_local_time(entry.created_at));
     }
     println!();
     Ok(())
 }
 
-/// Extract one or more field paths like `metadata.url`.
-fn print_fields(rows: &[Secret], fields: &[String]) -> Result<()> {
+/// Extract one or more metadata field paths like `metadata.url`.
+fn print_fields(rows: &[Entry], fields: &[String]) -> Result<()> {
     for row in rows {
         for field in fields {
             let val = extract_field(row, field)?;
@@ -401,13 +478,13 @@ fn print_fields(rows: &[Secret], fields: &[String]) -> Result<()> {
     Ok(())
 }
 
-fn extract_field(row: &Secret, field: &str) -> Result<String> {
+fn extract_field(entry: &Entry, field: &str) -> Result<String> {
     let (section, key) = field
         .split_once('.')
         .ok_or_else(|| anyhow::anyhow!("Invalid field path '{}'. Use metadata.<key>.", field))?;
 
     let obj = match section {
-        "metadata" | "meta" => &row.metadata,
+        "metadata" | "meta" => &entry.metadata,
         other => anyhow::bail!("Unknown field section '{}'. Use 'metadata'.", other),
     };
 
@@ -421,9 +498,9 @@ fn extract_field(row: &Secret, field: &str) -> Result<String> {
             anyhow::anyhow!(
                 "Field '{}' not found in record [{}/{}/{}]",
                 field,
-                row.namespace,
-                row.kind,
-                row.name
+                entry.namespace,
+                entry.kind,
+                entry.name
             )
         })
 }
@@ -435,62 +512,57 @@ mod tests {
     use serde_json::json;
     use uuid::Uuid;
 
-    fn sample_secret() -> Secret {
-        let key = [0x42u8; 32];
-        let encrypted = crypto::encrypt_json(&key, &json!({"token": "abc123"})).unwrap();
-
-        Secret {
+    fn sample_entry() -> Entry {
+        Entry {
             id: Uuid::nil(),
             namespace: "refining".to_string(),
             kind: "service".to_string(),
             name: "gitea.main".to_string(),
             tags: vec!["prod".to_string()],
-            metadata: json!({"url": "https://gitea.refining.dev", "enabled": true}),
-            encrypted,
+            metadata: json!({"url": "https://code.example.com", "enabled": true}),
             version: 1,
             created_at: Utc::now(),
             updated_at: Utc::now(),
         }
     }
 
-    #[test]
-    fn rejects_show_secrets_flag() {
-        let err = validate_safe_search_args(true, &[]).unwrap_err();
-        assert!(err.to_string().contains("no longer reveals secrets"));
+    fn sample_fields() -> Vec<SecretField> {
+        let key = [0x42u8; 32];
+        let enc = crypto::encrypt_json(&key, &json!("abc123")).unwrap();
+        vec![SecretField {
+            id: Uuid::nil(),
+            entry_id: Uuid::nil(),
+            field_name: "token".to_string(),
+            encrypted: enc,
+            version: 1,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }]
     }
 
     #[test]
     fn rejects_secret_field_extraction() {
         let fields = vec!["secret.token".to_string()];
-        let err = validate_safe_search_args(false, &fields).unwrap_err();
+        let err = validate_safe_search_args(&fields).unwrap_err();
         assert!(err.to_string().contains("sensitive"));
     }
 
     #[test]
-    fn metadata_env_map_excludes_secret_values() {
-        let row = sample_secret();
-        let map = build_metadata_env_map(&row, "");
+    fn to_json_full_includes_secrets_schema() {
+        let entry = sample_entry();
+        let fields = sample_fields();
+        let v = to_json(&entry, false, Some(&fields));
 
-        assert_eq!(
-            map.get("GITEA_MAIN_URL").map(String::as_str),
-            Some("https://gitea.refining.dev")
-        );
-        assert_eq!(
-            map.get("GITEA_MAIN_ENABLED").map(String::as_str),
-            Some("true")
-        );
-        assert!(!map.contains_key("GITEA_MAIN_TOKEN"));
+        let secrets = v.get("secrets").unwrap().as_array().unwrap();
+        assert_eq!(secrets.len(), 1);
+        assert_eq!(secrets[0]["field_name"], "token");
     }
 
     #[test]
-    fn injected_env_map_includes_secret_values() {
-        let row = sample_secret();
-        let key = [0x42u8; 32];
-        let map = build_injected_env_map(&row, "", &key).unwrap();
-
-        assert_eq!(
-            map.get("GITEA_MAIN_TOKEN").map(String::as_str),
-            Some("abc123")
-        );
+    fn to_json_summary_omits_secrets_schema() {
+        let entry = sample_entry();
+        let fields = sample_fields();
+        let v = to_json(&entry, true, Some(&fields));
+        assert!(v.get("secrets").is_none());
     }
 }

src/commands/update.rs

@@ -1,23 +1,16 @@
 use anyhow::Result;
 use serde_json::{Map, Value, json};
-use sqlx::{FromRow, PgPool};
+use sqlx::PgPool;
 use uuid::Uuid;
 
 use super::add::{
-    collect_field_paths, collect_key_paths, insert_path, parse_key_path, parse_kv, remove_path,
+    collect_field_paths, collect_key_paths, flatten_json_fields, insert_path, parse_key_path,
+    parse_kv, remove_path,
 };
 use crate::crypto;
 use crate::db;
-use crate::output::OutputMode;
-
-#[derive(FromRow)]
-struct UpdateRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
-    encrypted: Vec<u8>,
-}
+use crate::models::EntryRow;
+use crate::output::{OutputMode, print_json};
 
 pub struct UpdateArgs<'a> {
     pub namespace: &'a str,
@@ -35,9 +28,9 @@ pub struct UpdateArgs<'a> {
 pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
     let mut tx = pool.begin().await?;
 
-    let row: Option<UpdateRow> = sqlx::query_as(
-        "SELECT id, version, tags, metadata, encrypted \
-         FROM secrets \
+    let row: Option<EntryRow> = sqlx::query_as(
+        "SELECT id, version, tags, metadata \
+         FROM entries \
          WHERE namespace = $1 AND kind = $2 AND name = $3 \
          FOR UPDATE",
     )
@@ -56,11 +49,11 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
         )
     })?;
 
-    // Snapshot current state before modifying.
-    if let Err(e) = db::snapshot_history(
+    // Snapshot current entry state before modifying.
+    if let Err(e) = db::snapshot_entry_history(
         &mut tx,
-        db::SnapshotParams {
-            secret_id: row.id,
+        db::EntrySnapshotParams {
+            entry_id: row.id,
             namespace: args.namespace,
             kind: args.kind,
             name: args.name,
@@ -68,15 +61,14 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
             action: "update",
             tags: &row.tags,
             metadata: &row.metadata,
-            encrypted: &row.encrypted,
         },
     )
     .await
     {
-        tracing::warn!(error = %e, "failed to snapshot history before update");
+        tracing::warn!(error = %e, "failed to snapshot entry history before update");
     }
 
-    // Merge tags
+    // ── Merge tags ────────────────────────────────────────────────────────────
     let mut tags: Vec<String> = row.tags;
     for t in args.add_tags {
         if !tags.contains(t) {
@@ -85,7 +77,7 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
     }
     tags.retain(|t| !args.remove_tags.contains(t));
 
-    // Merge metadata
+    // ── Merge metadata ────────────────────────────────────────────────────────
     let mut meta_map: Map<String, Value> = match row.metadata {
         Value::Object(m) => m,
         _ => Map::new(),
@@ -100,43 +92,14 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
     }
     let metadata = Value::Object(meta_map);
 
-    // Decrypt existing encrypted blob, merge changes, re-encrypt
-    let existing_json = if row.encrypted.is_empty() {
-        Value::Object(Map::new())
-    } else {
-        crypto::decrypt_json(master_key, &row.encrypted)?
-    };
-    let mut enc_map: Map<String, Value> = match existing_json {
-        Value::Object(m) => m,
-        _ => Map::new(),
-    };
-    for entry in args.secret_entries {
-        let (path, value) = parse_kv(entry)?;
-        insert_path(&mut enc_map, &path, value)?;
-    }
-    for key in args.remove_secrets {
-        let path = parse_key_path(key)?;
-        remove_path(&mut enc_map, &path)?;
-    }
-    let secret_json = Value::Object(enc_map);
-    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
-
-    tracing::debug!(
-        namespace = args.namespace,
-        kind = args.kind,
-        name = args.name,
-        "updating record"
-    );
-
-    // CAS: update only if version hasn't changed (FOR UPDATE lock ensures this).
+    // CAS update of the entry row.
     let result = sqlx::query(
-        "UPDATE secrets \
-         SET tags = $1, metadata = $2, encrypted = $3, version = version + 1, updated_at = NOW() \
-         WHERE id = $4 AND version = $5",
+        "UPDATE entries \
+         SET tags = $1, metadata = $2, version = version + 1, updated_at = NOW() \
+         WHERE id = $3 AND version = $4",
     )
     .bind(&tags)
     .bind(&metadata)
-    .bind(&encrypted_bytes)
     .bind(row.id)
     .bind(row.version)
     .execute(&mut *tx)
@@ -152,6 +115,116 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
         );
     }
 
+    let new_version = row.version + 1;
+
+    // ── Update secret fields ──────────────────────────────────────────────────
+    for entry in args.secret_entries {
+        let (path, field_value) = parse_kv(entry)?;
+
+        // For nested paths (e.g. credentials:type), flatten into dot-separated names
+        // and treat the sub-value as the individual field to store.
+        let flat = flatten_json_fields("", &{
+            let mut m = Map::new();
+            insert_path(&mut m, &path, field_value)?;
+            Value::Object(m)
+        });
+
+        for (field_name, fv) in &flat {
+            let encrypted = crypto::encrypt_json(master_key, fv)?;
+
+            // Snapshot existing field before replacing.
+            #[derive(sqlx::FromRow)]
+            struct ExistingField {
+                id: Uuid,
+                encrypted: Vec<u8>,
+            }
+            let existing_field: Option<ExistingField> = sqlx::query_as(
+                "SELECT id, encrypted \
+                 FROM secrets WHERE entry_id = $1 AND field_name = $2",
+            )
+            .bind(row.id)
+            .bind(field_name)
+            .fetch_optional(&mut *tx)
+            .await?;
+
+            if let Some(ef) = &existing_field
+                && let Err(e) = db::snapshot_secret_history(
+                    &mut tx,
+                    db::SecretSnapshotParams {
+                        entry_id: row.id,
+                        secret_id: ef.id,
+                        entry_version: row.version,
+                        field_name,
+                        encrypted: &ef.encrypted,
+                        action: "update",
+                    },
+                )
+                .await
+            {
+                tracing::warn!(error = %e, "failed to snapshot secret field history");
+            }
+
+            sqlx::query(
+                "INSERT INTO secrets (entry_id, field_name, encrypted) \
+                 VALUES ($1, $2, $3) \
+                 ON CONFLICT (entry_id, field_name) DO UPDATE SET \
+                     encrypted  = EXCLUDED.encrypted, \
+                     version    = secrets.version + 1, \
+                     updated_at = NOW()",
+            )
+            .bind(row.id)
+            .bind(field_name)
+            .bind(&encrypted)
+            .execute(&mut *tx)
+            .await?;
+        }
+    }
+
+    // ── Remove secret fields ──────────────────────────────────────────────────
+    for key in args.remove_secrets {
+        let path = parse_key_path(key)?;
+        // Dot-join the path to match flattened field_name storage.
+        let field_name = path.join(".");
+
+        // Snapshot before delete.
+        #[derive(sqlx::FromRow)]
+        struct FieldToDelete {
+            id: Uuid,
+            encrypted: Vec<u8>,
+        }
+        let field: Option<FieldToDelete> = sqlx::query_as(
+            "SELECT id, encrypted \
+             FROM secrets WHERE entry_id = $1 AND field_name = $2",
+        )
+        .bind(row.id)
+        .bind(&field_name)
+        .fetch_optional(&mut *tx)
+        .await?;
+
+        if let Some(f) = field {
+            if let Err(e) = db::snapshot_secret_history(
+                &mut tx,
+                db::SecretSnapshotParams {
+                    entry_id: row.id,
+                    secret_id: f.id,
+                    entry_version: new_version,
+                    field_name: &field_name,
+                    encrypted: &f.encrypted,
+                    action: "delete",
+                },
+            )
+            .await
+            {
+                tracing::warn!(error = %e, "failed to snapshot secret field history before delete");
+            }
+
+            sqlx::query("DELETE FROM secrets WHERE id = $1")
+                .bind(f.id)
+                .execute(&mut *tx)
+                .await?;
+        }
+    }
+
     let meta_keys = collect_key_paths(args.meta_entries)?;
     let remove_meta_keys = collect_field_paths(args.remove_meta)?;
     let secret_keys = collect_key_paths(args.secret_entries)?;
@@ -190,11 +263,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);

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")?;

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()))?;

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

src/db.rs

@@ -1,7 +1,10 @@
 use anyhow::Result;
+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()
@@ -17,61 +20,46 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
     tracing::debug!("running migrations");
     sqlx::raw_sql(
         r#"
-        CREATE TABLE IF NOT EXISTS secrets (
+        -- ── entries: top-level entities (server, service, key, …) ──────────────
+        CREATE TABLE IF NOT EXISTS entries (
             id          UUID PRIMARY KEY DEFAULT uuidv7(),
             namespace   VARCHAR(64)  NOT NULL,
             kind        VARCHAR(64)  NOT NULL,
             name        VARCHAR(256) NOT NULL,
             tags        TEXT[]       NOT NULL DEFAULT '{}',
             metadata    JSONB        NOT NULL DEFAULT '{}',
-            encrypted   BYTEA        NOT NULL DEFAULT '\x',
             version     BIGINT       NOT NULL DEFAULT 1,
             created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
             updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
             UNIQUE(namespace, kind, name)
         );
 
-        -- idempotent column add for existing tables
-        DO $$ BEGIN
-            ALTER TABLE secrets ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}';
-        EXCEPTION WHEN OTHERS THEN NULL;
-        END $$;
+        CREATE INDEX IF NOT EXISTS idx_entries_namespace ON entries(namespace);
+        CREATE INDEX IF NOT EXISTS idx_entries_kind      ON entries(kind);
+        CREATE INDEX IF NOT EXISTS idx_entries_tags      ON entries USING GIN(tags);
+        CREATE INDEX IF NOT EXISTS idx_entries_metadata  ON entries USING GIN(metadata jsonb_path_ops);
 
-        DO $$ BEGIN
-            ALTER TABLE secrets ADD COLUMN IF NOT EXISTS version BIGINT NOT NULL DEFAULT 1;
-        EXCEPTION WHEN OTHERS THEN NULL;
-        END $$;
+        -- ── secrets: one row per encrypted field, plaintext schema metadata ────
+        CREATE TABLE IF NOT EXISTS secrets (
+            id          UUID PRIMARY KEY DEFAULT uuidv7(),
+            entry_id    UUID         NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+            field_name  VARCHAR(256) NOT NULL,
+            encrypted   BYTEA        NOT NULL DEFAULT '\x',
+            version     BIGINT       NOT NULL DEFAULT 1,
+            created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+            updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+            UNIQUE(entry_id, field_name)
+        );
 
-        -- Migrate encrypted column from JSONB to BYTEA if still JSONB type.
-        -- After migration, old plaintext rows will have their JSONB data
-        -- stored as raw bytes (UTF-8 encoded).
-        DO $$ BEGIN
-            IF EXISTS (
-                SELECT 1 FROM information_schema.columns
-                WHERE table_name = 'secrets'
-                  AND column_name = 'encrypted'
-                  AND data_type = 'jsonb'
-            ) THEN
-                ALTER TABLE secrets RENAME COLUMN encrypted TO encrypted_jsonb_old;
-                ALTER TABLE secrets ADD COLUMN encrypted BYTEA NOT NULL DEFAULT '\x';
-                -- Copy existing JSONB data as raw UTF-8 bytes so nothing is lost
-                UPDATE secrets SET encrypted = convert_to(encrypted_jsonb_old::text, 'UTF8');
-                ALTER TABLE secrets DROP COLUMN encrypted_jsonb_old;
-            END IF;
-        EXCEPTION WHEN OTHERS THEN NULL;
-        END $$;
+        CREATE INDEX IF NOT EXISTS idx_secrets_entry_id ON secrets(entry_id);
 
-        CREATE INDEX IF NOT EXISTS idx_secrets_namespace ON secrets(namespace);
-        CREATE INDEX IF NOT EXISTS idx_secrets_kind ON secrets(kind);
-        CREATE INDEX IF NOT EXISTS idx_secrets_tags ON secrets USING GIN(tags);
-        CREATE INDEX IF NOT EXISTS idx_secrets_metadata ON secrets USING GIN(metadata jsonb_path_ops);
-
-        -- Key-value config table: stores Argon2id salt (shared across devices)
+        -- ── kv_config: global key-value store (Argon2id salt, etc.) ────────────
         CREATE TABLE IF NOT EXISTS kv_config (
             key   TEXT PRIMARY KEY,
             value BYTEA NOT NULL
         );
 
+        -- ── audit_log: append-only operation log ────────────────────────────────
         CREATE TABLE IF NOT EXISTS audit_log (
             id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
             action      VARCHAR(32)  NOT NULL,
@@ -83,14 +71,13 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
             created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
         );
 
-        CREATE INDEX IF NOT EXISTS idx_audit_log_created ON audit_log(created_at DESC);
-        CREATE INDEX IF NOT EXISTS idx_audit_log_ns_kind ON audit_log(namespace, kind);
+        CREATE INDEX IF NOT EXISTS idx_audit_log_created  ON audit_log(created_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_audit_log_ns_kind  ON audit_log(namespace, kind);
 
-        -- History table: snapshot of secrets before each write operation.
-        -- Supports rollback to any prior version via `secrets rollback`.
-        CREATE TABLE IF NOT EXISTS secrets_history (
+        -- ── entries_history: entry-level snapshot (tags + metadata) ─────────────
+        CREATE TABLE IF NOT EXISTS entries_history (
             id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-            secret_id   UUID         NOT NULL,
+            entry_id    UUID         NOT NULL,
             namespace   VARCHAR(64)  NOT NULL,
             kind        VARCHAR(64)  NOT NULL,
             name        VARCHAR(256) NOT NULL,
@@ -98,13 +85,32 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
             action      VARCHAR(16)  NOT NULL,
             tags        TEXT[]       NOT NULL DEFAULT '{}',
             metadata    JSONB        NOT NULL DEFAULT '{}',
-            encrypted   BYTEA        NOT NULL DEFAULT '\x',
             actor       VARCHAR(128) NOT NULL DEFAULT '',
             created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
         );
 
-        CREATE INDEX IF NOT EXISTS idx_history_secret_id ON secrets_history(secret_id, version DESC);
-        CREATE INDEX IF NOT EXISTS idx_history_ns_kind_name ON secrets_history(namespace, kind, name, version DESC);
+        CREATE INDEX IF NOT EXISTS idx_entries_history_entry_id
+            ON entries_history(entry_id, version DESC);
+        CREATE INDEX IF NOT EXISTS idx_entries_history_ns_kind_name
+            ON entries_history(namespace, kind, name, version DESC);
+
+        -- ── secrets_history: field-level snapshot ───────────────────────────────
+        CREATE TABLE IF NOT EXISTS secrets_history (
+            id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            entry_id        UUID         NOT NULL,
+            secret_id       UUID         NOT NULL,
+            entry_version   BIGINT       NOT NULL,
+            field_name      VARCHAR(256) NOT NULL,
+            encrypted       BYTEA        NOT NULL DEFAULT '\x',
+            action          VARCHAR(16)  NOT NULL,
+            actor           VARCHAR(128) NOT NULL DEFAULT '',
+            created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_secrets_history_entry_id
+            ON secrets_history(entry_id, entry_version DESC);
+        CREATE INDEX IF NOT EXISTS idx_secrets_history_secret_id
+            ON secrets_history(secret_id);
         "#,
     )
     .execute(pool)
@@ -113,33 +119,31 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
     Ok(())
 }
 
-/// Snapshot parameters grouped to avoid too-many-arguments lint.
-pub struct SnapshotParams<'a> {
-    pub secret_id: uuid::Uuid,
+// ── Entry-level history snapshot ────────────────────────────────────────────
+
+pub struct EntrySnapshotParams<'a> {
+    pub entry_id: uuid::Uuid,
     pub namespace: &'a str,
     pub kind: &'a str,
     pub name: &'a str,
     pub version: i64,
     pub action: &'a str,
     pub tags: &'a [String],
-    pub metadata: &'a serde_json::Value,
-    pub encrypted: &'a [u8],
+    pub metadata: &'a Value,
 }
 
-/// Snapshot a secrets row into `secrets_history` before a write operation.
-/// `action` is one of "add", "update", "delete".
-/// Failures are non-fatal (caller should warn).
-pub async fn snapshot_history(
+/// Snapshot an entry row into `entries_history` before a write operation.
+pub async fn snapshot_entry_history(
     tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
-    p: SnapshotParams<'_>,
+    p: EntrySnapshotParams<'_>,
 ) -> Result<()> {
-    let actor = std::env::var("USER").unwrap_or_default();
+    let actor = current_actor();
     sqlx::query(
-        "INSERT INTO secrets_history \
-         (secret_id, namespace, kind, name, version, action, tags, metadata, encrypted, actor) \
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)",
+        "INSERT INTO entries_history \
+         (entry_id, namespace, kind, name, version, action, tags, metadata, actor) \
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)",
     )
-    .bind(p.secret_id)
+    .bind(p.entry_id)
     .bind(p.namespace)
     .bind(p.kind)
     .bind(p.name)
@@ -147,15 +151,49 @@ pub async fn snapshot_history(
     .bind(p.action)
     .bind(p.tags)
     .bind(p.metadata)
-    .bind(p.encrypted)
     .bind(&actor)
     .execute(&mut **tx)
     .await?;
     Ok(())
 }
 
+// ── Secret field-level history snapshot ─────────────────────────────────────
+
+pub struct SecretSnapshotParams<'a> {
+    pub entry_id: uuid::Uuid,
+    pub secret_id: uuid::Uuid,
+    pub entry_version: i64,
+    pub field_name: &'a str,
+    pub encrypted: &'a [u8],
+    pub action: &'a str,
+}
+
+/// Snapshot a single secret field into `secrets_history`.
+pub async fn snapshot_secret_history(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    p: SecretSnapshotParams<'_>,
+) -> Result<()> {
+    let actor = current_actor();
+    sqlx::query(
+        "INSERT INTO secrets_history \
+         (entry_id, secret_id, entry_version, field_name, encrypted, action, actor) \
+         VALUES ($1, $2, $3, $4, $5, $6, $7)",
+    )
+    .bind(p.entry_id)
+    .bind(p.secret_id)
+    .bind(p.entry_version)
+    .bind(p.field_name)
+    .bind(p.encrypted)
+    .bind(p.action)
+    .bind(&actor)
+    .execute(&mut **tx)
+    .await?;
+    Ok(())
+}
+
+// ── Argon2 salt helpers ──────────────────────────────────────────────────────
+
 /// Load the Argon2id salt from the database.
-/// Returns None if not yet initialized.
 pub async fn load_argon2_salt(pool: &PgPool) -> Result<Option<Vec<u8>>> {
     let row: Option<(Vec<u8>,)> =
         sqlx::query_as("SELECT value FROM kv_config WHERE key = 'argon2_salt'")

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;
 
@@ -36,8 +41,8 @@ use output::resolve_output_mode;
   # Pipe-friendly (non-TTY defaults to json-compact automatically)
   secrets search -n refining --kind service | jq '.[].name'
 
-  # Inject secrets into environment variables when you really need them
-  secrets inject -n refining --kind service --name gitea"
+  # Run a command with secrets injected into its child process environment
+  secrets run -n refining --kind service --name gitea -- printenv"
 )]
 struct Cli {
     /// Database URL, overrides saved config (one-time override)
@@ -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
@@ -106,7 +111,13 @@ EXAMPLES:
 
   # Write a multiline file into a nested secret field
   secrets add -n refining --kind server --name my-server \\
-    -s credentials:content@./keys/server.pem")]
+    -s credentials:content@./keys/server.pem
+
+  # Shared PEM (key_ref): store key once, reference from multiple servers
+  secrets add -n refining --kind key --name my-shared-key \\
+    --tag aliyun -s content=@./keys/shared.pem
+  secrets add -n refining --kind server --name i-abc123 \\
+    -m ip=10.0.0.1 -m key_ref=my-shared-key -s username=ecs-user")]
     Add {
         /// Namespace, e.g. refining, ricnsmart
         #[arg(short, long)]
@@ -114,19 +125,20 @@ 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
         #[arg(long = "tag")]
         tags: Vec<String>,
-        /// Plaintext metadata: key=value, key:=<json>, key=@file, or nested:path@file
+        /// Plaintext metadata: key=value, key:=<json>, key=@file, or nested:path@file.
+        /// Use key_ref=<name> to reference a shared key entry (kind=key); run merges its secrets.
         #[arg(long = "meta", short = 'm')]
         meta: Vec<String>,
         /// Secret entry: key=value, key:=<json>, key=@file, or nested:path@file
         #[arg(long = "secret", short = 's')]
         secrets: Vec<String>,
-        /// Output format: text (default on TTY), json, json-compact, env
+        /// Output format: text (default on TTY), json, json-compact
         #[arg(short, long = "output")]
         output: Option<String>,
     },
@@ -135,7 +147,7 @@ EXAMPLES:
     ///
     /// Supports fuzzy search (-q), exact lookup (--name), field extraction (-f),
     /// summary view (--summary), pagination (--limit / --offset), and structured
-    /// output (-o json / json-compact / env). When stdout is not a TTY, output
+    /// output (-o json / json-compact). When stdout is not a TTY, output
     /// defaults to json-compact automatically.
     #[command(after_help = "EXAMPLES:
   # Discover all records (summary, safe default limit)
@@ -157,11 +169,7 @@ EXAMPLES:
   secrets search -n refining --kind service --name gitea \\
     -f metadata.url -f metadata.default_org
 
-  # Export metadata as env vars (single record only)
-  secrets search -n refining --kind service --name gitea -o env
-
-  # Inject decrypted secrets only when needed
-  secrets inject -n refining --kind service --name gitea
+  # Run a command with decrypted secrets only when needed
   secrets run -n refining --kind service --name gitea -- printenv
 
   # Paginate large result sets
@@ -180,7 +188,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)
@@ -189,9 +197,6 @@ EXAMPLES:
         /// Fuzzy keyword (matches name, namespace, kind, tags, metadata text)
         #[arg(short, long)]
         query: Option<String>,
-        /// Deprecated: search never reveals secrets; use inject/run instead
-        #[arg(long)]
-        show_secrets: bool,
         /// Extract metadata field value(s) directly: metadata.<key> (repeatable)
         #[arg(short = 'f', long = "field")]
         fields: Vec<String>,
@@ -207,28 +212,44 @@ EXAMPLES:
         /// Sort order: name (default), updated, created
         #[arg(long, default_value = "name")]
         sort: String,
-        /// Output format: text (default on TTY), json, json-compact, env
+        /// Output format: text (default on TTY), json, json-compact
         #[arg(short, long = "output")]
         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>,
@@ -272,7 +293,11 @@ EXAMPLES:
   # Update nested typed JSON fields
   secrets update -n refining --kind service --name deploy-bot \\
     -s auth:config:='{\"issuer\":\"gitea\",\"rotate\":true}' \\
-    -s auth:retry:=5")]
+    -s auth:retry:=5
+
+  # Rotate shared PEM (all servers with key_ref=my-shared-key get the new key)
+  secrets update -n refining --kind key --name my-shared-key \\
+    -s content=@./keys/new-shared.pem")]
     Update {
         /// Namespace, e.g. refining, ricnsmart
         #[arg(short, long)]
@@ -289,7 +314,8 @@ EXAMPLES:
         /// Remove a tag (repeatable)
         #[arg(long = "remove-tag")]
         remove_tags: Vec<String>,
-        /// Set or overwrite a metadata field: key=value, key:=<json>, key=@file, or nested:path@file
+        /// Set or overwrite a metadata field: key=value, key:=<json>, key=@file, or nested:path@file.
+        /// Use key_ref=<name> to reference a shared key entry (kind=key).
         #[arg(long = "meta", short = 'm')]
         meta: Vec<String>,
         /// Delete a metadata field by key or nested path, e.g. old_port or credentials:content
@@ -365,51 +391,34 @@ EXAMPLES:
         output: Option<String>,
     },
 
-    /// Print secrets as environment variables (stdout only, nothing persisted).
-    ///
-    /// Outputs KEY=VALUE pairs for all matched records. Safe to pipe or eval.
-    #[command(after_help = "EXAMPLES:
-  # Print env vars for a single service
-  secrets inject -n refining --kind service --name gitea
-
-  # With a custom prefix
-  secrets inject -n refining --kind service --name gitea --prefix GITEA
-
-  # JSON output (all vars as a JSON object)
-  secrets inject -n refining --kind service --name gitea -o json
-
-  # Eval into current shell (use with caution)
-  eval $(secrets inject -n refining --kind service --name gitea)")]
-    Inject {
-        #[arg(short, long)]
-        namespace: Option<String>,
-        #[arg(long)]
-        kind: Option<String>,
-        #[arg(long)]
-        name: Option<String>,
-        #[arg(long)]
-        tag: Vec<String>,
-        /// Prefix to prepend to every variable name (uppercased automatically)
-        #[arg(long, default_value = "")]
-        prefix: String,
-        /// Output format: text/KEY=VALUE (default), json, json-compact
-        #[arg(short, long = "output")]
-        output: Option<String>,
-    },
-
     /// Run a command with secrets injected as environment variables.
     ///
     /// Secrets are available only to the child process; the current shell
     /// environment is not modified. The process exit code is propagated.
+    ///
+    /// Use -s/--secret to inject only specific fields. Use --dry-run to preview
+    /// which variables would be injected without executing the command.
     #[command(after_help = "EXAMPLES:
   # Run a script with a single service's secrets injected
   secrets run -n refining --kind service --name gitea -- ./deploy.sh
 
+  # Inject only specific fields (minimal exposure)
+  secrets run -n refining --kind service --name aliyun \\
+    -s access_key_id -s access_key_secret -- aliyun ecs DescribeInstances
+
   # Run with a tag filter (all matched records merged)
   secrets run --tag production -- env | grep GITEA
 
   # With prefix
-  secrets run -n refining --kind service --name gitea --prefix GITEA -- printenv")]
+  secrets run -n refining --kind service --name gitea --prefix GITEA -- printenv
+
+  # Preview which variables would be injected (no command executed)
+  secrets run -n refining --kind service --name gitea --dry-run
+
+  # Preview with field filter and JSON output
+  secrets run -n refining --kind service --name gitea -s token --dry-run -o json
+
+  # metadata.key_ref entries get key secrets merged (e.g. server + shared PEM)")]
     Run {
         #[arg(short, long)]
         namespace: Option<String>,
@@ -419,18 +428,27 @@ EXAMPLES:
         name: Option<String>,
         #[arg(long)]
         tag: Vec<String>,
+        /// Only inject these secret field names (repeatable). Omit to inject all fields.
+        #[arg(long = "secret", short = 's')]
+        secret_fields: Vec<String>,
         /// Prefix to prepend to every variable name (uppercased automatically)
         #[arg(long, default_value = "")]
         prefix: String,
+        /// Preview variables that would be injected without executing the command
+        #[arg(long)]
+        dry_run: bool,
+        /// Output format for --dry-run: json (default), json-compact, text
+        #[arg(short, long = "output")]
+        output: Option<String>,
         /// Command and arguments to execute with injected environment
-        #[arg(last = true, required = true)]
+        #[arg(last = true)]
         command: Vec<String>,
     },
 
     /// 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
@@ -442,6 +460,83 @@ EXAMPLES:
         #[arg(long)]
         check: bool,
     },
+
+    /// Export records to a file (JSON, TOML, or YAML).
+    ///
+    /// Decrypts and exports all matched records. Requires master key unless --no-secrets is used.
+    #[command(after_help = "EXAMPLES:
+  # Export everything to JSON
+  secrets export --file backup.json
+
+  # Export a specific namespace to TOML
+  secrets export -n refining --file refining.toml
+
+  # Export a specific kind
+  secrets export -n refining --kind service --file services.yaml
+
+  # Export by tag
+  secrets export --tag production --file prod.json
+
+  # Export schema only (no decryption needed)
+  secrets export --no-secrets --file schema.json
+
+  # Print to stdout in YAML
+  secrets export -n refining --format yaml")]
+    Export {
+        /// Filter by namespace
+        #[arg(short, long)]
+        namespace: Option<String>,
+        /// Filter by kind, e.g. server, service
+        #[arg(long)]
+        kind: Option<String>,
+        /// Exact name filter
+        #[arg(long)]
+        name: Option<String>,
+        /// Filter by tag (repeatable)
+        #[arg(long)]
+        tag: Vec<String>,
+        /// Fuzzy keyword search
+        #[arg(short, long)]
+        query: Option<String>,
+        /// Output file path (format inferred from extension: .json / .toml / .yaml / .yml)
+        #[arg(long)]
+        file: Option<String>,
+        /// Explicit format: json, toml, or yaml (overrides file extension; required for stdout)
+        #[arg(long)]
+        format: Option<String>,
+        /// Omit secrets from output (no master key required)
+        #[arg(long)]
+        no_secrets: bool,
+    },
+
+    /// Import records from a file (JSON, TOML, or YAML).
+    ///
+    /// Reads an export file and inserts or updates entries. Requires master key to re-encrypt secrets.
+    #[command(after_help = "EXAMPLES:
+  # Import a JSON backup (conflict = error by default)
+  secrets import backup.json
+
+  # Import and overwrite existing records
+  secrets import --force refining.toml
+
+  # Preview what would be imported (no writes)
+  secrets import --dry-run backup.yaml
+
+  # JSON output for the import summary
+  secrets import backup.json -o json")]
+    Import {
+        /// Input file path (format inferred from extension: .json / .toml / .yaml / .yml)
+        file: String,
+        /// Overwrite existing records on conflict (default: error and abort)
+        #[arg(long)]
+        force: bool,
+        /// Preview operations without writing to the database
+        #[arg(long)]
+        dry_run: bool,
+        /// Output format: text (default on TTY), json, json-compact
+        #[arg(short, long = "output")]
+        output: Option<String>,
+    },
 }
 
 #[derive(Subcommand)]
@@ -459,6 +554,7 @@ enum ConfigAction {
 
 #[tokio::main]
 async fn main() -> Result<()> {
+    load_dotenv();
     let cli = Cli::parse();
 
     let filter = if cli.verbose {
@@ -531,7 +627,6 @@ async fn main() -> Result<()> {
             name,
             tag,
             query,
-            show_secrets,
             fields,
             summary,
             limit,
@@ -549,7 +644,6 @@ async fn main() -> Result<()> {
                     name: name.as_deref(),
                     tags: &tag,
                     query: query.as_deref(),
-                    show_secrets,
                     fields: &fields,
                     summary,
                     limit,
@@ -565,12 +659,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 {
@@ -616,7 +721,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 {
@@ -642,40 +757,24 @@ async fn main() -> Result<()> {
             .await?;
         }
 
-        Commands::Inject {
-            namespace,
-            kind,
-            name,
-            tag,
-            prefix,
-            output,
-        } => {
-            let master_key = crypto::load_master_key()?;
-            let out = resolve_output_mode(output.as_deref())?;
-            commands::run::run_inject(
-                &pool,
-                commands::run::InjectArgs {
-                    namespace: namespace.as_deref(),
-                    kind: kind.as_deref(),
-                    name: name.as_deref(),
-                    tags: &tag,
-                    prefix: &prefix,
-                    output: out,
-                },
-                &master_key,
-            )
-            .await?;
-        }
-
         Commands::Run {
             namespace,
             kind,
             name,
             tag,
+            secret_fields,
             prefix,
+            dry_run,
+            output,
             command,
         } => {
             let master_key = crypto::load_master_key()?;
+            let out = resolve_output_mode(output.as_deref())?;
+            if !dry_run && command.is_empty() {
+                anyhow::bail!(
+                    "No command specified. Usage: secrets run [filter flags] -- <command> [args]"
+                );
+            }
             commands::run::run_exec(
                 &pool,
                 commands::run::RunArgs {
@@ -683,13 +782,71 @@ async fn main() -> Result<()> {
                     kind: kind.as_deref(),
                     name: name.as_deref(),
                     tags: &tag,
+                    secret_fields: &secret_fields,
                     prefix: &prefix,
+                    dry_run,
+                    output: out,
                     command: &command,
                 },
                 &master_key,
             )
             .await?;
         }
+
+        Commands::Export {
+            namespace,
+            kind,
+            name,
+            tag,
+            query,
+            file,
+            format,
+            no_secrets,
+        } => {
+            let master_key = if no_secrets {
+                None
+            } else {
+                Some(crypto::load_master_key()?)
+            };
+            let _span = tracing::info_span!("cmd", command = "export").entered();
+            commands::export_cmd::run(
+                &pool,
+                commands::export_cmd::ExportArgs {
+                    namespace: namespace.as_deref(),
+                    kind: kind.as_deref(),
+                    name: name.as_deref(),
+                    tags: &tag,
+                    query: query.as_deref(),
+                    file: file.as_deref(),
+                    format: format.as_deref(),
+                    no_secrets,
+                },
+                master_key.as_ref(),
+            )
+            .await?;
+        }
+
+        Commands::Import {
+            file,
+            force,
+            dry_run,
+            output,
+        } => {
+            let master_key = crypto::load_master_key()?;
+            let _span = tracing::info_span!("cmd", command = "import").entered();
+            let out = resolve_output_mode(output.as_deref())?;
+            commands::import_cmd::run(
+                &pool,
+                commands::import_cmd::ImportArgs {
+                    file: &file,
+                    force,
+                    dry_run,
+                    output: out,
+                },
+                &master_key,
+            )
+            .await?;
+        }
     }
 
     Ok(())

src/models.rs

@@ -1,20 +1,211 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use std::collections::BTreeMap;
 use uuid::Uuid;
 
+/// A top-level entry (server, service, key, …).
+/// Sensitive fields are stored separately in `secrets`.
 #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
-pub struct Secret {
+pub struct Entry {
     pub id: Uuid,
     pub namespace: String,
     pub kind: String,
     pub name: String,
     pub tags: Vec<String>,
     pub metadata: Value,
+    pub version: i64,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// A single encrypted field belonging to an Entry.
+#[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
+pub struct SecretField {
+    pub id: Uuid,
+    pub entry_id: Uuid,
+    pub field_name: String,
     /// AES-256-GCM ciphertext: nonce(12B) || ciphertext+tag
-    /// Decrypt with crypto::decrypt_json() before use.
     pub encrypted: Vec<u8>,
     pub version: i64,
     pub created_at: DateTime<Utc>,
     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 encrypted: Vec<u8>,
+}
+
+// ── Export / Import types ──────────────────────────────────────────────────────
+
+/// Supported file formats for export/import.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum ExportFormat {
+    Json,
+    Toml,
+    Yaml,
+}
+
+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();
+        Self::from_str(&ext).map_err(|_| {
+            anyhow::anyhow!(
+                "Cannot infer format from extension '.{}'. Use --format json|toml|yaml",
+                ext
+            )
+        })
+    }
+
+    /// Parse from --format CLI value.
+    pub fn from_str(s: &str) -> anyhow::Result<Self> {
+        match s.to_lowercase().as_str() {
+            "json" => Ok(Self::Json),
+            "toml" => Ok(Self::Toml),
+            "yaml" | "yml" => Ok(Self::Yaml),
+            other => anyhow::bail!("Unknown format '{}'. Expected: json, toml, or yaml", other),
+        }
+    }
+
+    /// Serialize ExportData to a string in this format.
+    pub fn serialize(&self, data: &ExportData) -> anyhow::Result<String> {
+        match self {
+            Self::Json => Ok(serde_json::to_string_pretty(data)?),
+            Self::Toml => {
+                let toml_val = json_to_toml_value(&serde_json::to_value(data)?)?;
+                toml::to_string_pretty(&toml_val)
+                    .map_err(|e| anyhow::anyhow!("TOML serialization failed: {}", e))
+            }
+            Self::Yaml => serde_yaml::to_string(data)
+                .map_err(|e| anyhow::anyhow!("YAML serialization failed: {}", e)),
+        }
+    }
+
+    /// Deserialize ExportData from a string in this format.
+    pub fn deserialize(&self, content: &str) -> anyhow::Result<ExportData> {
+        match self {
+            Self::Json => Ok(serde_json::from_str(content)?),
+            Self::Toml => {
+                let toml_val: toml::Value = toml::from_str(content)
+                    .map_err(|e| anyhow::anyhow!("TOML parse error: {}", e))?;
+                let json_val = toml_to_json_value(&toml_val);
+                Ok(serde_json::from_value(json_val)?)
+            }
+            Self::Yaml => serde_yaml::from_str(content)
+                .map_err(|e| anyhow::anyhow!("YAML parse error: {}", e)),
+        }
+    }
+}
+
+/// Top-level structure for export/import files.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ExportData {
+    pub version: u32,
+    pub exported_at: String,
+    pub entries: Vec<ExportEntry>,
+}
+
+/// A single entry with decrypted secrets for export/import.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ExportEntry {
+    pub namespace: String,
+    pub kind: String,
+    pub name: String,
+    #[serde(default)]
+    pub tags: Vec<String>,
+    #[serde(default)]
+    pub metadata: Value,
+    /// Decrypted secret fields. None means no secrets in this export (--no-secrets).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub secrets: Option<BTreeMap<String, Value>>,
+}
+
+// ── TOML ↔ JSON value conversion ──────────────────────────────────────────────
+
+/// Convert a serde_json Value to a toml Value.
+/// `null` values are filtered out (TOML does not support null).
+/// Mixed-type arrays are serialised as JSON strings.
+pub fn json_to_toml_value(v: &Value) -> anyhow::Result<toml::Value> {
+    match v {
+        Value::Null => anyhow::bail!("TOML does not support null values"),
+        Value::Bool(b) => Ok(toml::Value::Boolean(*b)),
+        Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Ok(toml::Value::Integer(i))
+            } else if let Some(f) = n.as_f64() {
+                Ok(toml::Value::Float(f))
+            } else {
+                anyhow::bail!("unsupported number: {}", n)
+            }
+        }
+        Value::String(s) => Ok(toml::Value::String(s.clone())),
+        Value::Array(arr) => {
+            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(e) => {
+                    tracing::debug!(error = %e, "mixed-type array; falling back to JSON string");
+                    Ok(toml::Value::String(serde_json::to_string(v)?))
+                }
+            }
+        }
+        Value::Object(map) => {
+            let mut toml_map = toml::map::Map::new();
+            for (k, val) in map {
+                if val.is_null() {
+                    // Skip null entries
+                    continue;
+                }
+                match json_to_toml_value(val) {
+                    Ok(tv) => {
+                        toml_map.insert(k.clone(), tv);
+                    }
+                    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)?));
+                    }
+                }
+            }
+            Ok(toml::Value::Table(toml_map))
+        }
+    }
+}
+
+/// Convert a toml Value back to a serde_json Value.
+pub fn toml_to_json_value(v: &toml::Value) -> Value {
+    match v {
+        toml::Value::Boolean(b) => Value::Bool(*b),
+        toml::Value::Integer(i) => Value::Number((*i).into()),
+        toml::Value::Float(f) => serde_json::Number::from_f64(*f)
+            .map(Value::Number)
+            .unwrap_or(Value::Null),
+        toml::Value::String(s) => Value::String(s.clone()),
+        toml::Value::Datetime(dt) => Value::String(dt.to_string()),
+        toml::Value::Array(arr) => Value::Array(arr.iter().map(toml_to_json_value).collect()),
+        toml::Value::Table(map) => {
+            let obj: serde_json::Map<String, Value> = map
+                .iter()
+                .map(|(k, v)| (k.clone(), toml_to_json_value(v)))
+                .collect();
+            Value::Object(obj)
+        }
+    }
+}

src/output.rs

@@ -1,5 +1,4 @@
 use chrono::{DateTime, Local, Utc};
-use std::io::IsTerminal;
 use std::str::FromStr;
 
 /// Output format for all commands.
@@ -12,8 +11,6 @@ pub enum OutputMode {
     Json,
     /// Single-line JSON (default when stdout is NOT a TTY, e.g. piped to jq)
     JsonCompact,
-    /// KEY=VALUE pairs suitable for `source` or `.env` files
-    Env,
 }
 
 impl FromStr for OutputMode {
@@ -24,9 +21,8 @@ impl FromStr for OutputMode {
             "text" => Ok(Self::Text),
             "json" => Ok(Self::Json),
             "json-compact" => Ok(Self::JsonCompact),
-            "env" => Ok(Self::Env),
             other => Err(anyhow::anyhow!(
-                "Unknown output format '{}'. Valid: text, json, json-compact, env",
+                "Unknown output format '{}'. Valid: text, json, json-compact",
                 other
             )),
         }
@@ -35,16 +31,12 @@ impl FromStr for OutputMode {
 
 /// Resolve the effective output mode.
 /// - Explicit value from `--output` takes priority.
-/// - TTY → text; non-TTY (piped/redirected) → json-compact.
+/// - Default is always `Json` (AI-first); use `-o text` for human-readable output.
 pub fn resolve_output_mode(explicit: Option<&str>) -> anyhow::Result<OutputMode> {
     if let Some(s) = explicit {
         return s.parse();
     }
-    if std::io::stdout().is_terminal() {
-        Ok(OutputMode::Text)
-    } else {
-        Ok(OutputMode::JsonCompact)
-    }
+    Ok(OutputMode::Json)
 }
 
 /// Format a UTC timestamp for local human-readable output.
@@ -53,3 +45,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(())
+}

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-----