chore: bump version to 0.7.0 for upgrade feature

Made-with: Cursor

.gitea/workflows/secrets.yml

@@ -24,120 +24,127 @@ env:
   RUST_BACKTRACE: short
 
 jobs:
-  # ========== 版本检查（只跑一次，供后续 job 共用）==========
   version:
-    name: 检查版本
+    name: 版本 & Release
     runs-on: debian
     outputs:
-      version: ${{ steps.version.outputs.version }}
+      version: ${{ steps.ver.outputs.version }}
-      tag: ${{ steps.version.outputs.tag }}
+      tag: ${{ steps.ver.outputs.tag }}
-      tag_exists: ${{ steps.version.outputs.tag_exists }}
+      tag_exists: ${{ steps.ver.outputs.tag_exists }}
+      release_id: ${{ steps.release.outputs.release_id }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: 检查版本
+      - name: 解析版本
-        id: version
+        id: ver
         run: |
           version=$(grep -m1 '^version' Cargo.toml | sed 's/.*"\(.*\)".*/\1/')
           tag="secrets-${version}"
-          echo "version=${version}" >> $GITHUB_OUTPUT
+          previous_tag=$(git tag --list 'secrets-*' --sort=-v:refname | awk -v tag="$tag" '$0 != tag { print; exit }')
-          echo "tag=${tag}" >> $GITHUB_OUTPUT
+
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "previous_tag=${previous_tag}" >> "$GITHUB_OUTPUT"
 
           if git rev-parse "refs/tags/${tag}" >/dev/null 2>&1; then
-            echo "tag_exists=true" >> $GITHUB_OUTPUT
+            echo "tag_exists=true" >> "$GITHUB_OUTPUT"
             echo "版本 ${tag} 已存在"
           else
-            echo "tag_exists=false" >> $GITHUB_OUTPUT
+            echo "tag_exists=false" >> "$GITHUB_OUTPUT"
             echo "将创建新版本 ${tag}"
           fi
 
       - name: 创建 Tag
-        if: steps.version.outputs.tag_exists == 'false'
+        if: steps.ver.outputs.tag_exists == 'false'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "${{ steps.version.outputs.tag }}" -m "Release ${{ steps.version.outputs.tag }}"
+          git tag -a "${{ steps.ver.outputs.tag }}" -m "Release ${{ steps.ver.outputs.tag }}"
-          git push origin "${{ steps.version.outputs.tag }}"
+          git push origin "${{ steps.ver.outputs.tag }}"
 
-  # ========== 矩阵构建 ==========
+      - name: 解析或创建 Release
-  build:
+        id: release
-    name: Build (${{ matrix.target }})
+        env:
-    needs: version
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
-    continue-on-error: true       # 某平台失败/超时不阻断其他平台和 notify
+        run: |
-    timeout-minutes: 30           # runner 不在线时 30 分钟后放弃
+          if [ -z "$RELEASE_TOKEN" ]; then
-    strategy:
+            echo "release_id=" >> "$GITHUB_OUTPUT"
-      fail-fast: false
+            exit 0
-      matrix:
+          fi
-        include:
-          - runner: debian
-            target: x86_64-unknown-linux-musl
-            archive_suffix: x86_64-linux-musl
-            os: linux
-          - runner: darwin-arm64
-            target: aarch64-apple-darwin
-            archive_suffix: aarch64-macos
-            os: macos
-          - runner: windows
-            target: x86_64-pc-windows-msvc
-            archive_suffix: x86_64-windows
-            os: windows
 
-    runs-on: ${{ matrix.runner }}
+          command -v jq >/dev/null 2>&1 || (sudo apt-get update -qq && sudo apt-get install -y -qq jq)
+
+          tag="${{ steps.ver.outputs.tag }}"
+          version="${{ steps.ver.outputs.version }}"
+          release_api="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
+
+          http_code=$(curl -sS -o /tmp/release.json -w '%{http_code}' \
+            -H "Authorization: token $RELEASE_TOKEN" \
+            "${release_api}/tags/${tag}")
+
+          if [ "$http_code" = "200" ]; then
+            release_id=$(jq -r '.id // empty' /tmp/release.json)
+            if [ -n "$release_id" ]; then
+              echo "已找到现有 Release: ${release_id}"
+              echo "release_id=${release_id}" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          fi
+
+          previous_tag="${{ steps.ver.outputs.previous_tag }}"
+          if [ -n "$previous_tag" ]; then
+            changes=$(git log --pretty=format:'- %s (%h)' "${previous_tag}..HEAD")
+          else
+            changes=$(git log --pretty=format:'- %s (%h)')
+          fi
+          [ -z "$changes" ] && changes="- 首次发布"
+
+          body=$(printf '## 变更日志\n\n%s' "$changes")
+
+          payload=$(jq -n \
+            --arg tag "$tag" \
+            --arg name "${{ env.BINARY_NAME }} ${version}" \
+            --arg body "$body" \
+            '{tag_name: $tag, name: $name, body: $body, draft: true}')
+
+          http_code=$(curl -sS -o /tmp/create-release.json -w '%{http_code}' \
+            -H "Authorization: token $RELEASE_TOKEN" \
+            -H "Content-Type: application/json" \
+            -X POST "$release_api" \
+            -d "$payload")
+
+          if [ "$http_code" = "201" ] || [ "$http_code" = "200" ]; then
+            release_id=$(jq -r '.id // empty' /tmp/create-release.json)
+          fi
+
+          if [ -n "$release_id" ]; then
+            echo "已创建草稿 Release: ${release_id}"
+            echo "release_id=${release_id}" >> "$GITHUB_OUTPUT"
+          else
+            echo "⚠ 创建 Release 失败 (HTTP ${http_code})，跳过产物上传"
+            cat /tmp/create-release.json 2>/dev/null || true
+            echo "release_id=" >> "$GITHUB_OUTPUT"
+          fi
+
+  check:
+    name: 质量检查 (fmt / clippy / test)
+    runs-on: debian
+    timeout-minutes: 10
     steps:
-      # ========== 环境准备 ==========
+      - name: 安装 Rust
-      - name: 安装依赖 (Linux)
-        if: matrix.os == 'linux'
         run: |
-          sudo apt-get update
+          if ! command -v cargo >/dev/null 2>&1; then
-          sudo apt-get install -y jq curl git pkg-config musl-tools binutils
-
-          if ! command -v cargo &>/dev/null; then
-            echo "安装 Rust 工具链..."
             curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-            source "$HOME/.cargo/env"
+            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
-            rustup component add rustfmt clippy
           fi
-
+          source "$HOME/.cargo/env" 2>/dev/null || true
-          rustup target add ${{ matrix.target }}
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
-
-      - name: 安装依赖 (macOS)
-        if: matrix.os == 'macos'
-        run: |
-          brew install jq
-
-          if ! command -v cargo &>/dev/null; then
-            echo "安装 Rust 工具链..."
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-            source "$HOME/.cargo/env"
-            rustup component add rustfmt clippy
-          fi
-
-          rustup target add ${{ matrix.target }}
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
-
-      - name: 安装依赖 (Windows)
-        if: matrix.os == 'windows'
-        shell: pwsh
-        run: |
-          # 检查 Rust 是否已安装
-          if (-not (Get-Command cargo -ErrorAction SilentlyContinue)) {
-            Write-Host "安装 Rust 工具链..."
-            Invoke-WebRequest -Uri "https://win.rustup.rs/x86_64" -OutFile rustup-init.exe
-            .\rustup-init.exe -y --default-toolchain stable
-            Remove-Item rustup-init.exe
-          }
           rustup component add rustfmt clippy
-          rustup target add ${{ matrix.target }}
 
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
-      # ========== Cargo 缓存 ==========
+      - name: 缓存 Cargo
-      - name: 缓存 Cargo 依赖
         uses: actions/cache@v4
         with:
           path: |
@@ -145,169 +152,322 @@ jobs:
             ~/.cargo/registry/cache
             ~/.cargo/git/db
             target
-          key: cargo-secrets-${{ matrix.target }}-${{ hashFiles('Cargo.lock') }}
+          key: cargo-check-${{ hashFiles('Cargo.lock') }}
           restore-keys: |
-            cargo-secrets-${{ matrix.target }}-
+            cargo-check-
 
-      - name: 检查代码格式
+      - run: cargo fmt -- --check
-        if: matrix.os != 'windows'
+      - run: cargo clippy --locked -- -D warnings
-        run: cargo fmt -- --check
+      - run: cargo test --locked
 
-      - name: 检查代码格式 (Windows)
+  build-linux:
-        if: matrix.os == 'windows'
+    name: Build (x86_64-unknown-linux-musl)
-        shell: pwsh
+    needs: [version, check]
-        run: cargo fmt -- --check
-
-      - name: 运行 Clippy 检查
-        if: matrix.os != 'windows'
-        run: cargo clippy --release --target ${{ matrix.target }} -- -D warnings
-
-      - name: 运行 Clippy 检查 (Windows)
-        if: matrix.os == 'windows'
-        shell: pwsh
-        run: cargo clippy --release --target ${{ matrix.target }} -- -D warnings
-
-      - name: 构建
-        if: matrix.os != 'windows'
-        env:
-          GIT_TAG: ${{ needs.version.outputs.version }}
-        run: cargo build --release --target ${{ matrix.target }} --verbose
-
-      - name: 构建 (Windows)
-        if: matrix.os == 'windows'
-        shell: pwsh
-        env:
-          GIT_TAG: ${{ needs.version.outputs.version }}
-        run: cargo build --release --target ${{ matrix.target }} --verbose
-
-      - name: Strip 二进制 (Linux)
-        if: matrix.os == 'linux'
-        run: strip target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}
-
-      - name: Strip 二进制 (macOS)
-        if: matrix.os == 'macos'
-        run: strip -x target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}
-
-      # ========== 上传 Release 产物 ==========
-      - name: 上传 Release 产物 (Linux/macOS)
-        if: needs.version.outputs.tag_exists == 'false' && matrix.os != 'windows'
-        env:
-          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
-        run: |
-          [ -z "$RELEASE_TOKEN" ] && echo "跳过：未配置 RELEASE_TOKEN" && exit 0
-
-          tag="${{ needs.version.outputs.tag }}"
-          binary="target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}"
-          archive="${{ env.BINARY_NAME }}-${tag}-${{ matrix.archive_suffix }}.tar.gz"
-
-          tar -czf "$archive" -C "$(dirname $binary)" "$(basename $binary)"
-
-          # 查找已有 Release（由首个完成的 job 创建，后续 job 直接上传）
-          release_url="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
-          release_id=$(curl -sS -H "Authorization: token $RELEASE_TOKEN" \
-            "${release_url}/tags/${tag}" | jq -r '.id // empty')
-
-          if [ -z "$release_id" ]; then
-            release_id=$(curl -sS -H "Authorization: token $RELEASE_TOKEN" \
-              -H "Content-Type: application/json" \
-              -X POST "$release_url" \
-              -d "{\"tag_name\": \"${tag}\", \"name\": \"${tag}\", \"body\": \"Release ${tag}\"}" \
-              | jq -r '.id')
-          fi
-
-          upload_url="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${release_id}/assets"
-          curl -sS -H "Authorization: token $RELEASE_TOKEN" \
-            -F "attachment=@${archive}" \
-            "$upload_url"
-
-          echo "已上传: ${archive} → Release ${tag}"
-
-      - name: 上传 Release 产物 (Windows)
-        if: needs.version.outputs.tag_exists == 'false' && matrix.os == 'windows'
-        shell: pwsh
-        env:
-          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
-        run: |
-          if (-not $env:RELEASE_TOKEN) { Write-Host "跳过：未配置 RELEASE_TOKEN"; exit 0 }
-
-          $tag = "${{ needs.version.outputs.tag }}"
-          $binary = "target\${{ matrix.target }}\release\${{ env.BINARY_NAME }}.exe"
-          $archive = "${{ env.BINARY_NAME }}-${tag}-${{ matrix.archive_suffix }}.zip"
-
-          Compress-Archive -Path $binary -DestinationPath $archive
-
-          $headers = @{ "Authorization" = "token $env:RELEASE_TOKEN"; "Content-Type" = "application/json" }
-          $release_url = "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
-
-          # 查找已有 Release
-          $existing = Invoke-RestMethod -Uri "${release_url}/tags/${tag}" -Headers $headers -ErrorAction SilentlyContinue
-          if ($existing.id) {
-            $release_id = $existing.id
-          } else {
-            $body = @{ tag_name = $tag; name = $tag; body = "Release ${tag}" } | ConvertTo-Json
-            $release_id = (Invoke-RestMethod -Uri $release_url -Method Post -Headers $headers -Body $body).id
-          }
-
-          $upload_url = "${release_url}/${release_id}/assets"
-          $upload_headers = @{ "Authorization" = "token $env:RELEASE_TOKEN" }
-          $form = @{ attachment = Get-Item $archive }
-          Invoke-RestMethod -Uri $upload_url -Method Post -Headers $upload_headers -Form $form
-
-          Write-Host "已上传: ${archive} → Release ${tag}"
-
-  # ========== 汇总通知 ==========
-  notify:
-    name: 发送通知
-    needs: [version, build]
-    if: always() && github.event_name == 'push'
     runs-on: debian
