chore: bump version to 0.6.1

Made-with: Cursor
feat(config): verify DB connection before saving set-db
2026-03-19 10:39:07 +08:00 · 2026-03-19 10:38:38 +08:00 · 2026-03-19 10:30:45 +08:00 · 2026-03-19 09:31:53 +08:00 · 2026-03-19 09:17:04 +08:00 · 2026-03-18 20:10:13 +08:00
24 changed files with 3502 additions and 477 deletions
--- a/.gitea/workflows/secrets.yml
+++ b/.gitea/workflows/secrets.yml
@@ -128,71 +128,6 @@ jobs:
            echo "release_id=" >> "$GITHUB_OUTPUT"
          fi
  probe-runners:
    name: 探测 Runner
    runs-on: debian
    outputs:
      has_linux: ${{ steps.probe.outputs.has_linux }}
      has_macos: ${{ steps.probe.outputs.has_macos }}
      has_windows: ${{ steps.probe.outputs.has_windows }}
    steps:
      - name: 查询可用 Runner
        id: probe
        env:
          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
        run: |
          fallback_all() {
            echo "has_linux=true" >> "$GITHUB_OUTPUT"
            echo "has_macos=true" >> "$GITHUB_OUTPUT"
            echo "has_windows=true" >> "$GITHUB_OUTPUT"
          }
          if [ -z "$RELEASE_TOKEN" ]; then
            echo "未配置 RELEASE_TOKEN，默认尝试所有平台"
            fallback_all; exit 0
          fi
          command -v jq >/dev/null 2>&1 || (sudo apt-get update -qq && sudo apt-get install -y -qq jq)
          http_code=$(curl -sS -o /tmp/runners.json -w '%{http_code}' \
            -H "Authorization: token $RELEASE_TOKEN" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/actions/runners")
          if [ "$http_code" != "200" ]; then
            echo "Runner API 返回 HTTP ${http_code}，默认尝试所有平台"
            fallback_all; exit 0
          fi
          has_runner() {
            local label="$1"
            jq -e --arg label "$label" '
              (.runners // .data // . // [])
              | any(
                  (
                    (.online == true)
                    or (
                      ((.status // "") | ascii_downcase)
                      | IN("online", "idle", "busy", "active")
                    )
                  )
                  and (
                    (.labels // [])
                    | map(if type == "object" then (.name // .label // "") else tostring end | ascii_downcase)
                    | index($label)
                  ) != null
                )
            ' /tmp/runners.json >/dev/null
          }
          for pair in "debian:has_linux" "darwin-arm64:has_macos" "windows:has_windows"; do
            label="$(printf '%s' "${pair%%:*}" | tr '[:upper:]' '[:lower:]')"; key="${pair##*:}"
            if has_runner "$label"; then
              echo "${key}=true" >> "$GITHUB_OUTPUT"
            else
              echo "${key}=false" >> "$GITHUB_OUTPUT"
            fi
          done
  check:
    name: 质量检查 (fmt / clippy / test)
    runs-on: debian
@@ -227,10 +162,9 @@ jobs:
  build-linux:
    name: Build (x86_64-unknown-linux-musl)
-    needs: [version, probe-runners, check]
+    needs: [version, check]
    if: needs.probe-runners.outputs.has_linux == 'true'
    runs-on: debian
-    timeout-minutes: 1
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        run: |
@@ -274,12 +208,31 @@ jobs:
            -F "attachment=@${archive}" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"
      - name: 飞书通知
        if: always()
        env:
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
        run: |
          [ -z "$WEBHOOK_URL" ] && exit 0
          command -v jq >/dev/null 2>&1 || (sudo apt-get update -qq && sudo apt-get install -y -qq jq)
          tag="${{ needs.version.outputs.tag }}"
          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
          result="${{ job.status }}"
          if [ "$result" = "success" ]; then icon="✅"; else icon="❌"; fi
          msg="secrets linux 构建${icon}
          版本：${tag}
          提交：${commit}
          作者：${{ github.actor }}
          详情：${url}"
          payload=$(jq -n --arg text "$msg" '{msg_type: "text", content: {text: $text}}')
          curl -sS -H "Content-Type: application/json" -X POST -d "$payload" "$WEBHOOK_URL"
  build-macos:
    name: Build (aarch64-apple-darwin)
-    needs: [version, probe-runners, check]
+    needs: [version, check]
    if: needs.probe-runners.outputs.has_macos == 'true'
    runs-on: darwin-arm64
-    timeout-minutes: 1
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        run: |
@@ -321,12 +274,30 @@ jobs:
            -F "attachment=@${archive}" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"
      - name: 飞书通知
        if: always()
        env:
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
        run: |
          [ -z "$WEBHOOK_URL" ] && exit 0
          tag="${{ needs.version.outputs.tag }}"
          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
          result="${{ job.status }}"
          if [ "$result" = "success" ]; then icon="✅"; else icon="❌"; fi
          msg="secrets macOS 构建${icon}
          版本：${tag}
          提交：${commit}
          作者：${{ github.actor }}
          详情：${url}"
          payload=$(python3 -c "import json,sys; print(json.dumps({'msg_type':'text','content':{'text':sys.argv[1]}}))" "$msg")
          curl -sS -H "Content-Type: application/json" -X POST -d "$payload" "$WEBHOOK_URL"
  build-windows:
    name: Build (x86_64-pc-windows-msvc)
-    needs: [version, probe-runners, check]
+    needs: [version, check]
    if: needs.probe-runners.outputs.has_windows == 'true'
    runs-on: windows
-    timeout-minutes: 1
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        shell: pwsh
@@ -372,34 +343,43 @@ jobs:
            -Headers @{ "Authorization" = "token $env:RELEASE_TOKEN" } `
            -Form @{ attachment = Get-Item $archive }
      - name: 飞书通知
        if: always()
        shell: pwsh
        env:
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
        run: |
          if (-not $env:WEBHOOK_URL) { exit 0 }
          $tag = "${{ needs.version.outputs.tag }}"
          $commit = (git log -1 --pretty=format:"%s" 2>$null) ?? "N/A"
          $url = "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
          $result = "${{ job.status }}"
          $icon = if ($result -eq "success") { "✅" } else { "❌" }
          $msg = "secrets windows 构建${icon}`n版本：${tag}`n提交：${commit}`n作者：${{ github.actor }}`n详情：${url}"
          $payload = @{ msg_type = "text"; content = @{ text = $msg } } | ConvertTo-Json
          Invoke-RestMethod -Uri $env:WEBHOOK_URL -Method Post `
            -ContentType "application/json" -Body $payload
  publish-release:
    name: 发布草稿 Release
-    needs: [version, check, build-linux, build-macos, build-windows]
+    needs: [version, build-linux]
    if: always() && needs.version.outputs.release_id != ''
    runs-on: debian
-    timeout-minutes: 2
+    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - name: 发布草稿
        env:
          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
        run: |
          [ -z "$RELEASE_TOKEN" ] && exit 0
          version_r="${{ needs.version.result }}"
          check_r="${{ needs.check.result }}"
          linux_r="${{ needs.build-linux.result }}"
-          macos_r="${{ needs.build-macos.result }}"
+          if [ "$linux_r" != "success" ]; then
-          windows_r="${{ needs.build-windows.result }}"
+            echo "Linux 构建未成功 (${linux_r})，保留草稿 Release"
-
+            exit 0
-          for result in "$version_r" "$check_r" "$linux_r" "$macos_r" "$windows_r"; do
+          fi
            case "$result" in
              success|skipped) ;;
              *)
                echo "存在失败或取消的 job，保留草稿 Release"
                exit 0
                ;;
            esac
          done
          release_api="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}"
          http_code=$(curl -sS -o /tmp/publish-release.json -w '%{http_code}' \
@@ -413,18 +393,10 @@ jobs:
            cat /tmp/publish-release.json 2>/dev/null || true
            exit 1
          fi
          echo "Release 已发布"
-  notify:
+      - name: 飞书汇总通知
-    name: 通知
+        if: always()
    needs: [version, probe-runners, check, build-linux, build-macos, build-windows, publish-release]
    if: always() && github.event_name == 'push'
    runs-on: debian
    timeout-minutes: 1
    continue-on-error: true
    steps:
      - uses: actions/checkout@v4
      - name: 发送飞书通知
        env:
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
        run: |
@@ -436,43 +408,29 @@ jobs:
          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
-          version_r="${{ needs.version.result }}"
+          check_r="${{ needs.version.result }}"
          check_r="${{ needs.check.result }}"
          linux_r="${{ needs.build-linux.result }}"
-          macos_r="${{ needs.build-macos.result }}"
+          publish_r="${{ job.status }}"
          windows_r="${{ needs.build-windows.result }}"
          publish_r="${{ needs.publish-release.result }}"
-          if [ "$version_r" = "success" ] && [ "$check_r" = "success" ] \
+          icon() { case "$1" in success) echo "✅";; skipped) echo "⏭";; *) echo "❌";; esac; }
-            && [ "$linux_r" != "failure" ] && [ "$linux_r" != "cancelled" ] \
+
-            && [ "$macos_r" != "failure" ] && [ "$macos_r" != "cancelled" ] \
+          if [ "$linux_r" = "success" ] && [ "$publish_r" = "success" ]; then
-            && [ "$windows_r" != "failure" ] && [ "$windows_r" != "cancelled" ] \
+            status="发布成功 ✅"
-            && [ "$publish_r" != "failure" ] && [ "$publish_r" != "cancelled" ]; then
+          elif [ "$linux_r" != "success" ]; then
            status="构建成功 ✅"
          else
            status="构建失败 ❌"
          fi
          icon() {
            case "$1" in
              success) echo "✅" ;;
              skipped) echo "⏭" ;;
              *) echo "❌" ;;
            esac
          }
          msg="${{ env.BINARY_NAME }} ${status}"
          if [ "$tag_exists" = "false" ]; then
            msg="${msg}
          🆕 新版本 ${tag}"
          else
-            msg="${msg}
+            status="发布失败 ❌"
          🔄 重复构建 ${tag}"
          fi
-          msg="${msg}
+          if [ "$tag_exists" = "false" ]; then
-          构建结果：linux$(icon "$linux_r") macOS$(icon "$macos_r") windows$(icon "$windows_r")
+            version_line="🆕 新版本 ${tag}"
-          Release：$(icon "$publish_r")
+          else
            version_line="🔄 重复构建 ${tag}"
          fi
          msg="secrets ${status}
          ${version_line}
          linux $(icon "$linux_r") | Release $(icon "$publish_r")
          提交：${commit}
          作者：${{ github.actor }}
          详情：${url}"
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 /target
 .env
-.DS_Store
+.DS_Store
 .cursor/
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -25,12 +25,36 @@
      "command": "./target/debug/secrets help add",
      "dependsOn": "build"
    },
    {
      "label": "cli: help config",
      "type": "shell",
      "command": "./target/debug/secrets help config",
      "dependsOn": "build"
    },
    {
      "label": "cli: config path",
      "type": "shell",
      "command": "./target/debug/secrets config path",
      "dependsOn": "build"
    },
    {
      "label": "cli: config show",
      "type": "shell",
      "command": "./target/debug/secrets config show",
      "dependsOn": "build"
    },
    {
      "label": "test: search all",
      "type": "shell",
      "command": "./target/debug/secrets search",
      "dependsOn": "build"
    },
    {
      "label": "test: search all (verbose)",
      "type": "shell",
      "command": "./target/debug/secrets --verbose search",
      "dependsOn": "build"
    },
    {
      "label": "test: search by namespace (refining)",
      "type": "shell",
@@ -82,7 +106,7 @@
    {
      "label": "test: search with secrets revealed",
      "type": "shell",
-      "command": "./target/debug/secrets search -n refining --kind service --name gitea --show-secrets",
+      "command": "./target/debug/secrets search -n refining --kind service --show-secrets",
      "dependsOn": "build"
    },
    {
@@ -97,6 +121,24 @@
      "command": "echo '--- add ---' && ./target/debug/secrets add -n test --kind demo --name roundtrip-test --tag test -m foo=bar -s password=secret123 && echo '--- search ---' && ./target/debug/secrets search -n test --show-secrets && echo '--- delete ---' && ./target/debug/secrets delete -n test --kind demo --name roundtrip-test && echo '--- verify deleted ---' && ./target/debug/secrets search -n test",
      "dependsOn": "build"
    },
    {
      "label": "test: add + delete roundtrip (verbose)",
      "type": "shell",
      "command": "echo '--- add (verbose) ---' && ./target/debug/secrets --verbose add -n test --kind demo --name roundtrip-verbose --tag test -m foo=bar -s password=secret123 && echo '--- delete (verbose) ---' && ./target/debug/secrets --verbose delete -n test --kind demo --name roundtrip-verbose",
      "dependsOn": "build"
    },
    {
      "label": "test: update roundtrip",
      "type": "shell",
      "command": "echo '--- add ---' && ./target/debug/secrets add -n test --kind demo --name update-test --tag v1 -m env=staging && echo '--- update ---' && ./target/debug/secrets update -n test --kind demo --name update-test --add-tag v2 --remove-tag v1 -m env=production && echo '--- verify ---' && ./target/debug/secrets search -n test --kind demo && echo '--- cleanup ---' && ./target/debug/secrets delete -n test --kind demo --name update-test",
      "dependsOn": "build"
    },
    {
      "label": "test: audit log",
      "type": "shell",
      "command": "echo '--- add ---' && ./target/debug/secrets add -n test --kind demo --name audit-test -m foo=bar -s key=val && echo '--- update ---' && ./target/debug/secrets update -n test --kind demo --name audit-test -m foo=baz && echo '--- delete ---' && ./target/debug/secrets delete -n test --kind demo --name audit-test && echo '--- audit log (last 5) ---' && psql $DATABASE_URL -c \"SELECT action, namespace, kind, name, actor, detail, created_at FROM audit_log ORDER BY created_at DESC LIMIT 5;\"",
      "dependsOn": "build"
    },
    {
      "label": "test: add with file secret",
      "type": "shell",
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,33 +1,41 @@
 # Secrets CLI — AGENTS.md
-跨设备密钥与配置管理 CLI 工具，将 refining / ricnsmart 两个项目的服务器信息、服务凭据存储到 PostgreSQL 18，供 AI 工具读取上下文。
+跨设备密钥与配置管理 CLI 工具，将 refining / ricnsmart 两个项目的服务器信息、服务凭据存储到 PostgreSQL 18，供 AI 工具读取上下文。敏感数据（encrypted 字段）使用 AES-256-GCM 加密，主密钥由 Argon2id 从主密码派生并存入平台安全存储（macOS Keychain / Windows Credential Manager / Linux keyutils）。
 ## 项目结构
 ```
 secrets/
  src/
-    main.rs              # CLI 入口，clap 命令定义，auto-migrate
+    main.rs              # CLI 入口，clap 命令定义，auto-migrate，--verbose 全局参数
-    db.rs                # PgPool 创建 + 建表/索引（幂等）
+    output.rs            # OutputMode 枚举 + TTY 检测（TTY→text，非 TTY→json-compact）
-    models.rs            # Secret 结构体（sqlx::FromRow + serde）
+    config.rs            # 配置读写：~/.config/secrets/config.toml（database_url）
    db.rs                # PgPool 创建 + 建表/索引（幂等，含 audit_log + kv_config + secrets_history）
    crypto.rs            # AES-256-GCM 加解密、Argon2id 派生、OS 钥匙串
    models.rs            # Secret 结构体（sqlx::FromRow + serde，含 version 字段）
    audit.rs             # 审计写入：log_tx（事务内）/ log（池，保留备用）
    commands/
-      add.rs             # add 命令：upsert，支持 --meta key=value / --secret key=@file
+      init.rs            # init 命令：主密钥初始化（每台设备一次）
-      search.rs          # search 命令：多条件动态查询
+      add.rs             # add 命令：upsert，事务化，含历史快照，支持 key:=json 类型化值
-      delete.rs          # delete 命令
+      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 命令：临时环境变量注入
  scripts/
-    seed-data.sh         # 从 refining/ricnsmart config.toml 导入全量数据
+    setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
  .gitea/workflows/
    secrets.yml          # CI：fmt + clippy + musl 构建 + Release 上传 + 飞书通知
-  .vscode/tasks.json     # 本地测试任务（build / search / add+delete roundtrip 等）
+  .vscode/tasks.json     # 本地测试任务（build / config / search / add+delete / update / audit 等）
  .env                   # DATABASE_URL（gitignore，不提交）
 ```
 ## 数据库
- **Host**: `47.117.131.22:5432`（阿里云上海 ECS，PostgreSQL 18 with io_uring）
+- **Host**: `<host>:<port>`
 - **Database**: `secrets`
- **连接串**: `postgres://postgres:<password>@47.117.131.22:5432/secrets`
+- **连接串**: `postgres://postgres:<password>@<host>:<port>/secrets`
- **表**: 单张 `secrets` 表，首次连接自动建表（auto-migrate）
+- **表**: `secrets`（主表）+ `audit_log`（审计表）+ `kv_config`（Argon2 salt 等），首次连接自动建表（auto-migrate）
 ### 表结构
@@ -39,13 +47,53 @@ secrets (
  name        VARCHAR(256)  NOT NULL,              -- 人类可读标识
  tags        TEXT[]        NOT NULL DEFAULT '{}', -- 灵活标签: ["aliyun","hongkong"]
  metadata    JSONB         NOT NULL DEFAULT '{}', -- 明文描述: ip, desc, domains, location...
-  encrypted   JSONB         NOT NULL DEFAULT '{}', -- 敏感数据: ssh_key, password, token...
+  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(),
  UNIQUE(namespace, kind, name)
 )
 ```
 ```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()
 )
 ```
 ```sql
 kv_config (
  key   TEXT PRIMARY KEY,   -- 如 'argon2_salt'
  value BYTEA NOT NULL        -- Argon2id salt，首台设备 init 时生成
 )
 ```
 ### audit_log 表结构
 ```sql
 audit_log (
  id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  action      VARCHAR(32)   NOT NULL,              -- 'add' | 'update' | 'delete'
  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 环境变量）
  created_at  TIMESTAMPTZ   NOT NULL DEFAULT NOW()
 )
 ```
 ### 字段职责划分
 | 字段 | 存什么 | 示例 |
@@ -55,44 +103,133 @@ secrets (
 | `name` | 唯一标识名 | `i-uf63f2uookgs5uxmrdyc`, `gitea` |
 | `tags` | 多维分类标签 | `["aliyun","hongkong","ricn"]` |
 | `metadata` | 明文非敏感信息 | `{"ip":"47.243.154.187","desc":"Grafana","domains":["..."]}` |
-| `encrypted` | 敏感凭据（MVP 阶段明文存储，后续对 value 加密） | `{"ssh_key":"-----BEGIN...","password":"..."}` |
+| `encrypted` | 敏感凭据，AES-256-GCM 加密存储 | 二进制密文，解密后为 `{"ssh_key":"...","password":"..."}` |
 ## 数据库配置
 首次使用需显式配置数据库连接，设置一次后在该设备上持久生效：
 ```bash
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 secrets config show   # 查看当前配置（密码脱敏）
 secrets config path   # 打印配置文件路径
 ```
 `set-db` 会先验证连接可用，成功后才写入配置文件；连接失败时提示 "Database connection failed" 且不修改配置。
 配置文件：`~/.config/secrets/config.toml`，权限 0600。`--db-url` 参数可一次性覆盖。
 ## 主密钥与加密
 首次使用（每台设备各执行一次）：
 ```bash
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 secrets init   # 提示输入主密码，Argon2id 派生主密钥后存入 OS 钥匙串
 ```
 主密码不存储；salt 存于 `kv_config`，首台设备生成后共享，确保同一主密码在所有设备派生出相同主密钥。
 主密钥存储后端：macOS Keychain、Windows Credential Manager、Linux keyutils（会话级，重启后需再次 `secrets init`）。
 **从旧版（明文 JSONB）升级**：升级后执行 `secrets init` 即可（明文记录需手动重新 add 或通过 update 更新）。
 ## CLI 命令
 ### AI 使用主路径
 **读取一律用 `search`，写入用 `add` / `update`，避免反复查帮助。**
 输出格式规则：
 - TTY（终端直接运行）→ 默认 `text`
 - 非 TTY（管道/重定向/AI 调用）→ 自动 `json-compact`
 - 显式 `-o json` → 美化 JSON
 - 显式 `-o env` → KEY=VALUE（可 source）
 ---
 ### init — 主密钥初始化（每台设备一次）
 ```bash
-# 查看版本
+# 首次设备：生成 Argon2id salt 并存库，派生主密钥后存 OS 钥匙串
-secrets -V / --version
+secrets init
-# 查看帮助
+# 后续设备：复用已有 salt，派生主密钥后存钥匙串（主密码需与首台相同）
-secrets -h / --help
+secrets init
 secrets help <subcommand>   # 子命令详细帮助，如 secrets help add
 # 添加或更新记录（upsert）
 secrets add -n <namespace> --kind <kind> --name <name> \
  [--tag <tag>]...          # 可重复
  [-m key=value]...         # --meta 明文字段，-m 是短标志
  [-s key=value]...         # --secret 敏感字段，value 以 @ 开头表示从文件读取
 # 搜索（默认隐藏 encrypted 内容）
 secrets search [-n <namespace>] [--kind <kind>] [--tag <tag>] [-q <keyword>] [--show-secrets]
 # -q 匹配范围：name、namespace、kind、metadata 全文内容、tags
 # 增量更新已有记录（合并语义，记录不存在则报错）
 secrets update -n <namespace> --kind <kind> --name <name> \
  [--add-tag <tag>]...        # 添加标签（不影响已有标签）
  [--remove-tag <tag>]...     # 移除标签
  [-m key=value]...           # 新增或覆盖 metadata 字段（不影响其他字段）
  [--remove-meta <key>]...    # 删除 metadata 字段
  [-s key=value]...           # 新增或覆盖 encrypted 字段（不影响其他字段）
  [--remove-secret <key>]...  # 删除 encrypted 字段
 # 删除
 secrets delete -n <namespace> --kind <kind> --name <name>
 ```
-### 示例
+### search — 发现与读取
 ```bash
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             gitea | i-uf63f2uookgs5uxmrdyc | mqtt
 #   --tag              aliyun | hongkong | production
 #   -q / --query       mqtt | grafana | gitea   （模糊匹配 name/namespace/kind/tags/metadata）
 #   --show-secrets     不带值的 flag，显示 encrypted 字段内容
 #   -f / --field       metadata.ip | metadata.url | secret.token | secret.ssh_key
 #   --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
 # 发现概览（起步推荐）
 secrets search --summary --limit 20
 secrets search -n refining --summary --limit 20
 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）
 secrets search -n refining --kind service --name gitea -o json --show-secrets
 # 直接提取字段值（最短路径，-f secret.* 自动解锁 secrets）
 secrets search -n refining --kind service --name gitea -f secret.token
 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 -f secret.token
 # 模糊关键词搜索
 secrets search -q mqtt
 secrets search -q grafana
 secrets search -q 47.117
 # 按条件过滤
 secrets search -n refining --kind service
 secrets search -n ricnsmart --kind server
 secrets search --tag hongkong
 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）
 secrets search -n refining --kind service | jq '.[].name'
 secrets search -n refining --kind service --name gitea --show-secrets | jq '.secrets.token'
 # 导出为 env 文件（单条记录）
 secrets search -n refining --kind service --name gitea -o env --show-secrets \
  > ~/.config/gitea/config.env
 ```
 ---
 ### add — 新增或全量覆盖（upsert）
 ```bash
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             gitea | i-uf63f2uookgs5uxmrdyc
 #   --tag              aliyun | hongkong（可重复）
 #   -m / --meta        ip=47.117.131.22 | desc="Aliyun ECS" | url=https://...（可重复）
 #   -s / --secret      token=<value> | ssh_key=@./key.pem | password=secret123（可重复）
 # 添加服务器
 secrets add -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
  --tag aliyun --tag shanghai \
@@ -102,30 +239,200 @@ secrets add -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
 # 添加服务凭据
 secrets add -n refining --kind service --name gitea \
  --tag gitea \
-  -m url=https://gitea.refining.dev \
+  -m url=https://gitea.refining.dev -m default_org=refining -m username=voson \
-  -s token=<token>
+  -s token=<token> -s runner_token=<runner_token>
-# 搜索含 mqtt 的所有记录
+# 从文件读取 token
-secrets search -q mqtt
+secrets add -n ricnsmart --kind service --name mqtt \
  -m host=mqtt.ricnsmart.com -m port=1883 \
  -s password=@./mqtt_password.txt
-# 查看 refining 的全部服务配置（显示 secrets）
+# 使用类型化值（key:=<json>）存储非字符串类型
-secrets search -n refining --kind service --show-secrets
+secrets add -n refining --kind service --name prometheus \
  -m scrape_interval:=15 \
  -m enabled:=true \
  -m labels:='["prod","metrics"]' \
  -s api_key=abc123
 ```
-# 按 tag 筛选
+---
 secrets search --tag hongkong
-# 只更新一个 IP（不影响其他 metadata/secrets/tags）
+### update — 增量更新（记录必须已存在）
 只有传入的字段才会变动，其余全部保留。
 ```bash
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             gitea | i-uf63f2uookgs5uxmrdyc
 #   --add-tag          production | backup（不影响已有 tag，可重复）
 #   --remove-tag       staging | deprecated（可重复）
 #   -m / --meta        ip=10.0.0.1 | desc="新描述"（新增或覆盖，可重复）
 #   --remove-meta      old_port | legacy_key（删除 metadata 字段，可重复）
 #   -s / --secret      token=<new> | ssh_key=@./new.pem（新增或覆盖，可重复）
 #   --remove-secret    old_password | deprecated_key（删除 secret 字段，可重复）
 # 更新单个 metadata 字段
 secrets update -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
  -m ip=10.0.0.1
-# 给一条记录新增 tag 并轮换密码
+# 轮换 token
 secrets update -n refining --kind service --name gitea \
  -s token=<new-token>
 # 新增 tag 并轮换 token
 secrets update -n refining --kind service --name gitea \
  --add-tag production \
  -s token=<new-token>
-# 移除一个废弃的 metadata 字段
+# 移除废弃字段
 secrets update -n refining --kind service --name mqtt \
-  --remove-meta old_port
+  --remove-meta old_port --remove-secret old_password
 # 移除 tag
 secrets update -n refining --kind service --name gitea --remove-tag staging
 ```
 ---
 ### delete — 删除记录
 ```bash
 # 参数说明（带典型值）
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             gitea | i-uf63f2uookgs5uxmrdyc（必须精确匹配）
 # 删除服务凭据
 secrets delete -n refining --kind service --name legacy-mqtt
 # 删除服务器记录
 secrets delete -n ricnsmart --kind server --name i-old-server-id
 ```
 ---
 ### history — 查看变更历史
 ```bash
 # 参数说明
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             记录名
 #   --limit            返回条数（默认 20）
 # 查看某条记录的历史版本列表
 secrets history -n refining --kind service --name gitea
 # 查最近 5 条
 secrets history -n refining --kind service --name gitea --limit 5
 # JSON 输出
 secrets history -n refining --kind service --name gitea -o json
 ```
 ---
 ### rollback — 回滚到指定版本
 ```bash
 # 参数说明
 #   -n / --namespace     refining | ricnsmart
 #   --kind               server | service
 #   --name               记录名
 #   --to-version <N>     目标版本号（省略则恢复最近一次快照）
 # 撤销上次修改（回滚到最近一次快照）
 secrets rollback -n refining --kind service --name gitea
 # 回滚到版本 3
 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，进程退出码透传。
 ```bash
 # 参数说明
 #   -n / --namespace   refining | ricnsmart
 #   --kind             server | service
 #   --name             记录名
 #   --tag              按 tag 过滤（可重复）
 #   --prefix           变量名前缀
 #   -- <command>       执行的命令及参数
 # 向脚本注入单条记录的 secrets
 secrets run -n refining --kind service --name gitea -- ./deploy.sh
 # 按 tag 批量注入（多条记录合并）
 secrets run --tag production -- env | grep -i token
 # 验证注入了哪些变量
 secrets run -n refining --kind service --name gitea -- printenv
 ```
 ---
 ### config — 配置管理（无需主密钥）
 ```bash
 # 设置数据库连接（每台设备执行一次，之后永久生效；先验证连接可用再写入）
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 # 查看当前配置（密码脱敏）
 secrets config show
 # 打印配置文件路径
 secrets config path
 # 输出: /Users/<user>/.config/secrets/config.toml
 ```
 ---
 ### 全局参数
 ```bash
 # debug 日志（位于子命令之前）
 secrets --verbose search -q mqtt
 secrets -v add -n refining --kind service --name gitea -m url=xxx -s token=yyy
 # 或通过环境变量精细控制
 RUST_LOG=secrets=trace secrets search
 # 一次性覆盖数据库连接
 secrets --db-url "postgres://..." search -n refining
 ```
 ## 代码规范
@@ -134,7 +441,11 @@ secrets update -n refining --kind service --name mqtt \
 - 异步：全程 `tokio`，数据库操作 `sqlx` async
 - SQL：使用 `sqlx::query` / `sqlx::query_as` 绑定参数，禁止字符串拼接（搜索的动态 WHERE 子句除外，需使用参数绑定 `$1/$2`）
 - 新增 `kind` 类型时：只需在 `add` 调用时传入，无需改代码
- 字段命名：CLI 短标志 `-n`=namespace，`-m`=meta，`-s`=secret，`-q`=query
+- 字段命名：CLI 短标志 `-n`=namespace，`-m`=meta，`-s`=secret，`-q`=query，`-v`=verbose，`-f`=field，`-o`=output
 - 日志：用户可见输出用 `println!`；调试/运维信息用 `tracing::debug!`/`info!`/`warn!`/`error!`
 - 审计：`add`/`update`/`delete` 成功后调用 `audit::log()`，写入 `audit_log` 表；失败只 warn 不中断
 - 加密：`encrypted` 列存储 AES-256-GCM 密文；`add`/`update`/`search`/`delete` 需主密钥（`secrets init` 后从 OS 钥匙串加载）
 - 输出：读命令通过 `OutputMode` 支持 text/json/json-compact/env；写命令 `add` 同样支持 `-o json`
 ## 提交前检查（必须全部通过）
@@ -152,7 +463,7 @@ grep '^version' Cargo.toml
 git tag -l 'secrets-*'
 ```
-若当前版本已被 tag（例如已有 `secrets-0.1.0` 且 `Cargo.toml` 仍为 `0.1.0`），则应在 `Cargo.toml` 中 bump 版本号后再提交，以便 CI 自动打新 Tag 并发布 Release。
+若当前版本已被 tag（例如已有 `secrets-0.3.0` 且 `Cargo.toml` 仍为 `0.3.0`），则应在 `Cargo.toml` 中 bump 版本号后再提交，以便 CI 自动打新 Tag 并发布 Release。
 ### 2. 格式、Lint、测试
@@ -176,9 +487,13 @@ cargo fmt -- --check && cargo clippy -- -D warnings && cargo test
 - 新版本自动打 Tag（格式 `secrets-<version>`）并上传二进制到 Gitea Release
 - 通知：飞书 Webhook（`vars.WEBHOOK_URL`）
 - 所需 secrets/vars：`RELEASE_TOKEN`（Release 上传，Gitea PAT）、`vars.WEBHOOK_URL`（通知，可选）
 - **注意**：Gitea Actions 的 Secret/Variable 创建时，`data`/`value` 字段需传入**原始值**，不要使用 base64 编码
 ## 环境变量
 | 变量 | 说明 |
 |------|------|
-| `DATABASE_URL` | PostgreSQL 连接串，优先级高于 `--db-url` 参数 |
+| `RUST_LOG` | 日志级别，如 `secrets=debug`、`secrets=trace`（默认 warn） |
 | `USER` | 审计日志 actor 字段来源，Shell 自动设置，通常无需手动配置 |
 数据库连接通过 `secrets config set-db` 持久化到 `~/.config/secrets/config.toml`，不支持环境变量。
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,6 +2,50 @@
 # It is not intended for manual editing.
 version = 4
 [[package]]
 name = "aead"
 version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
 dependencies = [
 "crypto-common",
 "generic-array",
 ]
 [[package]]
 name = "aes"
 version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
 dependencies = [
 "cfg-if",
 "cipher",
 "cpufeatures 0.2.17",
 ]
 [[package]]
 name = "aes-gcm"
 version = "0.10.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
 dependencies = [
 "aead",
 "aes",
 "cipher",
 "ctr",
 "ghash",
 "subtle",
 ]
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
 dependencies = [
 "memchr",
 ]
 [[package]]
 name = "allocator-api2"
 version = "0.2.21"
@@ -73,6 +117,18 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 [[package]]
 name = "argon2"
 version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
 dependencies = [
 "base64ct",
 "blake2",
 "cpufeatures 0.2.17",
 "password-hash",
 ]
 [[package]]
 name = "atoi"
 version = "2.0.0"
@@ -109,6 +165,15 @@ dependencies = [
 "serde_core",
 ]
 [[package]]
 name = "blake2"
 version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
 dependencies = [
 "digest",
 ]
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -152,6 +217,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 [[package]]
 name = "chacha20"
 version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
 dependencies = [
 "cfg-if",
 "cpufeatures 0.3.0",
 "rand_core 0.10.0",
 ]
 [[package]]
 name = "chrono"
 version = "0.4.44"
@@ -166,6 +242,16 @@ dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "cipher"
 version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
 "crypto-common",
 "inout",
 ]
 [[package]]
 name = "clap"
 version = "4.6.0"
@@ -227,6 +313,26 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 [[package]]
 name = "core-foundation"
 version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
 dependencies = [
 "core-foundation-sys",
 "libc",
 ]
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
 dependencies = [
 "core-foundation-sys",
 "libc",
 ]
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
@@ -242,6 +348,15 @@ dependencies = [
 "libc",
 ]
 [[package]]
 name = "cpufeatures"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
 dependencies = [
 "libc",
 ]
 [[package]]
 name = "crc"
 version = "3.4.0"
@@ -279,9 +394,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
 "generic-array",
 "rand_core 0.6.4",
 "typenum",
 ]
 [[package]]
 name = "ctr"
 version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
 dependencies = [
 "cipher",
 ]
 [[package]]
 name = "der"
 version = "0.7.10"
@@ -305,6 +430,27 @@ dependencies = [
 "subtle",
 ]
 [[package]]
 name = "dirs"
 version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
 dependencies = [
 "dirs-sys",
 ]
 [[package]]
 name = "dirs-sys"
 version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
 dependencies = [
 "libc",
 "option-ext",
 "redox_users",
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "displaydoc"
 version = "0.2.5"
@@ -502,10 +648,21 @@ dependencies = [
 "cfg-if",
 "libc",
 "r-efi",
 "rand_core 0.10.0",
 "wasip2",
 "wasip3",
 ]
 [[package]]
 name = "ghash"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
 dependencies = [
 "opaque-debug",
 "polyval",
 ]
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -715,6 +872,15 @@ dependencies = [
 "serde_core",
 ]
 [[package]]
 name = "inout"
 version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
 dependencies = [
 "generic-array",
 ]
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
@@ -737,6 +903,21 @@ dependencies = [
 "wasm-bindgen",
 ]
 [[package]]
 name = "keyring"
 version = "3.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
 dependencies = [
 "byteorder",
 "linux-keyutils",
 "log",
 "security-framework 2.11.1",
 "security-framework 3.7.0",
 "windows-sys 0.60.2",
 "zeroize",
 ]
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -786,6 +967,16 @@ dependencies = [
 "vcpkg",
 ]
 [[package]]
 name = "linux-keyutils"
 version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "761e49ec5fd8a5a463f9b84e877c373d888935b71c6be78f3767fe2ae6bed18e"
 dependencies = [
 "bitflags",
 "libc",
 ]
 [[package]]
 name = "litemap"
 version = "0.8.1"
@@ -807,6 +998,15 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 [[package]]
 name = "matchers"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
 dependencies = [
 "regex-automata",
 ]
 [[package]]
 name = "md-5"
 version = "0.10.6"
@@ -834,6 +1034,15 @@ dependencies = [
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "nu-ansi-term"
 version = "0.50.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
 dependencies = [
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "num-bigint-dig"
 version = "0.8.6"
@@ -845,7 +1054,7 @@ dependencies = [
 "num-integer",
 "num-iter",
 "num-traits",
- "rand",
+ "rand 0.8.5",
 "smallvec",
 "zeroize",
 ]
@@ -892,6 +1101,18 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 [[package]]
 name = "opaque-debug"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 [[package]]
 name = "option-ext"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 [[package]]
 name = "parking"
 version = "2.2.1"
@@ -921,6 +1142,17 @@ dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "password-hash"
 version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
 dependencies = [
 "base64ct",
 "rand_core 0.6.4",
 "subtle",
 ]
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
@@ -975,6 +1207,18 @@ version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
 [[package]]
 name = "polyval"
 version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
 dependencies = [
 "cfg-if",
 "cpufeatures 0.2.17",
 "opaque-debug",
 "universal-hash",
 ]
 [[package]]
 name = "potential_utf"
 version = "0.1.4"
@@ -1035,7 +1279,18 @@ checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
 dependencies = [
 "libc",
 "rand_chacha",
- "rand_core",
+ "rand_core 0.6.4",
 ]
 [[package]]
 name = "rand"
 version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
 dependencies = [
 "chacha20",
 "getrandom 0.4.2",
 "rand_core 0.10.0",
 ]
 [[package]]
@@ -1045,7 +1300,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
 dependencies = [
 "ppv-lite86",
- "rand_core",
+ "rand_core 0.6.4",
 ]
 [[package]]
@@ -1057,6 +1312,12 @@ dependencies = [
 "getrandom 0.2.17",
 ]
 [[package]]
 name = "rand_core"
 version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -1075,6 +1336,34 @@ dependencies = [
 "bitflags",
 ]
 [[package]]
 name = "redox_users"
 version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
 dependencies = [
 "getrandom 0.2.17",
 "libredox",
 "thiserror",
 ]
 [[package]]
 name = "regex-automata"
 version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
 dependencies = [
 "aho-corasick",
 "memchr",
 "regex-syntax",
 ]
 [[package]]
 name = "regex-syntax"
 version = "0.8.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -1089,6 +1378,17 @@ dependencies = [
 "windows-sys 0.52.0",
 ]
 [[package]]
 name = "rpassword"
 version = "7.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "66d4c8b64f049c6721ec8ccec37ddfc3d641c4a7fca57e8f2a89de509c73df39"
 dependencies = [
 "libc",
 "rtoolbox",
 "windows-sys 0.59.0",
 ]
 [[package]]
 name = "rsa"
 version = "0.9.10"
@@ -1102,13 +1402,23 @@ dependencies = [
 "num-traits",
 "pkcs1",
 "pkcs8",
- "rand_core",
+ "rand_core 0.6.4",
 "signature",
 "spki",
 "subtle",
 "zeroize",
 ]
 [[package]]
 name = "rtoolbox"
 version = "0.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7cc970b249fbe527d6e02e0a227762c9108b2f49d81094fe357ffc6d14d7f6f"
 dependencies = [
 "libc",
 "windows-sys 0.52.0",
 ]
 [[package]]
 name = "rustls"
 version = "0.23.36"
@@ -1163,20 +1473,63 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 [[package]]
 name = "secrets"
-version = "0.2.0"
+version = "0.6.0"
 dependencies = [
 "aes-gcm",
 "anyhow",
 "argon2",
 "chrono",
 "clap",
- "dotenvy",
+ "dirs",
 "keyring",
 "rand 0.10.0",
 "rpassword",
 "serde",
 "serde_json",
 "sqlx",
 "tokio",
 "toml",
 "tracing",
 "tracing-subscriber",
 "uuid",
 ]
 [[package]]
 name = "security-framework"
 version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
 dependencies = [
 "bitflags",
 "core-foundation 0.9.4",
 "core-foundation-sys",
 "libc",
 "security-framework-sys",
 ]
 [[package]]
 name = "security-framework"
 version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
 "bitflags",
 "core-foundation 0.10.1",
 "core-foundation-sys",
 "libc",
 "security-framework-sys",
 ]
 [[package]]
 name = "security-framework-sys"
 version = "2.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
 dependencies = [
 "core-foundation-sys",
 "libc",
 ]
 [[package]]
 name = "semver"
 version = "1.0.27"
@@ -1254,7 +1607,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
 dependencies = [
 "cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 "digest",
 ]
@@ -1265,10 +1618,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
 "cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 "digest",
 ]
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
 dependencies = [
 "lazy_static",
 ]
 [[package]]
 name = "shlex"
 version = "1.3.0"
@@ -1292,7 +1654,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
 "digest",
- "rand_core",
+ "rand_core 0.6.4",
 ]
 [[package]]
@@ -1458,7 +1820,7 @@ dependencies = [
 "memchr",
 "once_cell",
 "percent-encoding",
- "rand",
+ "rand 0.8.5",
 "rsa",
 "serde",
 "sha1",
@@ -1498,7 +1860,7 @@ dependencies = [
 "md-5",
 "memchr",
 "once_cell",
- "rand",
+ "rand 0.8.5",
 "serde",
 "serde_json",
 "sha2",
@@ -1608,6 +1970,15 @@ dependencies = [
 "syn",
 ]
 [[package]]
 name = "thread_local"
 version = "1.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
 dependencies = [
 "cfg-if",
 ]
 [[package]]
 name = "tinystr"
 version = "0.8.2"
@@ -1741,6 +2112,36 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
 "once_cell",
 "valuable",
 ]
 [[package]]
 name = "tracing-log"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
 dependencies = [
 "log",
 "once_cell",
 "tracing-core",
 ]
 [[package]]
 name = "tracing-subscriber"
 version = "0.3.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
 dependencies = [
 "matchers",
 "nu-ansi-term",
 "once_cell",
 "regex-automata",
 "sharded-slab",
 "smallvec",
 "thread_local",
 "tracing",
 "tracing-core",
 "tracing-log",
 ]
 [[package]]
@@ -1782,6 +2183,16 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
 dependencies = [
 "crypto-common",
 "subtle",
 ]
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -1818,12 +2229,17 @@ version = "1.22.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a68d3c8f01c0cfa54a75291d83601161799e4a89a39e0929f4b0354d88757a37"
 dependencies = [
 "getrandom 0.4.2",
 "js-sys",
 "serde_core",
 "wasm-bindgen",
 ]
 [[package]]
 name = "valuable"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 [[package]]
 name = "vcpkg"
 version = "0.2.15"
@@ -2050,6 +2466,24 @@ dependencies = [
 "windows-targets 0.52.6",
 ]
 [[package]]
 name = "windows-sys"
 version = "0.59.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
 dependencies = [
 "windows-targets 0.52.6",
 ]
 [[package]]
 name = "windows-sys"
 version = "0.60.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
 dependencies = [
 "windows-targets 0.53.5",
 ]
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
@@ -2083,13 +2517,30 @@ dependencies = [
 "windows_aarch64_gnullvm 0.52.6",
 "windows_aarch64_msvc 0.52.6",
 "windows_i686_gnu 0.52.6",
- "windows_i686_gnullvm",
+ "windows_i686_gnullvm 0.52.6",
 "windows_i686_msvc 0.52.6",
 "windows_x86_64_gnu 0.52.6",
 "windows_x86_64_gnullvm 0.52.6",
 "windows_x86_64_msvc 0.52.6",
 ]
 [[package]]
 name = "windows-targets"
 version = "0.53.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
 dependencies = [
 "windows-link",
 "windows_aarch64_gnullvm 0.53.1",
 "windows_aarch64_msvc 0.53.1",
 "windows_i686_gnu 0.53.1",
 "windows_i686_gnullvm 0.53.1",
 "windows_i686_msvc 0.53.1",
 "windows_x86_64_gnu 0.53.1",
 "windows_x86_64_gnullvm 0.53.1",
 "windows_x86_64_msvc 0.53.1",
 ]
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.48.5"
@@ -2102,6 +2553,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.48.5"
@@ -2114,6 +2571,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
 [[package]]
 name = "windows_i686_gnu"
 version = "0.48.5"
@@ -2126,12 +2589,24 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
 [[package]]
 name = "windows_i686_gnu"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
 [[package]]
 name = "windows_i686_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 [[package]]
 name = "windows_i686_gnullvm"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
 [[package]]
 name = "windows_i686_msvc"
 version = "0.48.5"
@@ -2144,6 +2619,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 [[package]]
 name = "windows_i686_msvc"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.48.5"
@@ -2156,6 +2637,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.48.5"
@@ -2168,6 +2655,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.48.5"
@@ -2180,6 +2673,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
 [[package]]
 name = "winnow"
 version = "1.0.0"
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,16 +1,23 @@
 [package]
 name = "secrets"
-version = "0.2.0"
+version = "0.6.1"
 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", "env"] }
+clap = { version = "4.6.0", features = ["derive"] }
-dotenvy = "0.15.7"
+dirs = "6.0.0"
 keyring = { version = "3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
 rand = "0.10.0"
 rpassword = "7.4.0"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
 sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
 tokio = { version = "1.50.0", features = ["full"] }
 toml = "1.0.7"
-uuid = { version = "1.22.0", features = ["serde", "v4"] }
+tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 uuid = { version = "1.22.0", features = ["serde"] }
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 跨设备密钥与配置管理 CLI，基于 Rust + PostgreSQL 18。
-将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。
+将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。敏感数据（`encrypted` 字段）使用 AES-256-GCM 加密存储，主密钥由 Argon2id 从主密码派生并存入系统钥匙串。
 ## 安装
@@ -11,61 +11,138 @@ cargo build --release
 # 或从 Release 页面下载预编译二进制
 ```
-配置数据库连接：
+## 首次使用（每台设备各执行一次）
 ```bash
-export DATABASE_URL=postgres://postgres:<password>@<host>:5432/secrets
+# 1. 配置数据库连接（会先验证连接可用再写入）
-# 或在项目根目录创建 .env 文件写入上述变量
+secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 # 2. 初始化主密钥（提示输入主密码，派生后存入 OS 钥匙串）
 secrets init
 ```
-## 使用
+主密码不会存储，仅用于派生主密钥。同一主密码在所有设备上会得到相同主密钥（salt 存于数据库，首台设备生成后共享）。
 **主密钥存储**：macOS → Keychain；Windows → Credential Manager；Linux → keyutils（会话级，重启后需再次 `secrets init`）。
 **从旧版（明文存储）升级**：升级后首次运行需执行 `secrets init` 即可（明文记录需手动重新 add 或通过 update 更新）。
 ## AI Agent 快速指南
 这个 CLI 以 AI 使用优先设计。核心路径只有一条：**读取用 `search`，写入用 `add` / `update`**。
 ### 第一步：发现有哪些数据
 ```bash
-# 查看版本
+# 列出所有记录摘要（默认最多 50 条，安全起步）
-secrets -V
+secrets search --summary --limit 20
 secrets --version
-# 查看帮助
+# 按 namespace 过滤
 secrets search -n refining --summary --limit 20
 # 按最近更新排序
 secrets search --sort updated --limit 10 --summary
 ```
 `--summary` 只返回轻量字段（namespace、kind、name、tags、desc、updated_at），不含完整 metadata 和 secrets。
 ### 第二步：精确读取单条记录
 ```bash
 # 精确定位（namespace + kind + name 三元组）
 secrets search -n refining --kind service --name gitea
 # 获取完整记录含 secrets（JSON 格式，AI 最易解析）
 secrets search -n refining --kind service --name gitea -o json --show-secrets
 # 直接提取单个字段值（最短路径）
 secrets search -n refining --kind service --name gitea -f secret.token
 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 -f secret.token
 ```
 `-f secret.*` 会自动解锁 secrets，无需额外加 `--show-secrets`。
 ### 输出格式
 | 场景 | 推荐命令 |
 |------|----------|
 | AI 解析 / 管道处理 | `-o json` 或 `-o json-compact` |
 | 写入 `.env` 文件 | `-o env --show-secrets` |
 | 人类查看 | 默认 `text`（TTY 下自动启用） |
 | 非 TTY（管道/重定向） | 自动 `json-compact` |
 ```bash
 # 管道直接 jq 解析（非 TTY 自动 json-compact）
 secrets search -n refining --kind service | jq '.[].name'
 secrets search -n refining --kind service --name gitea --show-secrets | jq '.secrets.token'
 # 导出为可 source 的 env 文件（单条记录）
 secrets search -n refining --kind service --name gitea -o env --show-secrets \
  > ~/.config/gitea/config.env
 ```
 ## 完整命令参考
 ```bash
 # 查看帮助（包含各子命令 EXAMPLES）
 secrets --help
-secrets -h
+secrets init --help           # 主密钥初始化
 secrets search --help
 secrets add --help
 secrets update --help
 secrets delete --help
 secrets config --help
-# 查看子命令帮助
+# ── search ──────────────────────────────────────────────────────────────────
-secrets help add
+secrets search --summary --limit 20                        # 发现概览
-secrets help search
+secrets search -n refining --kind service                  # 按 namespace + kind
-secrets help delete
+secrets search -n refining --kind service --name gitea     # 精确查找
-secrets help update
+secrets search -q mqtt                                     # 关键词模糊搜索
 secrets search --tag hongkong                              # 按 tag 过滤
 secrets search -n refining --kind service --name gitea -f secret.token   # 提取字段
 secrets search -n refining --kind service --name gitea -o json --show-secrets  # 完整 JSON
 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=1.2.3.4 -m desc="My Server" \
+  -m ip=47.117.131.22 -m desc="Aliyun Shanghai ECS" \
-  -s username=root \
+  -s username=root -s ssh_key=@./keys/server.pem
  -s ssh_key=@./keys/my.pem
 # 添加服务凭据
 secrets add -n refining --kind service --name gitea \
-  -m url=https://gitea.example.com \
+  --tag gitea \
  -m url=https://gitea.refining.dev -m default_org=refining \
  -s token=<token>
-# 搜索（默认隐藏敏感字段）
+# ── update ───────────────────────────────────────────────────────────────────
 secrets search
 secrets search -n refining --kind server
 secrets search --tag hongkong
 secrets search -q mqtt              # 关键词匹配 name / metadata / tags
 secrets search -n refining --kind service --name gitea --show-secrets
 # 增量更新已有记录（合并语义，记录不存在则报错）
 secrets update -n refining --kind server --name my-server -m ip=10.0.0.1
-secrets update -n refining --kind service --name gitea --add-tag production -s token=<new-token>
+secrets update -n refining --kind service --name gitea --add-tag production -s token=<new>
 secrets update -n refining --kind service --name mqtt --remove-meta old_port --remove-secret old_key
-# 删除
+# ── delete ───────────────────────────────────────────────────────────────────
-secrets delete -n refining --kind server --name my-server
+secrets delete -n refining --kind service --name legacy-mqtt
 # ── init ─────────────────────────────────────────────────────────────────────
 secrets init              # 主密钥初始化（每台设备一次，主密码派生后存钥匙串）
 # ── config ───────────────────────────────────────────────────────────────────
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"   # 先验证再写入
 secrets config show    # 密码脱敏展示
 secrets config path    # 打印配置文件路径
 # ── 调试 ──────────────────────────────────────────────────────────────────────
 secrets --verbose search -q mqtt
 RUST_LOG=secrets=trace secrets search
 ```
 ## 数据模型
-单张 `secrets` 表，首次连接自动建表。
+单张 `secrets` 表，首次连接自动建表；同时自动创建 `audit_log` 表，记录所有写操作。
 | 字段 | 说明 |
 |------|------|
@@ -74,24 +151,42 @@ secrets delete -n refining --kind server --name my-server
 | `name` | 人类可读唯一标识 |
 | `tags` | 多维标签，如 `["aliyun","hongkong"]` |
 | `metadata` | 明文描述信息（ip、desc、domains 等） |
-| `encrypted` | 敏感凭据（ssh_key、password、token 等），MVP 阶段明文存储，预留加密字段 |
+| `encrypted` | 敏感凭据（ssh_key、password、token 等），AES-256-GCM 加密存储 |
-`-m` / `--meta` 写入 `metadata`，`-s` / `--secret` 写入 `encrypted`，`value=@file` 从文件读取内容。
+`-m` / `--meta` 写入 `metadata`，`-s` / `--secret` 写入 `encrypted`，`value=@file` 从文件读取内容。加解密使用主密钥（由 `secrets init` 设置）。
 ## 审计日志
 `add`、`update`、`delete` 操作成功后自动向 `audit_log` 表写入一条记录，包含操作类型、操作对象和变更摘要（不含 secret 值）。操作者取自 `$USER` 环境变量。
 ```sql
 -- 查看最近 20 条审计记录
 SELECT action, namespace, kind, name, actor, detail, created_at
 FROM audit_log
 ORDER BY created_at DESC
 LIMIT 20;
 ```
 ## 项目结构
 ```
 src/
-  main.rs          # CLI 入口（clap）
+  main.rs          # CLI 入口（clap），含各子命令 after_help 示例
-  db.rs            # 连接池 + auto-migrate
+  output.rs        # OutputMode 枚举 + TTY 检测
  config.rs        # 配置读写（~/.config/secrets/config.toml）
  db.rs            # 连接池 + auto-migrate（secrets + audit_log + kv_config）
  crypto.rs        # AES-256-GCM 加解密、Argon2id 派生、OS 钥匙串
  models.rs        # Secret 结构体
  audit.rs         # 审计日志写入（audit_log 表）
  commands/
-    add.rs         # upsert
+    init.rs        # 主密钥初始化（首次/新设备）
-    search.rs      # 多条件查询
+    add.rs         # upsert，支持 -o json
    config.rs      # config set-db/show/path
    search.rs      # 多条件查询，支持 -f/-o/--summary/--limit/--offset/--sort
    delete.rs      # 删除
    update.rs      # 增量更新（合并 tags/metadata/encrypted）
 scripts/
-  seed-data.sh     # 导入 refining / ricnsmart 全量数据
+  setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
 ```
 ## CI/CD（Gitea Actions）
@@ -107,5 +202,6 @@ scripts/
 - `RELEASE_TOKEN`（Secret）：Gitea PAT，用于创建 Release 上传二进制
 - `WEBHOOK_URL`（Variable）：飞书通知，可选
 - **注意**：Secret/Variable 的 `data`/`value` 字段需传入原始值，不要 base64 编码
 详见 [AGENTS.md](AGENTS.md)。
--- a/scripts/setup-gitea-actions.sh
+++ b/scripts/setup-gitea-actions.sh
@@ -7,7 +7,9 @@
 #   - secrets.RELEASE_TOKEN  (必选) Release 上传用，值为 Gitea PAT
 #   - vars.WEBHOOK_URL       (可选) 飞书通知
 #
-# 注意: Gitea 不允许 secret/variable 名以 GITEA_ 或 GITHUB_ 开头，故使用 RELEASE_TOKEN
+# 注意:
 #   - Gitea 不允许 secret/variable 名以 GITEA_ 或 GITHUB_ 开头，故使用 RELEASE_TOKEN
 #   - Secret/Variable 的 data/value 字段需传入原始值，不要使用 base64 编码
 #
 # 用法:
 #   1. 从 ~/.config/gitea/config.env 读取 GITEA_URL, GITEA_TOKEN, GITEA_WEBHOOK_URL
@@ -108,11 +110,13 @@ echo "━━━━━━━━━━━━━━━━━━━━━━━━
 echo ""
 # 1. 创建 Secret: RELEASE_TOKEN
 # 注意: Gitea Actions API 的 data 字段需传入原始值，不要使用 base64 编码
 echo "1. 创建 Secret: RELEASE_TOKEN"
 secret_payload=$(jq -n --arg t "$GITEA_TOKEN" '{data: $t}')
 resp=$(curl -s -w "\n%{http_code}" -X PUT \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
-  -d "{\"data\":\"${GITEA_TOKEN}\"}" \
+  -d "$secret_payload" \
  "${API_BASE}/repos/${OWNER}/${REPO}/actions/secrets/RELEASE_TOKEN")
 http_code=$(echo "$resp" | tail -n1)
 body=$(echo "$resp" | sed '$d')
@@ -126,14 +130,16 @@ else
 fi
 # 2. 创建/更新 Variable: WEBHOOK_URL（可选）
 # 注意: Secret 和 Variable 均使用原始值，不要 base64 编码
 WEBHOOK_VALUE="${WEBHOOK_URL:-$GITEA_WEBHOOK_URL}"
 if [[ -n "$WEBHOOK_VALUE" ]]; then
  echo ""
  echo "2. 创建/更新 Variable: WEBHOOK_URL"
  var_payload=$(jq -n --arg v "$WEBHOOK_VALUE" '{value: $v}')
  resp=$(curl -s -w "\n%{http_code}" -X POST \
    -H "Authorization: token $GITEA_TOKEN" \
    -H "Content-Type: application/json" \
-    -d "{\"value\":\"${WEBHOOK_VALUE}\"}" \
+    -d "$var_payload" \
    "${API_BASE}/repos/${OWNER}/${REPO}/actions/variables/WEBHOOK_URL")
  http_code=$(echo "$resp" | tail -n1)
  body=$(echo "$resp" | sed '$d')
@@ -145,7 +151,7 @@ if [[ -n "$WEBHOOK_VALUE" ]]; then
    resp=$(curl -s -w "\n%{http_code}" -X PUT \
      -H "Authorization: token $GITEA_TOKEN" \
      -H "Content-Type: application/json" \
-      -d "{\"value\":\"${WEBHOOK_VALUE}\"}" \
+      -d "$var_payload" \
      "${API_BASE}/repos/${OWNER}/${REPO}/actions/variables/WEBHOOK_URL")
    http_code=$(echo "$resp" | tail -n1)
    if [[ "$http_code" == "200" || "$http_code" == "204" ]]; then
--- a/src/audit.rs
+++ b/src/audit.rs
@@ -0,0 +1,64 @@
 use serde_json::Value;
 use sqlx::{PgPool, Postgres, Transaction};
 /// Write an audit entry within an existing transaction.
 pub async fn log_tx(
    tx: &mut Transaction<'_, Postgres>,
    action: &str,
    namespace: &str,
    kind: &str,
    name: &str,
    detail: Value,
 ) {
    let actor = std::env::var("USER").unwrap_or_default();
    let result: Result<_, sqlx::Error> = sqlx::query(
        "INSERT INTO audit_log (action, namespace, kind, name, detail, actor) \
         VALUES ($1, $2, $3, $4, $5, $6)",
    )
    .bind(action)
    .bind(namespace)
    .bind(kind)
    .bind(name)
    .bind(&detail)
    .bind(&actor)
    .execute(&mut **tx)
    .await;
    if let Err(e) = result {
        tracing::warn!(error = %e, "failed to write audit log");
    } else {
        tracing::debug!(action, namespace, kind, name, actor, "audit logged");
    }
 }
 /// Write an audit entry using the pool (fire-and-forget, non-fatal).
 /// Kept for future use or scenarios without an active transaction.
 #[allow(dead_code)]
 pub async fn log(
    pool: &PgPool,
    action: &str,
    namespace: &str,
    kind: &str,
    name: &str,
    detail: Value,
 ) {
    let actor = std::env::var("USER").unwrap_or_default();
    let result: Result<_, sqlx::Error> = sqlx::query(
        "INSERT INTO audit_log (action, namespace, kind, name, detail, actor) \
         VALUES ($1, $2, $3, $4, $5, $6)",
    )
    .bind(action)
    .bind(namespace)
    .bind(kind)
    .bind(name)
    .bind(&detail)
    .bind(&actor)
    .execute(pool)
    .await;
    if let Err(e) = result {
        tracing::warn!(error = %e, "failed to write audit log");
    } else {
        tracing::debug!(action, namespace, kind, name, actor, "audit logged");
    }
 }
--- a/src/commands/add.rs
+++ b/src/commands/add.rs
@@ -1,13 +1,33 @@
 use anyhow::Result;
-use serde_json::{Map, Value};
+use serde_json::{Map, Value, json};
 use sqlx::PgPool;
 use std::fs;
-/// Parse "key=value" entries. Value starting with '@' reads from file.
+use crate::crypto;
-pub(crate) fn parse_kv(entry: &str) -> Result<(String, String)> {
+use crate::db;
 use crate::output::OutputMode;
 /// Parse "key=value" or "key:=<json>" entries.
 /// - `key=value`   → stores the literal string `value`
 /// - `key:=<json>` → parses `<json>` as a typed JSON value (number, bool, null, array, object)
 /// - `value=@file` → reads the file content as a string (only for `=` form)
 pub(crate) fn parse_kv(entry: &str) -> Result<(String, Value)> {
    // Typed JSON form: key:=<json>
    if let Some((key, json_str)) = entry.split_once(":=") {
        let val: Value = serde_json::from_str(json_str).map_err(|e| {
            anyhow::anyhow!(
                "Invalid JSON value for key '{}': {} (use key=value for plain strings)",
                key,
                e
            )
        })?;
        return Ok((key.to_string(), val));
    }
    // Plain string form: key=value or key=@file
    let (key, raw_val) = entry.split_once('=').ok_or_else(|| {
        anyhow::anyhow!(
-            "Invalid format '{}'. Expected: key=value or key=@file",
+            "Invalid format '{}'. Expected: key=value, key=@file, or key:=<json>",
            entry
        )
    })?;
@@ -19,68 +39,154 @@ pub(crate) fn parse_kv(entry: &str) -> Result<(String, String)> {
        raw_val.to_string()
    };
-    Ok((key.to_string(), value))
+    Ok((key.to_string(), Value::String(value)))
 }
-fn build_json(entries: &[String]) -> Result<Value> {
+pub(crate) fn build_json(entries: &[String]) -> Result<Value> {
    let mut map = Map::new();
    for entry in entries {
        let (key, value) = parse_kv(entry)?;
-        map.insert(key, Value::String(value));
+        map.insert(key, value);
    }
    Ok(Value::Object(map))
 }
-pub async fn run(
+pub struct AddArgs<'a> {
-    pool: &PgPool,
+    pub namespace: &'a str,
-    namespace: &str,
+    pub kind: &'a str,
-    kind: &str,
+    pub name: &'a str,
-    name: &str,
+    pub tags: &'a [String],
-    tags: &[String],
+    pub meta_entries: &'a [String],
-    meta_entries: &[String],
+    pub secret_entries: &'a [String],
-    secret_entries: &[String],
+    pub output: OutputMode,
-) -> Result<()> {
+}
-    let metadata = build_json(meta_entries)?;
+
-    let encrypted = build_json(secret_entries)?;
+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");
    let meta_keys: Vec<&str> = args
        .meta_entries
        .iter()
        .filter_map(|s| s.split_once(['=', ':']).map(|(k, _)| k))
        .collect();
    let secret_keys: Vec<&str> = args
        .secret_entries
        .iter()
        .filter_map(|s| s.split_once(['=', ':']).map(|(k, _)| k))
        .collect();
    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 \
         WHERE namespace = $1 AND kind = $2 AND name = $3",
    )
    .bind(args.namespace)
    .bind(args.kind)
    .bind(args.name)
    .fetch_optional(&mut *tx)
    .await?;
    if let Some(ex) = existing
        && let Err(e) = db::snapshot_history(
            &mut tx,
            db::SnapshotParams {
                secret_id: ex.id,
                namespace: args.namespace,
                kind: args.kind,
                name: args.name,
                version: ex.version,
                action: "add",
                tags: &ex.tags,
                metadata: &ex.metadata,
                encrypted: &ex.encrypted,
            },
        )
        .await
    {
        tracing::warn!(error = %e, "failed to snapshot history before upsert");
    }
    sqlx::query(
        r#"
-        INSERT INTO secrets (namespace, kind, name, tags, metadata, encrypted, updated_at)
+        INSERT INTO secrets (namespace, kind, name, tags, metadata, encrypted, version, updated_at)
-        VALUES ($1, $2, $3, $4, $5, $6, NOW())
+        VALUES ($1, $2, $3, $4, $5, $6, 1, NOW())
        ON CONFLICT (namespace, kind, name)
        DO UPDATE SET
-            tags      = EXCLUDED.tags,
+            tags       = EXCLUDED.tags,
-            metadata  = EXCLUDED.metadata,
+            metadata   = EXCLUDED.metadata,
-            encrypted = EXCLUDED.encrypted,
+            encrypted  = EXCLUDED.encrypted,
            version    = secrets.version + 1,
            updated_at = NOW()
        "#,
    )
-    .bind(namespace)
+    .bind(args.namespace)
-    .bind(kind)
+    .bind(args.kind)
-    .bind(name)
+    .bind(args.name)
-    .bind(tags)
+    .bind(args.tags)
    .bind(&metadata)
-    .bind(&encrypted)
+    .bind(&encrypted_bytes)
-    .execute(pool)
+    .execute(&mut *tx)
    .await?;
-    println!("Added: [{}/{}] {}", namespace, kind, name);
+    crate::audit::log_tx(
-    if !tags.is_empty() {
+        &mut tx,
-        println!("  tags:     {}", tags.join(", "));
+        "add",
-    }
+        args.namespace,
-    if !meta_entries.is_empty() {
+        args.kind,
-        let keys: Vec<&str> = meta_entries
+        args.name,
-            .iter()
+        json!({
-            .filter_map(|s| s.split_once('=').map(|(k, _)| k))
+            "tags": args.tags,
-            .collect();
+            "meta_keys": meta_keys,
-        println!("  metadata: {}", keys.join(", "));
+            "secret_keys": secret_keys,
-    }
+        }),
-    if !secret_entries.is_empty() {
+    )
-        let keys: Vec<&str> = secret_entries
+    .await;
-            .iter()
+
-            .filter_map(|s| s.split_once('=').map(|(k, _)| k))
+    tx.commit().await?;
-            .collect();
+
-        println!("  secrets:  {}", keys.join(", "));
+    let result_json = json!({
        "action": "added",
        "namespace": args.namespace,
        "kind": args.kind,
        "name": args.name,
        "tags": args.tags,
        "meta_keys": meta_keys,
        "secret_keys": secret_keys,
    });
    match args.output {
        OutputMode::Json => {
            println!("{}", serde_json::to_string_pretty(&result_json)?);
        }
        OutputMode::JsonCompact => {
            println!("{}", serde_json::to_string(&result_json)?);
        }
        _ => {
            println!("Added: [{}/{}] {}", args.namespace, args.kind, args.name);
            if !args.tags.is_empty() {
                println!("  tags:     {}", args.tags.join(", "));
            }
            if !args.meta_entries.is_empty() {
                println!("  metadata: {}", meta_keys.join(", "));
            }
            if !args.secret_entries.is_empty() {
                println!("  secrets:  {}", secret_keys.join(", "));
            }
        }
    }
    Ok(())
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -0,0 +1,54 @@
 use crate::config::{self, Config, config_path};
 use anyhow::Result;
 pub async fn run(action: crate::ConfigAction) -> Result<()> {
    match action {
        crate::ConfigAction::SetDb { url } => {
            // Verify connection before writing config
            let pool = crate::db::create_pool(&url)
                .await
                .map_err(|e| anyhow::anyhow!("Database connection failed: {}", e))?;
            drop(pool);
            let cfg = Config {
                database_url: Some(url.clone()),
            };
            config::save_config(&cfg)?;
            println!("Database URL saved to: {}", config_path().display());
            println!("  {}", mask_password(&url));
        }
        crate::ConfigAction::Show => {
            let cfg = config::load_config()?;
            match cfg.database_url {
                Some(url) => {
                    println!("database_url = {}", mask_password(&url));
                    println!("config file:  {}", config_path().display());
                }
                None => {
                    println!("Database URL not configured.");
                    println!("Run: secrets config set-db <DATABASE_URL>");
                }
            }
        }
        crate::ConfigAction::Path => {
            println!("{}", config_path().display());
        }
    }
    Ok(())
 }
 /// Mask the password in a postgres://user:password@host/db URL.
 fn mask_password(url: &str) -> String {
    if let Some(at_pos) = url.rfind('@')
        && let Some(scheme_end) = url.find("://")
    {
        let prefix = &url[..scheme_end + 3];
        let credentials = &url[scheme_end + 3..at_pos];
        let rest = &url[at_pos..];
        if let Some(colon_pos) = credentials.find(':') {
            let user = &credentials[..colon_pos];
            return format!("{}{}:***{}", prefix, user, rest);
        }
    }
    url.to_string()
 }
--- a/src/commands/delete.rs
+++ b/src/commands/delete.rs
@@ -1,19 +1,107 @@
 use anyhow::Result;
-use sqlx::PgPool;
+use serde_json::{Value, json};
 use sqlx::{FromRow, PgPool};
 use uuid::Uuid;
-pub async fn run(pool: &PgPool, namespace: &str, kind: &str, name: &str) -> Result<()> {
+use crate::db;
-    let result =
+use crate::output::OutputMode;
        sqlx::query("DELETE FROM secrets WHERE namespace = $1 AND kind = $2 AND name = $3")
            .bind(namespace)
            .bind(kind)
            .bind(name)
            .execute(pool)
            .await?;
-    if result.rows_affected() == 0 {
+#[derive(FromRow)]
-        println!("Not found: [{}/{}] {}", namespace, kind, name);
+struct DeleteRow {
-    } else {
+    id: Uuid,
-        println!("Deleted: [{}/{}] {}", namespace, kind, name);
+    version: i64,
    tags: Vec<String>,
    metadata: Value,
    encrypted: Vec<u8>,
 }
 pub async fn run(
    pool: &PgPool,
    namespace: &str,
    kind: &str,
    name: &str,
    output: OutputMode,
 ) -> Result<()> {
    tracing::debug!(namespace, kind, name, "deleting record");
    let mut tx = pool.begin().await?;
    let row: Option<DeleteRow> = sqlx::query_as(
        "SELECT id, version, tags, metadata, encrypted FROM secrets \
         WHERE namespace = $1 AND kind = $2 AND name = $3 \
         FOR UPDATE",
    )
    .bind(namespace)
    .bind(kind)
    .bind(name)
    .fetch_optional(&mut *tx)
    .await?;
    let Some(row) = row else {
        tx.rollback().await?;
        tracing::warn!(namespace, kind, name, "record not found for deletion");
        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),
        }
        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,
            namespace,
            kind,
            name,
            version: row.version,
            action: "delete",
            tags: &row.tags,
            metadata: &row.metadata,
            encrypted: &row.encrypted,
        },
    )
    .await
    {
        tracing::warn!(error = %e, "failed to snapshot history before delete");
    }
    sqlx::query("DELETE FROM secrets WHERE id = $1")
        .bind(row.id)
        .execute(&mut *tx)
        .await?;
    crate::audit::log_tx(&mut tx, "delete", namespace, kind, name, json!({})).await;
    tx.commit().await?;
    match output {
        OutputMode::Json => println!(
            "{}",
            serde_json::to_string_pretty(
                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
            )?
        ),
        OutputMode::JsonCompact => println!(
            "{}",
            serde_json::to_string(
                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
            )?
        ),
        _ => println!("Deleted: [{}/{}] {}", namespace, kind, name),
    }
    Ok(())
 }
--- a/src/commands/init.rs
+++ b/src/commands/init.rs
@@ -0,0 +1,62 @@
 use anyhow::{Context, Result};
 use rand::RngExt;
 use sqlx::PgPool;
 use crate::{crypto, db};
 pub async fn run(pool: &PgPool) -> Result<()> {
    println!("Initializing secrets master key...");
    println!();
    // Read password (no echo)
    let password =
        rpassword::prompt_password("Enter master password: ").context("failed to read password")?;
    if password.is_empty() {
        anyhow::bail!("Master password must not be empty.");
    }
    let confirm = rpassword::prompt_password("Confirm master password: ")
        .context("failed to read password confirmation")?;
    if password != confirm {
        anyhow::bail!("Passwords do not match.");
    }
    // Get or create Argon2id salt
    let salt = match db::load_argon2_salt(pool).await? {
        Some(existing) => {
            println!("Found existing salt in database (not the first device).");
            existing
        }
        None => {
            println!("Generating new Argon2id salt and storing in database...");
            let mut salt = vec![0u8; 16];
            rand::rng().fill(&mut salt[..]);
            db::store_argon2_salt(pool, &salt).await?;
            salt
        }
    };
    // Derive master key
    print!("Deriving master key (Argon2id, this takes a moment)... ");
    let master_key = crypto::derive_master_key(&password, &salt)?;
    println!("done.");
    // Store in OS Keychain
    crypto::store_master_key(&master_key)?;
    // Self-test: encrypt and decrypt a canary value
    let canary = b"secrets-cli-canary";
    let enc = crypto::encrypt(&master_key, canary)?;
    let dec = crypto::decrypt(&master_key, &enc)?;
    if dec != canary {
        anyhow::bail!("Self-test failed: encryption roundtrip mismatch");
    }
    println!();
    println!("Master key stored in OS Keychain.");
    println!("You can now use `secrets add` / `secrets search` commands.");
    println!();
    println!("IMPORTANT: Remember your master password — it is not stored anywhere.");
    println!("           On a new device, run `secrets init` with the same password.");
    Ok(())
 }
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -1,4 +1,8 @@
 pub mod add;
 pub mod config;
 pub mod delete;
 pub mod init;
 pub mod rollback;
 pub mod run;
 pub mod search;
 pub mod update;
--- a/src/commands/rollback.rs
+++ b/src/commands/rollback.rs
@@ -0,0 +1,245 @@
 use anyhow::Result;
 use serde_json::{Value, json};
 use sqlx::{FromRow, PgPool};
 use uuid::Uuid;
 use crate::output::OutputMode;
 #[derive(FromRow)]
 struct HistoryRow {
    secret_id: Uuid,
    #[allow(dead_code)]
    namespace: String,
    #[allow(dead_code)]
    kind: String,
    #[allow(dead_code)]
    name: String,
    version: i64,
    action: String,
    tags: Vec<String>,
    metadata: Value,
    encrypted: Vec<u8>,
 }
 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.
    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 {
        sqlx::query_as(
            "SELECT secret_id, namespace, kind, name, version, action, tags, metadata, encrypted \
             FROM secrets_history \
             WHERE namespace = $1 AND kind = $2 AND name = $3 AND version = $4 \
             ORDER BY id DESC LIMIT 1",
        )
        .bind(args.namespace)
        .bind(args.kind)
        .bind(args.name)
        .bind(ver)
        .fetch_optional(pool)
        .await?
    } else {
        sqlx::query_as(
            "SELECT secret_id, namespace, kind, name, version, action, tags, metadata, encrypted \
             FROM secrets_history \
             WHERE namespace = $1 AND kind = $2 AND name = $3 \
             ORDER BY id DESC LIMIT 1",
        )
        .bind(args.namespace)
        .bind(args.kind)
        .bind(args.name)
        .fetch_optional(pool)
        .await?
    };
    let snap = snap.ok_or_else(|| {
        anyhow::anyhow!(
            "No history found for [{}/{}] {}{}.",
            args.namespace,
            args.kind,
            args.name,
            args.to_version
                .map(|v| format!(" at version {}", v))
                .unwrap_or_default()
        )
    })?;
    // 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)?;
    }
    let mut tx = pool.begin().await?;
    // Snapshot current live row (if it exists) before overwriting.
    #[derive(sqlx::FromRow)]
    struct LiveRow {
        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 \
         WHERE namespace = $1 AND kind = $2 AND name = $3 FOR UPDATE",
    )
    .bind(args.namespace)
    .bind(args.kind)
    .bind(args.name)
    .fetch_optional(&mut *tx)
    .await?;
    if let Some(lr) = live
        && let Err(e) = crate::db::snapshot_history(
            &mut tx,
            crate::db::SnapshotParams {
                secret_id: lr.id,
                namespace: args.namespace,
                kind: args.kind,
                name: args.name,
                version: lr.version,
                action: "rollback",
                tags: &lr.tags,
                metadata: &lr.metadata,
                encrypted: &lr.encrypted,
            },
        )
        .await
    {
        tracing::warn!(error = %e, "failed to snapshot current row before rollback");
    }
    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()) \
         ON CONFLICT (namespace, kind, name) DO UPDATE SET \
             tags       = EXCLUDED.tags, \
             metadata   = EXCLUDED.metadata, \
             encrypted  = EXCLUDED.encrypted, \
             version    = secrets.version + 1, \
             updated_at = NOW()",
    )
    .bind(snap.secret_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?;
    crate::audit::log_tx(
        &mut tx,
        "rollback",
        args.namespace,
        args.kind,
        args.name,
        json!({
            "restored_version": snap.version,
            "original_action": snap.action,
        }),
    )
    .await;
    tx.commit().await?;
    let result_json = json!({
        "action": "rolled_back",
        "namespace": args.namespace,
        "kind": args.kind,
        "name": args.name,
        "restored_version": snap.version,
    });
    match args.output {
        OutputMode::Json => println!("{}", serde_json::to_string_pretty(&result_json)?),
        OutputMode::JsonCompact => println!("{}", serde_json::to_string(&result_json)?),
        _ => 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,
                    r.created_at.format("%Y-%m-%d %H:%M:%S UTC")
                );
            }
            println!("  (use `secrets rollback --to-version <N>` to restore)");
        }
    }
    Ok(())
 }