+    timeout-minutes: 15
     steps:
+      - name: 安装依赖
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config musl-tools binutils curl
+          if ! command -v cargo >/dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+          fi
+          source "$HOME/.cargo/env" 2>/dev/null || true
+          rustup target add x86_64-unknown-linux-musl
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
       - uses: actions/checkout@v4
 
-      - name: 发送通知
+      - name: 缓存 Cargo
-        continue-on-error: true
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            target
+          key: cargo-x86_64-unknown-linux-musl-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            cargo-x86_64-unknown-linux-musl-
+
+      - run: cargo build --release --locked --target x86_64-unknown-linux-musl
+      - run: strip target/x86_64-unknown-linux-musl/release/${{ env.BINARY_NAME }}
+
+      - name: 上传 Release 产物
+        if: needs.version.outputs.release_id != ''
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          [ -z "$RELEASE_TOKEN" ] && exit 0
+          tag="${{ needs.version.outputs.tag }}"
+          bin="target/x86_64-unknown-linux-musl/release/${{ env.BINARY_NAME }}"
+          archive="${{ env.BINARY_NAME }}-${tag}-x86_64-linux-musl.tar.gz"
+          tar -czf "$archive" -C "$(dirname "$bin")" "$(basename "$bin")"
+          sha256sum "$archive" > "${archive}.sha256"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${archive}" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${archive}.sha256" \
+            "${{ 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 (macOS aarch64 + x86_64)
+    needs: [version, check]
+    runs-on: darwin-arm64
+    timeout-minutes: 15
+    steps:
+      - name: 安装依赖
+        run: |
+          if ! command -v cargo >/dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+          fi
+          source "$HOME/.cargo/env" 2>/dev/null || true
+          rustup target add aarch64-apple-darwin
+          rustup target add x86_64-apple-darwin
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - uses: actions/checkout@v4
+
+      - name: 缓存 Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            target
+          key: cargo-macos-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            cargo-macos-
+
+      - run: cargo build --release --locked --target aarch64-apple-darwin
+      - run: cargo build --release --locked --target x86_64-apple-darwin
+      - run: strip -x target/aarch64-apple-darwin/release/${{ env.BINARY_NAME }}
+      - run: strip -x target/x86_64-apple-darwin/release/${{ env.BINARY_NAME }}
+
+      - name: 上传 Release 产物
+        if: needs.version.outputs.release_id != ''
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          [ -z "$RELEASE_TOKEN" ] && exit 0
+          tag="${{ needs.version.outputs.tag }}"
+          release_id="${{ needs.version.outputs.release_id }}"
+
+          arm_bin="target/aarch64-apple-darwin/release/${{ env.BINARY_NAME }}"
+          arm_archive="${{ env.BINARY_NAME }}-${tag}-aarch64-macos.tar.gz"
+          tar -czf "$arm_archive" -C "$(dirname "$arm_bin")" "$(basename "$arm_bin")"
+          shasum -a 256 "$arm_archive" > "${arm_archive}.sha256"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${arm_archive}" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${release_id}/assets"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${arm_archive}.sha256" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${release_id}/assets"
+
+          intel_bin="target/x86_64-apple-darwin/release/${{ env.BINARY_NAME }}"
+          intel_archive="${{ env.BINARY_NAME }}-${tag}-x86_64-macos.tar.gz"
+          tar -czf "$intel_archive" -C "$(dirname "$intel_bin")" "$(basename "$intel_bin")"
+          shasum -a 256 "$intel_archive" > "${intel_archive}.sha256"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${intel_archive}" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${release_id}/assets"
+          curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+            -F "attachment=@${intel_archive}.sha256" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${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}
+          目标：aarch64-apple-darwin, x86_64-apple-darwin
+          提交：${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, check]
+    runs-on: windows
+    timeout-minutes: 15
+    steps:
+      - name: 安装依赖
+        shell: pwsh
+        run: |
+          if (-not (Get-Command cargo -ErrorAction SilentlyContinue)) {
+            Invoke-WebRequest -Uri "https://win.rustup.rs/x86_64" -OutFile rustup-init.exe
+            .\rustup-init.exe -y --default-toolchain stable
+            Remove-Item rustup-init.exe
+          }
+          rustup target add x86_64-pc-windows-msvc
+
+      - uses: actions/checkout@v4
+
+      - name: 缓存 Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            target
+          key: cargo-x86_64-pc-windows-msvc-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            cargo-x86_64-pc-windows-msvc-
+
+      - name: 构建
+        shell: pwsh
+        run: cargo build --release --locked --target x86_64-pc-windows-msvc
+
+      - name: 上传 Release 产物
+        if: needs.version.outputs.release_id != ''
+        shell: pwsh
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          if (-not $env:RELEASE_TOKEN) { exit 0 }
+          $tag = "${{ needs.version.outputs.tag }}"
+          $bin = "target\x86_64-pc-windows-msvc\release\${{ env.BINARY_NAME }}.exe"
+          $archive = "${{ env.BINARY_NAME }}-${tag}-x86_64-windows.zip"
+          Compress-Archive -Path $bin -DestinationPath $archive -Force
+          $hash = (Get-FileHash -Algorithm SHA256 $archive).Hash.ToLower()
+          Set-Content -Path "${archive}.sha256" -Value "$hash  $archive" -NoNewline
+          $url = "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"
+          Invoke-RestMethod -Uri $url -Method Post `
+            -Headers @{ "Authorization" = "token $env:RELEASE_TOKEN" } `
+            -Form @{ attachment = Get-Item $archive }
+          Invoke-RestMethod -Uri $url -Method Post `
+            -Headers @{ "Authorization" = "token $env:RELEASE_TOKEN" } `
+            -Form @{ attachment = Get-Item "${archive}.sha256" }
+
+      - 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, build-linux, build-macos, build-windows]
+    if: always() && needs.version.outputs.release_id != ''
+    runs-on: debian
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 发布草稿
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          [ -z "$RELEASE_TOKEN" ] && exit 0
+
+          linux_r="${{ needs.build-linux.result }}"
+          macos_r="${{ needs.build-macos.result }}"
+          windows_r="${{ needs.build-windows.result }}"
+          if [ "$linux_r" != "success" ] || [ "$macos_r" != "success" ] || [ "$windows_r" != "success" ]; then
+            echo "存在未成功的构建任务，保留草稿 Release"
+            echo "linux=${linux_r} macos=${macos_r} windows=${windows_r}"
+            exit 0
+          fi
+
+          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}' \
+            -H "Authorization: token $RELEASE_TOKEN" \
+            -H "Content-Type: application/json" \
+            -X PATCH "$release_api" \
+            -d '{"draft":false}')
+
+          if [ "$http_code" != "200" ]; then
+            echo "发布草稿 Release 失败 (HTTP ${http_code})"
+            cat /tmp/publish-release.json 2>/dev/null || true
+            exit 1
+          fi
+          echo "Release 已发布"
+
+      - 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 }}"
           tag_exists="${{ needs.version.outputs.tag_exists }}"