--- a/src/commands/run.rs
+++ b/src/commands/run.rs
@@ -0,0 +1,143 @@
 use anyhow::Result;
 use serde_json::Value;
 use sqlx::PgPool;
 use std::collections::HashMap;
 use crate::commands::search::build_env_map;
 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 prefix: &'a str,
    /// The command and its arguments to execute with injected secrets.
    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(
    pool: &PgPool,
    namespace: Option<&str>,
    kind: Option<&str>,
    name: Option<&str>,
    tags: &[String],
    prefix: &str,
    master_key: &[u8; 32],
 ) -> Result<HashMap<String, String>> {
    if namespace.is_none() && kind.is_none() && name.is_none() && tags.is_empty() {
        anyhow::bail!(
            "At least one filter (--namespace, --kind, --name, or --tag) is required for inject/run"
        );
    }
    let rows = crate::commands::search::fetch_rows(pool, namespace, kind, name, tags, None).await?;
    if rows.is_empty() {
        anyhow::bail!("No records matched the given filters.");
    }
    let mut map = HashMap::new();
    for row in &rows {
        let row_map = build_env_map(row, prefix, Some(master_key))?;
        for (k, v) in row_map {
            map.insert(k, v);
        }
    }
    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));
            }
        }
    }
    Ok(())
 }
 /// `run` command: inject secrets into a child process environment and execute.
 pub async fn run_exec(pool: &PgPool, args: RunArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
    if 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?;
    tracing::debug!(
        vars = env_map.len(),
        cmd = args.command[0].as_str(),
        "injecting secrets into child process"
    );
    let status = std::process::Command::new(&args.command[0])
        .args(&args.command[1..])
        .envs(&env_map)
        .status()
        .map_err(|e| anyhow::anyhow!("Failed to execute '{}': {}", args.command[0], e))?;
    if !status.success() {
        let code = status.code().unwrap_or(1);
        std::process::exit(code);
    }
    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('\'', "'\\''"))
 }
--- a/src/commands/search.rs
+++ b/src/commands/search.rs
@@ -1,36 +1,172 @@
 use anyhow::Result;
 use serde_json::{Value, json};
 use sqlx::PgPool;
 use std::collections::HashMap;
 use crate::crypto;
 use crate::models::Secret;
 use crate::output::OutputMode;
-pub async fn run(
+pub struct SearchArgs<'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>,
    pub show_secrets: bool,
    pub fields: &'a [String],
    pub summary: bool,
    pub limit: u32,
    pub offset: u32,
    pub sort: &'a str,
    pub output: OutputMode,
 }
 pub async fn run(pool: &PgPool, args: SearchArgs<'_>, master_key: Option<&[u8; 32]>) -> Result<()> {
    let rows = fetch_rows_paged(
        pool,
        PagedFetchArgs {
            namespace: args.namespace,
            kind: args.kind,
            name: args.name,
            tags: args.tags,
            query: args.query,
            sort: args.sort,
            limit: args.limit,
            offset: args.offset,
        },
    )
    .await?;
    // -f/--field: extract specific field values directly
    if !args.fields.is_empty() {
        return print_fields(&rows, args.fields, master_key);
    }
    match args.output {
        OutputMode::Json | OutputMode::JsonCompact => {
            let arr: Vec<Value> = rows
                .iter()
                .map(|r| to_json(r, args.show_secrets, args.summary, master_key))
                .collect();
            let out = if args.output == OutputMode::Json {
                serde_json::to_string_pretty(&arr)?
            } else {
                serde_json::to_string(&arr)?
            };
            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_env_map(row, "", master_key)?;
                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.show_secrets, args.summary, master_key)?;
            }
            println!("{} record(s) found.", rows.len());
            if rows.len() == args.limit as usize {
                println!(
                    "  (showing up to {}; use --offset {} to see more)",
                    args.limit,
                    args.offset + args.limit
                );
            }
        }
    }
    Ok(())
 }
 /// 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>,