-          build_result="${{ needs.build.result }}"
+          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
+          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
 
-          if [ "$build_result" = "success" ]; then
+          linux_r="${{ needs.build-linux.result }}"
-            status_text="构建成功 ✅"
+          macos_r="${{ needs.build-macos.result }}"
+          windows_r="${{ needs.build-windows.result }}"
+          publish_r="${{ job.status }}"
+
+          icon() { case "$1" in success) echo "✅";; skipped) echo "⏭";; *) echo "❌";; esac; }
+
+          if [ "$linux_r" = "success" ] && [ "$macos_r" = "success" ] && [ "$windows_r" = "success" ] && [ "$publish_r" = "success" ]; then
+            status="发布成功 ✅"
+          elif [ "$linux_r" != "success" ] || [ "$macos_r" != "success" ] || [ "$windows_r" != "success" ]; then
+            status="构建失败 ❌"
           else
-            status_text="构建失败 ❌"
+            status="发布失败 ❌"
           fi
 
-          commit_title=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
+          if [ "$tag_exists" = "false" ]; then
-          workflow_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
+            version_line="🆕 新版本 ${tag}"
-
-          if [ "$build_result" != "success" ]; then
-            payload=$(jq -n \
-              --arg title "${{ env.BINARY_NAME }} ${status_text}" \
-              --arg commit "$commit_title" \
-              --arg version "$tag" \
-              --arg author "${{ github.actor }}" \
-              --arg url "$workflow_url" \
-              '{msg_type: "text", content: {text: "\($title)\n提交：\($commit)\n版本：\($version)\n作者：\($author)\n详情：\($url)"}}')
-          elif [ "$tag_exists" = "false" ]; then
-            payload=$(jq -n \
-              --arg title "${{ env.BINARY_NAME }} ${status_text}" \
-              --arg commit "$commit_title" \
-              --arg version "$tag" \
-              --arg author "${{ github.actor }}" \
-              --arg url "$workflow_url" \
-              '{msg_type: "text", content: {text: "\($title)\n🆕 新版本已发布 (linux / macOS / windows)\n提交：\($commit)\n版本：\($version)\n作者：\($author)\n详情：\($url)"}}')
           else