-    tag: Option<&str>,
+    name: Option<&str>,
    tags: &[String],
    query: Option<&str>,
-    show_secrets: bool,
+) -> Result<Vec<Secret>> {
-) -> Result<()> {
+    fetch_rows_paged(
        pool,
        PagedFetchArgs {
            namespace,
            kind,
            name,
            tags,
            query,
            sort: "name",
            limit: 200,
            offset: 0,
        },
    )
    .await
 }
 /// Arguments for the internal paged fetch. Grouped to avoid too-many-arguments lint.
 struct PagedFetchArgs<'a> {
    namespace: Option<&'a str>,
    kind: Option<&'a str>,
    name: Option<&'a str>,
    tags: &'a [String],
    query: Option<&'a str>,
    sort: &'a str,
    limit: u32,
    offset: u32,
 }
 async fn fetch_rows_paged(pool: &PgPool, a: PagedFetchArgs<'_>) -> Result<Vec<Secret>> {
    let mut conditions: Vec<String> = Vec::new();
    let mut idx: i32 = 1;
-    if namespace.is_some() {
+    if a.namespace.is_some() {
        conditions.push(format!("namespace = ${}", idx));
        idx += 1;
    }
-    if kind.is_some() {
+    if a.kind.is_some() {
        conditions.push(format!("kind = ${}", idx));
        idx += 1;
    }
-    if tag.is_some() {
+    if a.name.is_some() {
-        conditions.push(format!("tags @> ARRAY[${}]", idx));
+        conditions.push(format!("name = ${}", idx));
        idx += 1;
    }
-    if query.is_some() {
+    if !a.tags.is_empty() {
        let placeholders: Vec<String> = a
            .tags
            .iter()
            .map(|_| {
                let p = format!("${}", idx);
                idx += 1;
                p
            })
            .collect();
        conditions.push(format!("tags @> ARRAY[{}]", placeholders.join(", ")));
    }
    if a.query.is_some() {
        conditions.push(format!(
-            "(name ILIKE ${i} OR namespace ILIKE ${i} OR kind ILIKE ${i} OR metadata::text ILIKE ${i} OR EXISTS (SELECT 1 FROM unnest(tags) t WHERE t ILIKE ${i}))",
+            "(name ILIKE ${i} ESCAPE '\\' OR namespace ILIKE ${i} ESCAPE '\\' OR kind ILIKE ${i} ESCAPE '\\' OR metadata::text ILIKE ${i} ESCAPE '\\' OR EXISTS (SELECT 1 FROM unnest(tags) t WHERE t ILIKE ${i} ESCAPE '\\'))",
            i = idx
        ));
        idx += 1;
    }
    let where_clause = if conditions.is_empty() {
@@ -39,72 +175,277 @@ pub async fn run(
        format!("WHERE {}", conditions.join(" AND "))
    };
    let order = match a.sort {
        "updated" => "updated_at DESC",
        "created" => "created_at DESC",
        _ => "namespace, kind, name",
    };
    let sql = format!(
-        "SELECT * FROM secrets {} ORDER BY namespace, kind, name",
+        "SELECT * FROM secrets {} ORDER BY {} LIMIT ${} OFFSET ${}",
-        where_clause
+        where_clause,
        order,
        idx,
        idx + 1
    );
    tracing::debug!(sql, "executing search query");
    let mut q = sqlx::query_as::<_, Secret>(&sql);
-    if let Some(v) = namespace {
+    if let Some(v) = a.namespace {
        q = q.bind(v);
    }
-    if let Some(v) = kind {
+    if let Some(v) = a.kind {
        q = q.bind(v);
    }
-    if let Some(v) = tag {
+    if let Some(v) = a.name {
        q = q.bind(v);
    }
-    if let Some(v) = query {
+    for v in a.tags {
-        q = q.bind(format!("%{}%", v));
+        q = q.bind(v.as_str());
    }
    if let Some(v) = a.query {
        q = q.bind(format!(
            "%{}%",
            v.replace('\\', "\\\\")
                .replace('%', "\\%")
                .replace('_', "\\_")
        ));
    }
    q = q.bind(a.limit as i64).bind(a.offset as i64);
    let rows = q.fetch_all(pool).await?;
    Ok(rows)
 }
-    if rows.is_empty() {
+/// Build a flat `KEY=VALUE` map from a record's metadata and decrypted secrets.
-        println!("No records found.");
+/// Variable names: `<PREFIX><NAME>_<FIELD>` (all uppercased, hyphens/dots → underscores).
-        return Ok(());
+/// If `prefix` is empty, the name segment alone is used as the prefix.
 pub fn build_env_map(
    row: &Secret,
    prefix: &str,
    master_key: Option<&[u8; 32]>,
 ) -> Result<HashMap<String, String>> {
    let name_part = row.name.to_uppercase().replace(['-', '.', ' '], "_");
    let effective_prefix = if prefix.is_empty() {
        name_part
    } else {
        format!(
            "{}_{}",
            prefix.to_uppercase().replace(['-', '.', ' '], "_"),
            name_part
        )
    };
    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));
        }
    }
-    for row in &rows {
+    if let Some(master_key) = master_key
-        println!("[{}/{}] {}", row.namespace, row.kind, row.name,);
+        && !row.encrypted.is_empty()
-        println!("  id:       {}", row.id);
+    {
        let decrypted = crypto::decrypt_json(master_key, &row.encrypted)?;
        if let Some(enc) = decrypted.as_object() {
            for (k, v) in enc {
                let key = format!(
                    "{}_{}",
                    effective_prefix,
                    k.to_uppercase().replace(['-', '.'], "_")
                );
                map.insert(key, json_value_to_env_string(v));
            }
        }
    }
    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(),
        Value::Null => String::new(),
        other => other.to_string(),
    }
 }
 /// Decrypt the encrypted blob for a row. Returns an empty object on empty blobs.
 fn try_decrypt(row: &Secret, master_key: Option<&[u8; 32]>) -> Result<Value> {
    if row.encrypted.is_empty() {
        return Ok(Value::Object(Default::default()));
    }
    let key = master_key.ok_or_else(|| {
        anyhow::anyhow!("master key required to decrypt secrets (run `secrets init`)")
    })?;
    crypto::decrypt_json(key, &row.encrypted)
 }
 fn to_json(
    row: &Secret,
    show_secrets: bool,
    summary: bool,
    master_key: Option<&[u8; 32]>,
 ) -> Value {
    if summary {
        let desc = row
            .metadata
            .get("desc")
            .or_else(|| row.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,
            "desc": desc,
            "updated_at": row.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
        });
    }
    let secrets_val = if show_secrets {
        match try_decrypt(row, master_key) {
            Ok(v) => v,
            Err(e) => json!({"_error": e.to_string()}),
        }
    } else {
        json!({"_encrypted": true})
    };
    json!({
        "id": row.id,
        "namespace": row.namespace,
        "kind": row.kind,
        "name": row.name,
        "tags": row.tags,
        "metadata": row.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(),
    })
 }
 fn print_text(
    row: &Secret,
    show_secrets: bool,
    summary: bool,
    master_key: Option<&[u8; 32]>,
 ) -> Result<()> {
    println!("[{}/{}] {}", row.namespace, row.kind, row.name);
    if summary {
        let desc = row
            .metadata
            .get("desc")
            .or_else(|| row.metadata.get("url"))
            .and_then(|v| v.as_str())
            .unwrap_or("-");
        if !row.tags.is_empty() {
            println!("  tags:    [{}]", row.tags.join(", "));
        }
        println!("  desc:    {}", desc);
        println!(
            "  updated: {}",
            row.updated_at.format("%Y-%m-%d %H:%M:%S UTC")
        );
    } else {
        println!("  id:       {}", row.id);
        if !row.tags.is_empty() {
            println!("  tags:     [{}]", row.tags.join(", "));
        }
        if row.metadata.as_object().is_some_and(|m| !m.is_empty()) {
            println!(
                "  metadata: {}",
                serde_json::to_string_pretty(&row.metadata)?
            );
        }
-
+        if !row.encrypted.is_empty() {
-        if show_secrets {
+            if show_secrets {
-            println!(
+                match try_decrypt(row, master_key) {
-                "  secrets:  {}",
+                    Ok(v) => println!("  secrets:  {}", serde_json::to_string_pretty(&v)?),
-                serde_json::to_string_pretty(&row.encrypted)?
+                    Err(e) => println!("  secrets:  [decrypt error: {}]", e),
-            );
+                }
-        } else {
+            } else {
-            let keys: Vec<String> = row
+                println!("  secrets:  [encrypted]  (--show-secrets to reveal)");
                .encrypted
                .as_object()
                .map(|m| m.keys().cloned().collect())
                .unwrap_or_default();
            if !keys.is_empty() {
                println!(
                    "  secrets:  [{}]  (--show-secrets to reveal)",
                    keys.join(", ")
                );
            }
        }
        println!(
            "  created:  {}",
            row.created_at.format("%Y-%m-%d %H:%M:%S UTC")
        );
        println!();
    }
-    println!("{} record(s) found.", rows.len());
+    println!();
    Ok(())
 }
 /// Extract one or more field paths like `metadata.url` or `secret.token`.
 fn print_fields(rows: &[Secret], fields: &[String], master_key: Option<&[u8; 32]>) -> Result<()> {
    for row in rows {
        let decrypted: Option<Value> = if fields
            .iter()
            .any(|f| f.starts_with("secret") || f.starts_with("encrypted"))
        {
            Some(try_decrypt(row, master_key)?)
        } else {
            None
        };
        for field in fields {
            let val = extract_field(row, field, decrypted.as_ref())?;
            println!("{}", val);
        }
    }
    Ok(())
 }
 fn extract_field(row: &Secret, field: &str, decrypted: Option<&Value>) -> Result<String> {
    let (section, key) = field.split_once('.').ok_or_else(|| {
        anyhow::anyhow!(
            "Invalid field path '{}'. Use metadata.<key> or secret.<key>",
            field
        )
    })?;
    let obj = match section {
        "metadata" | "meta" => &row.metadata,
        "secret" | "secrets" | "encrypted" => {
            decrypted.ok_or_else(|| anyhow::anyhow!("secret field requires master key"))?
        }
        other => anyhow::bail!(
            "Unknown field section '{}'. Use 'metadata' or 'secret'",
            other
        ),
    };
    obj.get(key)
        .and_then(|v| {
            v.as_str()
                .map(|s| s.to_string())
                .or_else(|| Some(v.to_string()))
        })
        .ok_or_else(|| {
            anyhow::anyhow!(
                "Field '{}' not found in record [{}/{}/{}]",
                field,
                row.namespace,
                row.kind,
                row.name
            )
        })
 }
--- a/src/commands/update.rs
+++ b/src/commands/update.rs
@@ -1,8 +1,21 @@
 use anyhow::Result;
-use serde_json::{Map, Value};
+use serde_json::{Map, Value, json};
-use sqlx::PgPool;
+use sqlx::{FromRow, PgPool};
 use uuid::Uuid;
 use super::add::parse_kv;
 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>,
 }
 pub struct UpdateArgs<'a> {
    pub namespace: &'a str,
@@ -14,20 +27,22 @@ pub struct UpdateArgs<'a> {
    pub remove_meta: &'a [String],
    pub secret_entries: &'a [String],
    pub remove_secrets: &'a [String],
    pub output: OutputMode,
 }
-pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
+pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
-    let row = sqlx::query!(
+    let mut tx = pool.begin().await?;
-        r#"
+
-        SELECT id, tags, metadata, encrypted
+    let row: Option<UpdateRow> = sqlx::query_as(
-        FROM secrets
+        "SELECT id, version, tags, metadata, encrypted \
-        WHERE namespace = $1 AND kind = $2 AND name = $3
+         FROM secrets \
-        "#,
+         WHERE namespace = $1 AND kind = $2 AND name = $3 \
-        args.namespace,
+         FOR UPDATE",
        args.kind,
        args.name,
    )
-    .fetch_optional(pool)
+    .bind(args.namespace)
    .bind(args.kind)
    .bind(args.name)
    .fetch_optional(&mut *tx)
    .await?;
    let row = row.ok_or_else(|| {
@@ -39,6 +54,26 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
        )
    })?;
    // Snapshot current state before modifying.
    if let Err(e) = db::snapshot_history(
        &mut tx,
        db::SnapshotParams {
            secret_id: row.id,
            namespace: args.namespace,
            kind: args.kind,
            name: args.name,
            version: row.version,
            action: "update",
            tags: &row.tags,
            metadata: &row.metadata,
            encrypted: &row.encrypted,
        },
    )
    .await
    {
        tracing::warn!(error = %e, "failed to snapshot history before update");
    }
    // Merge tags
    let mut tags: Vec<String> = row.tags;
    for t in args.add_tags {
@@ -55,70 +90,135 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
    };
    for entry in args.meta_entries {
        let (key, value) = parse_kv(entry)?;
-        meta_map.insert(key, Value::String(value));
+        meta_map.insert(key, value);
    }
    for key in args.remove_meta {
        meta_map.remove(key);
    }
    let metadata = Value::Object(meta_map);
-    // Merge encrypted
+    // Decrypt existing encrypted blob, merge changes, re-encrypt
-    let mut enc_map: Map<String, Value> = match row.encrypted {
+    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 (key, value) = parse_kv(entry)?;
-        enc_map.insert(key, Value::String(value));
+        enc_map.insert(key, value);
    }
    for key in args.remove_secrets {
        enc_map.remove(key);
    }
-    let encrypted = Value::Object(enc_map);
+    let secret_json = Value::Object(enc_map);
    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
-    sqlx::query!(
+    tracing::debug!(
-        r#"
+        namespace = args.namespace,
-        UPDATE secrets
+        kind = args.kind,
-        SET tags = $1, metadata = $2, encrypted = $3, updated_at = NOW()
+        name = args.name,
-        WHERE id = $4
+        "updating record"
-        "#,
+    );
-        &tags,
+
-        metadata,
+    // CAS: update only if version hasn't changed (FOR UPDATE lock ensures this).
-        encrypted,
+    let result = sqlx::query(
-        row.id,
+        "UPDATE secrets \
         SET tags = $1, metadata = $2, encrypted = $3, version = version + 1, updated_at = NOW() \
         WHERE id = $4 AND version = $5",
    )
-    .execute(pool)
+    .bind(&tags)
    .bind(&metadata)
    .bind(&encrypted_bytes)
    .bind(row.id)
    .bind(row.version)
    .execute(&mut *tx)
    .await?;
-    println!("Updated: [{}/{}] {}", args.namespace, args.kind, args.name);
+    if result.rows_affected() == 0 {
        tx.rollback().await?;
        anyhow::bail!(
            "Concurrent modification detected for [{}/{}] {}. Please retry.",
            args.namespace,
            args.kind,
            args.name
        );
    }
-    if !args.add_tags.is_empty() {
+    let meta_keys: Vec<&str> = args
-        println!("  +tags:     {}", args.add_tags.join(", "));
+        .meta_entries
-    }
+        .iter()
-    if !args.remove_tags.is_empty() {
+        .filter_map(|s| s.split_once(['=', ':']).map(|(k, _)| k))
-        println!("  -tags:     {}", args.remove_tags.join(", "));
+        .collect();
-    }
+    let secret_keys: Vec<&str> = args
-    if !args.meta_entries.is_empty() {
+        .secret_entries
-        let keys: Vec<&str> = args
+        .iter()
-            .meta_entries
+        .filter_map(|s| s.split_once(['=', ':']).map(|(k, _)| k))
-            .iter()
+        .collect();
-            .filter_map(|s| s.split_once('=').map(|(k, _)| k))
+
-            .collect();
+    crate::audit::log_tx(
-        println!("  +metadata: {}", keys.join(", "));
+        &mut tx,
-    }
+        "update",
-    if !args.remove_meta.is_empty() {
+        args.namespace,
-        println!("  -metadata: {}", args.remove_meta.join(", "));
+        args.kind,
-    }
+        args.name,
-    if !args.secret_entries.is_empty() {
+        json!({
-        let keys: Vec<&str> = args
+            "add_tags": args.add_tags,
-            .secret_entries
+            "remove_tags": args.remove_tags,
-            .iter()
+            "meta_keys": meta_keys,
-            .filter_map(|s| s.split_once('=').map(|(k, _)| k))
+            "remove_meta": args.remove_meta,
-            .collect();
+            "secret_keys": secret_keys,
-        println!("  +secrets:  {}", keys.join(", "));
+            "remove_secrets": args.remove_secrets,
-    }
+        }),
-    if !args.remove_secrets.is_empty() {
+    )
-        println!("  -secrets:  {}", args.remove_secrets.join(", "));
+    .await;
    tx.commit().await?;
    let result_json = json!({
        "action": "updated",
        "namespace": args.namespace,
        "kind": args.kind,
        "name": args.name,
        "add_tags": args.add_tags,
        "remove_tags": args.remove_tags,
        "meta_keys": meta_keys,
        "remove_meta": args.remove_meta,
        "secret_keys": secret_keys,
        "remove_secrets": args.remove_secrets,
    });
    match args.output {
        OutputMode::Json => {
            println!("{}", serde_json::to_string_pretty(&result_json)?);
        }
        OutputMode::JsonCompact => {
            println!("{}", serde_json::to_string(&result_json)?);
        }
        _ => {
            println!("Updated: [{}/{}] {}", args.namespace, args.kind, args.name);
            if !args.add_tags.is_empty() {
                println!("  +tags:     {}", args.add_tags.join(", "));
            }
            if !args.remove_tags.is_empty() {
                println!("  -tags:     {}", args.remove_tags.join(", "));
            }
            if !args.meta_entries.is_empty() {
                println!("  +metadata: {}", meta_keys.join(", "));
            }
            if !args.remove_meta.is_empty() {
                println!("  -metadata: {}", args.remove_meta.join(", "));
            }
            if !args.secret_entries.is_empty() {
                println!("  +secrets:  {}", secret_keys.join(", "));
            }
            if !args.remove_secrets.is_empty() {
                println!("  -secrets:  {}", args.remove_secrets.join(", "));
            }
        }
    }
    Ok(())
--- a/src/config.rs
+++ b/src/config.rs
@@ -0,0 +1,73 @@
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::PathBuf;
 #[derive(Debug, Serialize, Deserialize, Default)]
 pub struct Config {
    pub database_url: Option<String>,
 }
 pub fn config_dir() -> PathBuf {
    dirs::config_dir()
        .or_else(|| dirs::home_dir().map(|h| h.join(".config")))
        .unwrap_or_else(|| PathBuf::from(".config"))
        .join("secrets")
 }
 pub fn config_path() -> PathBuf {
    config_dir().join("config.toml")
 }
 pub fn load_config() -> Result<Config> {
    let path = config_path();
    if !path.exists() {
        return Ok(Config::default());
    }
    let content = fs::read_to_string(&path)
        .with_context(|| format!("failed to read config file: {}", path.display()))?;
    let config: Config = toml::from_str(&content)
        .with_context(|| format!("failed to parse config file: {}", path.display()))?;
    Ok(config)
 }
 pub fn save_config(config: &Config) -> Result<()> {
    let dir = config_dir();
    fs::create_dir_all(&dir)
        .with_context(|| format!("failed to create config dir: {}", dir.display()))?;
    let path = config_path();
    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()))?;
    // Set file permissions to 0600 (owner read/write only)
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let perms = fs::Permissions::from_mode(0o600);
        fs::set_permissions(&path, perms)
            .with_context(|| format!("failed to set file permissions: {}", path.display()))?;
    }
    Ok(())
 }
 /// Resolve database URL by priority:
 /// 1. --db-url CLI flag (if non-empty)
 /// 2. database_url in ~/.config/secrets/config.toml
 /// 3. Error with setup instructions
 pub fn resolve_db_url(cli_db_url: &str) -> Result<String> {
    if !cli_db_url.is_empty() {
        return Ok(cli_db_url.to_string());
    }
    let config = load_config()?;
    if let Some(url) = config.database_url
        && !url.is_empty()
    {
        return Ok(url);
    }
    anyhow::bail!("Database not configured. Run:\n\n    secrets config set-db <DATABASE_URL>\n")
 }
--- a/src/crypto.rs
+++ b/src/crypto.rs
@@ -0,0 +1,192 @@
 use aes_gcm::{
    Aes256Gcm, Key, Nonce,
    aead::{Aead, AeadCore, KeyInit, OsRng},
 };
 use anyhow::{Context, Result, bail};
 use argon2::{Argon2, Params, Version};
 use serde_json::Value;
 const KEYRING_SERVICE: &str = "secrets-cli";
 const KEYRING_USER: &str = "master-key";
 const NONCE_LEN: usize = 12;
 // ─── 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 argon2 = Argon2::new(argon2::Algorithm::Argon2id, Version::V0x13, params);
    let mut key = [0u8; 32];
    argon2
        .hash_password_into(password.as_bytes(), salt, &mut key)
        .map_err(|e| anyhow::anyhow!("Argon2id derivation failed: {}", e))?;
    Ok(key)
 }
 // ─── AES-256-GCM encrypt / decrypt ───────────────────────────────────────────
 /// Encrypt plaintext bytes with AES-256-GCM.
 /// Returns `nonce (12 B) || ciphertext+tag`.
 pub fn encrypt(master_key: &[u8; 32], plaintext: &[u8]) -> Result<Vec<u8>> {
    let key = Key::<Aes256Gcm>::from_slice(master_key);
    let cipher = Aes256Gcm::new(key);
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
    let ciphertext = cipher
        .encrypt(&nonce, plaintext)
        .map_err(|e| anyhow::anyhow!("AES-256-GCM encryption failed: {}", e))?;
    let mut out = Vec::with_capacity(NONCE_LEN + ciphertext.len());
    out.extend_from_slice(&nonce);
    out.extend_from_slice(&ciphertext);
    Ok(out)
 }
 /// Decrypt `nonce (12 B) || ciphertext+tag` with AES-256-GCM.
 pub fn decrypt(master_key: &[u8; 32], data: &[u8]) -> Result<Vec<u8>> {
    if data.len() < NONCE_LEN {
        bail!(
            "encrypted data too short ({}B); possibly corrupted",
            data.len()
        );
    }
    let (nonce_bytes, ciphertext) = data.split_at(NONCE_LEN);
    let key = Key::<Aes256Gcm>::from_slice(master_key);
    let cipher = Aes256Gcm::new(key);
    let nonce = Nonce::from_slice(nonce_bytes);
    cipher
        .decrypt(nonce, ciphertext)
        .map_err(|_| anyhow::anyhow!("decryption failed — wrong master key or corrupted data"))
 }
 // ─── JSON helpers ─────────────────────────────────────────────────────────────
 /// Serialize a JSON Value and encrypt it. Returns the encrypted blob.
 pub fn encrypt_json(master_key: &[u8; 32], value: &Value) -> Result<Vec<u8>> {
    let bytes = serde_json::to_vec(value).context("serialize JSON for encryption")?;
    encrypt(master_key, &bytes)
 }
 /// Decrypt an encrypted blob and deserialize it as a JSON Value.
 pub fn decrypt_json(master_key: &[u8; 32], data: &[u8]) -> Result<Value> {
    let bytes = decrypt(master_key, data)?;
    serde_json::from_slice(&bytes).context("deserialize decrypted JSON")
 }
 // ─── OS Keychain ──────────────────────────────────────────────────────────────
 /// Load the Master Key from the OS Keychain.
 /// Returns an error with a helpful message if it hasn't been initialized.
 pub fn load_master_key() -> Result<[u8; 32]> {
    let entry =
        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
    let hex = entry.get_password().map_err(|_| {
        anyhow::anyhow!("Master key not found in keychain. Run `secrets init` first.")
    })?;
    let bytes = hex::decode_hex(&hex)?;
    if bytes.len() != 32 {
        bail!(
            "stored master key has unexpected length {}; re-run `secrets init`",
            bytes.len()
        );
    }
    let mut key = [0u8; 32];
    key.copy_from_slice(&bytes);
    Ok(key)
 }
 /// Store the Master Key in the OS Keychain (overwrites any existing value).
 pub fn store_master_key(key: &[u8; 32]) -> Result<()> {
    let entry =
        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
    let hex = hex::encode_hex(key);
    entry
        .set_password(&hex)
        .map_err(|e| anyhow::anyhow!("keychain write failed: {}", e))?;
    Ok(())
 }
 /// Delete the Master Key from the OS Keychain (used by tests / reset).
 #[cfg(test)]
 pub fn delete_master_key() -> Result<()> {
    let entry =
        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
    let _ = entry.delete_credential();
    Ok(())
 }
 // ─── Minimal hex helpers (avoid extra dep) ────────────────────────────────────
 mod hex {
    use anyhow::{Result, bail};
    pub fn encode_hex(bytes: &[u8]) -> String {
        bytes.iter().map(|b| format!("{:02x}", b)).collect()
    }
    pub fn decode_hex(s: &str) -> Result<Vec<u8>> {
        if !s.len().is_multiple_of(2) {
            bail!("hex string has odd length");
        }
        (0..s.len())
            .step_by(2)
            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).map_err(|e| anyhow::anyhow!("{}", e)))
            .collect()
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn roundtrip_encrypt_decrypt() {
        let key = [0x42u8; 32];
        let plaintext = b"hello world";
        let enc = encrypt(&key, plaintext).unwrap();
        let dec = decrypt(&key, &enc).unwrap();
        assert_eq!(dec, plaintext);
    }
    #[test]
    fn encrypt_produces_different_ciphertexts() {
        let key = [0x42u8; 32];
        let plaintext = b"hello world";
        let enc1 = encrypt(&key, plaintext).unwrap();
        let enc2 = encrypt(&key, plaintext).unwrap();
        // Different nonces → different ciphertexts
        assert_ne!(enc1, enc2);
    }
    #[test]
    fn wrong_key_fails_decryption() {
        let key1 = [0x42u8; 32];
        let key2 = [0x43u8; 32];
        let enc = encrypt(&key1, b"secret").unwrap();
        assert!(decrypt(&key2, &enc).is_err());
    }
    #[test]
    fn json_roundtrip() {
        let key = [0x42u8; 32];
        let value = serde_json::json!({"token": "abc123", "password": "hunter2"});
        let enc = encrypt_json(&key, &value).unwrap();
        let dec = decrypt_json(&key, &enc).unwrap();
        assert_eq!(dec, value);
    }
    #[test]
    fn derive_master_key_deterministic() {
        let salt = b"fixed_test_salt_";
        let k1 = derive_master_key("password", salt).unwrap();
        let k2 = derive_master_key("password", salt).unwrap();
        assert_eq!(k1, k2);
    }
    #[test]
    fn derive_master_key_different_passwords() {
        let salt = b"fixed_test_salt_";
        let k1 = derive_master_key("password1", salt).unwrap();
        let k2 = derive_master_key("password2", salt).unwrap();
        assert_ne!(k1, k2);
    }
 }
--- a/src/db.rs
+++ b/src/db.rs
@@ -3,14 +3,18 @@ use sqlx::PgPool;
 use sqlx::postgres::PgPoolOptions;
 pub async fn create_pool(database_url: &str) -> Result<PgPool> {
    tracing::debug!("connecting to database");
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .acquire_timeout(std::time::Duration::from_secs(10))
        .connect(database_url)
        .await?;
    tracing::debug!("database connection established");
    Ok(pool)
 }
 pub async fn migrate(pool: &PgPool) -> Result<()> {
    tracing::debug!("running migrations");
    sqlx::raw_sql(
        r#"
        CREATE TABLE IF NOT EXISTS secrets (
@@ -20,7 +24,8 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
            name        VARCHAR(256) NOT NULL,
            tags        TEXT[]       NOT NULL DEFAULT '{}',
            metadata    JSONB        NOT NULL DEFAULT '{}',
-            encrypted   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)
@@ -32,13 +37,141 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
        EXCEPTION WHEN OTHERS THEN NULL;
        END $$;
        DO $$ BEGIN
            ALTER TABLE secrets ADD COLUMN IF NOT EXISTS version BIGINT NOT NULL DEFAULT 1;
        EXCEPTION WHEN OTHERS THEN NULL;
        END $$;
        -- 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_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)
        CREATE TABLE IF NOT EXISTS kv_config (
            key   TEXT PRIMARY KEY,
            value BYTEA NOT NULL
        );
        CREATE TABLE IF NOT EXISTS audit_log (
            id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
            action      VARCHAR(32)  NOT NULL,
            namespace   VARCHAR(64)  NOT NULL,
            kind        VARCHAR(64)  NOT NULL,
            name        VARCHAR(256) NOT NULL,
            detail      JSONB        NOT NULL DEFAULT '{}',
            actor       VARCHAR(128) NOT NULL DEFAULT '',
            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);
        -- 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 (
            id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
            secret_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,
            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);
        "#,
    )
    .execute(pool)
    .await?;
    tracing::debug!("migrations complete");
    Ok(())
 }
 /// Snapshot parameters grouped to avoid too-many-arguments lint.
 pub struct SnapshotParams<'a> {
    pub secret_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],
 }
 /// 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(
    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
    p: SnapshotParams<'_>,
 ) -> Result<()> {
    let actor = std::env::var("USER").unwrap_or_default();
    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)",
    )
    .bind(p.secret_id)
    .bind(p.namespace)
    .bind(p.kind)
    .bind(p.name)
    .bind(p.version)
    .bind(p.action)
    .bind(p.tags)
    .bind(p.metadata)
    .bind(p.encrypted)
    .bind(&actor)
    .execute(&mut **tx)
    .await?;
    Ok(())
 }
 /// 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'")
            .fetch_optional(pool)
            .await?;
    Ok(row.map(|(v,)| v))
 }
 /// Store the Argon2id salt in the database (only called once on first device init).
 pub async fn store_argon2_salt(pool: &PgPool, salt: &[u8]) -> Result<()> {
    sqlx::query(
        "INSERT INTO kv_config (key, value) VALUES ('argon2_salt', $1) \
         ON CONFLICT (key) DO NOTHING",
    )
    .bind(salt)
    .execute(pool)
    .await?;
    Ok(())
 }
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,94 +1,251 @@
 mod audit;
 mod commands;
 mod config;
 mod crypto;
 mod db;
 mod models;
 mod output;
 use anyhow::Result;
 use clap::{Parser, Subcommand};
-use dotenvy::dotenv;
+use tracing_subscriber::EnvFilter;
 use output::resolve_output_mode;
 #[derive(Parser)]
 #[command(
    name = "secrets",
    version,
-    about = "Secrets & config manager backed by PostgreSQL"
+    about = "Secrets & config manager backed by PostgreSQL — optimised for AI agents",
    after_help = "QUICK START:
  # 1. Configure database (once per device)
  secrets config set-db \"postgres://postgres:<password>@<host>:<port>/secrets\"
  # 2. Initialize master key (once per device)
  secrets init
  # Discover what namespaces / kinds exist
  secrets search --summary --limit 20
  # Precise lookup (JSON output for easy parsing)
  secrets search -n refining --kind service --name gitea -o json --show-secrets
  # Extract a single field value directly
  secrets search -n refining --kind service --name gitea -f secret.token
  # Pipe-friendly (non-TTY defaults to json-compact automatically)
  secrets search -n refining --kind service | jq '.[].name'"
 )]
 struct Cli {
-    /// Database URL (or set DATABASE_URL env var)
+    /// Database URL, overrides saved config (one-time override)
-    #[arg(long, env = "DATABASE_URL", global = true, default_value = "")]
+    #[arg(long, global = true, default_value = "")]
    db_url: String,
    /// Enable verbose debug output
    #[arg(long, short, global = true)]
    verbose: bool,
    #[command(subcommand)]
    command: Commands,
 }
 #[derive(Subcommand)]
 enum Commands {
-    /// Add or update a record (upsert)
+    /// Initialize master key on this device (run once per device).
    ///
    /// Prompts for a master password, derives a key with Argon2id, and stores
    /// it in the OS Keychain. Use the same password on every device.
    ///
    /// NOTE: Run `secrets config set-db <URL>` first if database is not configured.
    #[command(after_help = "PREREQUISITE:
  Database must be configured first. Run: secrets config set-db <DATABASE_URL>
 EXAMPLES:
  # First device: generates a new Argon2id salt and stores master key
  secrets init
  # Subsequent devices: reuses existing salt from the database
  secrets init")]
    Init,
    /// Add or update a record (upsert). Use -m for plaintext metadata, -s for secrets.
    #[command(after_help = "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\" \\
    -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 \\
    -s token=<token>
  # Add with token read from a file
  secrets add -n ricnsmart --kind service --name mqtt \\
    -m host=mqtt.ricnsmart.com -m port=1883 \\
    -s password=@./mqtt_password.txt")]
    Add {
-        /// Namespace (e.g. refining, ricnsmart)
+        /// Namespace, e.g. refining, ricnsmart
        #[arg(short, long)]
        namespace: String,
-        /// Kind of record (server, service, key, ...)
+        /// Kind of record: server, service, key, ...
        #[arg(long)]
        kind: String,
-        /// Human-readable name
+        /// Human-readable unique name, e.g. gitea, i-uf63f2uookgs5uxmrdyc
        #[arg(long)]
        name: String,
-        /// Tags for categorization (repeatable)
+        /// Tag for categorization (repeatable), e.g. --tag aliyun --tag hongkong
        #[arg(long = "tag")]
        tags: Vec<String>,
-        /// Plaintext metadata entry: key=value (repeatable, key=@file reads from file)
+        /// Plaintext metadata: key=value (repeatable; value=@file reads from file)
        #[arg(long = "meta", short = 'm')]
        meta: Vec<String>,
-        /// Secret entry: key=value (repeatable, key=@file reads from file)
+        /// Secret entry: key=value (repeatable; value=@file reads from file)
        #[arg(long = "secret", short = 's')]
        secrets: Vec<String>,
        /// Output format: text (default on TTY), json, json-compact, env
        #[arg(short, long = "output")]
        output: Option<String>,
    },
-    /// Search records
+    /// Search / read records. This is the primary read command for AI agents.
    ///
    /// 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
    /// defaults to json-compact automatically.
    #[command(after_help = "EXAMPLES:
  # Discover all records (summary, safe default limit)
  secrets search --summary --limit 20
  # Filter by namespace and kind
  secrets search -n refining --kind service
  # Exact lookup — returns 0 or 1 record
  secrets search -n refining --kind service --name gitea
  # Fuzzy keyword search (matches name, namespace, kind, tags, metadata)
  secrets search -q mqtt
  # Extract a single field value (implies --show-secrets for secret.*)
  secrets search -n refining --kind service --name gitea -f secret.token
  secrets search -n refining --kind service --name gitea -f metadata.url
  # Multiple fields at once
  secrets search -n refining --kind service --name gitea \\
    -f metadata.url -f metadata.default_org -f secret.token
  # Full JSON output with secrets revealed (ideal for AI parsing)
  secrets search -n refining --kind service --name gitea -o json --show-secrets
  # Export as env vars (source-able; single record only)
  secrets search -n refining --kind service --name gitea -o env --show-secrets
  # Paginate large result sets
  secrets search -n refining --summary --limit 10 --offset 0
  secrets search -n refining --summary --limit 10 --offset 10
  # Sort by most recently updated
  secrets search --sort updated --limit 5 --summary
  # Non-TTY / pipe: output is json-compact by default
  secrets search -n refining --kind service | jq '.[].name'
  secrets search -n refining --kind service --name gitea --show-secrets | jq '.secrets.token'")]
    Search {
-        /// Filter by namespace
+        /// Filter by namespace, e.g. refining, ricnsmart
        #[arg(short, long)]
        namespace: Option<String>,
-        /// Filter by kind
+        /// Filter by kind, e.g. server, service
        #[arg(long)]
        kind: Option<String>,
-        /// Filter by tag
+        /// Exact name filter, e.g. gitea, i-uf63f2uookgs5uxmrdyc
        #[arg(long)]
-        tag: Option<String>,
+        name: Option<String>,
-        /// Search by keyword (matches name, namespace, kind)
+        /// Filter by tag, e.g. --tag aliyun (repeatable for AND intersection)
        #[arg(long)]
        tag: Vec<String>,
        /// Fuzzy keyword (matches name, namespace, kind, tags, metadata text)
        #[arg(short, long)]
        query: Option<String>,
-        /// Reveal encrypted secret values
+        /// Reveal encrypted secret values in output
        #[arg(long)]
        show_secrets: bool,
        /// Extract field value(s) directly: metadata.<key> or secret.<key> (repeatable)
        #[arg(short = 'f', long = "field")]
        fields: Vec<String>,
        /// Return lightweight summary only (namespace, kind, name, tags, desc, updated_at)
        #[arg(long)]
        summary: bool,
        /// Maximum number of records to return [default: 50]
        #[arg(long, default_value = "50")]
        limit: u32,
        /// Skip this many records (for pagination)
        #[arg(long, default_value = "0")]
        offset: u32,
        /// Sort order: name (default), updated, created
        #[arg(long, default_value = "name")]
        sort: String,
        /// Output format: text (default on TTY), json, json-compact, env
        #[arg(short, long = "output")]
        output: Option<String>,
    },
-    /// Delete a record
+    /// Delete a record permanently. Requires exact namespace + kind + name.
    #[command(after_help = "EXAMPLES:
  # Delete a service credential
  secrets delete -n refining --kind service --name legacy-mqtt
  # Delete a server record
  secrets delete -n ricnsmart --kind server --name i-old-server-id")]
    Delete {
-        /// Namespace
+        /// Namespace, e.g. refining
        #[arg(short, long)]
        namespace: String,
-        /// Kind
+        /// Kind, e.g. server, service
        #[arg(long)]
        kind: String,
-        /// Name
+        /// Exact name of the record to delete
        #[arg(long)]
        name: String,
        /// Output format: text (default on TTY), json, json-compact
        #[arg(short, long = "output")]
        output: Option<String>,
    },
-    /// Incrementally update an existing record (merge semantics)
+    /// Incrementally update an existing record (merge semantics; record must exist).
    ///
    /// Only the fields you pass are changed — everything else is preserved.
    /// Use --add-tag / --remove-tag to modify tags without touching other fields.
    #[command(after_help = "EXAMPLES:
  # Update a single metadata field (all other fields unchanged)
  secrets update -n refining --kind server --name my-server -m ip=10.0.0.1
  # Rotate a secret token
  secrets update -n refining --kind service --name gitea -s token=<new-token>
  # Add a tag and rotate password at the same time
  secrets update -n refining --kind service --name gitea \\
    --add-tag production -s token=<new-token>
  # Remove a deprecated metadata field and a stale secret key
  secrets update -n refining --kind service --name mqtt \\
    --remove-meta old_port --remove-secret old_password
  # Remove a tag
  secrets update -n refining --kind service --name gitea --remove-tag staging")]
    Update {
-        /// Namespace (e.g. refining, ricnsmart)
+        /// Namespace, e.g. refining, ricnsmart
        #[arg(short, long)]
        namespace: String,
-        /// Kind of record (server, service, key, ...)
+        /// Kind of record: server, service, key, ...
        #[arg(long)]
        kind: String,
-        /// Human-readable name
+        /// Human-readable unique name
        #[arg(long)]
        name: String,
-        /// Add a tag (repeatable)
+        /// Add a tag (repeatable; does not affect existing tags)
        #[arg(long = "add-tag")]
        add_tags: Vec<String>,
        /// Remove a tag (repeatable)
@@ -97,36 +254,189 @@ enum Commands {
        /// Set or overwrite a metadata field: key=value (repeatable, @file supported)
        #[arg(long = "meta", short = 'm')]
        meta: Vec<String>,
-        /// Remove a metadata field by key (repeatable)
+        /// Delete a metadata field by key (repeatable)
        #[arg(long = "remove-meta")]
        remove_meta: Vec<String>,
        /// Set or overwrite a secret field: key=value (repeatable, @file supported)
        #[arg(long = "secret", short = 's')]
        secrets: Vec<String>,
-        /// Remove a secret field by key (repeatable)
+        /// Delete a secret field by key (repeatable)
        #[arg(long = "remove-secret")]
        remove_secrets: Vec<String>,
        /// Output format: text (default on TTY), json, json-compact
        #[arg(short, long = "output")]
        output: Option<String>,
    },
    /// Manage CLI configuration (database connection, etc.)
    #[command(after_help = "EXAMPLES:
  # Configure the database URL (run once per device; persisted to config file)
  secrets config set-db \"postgres://postgres:<password>@<host>:<port>/secrets\"
  # Show current config (password is masked)
  secrets config show
  # Print path to the config file
  secrets config path")]
    Config {
        #[command(subcommand)]
        action: ConfigAction,
    },
    /// Show the change history for a record.
    #[command(after_help = "EXAMPLES:
  # Show last 20 versions for a service record
  secrets history -n refining --kind service --name gitea
  # Show last 5 versions
  secrets history -n refining --kind service --name gitea --limit 5")]
    History {
        #[arg(short, long)]
        namespace: String,
        #[arg(long)]
        kind: String,
        #[arg(long)]
        name: String,
        /// Number of history entries to show [default: 20]
        #[arg(long, default_value = "20")]
        limit: u32,
        /// Output format: text (default on TTY), json, json-compact
        #[arg(short, long = "output")]
        output: Option<String>,
    },
    /// Roll back a record to a previous version.
    #[command(after_help = "EXAMPLES:
  # Roll back to the most recent snapshot (undo last change)
  secrets rollback -n refining --kind service --name gitea
  # Roll back to a specific version number
  secrets rollback -n refining --kind service --name gitea --to-version 3")]
    Rollback {
        #[arg(short, long)]
        namespace: String,
        #[arg(long)]
        kind: String,
        #[arg(long)]
        name: String,
        /// Target version to restore. Omit to restore the most recent snapshot.
        #[arg(long)]
        to_version: Option<i64>,
        /// Output format: text (default on TTY), json, json-compact
        #[arg(short, long = "output")]
        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.
    #[command(after_help = "EXAMPLES:
  # Run a script with a single service's secrets injected
  secrets run -n refining --kind service --name gitea -- ./deploy.sh
  # 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")]
    Run {
        #[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,
        /// Command and arguments to execute with injected environment
        #[arg(last = true, required = true)]
        command: Vec<String>,
    },
 }
 #[derive(Subcommand)]
 enum ConfigAction {
    /// Save database URL to config file (~/.config/secrets/config.toml)
    SetDb {
        /// PostgreSQL connection string, e.g. postgres://user:pass@<host>:<port>/dbname
        url: String,
    },
    /// Show current configuration (password masked)
    Show,
    /// Print path to the config file
    Path,
 }
 #[tokio::main]
 async fn main() -> Result<()> {
    dotenv().ok();
    let cli = Cli::parse();
-    let db_url = if cli.db_url.is_empty() {
+    let filter = if cli.verbose {
-        std::env::var("DATABASE_URL").map_err(|_| {
+        EnvFilter::new("secrets=debug")
            anyhow::anyhow!("DATABASE_URL not set. Use --db-url or set DATABASE_URL env var.")
        })?
    } else {
-        cli.db_url.clone()
+        EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("secrets=warn"))
    };
    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();
    // config subcommand needs no database or master key
    if let Commands::Config { action } = cli.command {
        return commands::config::run(action).await;
    }
    let db_url = config::resolve_db_url(&cli.db_url)?;
    let pool = db::create_pool(&db_url).await?;
    db::migrate(&pool).await?;
-    match &cli.command {
+    // init needs a pool but sets up the master key — handle before loading it
    if let Commands::Init = cli.command {
        return commands::init::run(&pool).await;
    }
    // All remaining commands require the master key from the OS Keychain,
    // except delete which operates on plaintext metadata only.
    match cli.command {
        Commands::Init | Commands::Config { .. } => unreachable!(),
        Commands::Add {
            namespace,
            kind,
@@ -134,33 +444,79 @@ async fn main() -> Result<()> {
            tags,
            meta,
            secrets,
            output,
        } => {
-            commands::add::run(&pool, namespace, kind, name, tags, meta, secrets).await?;
+            let master_key = crypto::load_master_key()?;
-        }
+            let _span =
-        Commands::Search {
+                tracing::info_span!("cmd", command = "add", %namespace, %kind, %name).entered();
-            namespace,
+            let out = resolve_output_mode(output.as_deref())?;
-            kind,
+            commands::add::run(
            tag,
            query,
            show_secrets,
        } => {
            commands::search::run(
                &pool,
-                namespace.as_deref(),
+                commands::add::AddArgs {
-                kind.as_deref(),
+                    namespace: &namespace,
-                tag.as_deref(),
+                    kind: &kind,
-                query.as_deref(),
+                    name: &name,
-                *show_secrets,
+                    tags: &tags,
                    meta_entries: &meta,
                    secret_entries: &secrets,
                    output: out,
                },
                &master_key,
            )
            .await?;
        }
        Commands::Search {
            namespace,
            kind,
            name,
            tag,
            query,
            show_secrets,
            fields,
            summary,
            limit,
            offset,
            sort,
            output,
        } => {
            let master_key = crypto::load_master_key()?;
            let _span = tracing::info_span!("cmd", command = "search").entered();
            let show = show_secrets || fields.iter().any(|f| f.starts_with("secret"));
            let out = resolve_output_mode(output.as_deref())?;
            commands::search::run(
                &pool,
                commands::search::SearchArgs {
                    namespace: namespace.as_deref(),
                    kind: kind.as_deref(),
                    name: name.as_deref(),
                    tags: &tag,
                    query: query.as_deref(),
                    show_secrets: show,
                    fields: &fields,
                    summary,
                    limit,
                    offset,
                    sort: &sort,
                    output: out,
                },
                Some(&master_key),
            )
            .await?;
        }
        Commands::Delete {
            namespace,
            kind,
            name,
            output,
        } => {
-            commands::delete::run(&pool, namespace, kind, name).await?;
+            let _span =
                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::Update {
            namespace,
            kind,
@@ -171,20 +527,110 @@ async fn main() -> Result<()> {
            remove_meta,
            secrets,
            remove_secrets,
            output,
        } => {
            let master_key = crypto::load_master_key()?;
            let _span =
                tracing::info_span!("cmd", command = "update", %namespace, %kind, %name).entered();
            let out = resolve_output_mode(output.as_deref())?;
            commands::update::run(
                &pool,
                commands::update::UpdateArgs {
-                    namespace,
+                    namespace: &namespace,
-                    kind,
+                    kind: &kind,
-                    name,
+                    name: &name,
-                    add_tags,
+                    add_tags: &add_tags,
-                    remove_tags,
+                    remove_tags: &remove_tags,
-                    meta_entries: meta,
+                    meta_entries: &meta,
-                    remove_meta,
+                    remove_meta: &remove_meta,
-                    secret_entries: secrets,
+                    secret_entries: &secrets,
-                    remove_secrets,
+                    remove_secrets: &remove_secrets,
                    output: out,
                },
                &master_key,
            )
            .await?;
        }
        Commands::History {
            namespace,
            kind,
            name,
            limit,
            output,
        } => {
            let out = resolve_output_mode(output.as_deref())?;
            commands::rollback::list_history(&pool, &namespace, &kind, &name, limit, out).await?;
        }
        Commands::Rollback {
            namespace,
            kind,
            name,
            to_version,
            output,
        } => {
            let master_key = crypto::load_master_key()?;
            let out = resolve_output_mode(output.as_deref())?;
            commands::rollback::run(
                &pool,
                commands::rollback::RollbackArgs {
                    namespace: &namespace,
                    kind: &kind,
                    name: &name,
                    to_version,
                    output: out,
                },
                &master_key,
            )
            .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,
            prefix,
            command,
        } => {
            let master_key = crypto::load_master_key()?;
            commands::run::run_exec(
                &pool,
                commands::run::RunArgs {
                    namespace: namespace.as_deref(),
                    kind: kind.as_deref(),
                    name: name.as_deref(),
                    tags: &tag,
                    prefix: &prefix,
                    command: &command,
                },
                &master_key,
            )
            .await?;
        }
--- a/src/models.rs
+++ b/src/models.rs
@@ -11,7 +11,10 @@ pub struct Secret {
    pub name: String,
    pub tags: Vec<String>,
    pub metadata: Value,
-    pub encrypted: Value,
+    /// 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>,
 }
--- a/src/output.rs
+++ b/src/output.rs
@@ -0,0 +1,47 @@
 use std::io::IsTerminal;
 use std::str::FromStr;
 /// Output format for all commands.
 #[derive(Debug, Clone, Default, PartialEq)]
 pub enum OutputMode {
    /// Human-readable text (default when stdout is a TTY)
    #[default]
    Text,
    /// Pretty-printed JSON
    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 {
    type Err = anyhow::Error;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "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",
                other
            )),
        }
    }
 }
 /// Resolve the effective output mode.
 /// - Explicit value from `--output` takes priority.
 /// - TTY → text; non-TTY (piped/redirected) → json-compact.
 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)
    }
 }
Author	SHA1	Message	Date
voson	3c21b3dac1	chore: bump version to 0.6.1 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Failing after 39s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Has been skipped Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Has been skipped Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been skipped Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Made-with: Cursor	2026-03-19 10:39:07 +08:00
voson	3b36d5a3dd	feat(config): verify DB connection before saving set-db Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Has been cancelled Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Has been cancelled Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details Secrets CLI - Build & Release / 发布草稿 Release (push) Has been cancelled Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Has been cancelled Details - Check connection with create_pool before writing to config - Show 'Database connection failed' on error, do not overwrite config - Update AGENTS.md and README.md Made-with: Cursor	2026-03-19 10:38:38 +08:00
voson	a765dcc428	feat: 0.6.0 — 事务/版本化/类型化/inject/run Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m37s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 37s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 50s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 写路径事务化：add/update/delete 与 audit 同事务，update CAS 并发保护 - 版本化与回滚：secrets_history 表、version 字段、history/rollback 命令 - 类型化字段：key:=<json> 支持数字、布尔、数组、对象 - 临时 env 模式：inject 输出 KEY=VALUE，run 向子进程注入 - inject/run 至少需一个过滤条件；search -o env 使用 shell_quote；JSON 输出含 version Made-with: Cursor	2026-03-19 10:30:45 +08:00
voson	31b0ea9bf1	refactor: 代码审阅优化 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m42s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m18s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Failing after 7m40s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details P0: - fix(config): config_dir 使用 home_dir 回退，避免 ~ 不展开 - fix(search): 模糊查询转义 LIKE 通配符 % 和 _ P1: - chore(db): 连接池添加 acquire_timeout 10s - refactor(update): 消除 meta_keys/secret_keys 重复计算 P2: - refactor(config): 合并 ConfigAction 枚举 - chore(deps): 移除 clap/env、uuid/v4 无用 features - perf(main): delete 命令跳过 master_key 加载 - i18n(config): 统一错误消息为英文 - perf(search): show_secrets=false 时不再解密获取 key_count - feat(delete,update): 支持 -o json/json-compact 输出 P3: - feat(search): --tag 支持多值交叉过滤 docs: 将 seed-data.sh 替换为 setup-gitea-actions.sh Made-with: Cursor	2026-03-19 09:31:53 +08:00
voson	dc0534cbc9	refactor(secrets): remove migrate_encrypt command Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 3s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m38s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m9s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 5s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Failing after 7m27s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details Made-with: Cursor	2026-03-19 09:17:04 +08:00
voson	8fdb6db87b	feat: 客户端加密 encrypted 字段，数据库只存密文 (v0.5.0) Some checks failed Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m27s Details Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m14s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Failing after 11m1s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 新增 src/crypto.rs：AES-256-GCM 加解密 + Argon2id 密钥派生 + OS Keychain 读写 - 新增 `secrets init` 命令：输入 Master Password，派生 Master Key 存入 Keychain - 新增 `secrets migrate-encrypt` 命令：将旧明文 JSONB 数据批量加密 - 修改 db.rs：encrypted 列 JSONB → BYTEA，新增 kv_config 表（存 Argon2id salt） - 修改 models.rs：encrypted 字段类型 Value → Vec<u8> - 修改 add/update：写入前 encrypt_json，update 读取后 decrypt → 合并 → 重新加密 - 修改 search：按需解密，未解密时显示 _encrypted:true/_key_count:N - 通过 6 个 crypto 单元测试（加解密、JSON roundtrip、Argon2id 确定性） Made-with: Cursor	2026-03-18 20:10:13 +08:00
voson	1f7984d798	feat: AI 优先的 search 增强与结构化输出 (v0.4.0) Some checks failed Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 57s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 33s Details Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 44s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - search: 新增 --name、-f/--field、-o/--output、--summary、--limit、--offset、--sort - search: 非 TTY 自动输出 json-compact，便于 AI 解析 - search: -f secret.* 自动解锁 secrets - add: 支持 -o json/json-compact 输出 - add: 重构为 AddArgs 结构体 - 全局: 各子命令 after_help 补充典型值示例 - output.rs: OutputMode 枚举 + TTY 检测 - 文档: README/AGENTS 面向 AI 的用法，连接串改为 <host>:<port> Made-with: Cursor	2026-03-18 17:17:43 +08:00
voson	140162f39a	ci(secrets): 飞书通知分散到各构建 job，放宽超时与构建条件 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 29s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 45s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m18s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 各 build job 超时 10→15min，publish-release 2→5min - 移除 build-macos/build-windows 的 if 条件，默认全平台构建 - 删除独立 notify job，在各 build job 内增加飞书单 job 通知 - 汇总通知并入 publish-release，用 needs 取状态不再调 API - publish-release 增加 if: always() 与 checkout 步骤 Made-with: Cursor	2026-03-18 16:32:45 +08:00
voson	535683b15c	feat: 添加结构化日志与审计 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 3s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m17s Details Secrets CLI - Build & Release / 通知 (push) Successful in 6s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Has been cancelled Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Has started running Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Has been cancelled Details - tracing + tracing-subscriber，全局 --verbose/-v 与 RUST_LOG 控制 - 新增 audit_log 表，add/update/delete 成功后自动写入审计记录 - 新增 src/audit.rs，审计失败仅 warn 不中断主流程 - 更新 README/AGENTS.md，补充 verbose、audit_log 说明 - .vscode/tasks.json 增加 verbose/update/audit 测试任务 Made-with: Cursor	2026-03-18 16:30:42 +08:00
voson	9620ff1923	feat(config): persist database URL to ~/.config/secrets/config.toml - Add 'secrets config set-db/show/path' subcommands - Remove dotenvy and DATABASE_URL env var support - Config file created with 0600 permission - Bump version to 0.3.0 Made-with: Cursor	2026-03-18 16:19:11 +08:00
voson	e6db23bd6d	fix(ci): 移除 probe-runners，用变量控制 build，解耦 notify Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 21s Details Secrets CLI - Build & Release / 通知 (push) Successful in 7s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 28s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 35s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 0s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 删除探测 Runner job（API 解析不可靠，且 always() 导致 job 被错误调度） - build-linux: 仅 needs version+check，默认执行 - build-macos: if vars.BUILD_MACOS != 'false'（默认开，runner 离线时设 false） - build-windows: if vars.BUILD_WINDOWS == 'true'（默认关，无 runner） - publish-release: 仅依赖 build-linux，避免被 macOS/Windows 阻塞 - notify: 仅 needs version+check + always()，失败也能发飞书；build 状态通过 API 查询 Made-with: Cursor	2026-03-18 16:04:16 +08:00
voson	c61c8292aa	fix: CI 无 DB 下 clippy 通过 + 失败时也发飞书通知 Some checks failed Secrets CLI - Build & Release / 探测 Runner (push) Successful in 1s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Has been skipped Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Has been skipped Details Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 34s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Has been cancelled Details Secrets CLI - Build & Release / 通知 (push) Has been cancelled Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - update.rs: sqlx::query! 改为 query/query_as，不依赖编译期 DB - workflow: build job 加 always() 且 check.result==success，失败时 notify 能执行 Made-with: Cursor	2026-03-18 15:50:10 +08:00