-            payload=$(jq -n \
+            version_line="🔄 重复构建 ${tag}"
-              --arg title "${{ env.BINARY_NAME }} ${status_text}" \
-              --arg commit "$commit_title" \
-              --arg version "$tag" \
-              --arg author "${{ github.actor }}" \
-              --arg url "$workflow_url" \
-              '{msg_type: "text", content: {text: "\($title)\n🔄 重复构建\n提交：\($commit)\n版本：\($version)\n作者：\($author)\n详情：\($url)"}}')
           fi
 
+          msg="secrets ${status}
+          ${version_line}
+          linux $(icon "$linux_r") | macOS $(icon "$macos_r") | windows $(icon "$windows_r") | Release $(icon "$publish_r")
+          提交：${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"

.gitignore

@@ -1,2 +1,4 @@
 /target
 .env
+.DS_Store
+.cursor/

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

AGENTS.md

@@ -1,33 +1,42 @@
 # 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 命令：临时环境变量注入
+      upgrade.rs         # upgrade 命令：检查、校验摘要并下载最新版本，自动替换二进制
   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 +48,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,35 +104,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 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 \
@@ -93,17 +240,214 @@ 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
+
+### 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
+
+# 轮换 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>
+
+# 移除废弃字段
+secrets update -n refining --kind service --name mqtt \
+  --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
+```
+
+---
+
+### upgrade — 自动更新 CLI 二进制
+
+从 Gitea Release 下载最新版本，校验对应 `.sha256` 摘要后替换当前二进制，无需数据库连接或主密钥。
+
+```bash
+# 检查是否有新版本（不下载）
+secrets upgrade --check
+
+# 下载、校验 SHA-256 并安装最新版本
+secrets upgrade
+```
+
+---
+
+### 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
 ```
 
 ## 代码规范
@@ -112,19 +456,60 @@ secrets search --tag hongkong
 - 异步：全程 `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`
+
+## 提交前检查（必须全部通过）
+
+每次提交代码前，请在本地依次执行以下检查，**全部通过后再 push**：
+
+### 1. 版本号（按需）
+
+若本次改动需要发版，请先确认 `Cargo.toml` 中的 `version` 已提升，避免 CI 打出的 Tag 与已有版本重复。**升级版本后需同时更新 `Cargo.lock`**（运行 `cargo build` 即可自动同步），否则 CI 中 `cargo clippy --locked` 会因 lock 与 manifest 不一致而失败。可通过 git tag 判断：
+
+```bash
+# 查看当前 Cargo.toml 版本
+grep '^version' Cargo.toml
+
+# 查看是否已存在该版本对应的 tag（CI 使用格式 secrets-<version>）
+git tag -l 'secrets-*'
+```
+
+若当前版本已被 tag（例如已有 `secrets-0.3.0` 且 `Cargo.toml` 仍为 `0.3.0`），则应在 `Cargo.toml` 中 bump 版本号，再执行 `cargo build` 同步 `Cargo.lock`，最后一并提交，以便 CI 自动打新 Tag 并发布 Release。
+
+### 2. 格式、Lint、测试
+
+```bash
+cargo fmt -- --check   # 格式检查（不通过则运行 cargo fmt 修复）
+cargo clippy -- -D warnings  # Lint 检查（消除所有 warning）
+cargo test             # 单元/集成测试
+```
+
+或一次性执行：
+
+```bash
+cargo fmt -- --check && cargo clippy -- -D warnings && cargo test
+```
 
 ## CI/CD
 
-- Gitea Actions（runner: debian）
+- Gitea Actions（runners: debian / darwin-arm64 / windows）
 - 触发：`src/**`、`Cargo.toml`、`Cargo.lock` 变更推送到 main
-- 构建目标：`x86_64-unknown-linux-musl`（静态链接，无 glibc 依赖）
+- 构建目标：`x86_64-unknown-linux-musl`、`aarch64-apple-darwin`、`x86_64-apple-darwin`（由 ARM mac runner 交叉编译）、`x86_64-pc-windows-msvc`
-- 新版本自动打 Tag（格式 `secrets-<version>`）并上传二进制到 Gitea Release
+- 新版本自动打 Tag（格式 `secrets-<version>`）并上传二进制与对应 `.sha256` 摘要到 Gitea Release
+- Release 仅在 Linux/macOS/Windows 构建全部成功后才会从 draft 发布
 - 通知：飞书 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`，不支持环境变量。

Cargo.toml

@@ -1,16 +1,31 @@
 [package]
 name = "secrets"
-version = "0.1.0"
+version = "0.7.0"
 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"
+flate2 = "1.1.9"
+keyring = { version = "3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
+rand = "0.10.0"
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
+rpassword = "7.4.0"
+self-replace = "1.5.0"
+semver = "1.0.27"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
-sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-native-tls", "postgres", "uuid", "json", "chrono"] }
+sha2 = "0.10.9"
+sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
+tar = "0.4.44"
+tempfile = "3.19"
 tokio = { version = "1.50.0", features = ["full"] }
 toml = "1.0.7"
-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"] }
+zip = { version = "8.2.0", default-features = false, features = ["deflate"] }

README.md

@@ -2,7 +2,7 @@
 
 跨设备密钥与配置管理 CLI，基于 Rust + PostgreSQL 18。
 
-将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。
+将服务器信息、服务凭据统一存入数据库，供本地工具和 AI 读取上下文。敏感数据（`encrypted` 字段）使用 AES-256-GCM 加密存储，主密钥由 Argon2id 从主密码派生并存入系统钥匙串。
 
 ## 安装
 
@@ -11,55 +11,145 @@ cargo build --release
 # 或从 Release 页面下载预编译二进制
 ```
 
-配置数据库连接：
+已有旧版本时，可执行 `secrets upgrade` 自动下载最新版并替换。该命令会校验 Release 附带的 `.sha256` 摘要后再安装。
+
+## 首次使用（每台设备各执行一次）
 
 ```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
+secrets upgrade --help     # 检查并更新 CLI 版本
 
-# 查看子命令帮助
+# ── 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 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 update -n refining --kind server --name my-server -m ip=10.0.0.1
-secrets search -n refining --kind server
+secrets update -n refining --kind service --name gitea --add-tag production -s token=<new>
-secrets search --tag hongkong
+secrets update -n refining --kind service --name mqtt --remove-meta old_port --remove-secret old_key
-secrets search -q mqtt              # 关键词匹配 name / metadata / tags
-secrets search -n refining --kind service --name gitea --show-secrets
 
-# 删除
+# ── 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    # 打印配置文件路径
+
+# ── upgrade ──────────────────────────────────────────────────────────────────
+secrets upgrade --check   # 仅检查是否有新版本
+secrets upgrade           # 下载、校验 SHA-256 并安装最新版（从 Gitea Release）
+
+# ── 调试 ──────────────────────────────────────────────────────────────────────
+secrets --verbose search -q mqtt
+RUST_LOG=secrets=trace secrets search
 ```
 
 ## 数据模型
 
-单张 `secrets` 表，首次连接自动建表。
+单张 `secrets` 表，首次连接自动建表；同时自动创建 `audit_log` 表，记录所有写操作。
 
 | 字段 | 说明 |
 |------|------|
@@ -68,28 +158,48 @@ 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）
+    upgrade.rs     # 从 Gitea Release 自更新
 scripts/
-  seed-data.sh     # 导入 refining / ricnsmart 全量数据
+  setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
 ```
 
 ## CI/CD（Gitea Actions）
 
-推送 `main` 分支时自动：fmt/clippy 检查 → musl 构建 → 创建 Release 并上传二进制。
+推送 `main` 分支时自动：fmt/clippy/test 检查 → Linux/macOS/Windows 构建 → 上传二进制与 `.sha256` 摘要 → 所有平台成功后发布 Release。
 
 **首次使用需配置 Actions 变量和 Secrets：**
 
@@ -100,5 +210,12 @@ scripts/
 
 - `RELEASE_TOKEN`（Secret）：Gitea PAT，用于创建 Release 上传二进制
 - `WEBHOOK_URL`（Variable）：飞书通知，可选
+- **注意**：Secret/Variable 的 `data`/`value` 字段需传入原始值，不要 base64 编码
+
+当前 Release 预编译产物覆盖：
+- Linux `x86_64-unknown-linux-musl`
+- macOS Apple Silicon `aarch64-apple-darwin`
+- macOS Intel `x86_64-apple-darwin`（由 ARM mac runner 交叉编译）
+- Windows `x86_64-pc-windows-msvc`
 
 详见 [AGENTS.md](AGENTS.md)。

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,12 +110,13 @@ echo "━━━━━━━━━━━━━━━━━━━━━━━━
 echo ""
 
 # 1. 创建 Secret: RELEASE_TOKEN
+# 注意: Gitea Actions API 的 data 字段需传入原始值，不要使用 base64 编码
 echo "1. 创建 Secret: RELEASE_TOKEN"
-encoded=$(echo -n "$GITEA_TOKEN" | base64)
+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\":\"${encoded}\"}" \
+  -d "$secret_payload" \
   "${API_BASE}/repos/${OWNER}/${REPO}/actions/secrets/RELEASE_TOKEN")
 http_code=$(echo "$resp" | tail -n1)
 body=$(echo "$resp" | sed '$d')
@@ -127,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')
@@ -146,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

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");
+    }
+}

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

src/commands/config.rs

@@ -0,0 +1,55 @@
+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);
+            println!("Database connection successful.");
+
+            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()
+}

src/commands/delete.rs

@@ -1,20 +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 = sqlx::query(
+use crate::output::OutputMode;
-        "DELETE FROM secrets WHERE namespace = $1 AND kind = $2 AND name = $3",
+
+#[derive(FromRow)]
+struct DeleteRow {
+    id: Uuid,
+    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)
-    .execute(pool)
+    .fetch_optional(&mut *tx)
     .await?;
 
-    if result.rows_affected() == 0 {
+    let Some(row) = row else {
-        println!("Not found: [{}/{}] {}", namespace, kind, name);
+        tx.rollback().await?;
-    } else {
+        tracing::warn!(namespace, kind, name, "record not found for deletion");
-        println!("Deleted: [{}/{}] {}", namespace, kind, name);
+        match output {
+            OutputMode::Json => println!(
+                "{}",
+                serde_json::to_string_pretty(
+                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
+                )?
+            ),
+            OutputMode::JsonCompact => println!(
+                "{}",
+                serde_json::to_string(
+                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
+                )?
+            ),
+            _ => println!("Not found: [{}/{}] {}", namespace, kind, name),
+        }
+        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(())
 }

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

src/commands/mod.rs

@@ -1,3 +1,9 @@
 pub mod add;
+pub mod config;
 pub mod delete;
+pub mod init;
+pub mod rollback;
+pub mod run;
 pub mod search;
+pub mod update;
+pub mod upgrade;

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

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('\'', "'\\''"))
+}

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,66 +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.encrypted.is_empty()
-            "[{}/{}] {}",
+    {
-            row.namespace, row.kind, row.name,
+        let decrypted = crypto::decrypt_json(master_key, &row.encrypted)?;
-        );
+        if let Some(enc) = decrypted.as_object() {
-        println!("  id:       {}", row.id);
+            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()) {
-        let meta_obj = row.metadata.as_object();
+            println!(
-        if let Some(m) = meta_obj {
+                "  metadata: {}",
-            if !m.is_empty() {
+                serde_json::to_string_pretty(&row.metadata)?
-                println!("  metadata: {}", serde_json::to_string_pretty(&row.metadata)?);
+            );
+        }
+        if !row.encrypted.is_empty() {
+            if show_secrets {
+                match try_decrypt(row, master_key) {
+                    Ok(v) => println!("  secrets:  {}", serde_json::to_string_pretty(&v)?),
+                    Err(e) => println!("  secrets:  [decrypt error: {}]", e),
+                }
+            } else {
+                println!("  secrets:  [encrypted]  (--show-secrets to reveal)");
             }
         }
-
+        println!(
-        if show_secrets {
+            "  created:  {}",
-            println!("  secrets:  {}", serde_json::to_string_pretty(&row.encrypted)?);
+            row.created_at.format("%Y-%m-%d %H:%M:%S UTC")
-        } else {
+        );
-            let keys: Vec<String> = row
-                .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
+            )
+        })
+}

src/commands/update.rs

@@ -0,0 +1,225 @@
+use anyhow::Result;
+use serde_json::{Map, Value, json};
+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,
+    pub kind: &'a str,
+    pub name: &'a str,
+    pub add_tags: &'a [String],
+    pub remove_tags: &'a [String],
+    pub meta_entries: &'a [String],
+    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<'_>, master_key: &[u8; 32]) -> Result<()> {
+    let mut tx = pool.begin().await?;
+
+    let row: Option<UpdateRow> = sqlx::query_as(
+        "SELECT id, version, tags, metadata, encrypted \
+         FROM secrets \
+         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?;
+
+    let row = row.ok_or_else(|| {
+        anyhow::anyhow!(
+            "Not found: [{}/{}] {}. Use `add` to create it first.",
+            args.namespace,
+            args.kind,
+            args.name
+        )
+    })?;
+
+    // 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 {
+        if !tags.contains(t) {
+            tags.push(t.clone());
+        }
+    }
+    tags.retain(|t| !args.remove_tags.contains(t));
+
+    // Merge metadata
+    let mut meta_map: Map<String, Value> = match row.metadata {
+        Value::Object(m) => m,
+        _ => Map::new(),
+    };
+    for entry in args.meta_entries {
+        let (key, value) = parse_kv(entry)?;
+        meta_map.insert(key, value);
+    }
+    for key in args.remove_meta {
+        meta_map.remove(key);
+    }
+    let metadata = Value::Object(meta_map);
+
+    // Decrypt existing encrypted blob, merge changes, re-encrypt
+    let existing_json = if row.encrypted.is_empty() {
+        Value::Object(Map::new())
+    } else {
+        crypto::decrypt_json(master_key, &row.encrypted)?
+    };
+    let mut enc_map: Map<String, Value> = match existing_json {
+        Value::Object(m) => m,
+        _ => Map::new(),
+    };
+    for entry in args.secret_entries {
+        let (key, value) = parse_kv(entry)?;
+        enc_map.insert(key, value);
+    }
+    for key in args.remove_secrets {
+        enc_map.remove(key);
+    }
+    let secret_json = Value::Object(enc_map);
+    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
+
+    tracing::debug!(
+        namespace = args.namespace,
+        kind = args.kind,
+        name = args.name,
+        "updating record"
+    );
+
+    // CAS: update only if version hasn't changed (FOR UPDATE lock ensures this).
+    let result = sqlx::query(
+        "UPDATE secrets \
+         SET tags = $1, metadata = $2, encrypted = $3, version = version + 1, updated_at = NOW() \
+         WHERE id = $4 AND version = $5",
+    )
+    .bind(&tags)
+    .bind(&metadata)
+    .bind(&encrypted_bytes)
+    .bind(row.id)
+    .bind(row.version)
+    .execute(&mut *tx)
+    .await?;
+
+    if result.rows_affected() == 0 {
+        tx.rollback().await?;
+        anyhow::bail!(
+            "Concurrent modification detected for [{}/{}] {}. Please retry.",
+            args.namespace,
+            args.kind,
+            args.name
+        );
+    }
+
+    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();
+
+    crate::audit::log_tx(
+        &mut tx,
+        "update",
+        args.namespace,
+        args.kind,
+        args.name,
+        json!({
+            "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,
+        }),
+    )
+    .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(())
+}

src/commands/upgrade.rs

@@ -0,0 +1,351 @@
+use anyhow::{Context, Result, bail};
+use flate2::read::GzDecoder;
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+use std::io::{Cursor, Read, Write};
+
+const GITEA_API: &str = "https://gitea.refining.dev/api/v1/repos/refining/secrets/releases/latest";
+
+const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+#[derive(Debug, Deserialize)]
+struct Release {
+    tag_name: String,
+    assets: Vec<Asset>,
+}
+
+#[derive(Debug, Deserialize)]
+struct Asset {
+    name: String,
+    browser_download_url: String,
+}
+
+fn available_assets(assets: &[Asset]) -> String {
+    assets
+        .iter()
+        .map(|a| a.name.as_str())
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+fn find_asset_by_suffix<'a>(assets: &'a [Asset], suffix: &str) -> Result<&'a Asset> {
+    assets
+        .iter()
+        .find(|a| a.name.ends_with(suffix))
+        .with_context(|| {
+            format!(
+                "no asset found for this platform (looking for suffix: {suffix})\navailable: {}",
+                available_assets(assets)
+            )
+        })
+}
+
+/// Detect the asset suffix for the current platform/arch at compile time.
+fn platform_asset_suffix() -> Result<&'static str> {
+    #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
+    {
+        Ok("x86_64-linux-musl.tar.gz")
+    }
+
+    #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
+    {
+        Ok("aarch64-macos.tar.gz")
+    }
+
+    #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
+    {
+        Ok("x86_64-macos.tar.gz")
+    }
+
+    #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
+    {
+        Ok("x86_64-windows.zip")
+    }
+
+    #[cfg(not(any(
+        all(target_os = "linux", target_arch = "x86_64"),
+        all(target_os = "macos", target_arch = "aarch64"),
+        all(target_os = "macos", target_arch = "x86_64"),
+        all(target_os = "windows", target_arch = "x86_64"),
+    )))]
+    bail!(
+        "Unsupported platform: {}/{}",
+        std::env::consts::OS,
+        std::env::consts::ARCH
+    )
+}
+
+/// Strip the "secrets-" prefix from the tag and parse as semver.
+fn parse_tag_version(tag: &str) -> Result<semver::Version> {
+    let ver_str = tag
+        .strip_prefix("secrets-")
+        .with_context(|| format!("unexpected tag format: {tag}"))?;
+    semver::Version::parse(ver_str)
+        .with_context(|| format!("failed to parse version from tag: {tag}"))
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    format!("{digest:x}")
+}
+
+fn parse_checksum_file(contents: &str) -> Result<String> {
+    let checksum = contents
+        .split_whitespace()
+        .next()
+        .context("checksum file is empty")?
+        .trim()
+        .to_ascii_lowercase();
+
+    if checksum.len() != 64 || !checksum.bytes().all(|b| b.is_ascii_hexdigit()) {
+        bail!("invalid SHA-256 checksum format")
+    }
+
+    Ok(checksum)
+}
+
+async fn download_bytes(client: &reqwest::Client, url: &str, context: &str) -> Result<Vec<u8>> {
+    Ok(client
+        .get(url)
+        .send()
+        .await
+        .with_context(|| format!("{context}: request failed"))?
+        .error_for_status()
+        .with_context(|| format!("{context}: server returned an error"))?
+        .bytes()
+        .await
+        .with_context(|| format!("{context}: failed to read response body"))?
+        .to_vec())
+}
+
+/// Extract the binary from a tar.gz archive (first file whose name == "secrets").
+fn extract_from_targz(bytes: &[u8]) -> Result<Vec<u8>> {
+    let gz = GzDecoder::new(Cursor::new(bytes));
+    let mut archive = tar::Archive::new(gz);
+    for entry in archive.entries().context("failed to read tar entries")? {
+        let mut entry = entry.context("bad tar entry")?;
+        let path = entry.path().context("bad tar entry path")?.into_owned();
+        let fname = path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or_default();
+        if fname == "secrets" || fname == "secrets.exe" {
+            let mut buf = Vec::new();
+            entry.read_to_end(&mut buf).context("read tar entry")?;
+            return Ok(buf);
+        }
+    }
+    bail!("binary not found inside tar.gz archive")
+}
+
+/// Extract the binary from a zip archive (first file whose name matches).
+#[cfg(target_os = "windows")]
+fn extract_from_zip(bytes: &[u8]) -> Result<Vec<u8>> {
+    let reader = Cursor::new(bytes);
+    let mut archive = zip::ZipArchive::new(reader).context("failed to open zip archive")?;
+    for i in 0..archive.len() {
+        let mut file = archive.by_index(i).context("bad zip entry")?;
+        let fname = file.name().to_owned();
+        if fname.ends_with("secrets.exe") || fname.ends_with("secrets") {
+            let mut buf = Vec::new();
+            file.read_to_end(&mut buf).context("read zip entry")?;
+            return Ok(buf);
+        }
+    }
+    bail!("binary not found inside zip archive")
+}
+
+pub async fn run(check_only: bool) -> Result<()> {
+    let current = semver::Version::parse(CURRENT_VERSION).context("invalid current version")?;
+
+    println!("Current version: v{current}");
+    println!("Checking for updates...");
+
+    let client = reqwest::Client::builder()
+        .user_agent(format!("secrets-cli/{CURRENT_VERSION}"))
+        .build()
+        .context("failed to build HTTP client")?;
+
+    let release: Release = client
+        .get(GITEA_API)
+        .send()
+        .await
+        .context("failed to fetch release info from Gitea")?
+        .error_for_status()
+        .context("Gitea API returned an error")?
+        .json()
+        .await
+        .context("failed to parse release JSON")?;
+
+    let latest = parse_tag_version(&release.tag_name)?;
+
+    if latest <= current {
+        println!("Already up to date (v{current})");
+        return Ok(());
+    }
+
+    println!("New version available: v{latest}");
+
+    if check_only {
+        println!("Run `secrets upgrade` to update.");
+        return Ok(());
+    }
+
+    let suffix = platform_asset_suffix()?;
+    let asset = find_asset_by_suffix(&release.assets, suffix)?;
+    let checksum_name = format!("{}.sha256", asset.name);
+    let checksum_asset = release
+        .assets
+        .iter()
+        .find(|a| a.name == checksum_name)
+        .with_context(|| {
+            format!(
+                "missing checksum asset for download: {checksum_name}\navailable: {}",
+                available_assets(&release.assets)
+            )
+        })?;
+
+    println!("Downloading {}...", asset.name);
+
+    let archive = download_bytes(&client, &asset.browser_download_url, "archive download").await?;
+    let checksum_contents = download_bytes(
+        &client,
+        &checksum_asset.browser_download_url,
+        "checksum download",
+    )
+    .await?;
+    let expected_checksum = parse_checksum_file(
+        std::str::from_utf8(&checksum_contents).context("checksum file is not valid UTF-8")?,
+    )?;
+    let actual_checksum = sha256_hex(&archive);
+
+    if actual_checksum != expected_checksum {
+        bail!(
+            "checksum verification failed for {}: expected {}, got {}",
+            asset.name,
+            expected_checksum,
+            actual_checksum
+        );
+    }
+
+    println!("Verified SHA-256: {actual_checksum}");
+
+    println!("Extracting...");
+
+    let binary = if suffix.ends_with(".tar.gz") {
+        extract_from_targz(&archive)?
+    } else {
+        #[cfg(target_os = "windows")]
+        {
+            extract_from_zip(&archive)?
+        }
+        #[cfg(not(target_os = "windows"))]
+        bail!("zip extraction is only supported on Windows")
+    };
+
+    // Write to a temporary file, set executable permission, then atomically replace.
+    let mut tmp = tempfile::NamedTempFile::new().context("failed to create temp file")?;
+    tmp.write_all(&binary)
+        .context("failed to write temp binary")?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let perms = std::fs::Permissions::from_mode(0o755);
+        std::fs::set_permissions(tmp.path(), perms).context("failed to chmod temp binary")?;
+    }
+
+    self_replace::self_replace(tmp.path()).context("failed to replace current binary")?;
+
+    println!("Updated: v{current} → v{latest}");
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use flate2::Compression;
+    use flate2::write::GzEncoder;
+    use tar::Builder;
+
+    #[test]
+    fn parse_tag_version_accepts_release_tag() {
+        let version = parse_tag_version("secrets-0.6.1").expect("version should parse");
+        assert_eq!(version, semver::Version::new(0, 6, 1));
+    }
+
+    #[test]
+    fn parse_tag_version_rejects_invalid_tag() {
+        let err = parse_tag_version("v0.6.1").expect_err("tag should be rejected");
+        assert!(err.to_string().contains("unexpected tag format"));
+    }
+
+    #[test]
+    fn parse_checksum_file_accepts_sha256sum_format() {
+        let checksum = parse_checksum_file(
+            "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef  secrets.tar.gz",
+        )
+        .expect("checksum should parse");
+        assert_eq!(
+            checksum,
+            "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+        );
+    }
+
+    #[test]
+    fn parse_checksum_file_rejects_invalid_checksum() {
+        let err = parse_checksum_file("not-a-sha256").expect_err("checksum should be rejected");
+        assert!(err.to_string().contains("invalid SHA-256 checksum format"));
+    }
+
+    #[test]
+    fn sha256_hex_matches_known_value() {
+        assert_eq!(
+            sha256_hex(b"abc"),
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+        );
+    }
+
+    #[test]
+    fn extract_from_targz_reads_binary() {
+        let payload = b"fake-secrets-binary";
+        let archive = make_test_targz("secrets", payload);
+        let extracted = extract_from_targz(&archive).expect("binary should extract");
+        assert_eq!(extracted, payload);
+    }
+
+    fn make_test_targz(name: &str, payload: &[u8]) -> Vec<u8> {
+        let encoder = GzEncoder::new(Vec::new(), Compression::default());
+        let mut builder = Builder::new(encoder);
+
+        let mut header = tar::Header::new_gnu();
+        header.set_mode(0o755);
+        header.set_size(payload.len() as u64);
+        header.set_cksum();
+        builder
+            .append_data(&mut header, name, payload)
+            .expect("append tar entry");
+
+        let encoder = builder.into_inner().expect("finish tar builder");
+        encoder.finish().expect("finish gzip")
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn extract_from_zip_reads_binary() {
+        use zip::write::SimpleFileOptions;
+
+        let cursor = Cursor::new(Vec::<u8>::new());
+        let mut writer = zip::ZipWriter::new(cursor);
+        writer
+            .start_file("secrets.exe", SimpleFileOptions::default())
+            .expect("start zip file");
+        writer
+            .write_all(b"fake-secrets-binary")
+            .expect("write zip payload");
+        let bytes = writer.finish().expect("finish zip").into_inner();
+
+        let extracted = extract_from_zip(&bytes).expect("binary should extract");
+        assert_eq!(extracted, b"fake-secrets-binary");
+    }
+}

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

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

src/db.rs

@@ -1,16 +1,20 @@
 use anyhow::Result;
-use sqlx::postgres::PgPoolOptions;
 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(5))
         .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(())
 }

src/main.rs

@@ -1,97 +1,463 @@
+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")]
+#[command(
+    name = "secrets",
+    version,
+    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; 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
+        #[arg(short, long)]
+        namespace: String,
+        /// Kind of record: server, service, key, ...
+        #[arg(long)]
+        kind: String,
+        /// Human-readable unique name
+        #[arg(long)]
+        name: String,
+        /// Add a tag (repeatable; does not affect existing tags)
+        #[arg(long = "add-tag")]
+        add_tags: Vec<String>,
+        /// Remove a tag (repeatable)
+        #[arg(long = "remove-tag")]
+        remove_tags: Vec<String>,
+        /// Set or overwrite a metadata field: key=value (repeatable, @file supported)
+        #[arg(long = "meta", short = 'm')]
+        meta: Vec<String>,
+        /// 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>,
+        /// 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>,
+    },
+
+    /// Check for a newer version and update the binary in-place.
+    ///
+    /// Downloads the latest release from Gitea and replaces the current binary.
+    /// No database connection or master key required.
+    #[command(after_help = "EXAMPLES:
+  # Check for updates only (no download)
+  secrets upgrade --check
+
+  # Download and install the latest version
+  secrets upgrade")]
+    Upgrade {
+        /// Only check if a newer version is available; do not download
+        #[arg(long)]
+        check: bool,
+    },
+}
+
+#[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;
+    }
+
+    // upgrade needs no database or master key either
+    if let Commands::Upgrade { check } = cli.command {
+        return commands::upgrade::run(check).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 { .. } | Commands::Upgrade { .. } => unreachable!(),
+
         Commands::Add {
             namespace,
             kind,
@@ -99,32 +465,195 @@ 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,
+            name,
+            add_tags,
+            remove_tags,
+            meta,
+            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,
+                    kind: &kind,
+                    name: &name,
+                    add_tags: &add_tags,
+                    remove_tags: &remove_tags,
+                    meta_entries: &meta,
+                    remove_meta: &remove_meta,
+                    secret_entries: &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?;
         }
     }
 

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

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