feat: 客户端加密 encrypted 字段，数据库只存密文 (v0.5.0)

- 新增 src/crypto.rs：AES-256-GCM 加解密 + Argon2id 密钥派生 + OS Keychain 读写 - 新增 `secrets init` 命令：输入 Master Password，派生 Master Key 存入 Keychain - 新增 `secrets migrate-encrypt` 命令：将旧明文 JSONB 数据批量加密 - 修改 db.rs：encrypted 列 JSONB → BYTEA，新增 kv_config 表（存 Argon2id salt） - 修改 models.rs：encrypted 字段类型 Value → Vec<u8> - 修改 add/update：写入前 encrypt_json，update 读取后 decrypt → 合并 → 重新加密 - 修改 search：按需解密，未解密时显示 _encrypted:true/_key_count:N - 通过 6 个 crypto 单元测试（加解密、JSON roundtrip、Argon2id 确定性） Made-with: Cursor
feat: AI 优先的 search 增强与结构化输出 (v0.4.0)
2026-03-18 20:10:13 +08:00 · 2026-03-18 17:17:43 +08:00 · 2026-03-18 16:32:45 +08:00
17 changed files with 1680 additions and 299 deletions
--- a/.gitea/workflows/secrets.yml
+++ b/.gitea/workflows/secrets.yml
@@ -164,7 +164,7 @@ jobs:
    name: Build (x86_64-unknown-linux-musl)
    needs: [version, check]
    runs-on: debian
-    timeout-minutes: 10
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        run: |
@@ -208,12 +208,31 @@ jobs:
            -F "attachment=@${archive}" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"

+      - name: 飞书通知
+        if: always()
+        env:
+          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
+        run: |
+          [ -z "$WEBHOOK_URL" ] && exit 0
+          command -v jq >/dev/null 2>&1 || (sudo apt-get update -qq && sudo apt-get install -y -qq jq)
+          tag="${{ needs.version.outputs.tag }}"
+          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
+          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
+          result="${{ job.status }}"
+          if [ "$result" = "success" ]; then icon="✅"; else icon="❌"; fi
+          msg="secrets linux 构建${icon}
+          版本：${tag}
+          提交：${commit}
+          作者：${{ github.actor }}
+          详情：${url}"
+          payload=$(jq -n --arg text "$msg" '{msg_type: "text", content: {text: $text}}')
+          curl -sS -H "Content-Type: application/json" -X POST -d "$payload" "$WEBHOOK_URL"
+
  build-macos:
    name: Build (aarch64-apple-darwin)
    needs: [version, check]
-    if: vars.BUILD_MACOS != 'false'
    runs-on: darwin-arm64
-    timeout-minutes: 10
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        run: |
@@ -255,12 +274,30 @@ jobs:
            -F "attachment=@${archive}" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${{ needs.version.outputs.release_id }}/assets"

+      - name: 飞书通知
+        if: always()
+        env:
+          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
+        run: |
+          [ -z "$WEBHOOK_URL" ] && exit 0
+          tag="${{ needs.version.outputs.tag }}"
+          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
+          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
+          result="${{ job.status }}"
+          if [ "$result" = "success" ]; then icon="✅"; else icon="❌"; fi
+          msg="secrets macOS 构建${icon}
+          版本：${tag}
+          提交：${commit}
+          作者：${{ github.actor }}
+          详情：${url}"
+          payload=$(python3 -c "import json,sys; print(json.dumps({'msg_type':'text','content':{'text':sys.argv[1]}}))" "$msg")
+          curl -sS -H "Content-Type: application/json" -X POST -d "$payload" "$WEBHOOK_URL"
+
  build-windows:
    name: Build (x86_64-pc-windows-msvc)
    needs: [version, check]
-    if: vars.BUILD_WINDOWS == 'true'
    runs-on: windows
-    timeout-minutes: 10
+    timeout-minutes: 15
    steps:
      - name: 安装依赖
        shell: pwsh
@@ -306,13 +343,32 @@ jobs:
            -Headers @{ "Authorization" = "token $env:RELEASE_TOKEN" } `
            -Form @{ attachment = Get-Item $archive }

+      - name: 飞书通知
+        if: always()
+        shell: pwsh
+        env:
+          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
+        run: |
+          if (-not $env:WEBHOOK_URL) { exit 0 }
+          $tag = "${{ needs.version.outputs.tag }}"
+          $commit = (git log -1 --pretty=format:"%s" 2>$null) ?? "N/A"
+          $url = "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"
+          $result = "${{ job.status }}"
+          $icon = if ($result -eq "success") { "✅" } else { "❌" }
+          $msg = "secrets windows 构建${icon}`n版本：${tag}`n提交：${commit}`n作者：${{ github.actor }}`n详情：${url}"
+          $payload = @{ msg_type = "text"; content = @{ text = $msg } } | ConvertTo-Json
+          Invoke-RestMethod -Uri $env:WEBHOOK_URL -Method Post `
+            -ContentType "application/json" -Body $payload
+
  publish-release:
    name: 发布草稿 Release
    needs: [version, build-linux]
-    if: needs.version.outputs.release_id != ''
+    if: always() && needs.version.outputs.release_id != ''
    runs-on: debian
-    timeout-minutes: 2
+    timeout-minutes: 5
    steps:
+      - uses: actions/checkout@v4
+
      - name: 发布草稿
        env:
          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
@@ -337,21 +393,12 @@ jobs:
            cat /tmp/publish-release.json 2>/dev/null || true
            exit 1
          fi
+          echo "Release 已发布"

-  notify:
-    name: 通知
-    needs: [version, check]
-    if: always() && github.event_name == 'push'
-    runs-on: debian
-    timeout-minutes: 1
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: 发送飞书通知
+      - name: 飞书汇总通知
+        if: always()
        env:
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
-          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
        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)
@@ -361,59 +408,29 @@ jobs:
          commit=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "N/A")
          url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_number }}"

-          version_r="${{ needs.version.result }}"
-          check_r="${{ needs.check.result }}"
+          check_r="${{ needs.version.result }}"
+          linux_r="${{ needs.build-linux.result }}"
+          publish_r="${{ job.status }}"

-          # 通过 API 查询当前 run 的构建 job 状态（best-effort）
-          linux_r="unknown"; macos_r="unknown"; windows_r="unknown"; publish_r="unknown"
-          if [ -n "$RELEASE_TOKEN" ]; then
-            sleep 3
-            run_api="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/actions/tasks"
-            http_code=$(curl -sS -o /tmp/jobs.json -w '%{http_code}' \
-              -H "Authorization: token $RELEASE_TOKEN" "$run_api" 2>/dev/null) || true
-            if [ "$http_code" = "200" ] && [ -f /tmp/jobs.json ]; then
-              get_status() {
-                jq -r --arg name "$1" '
-                  (.workflow_runs // .task_runs // . // [])[]?
-                  | select(.name == $name)
-                  | .status // "unknown"
-                ' /tmp/jobs.json 2>/dev/null | head -1
-              }
-              s=$(get_status "Build (x86_64-unknown-linux-musl)"); [ -n "$s" ] && linux_r="$s"
-              s=$(get_status "Build (aarch64-apple-darwin)"); [ -n "$s" ] && macos_r="$s"
-              s=$(get_status "Build (x86_64-pc-windows-msvc)"); [ -n "$s" ] && windows_r="$s"
-              s=$(get_status "发布草稿 Release"); [ -n "$s" ] && publish_r="$s"
-            fi
-          fi
+          icon() { case "$1" in success) echo "✅";; skipped) echo "⏭";; *) echo "❌";; esac; }

-          if [ "$version_r" = "success" ] && [ "$check_r" = "success" ]; then
-            status="检查通过 ✅"
+          if [ "$linux_r" = "success" ] && [ "$publish_r" = "success" ]; then
+            status="发布成功 ✅"
+          elif [ "$linux_r" != "success" ]; then
+            status="构建失败 ❌"
          else
-            status="检查失败 ❌"
+            status="发布失败 ❌"
          fi

-          icon() {
-            case "$1" in
-              success) echo "✅" ;;
-              skipped) echo "⏭" ;;
-              unknown) echo "⏳" ;;
-              *) echo "❌" ;;
-            esac
-          }
-
-          msg="${{ env.BINARY_NAME }} ${status}"
          if [ "$tag_exists" = "false" ]; then
-            msg="${msg}
-          🆕 新版本 ${tag}"
+            version_line="🆕 新版本 ${tag}"
          else
-            msg="${msg}
-          🔄 重复构建 ${tag}"
+            version_line="🔄 重复构建 ${tag}"
          fi

-          msg="${msg}
-          质量检查：$(icon "$check_r")
-          构建结果：linux$(icon "$linux_r") macOS$(icon "$macos_r") windows$(icon "$windows_r")
-          Release：$(icon "$publish_r")
+          msg="secrets ${status}
+          ${version_line}
+          linux $(icon "$linux_r") | Release $(icon "$publish_r")
          提交：${commit}
          作者：${{ github.actor }}
          详情：${url}"
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 /target
 .env
-.DS_Store
+.DS_Store
+.cursor/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,14 +8,15 @@
 secrets/
  src/
    main.rs              # CLI 入口，clap 命令定义，auto-migrate，--verbose 全局参数
+    output.rs            # OutputMode 枚举 + TTY 检测（TTY→text，非 TTY→json-compact）
    config.rs            # 配置读写：~/.config/secrets/config.toml（database_url）
    db.rs                # PgPool 创建 + 建表/索引（幂等，含 audit_log）
    models.rs            # Secret 结构体（sqlx::FromRow + serde）
    audit.rs             # 审计写入：向 audit_log 表记录所有写操作
    commands/
-      add.rs             # add 命令：upsert，支持 --meta key=value / --secret key=@file
+      add.rs             # add 命令：upsert，支持 --meta key=value / --secret key=@file / -o json
      config.rs          # config 命令：set-db / show / path（持久化 database_url）
-      search.rs          # search 命令：多条件动态查询
+      search.rs          # search 命令：多条件查询，-f/-o/--summary/--limit/--offset/--sort
      delete.rs          # delete 命令
      update.rs          # update 命令：增量更新（合并 tags/metadata/encrypted）
  scripts/
@@ -27,9 +28,9 @@ secrets/

 ## 数据库

- **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`（主表）+ `audit_log`（审计表），首次连接自动建表（auto-migrate）

 ### 表结构
@@ -80,8 +81,8 @@ audit_log (
 首次使用需显式配置数据库连接，设置一次后在该设备上持久生效：

 ```bash
-secrets config set-db "postgres://postgres:<password>@47.117.131.22:5432/secrets"
-secrets config show    # 查看当前配置（密码脱敏）
+secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
+secrets config show   # 查看当前配置（密码脱敏）
 secrets config path   # 打印配置文件路径
 ```

@@ -89,50 +90,90 @@ secrets config path   # 打印配置文件路径

 ## CLI 命令

+### AI 使用主路径
+
+**读取一律用 `search`，写入用 `add` / `update`，避免反复查帮助。**
+
+输出格式规则：
+- TTY（终端直接运行）→ 默认 `text`
+- 非 TTY（管道/重定向/AI 调用）→ 自动 `json-compact`
+- 显式 `-o json` → 美化 JSON
+- 显式 `-o env` → KEY=VALUE（可 source）
+
+---
+
+### search — 发现与读取
+
 ```bash
-# 查看版本
-secrets -V / --version
+# 参数说明（带典型值）
+#   -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 -h / --help
-secrets help <subcommand>   # 子命令详细帮助，如 secrets help add
+# 发现概览（起步推荐）
+secrets search --summary --limit 20
+secrets search -n refining --summary --limit 20
+secrets search --sort updated --limit 10 --summary

-# 添加或更新记录（upsert）
-secrets add -n <namespace> --kind <kind> --name <name> \
-  [--tag <tag>]...          # 可重复
-  [-m key=value]...         # --meta 明文字段，-m 是短标志
-  [-s key=value]...         # --secret 敏感字段，value 以 @ 开头表示从文件读取
+# 精确定位单条记录
+secrets search -n refining --kind service --name gitea
+secrets search -n refining --kind server --name i-uf63f2uookgs5uxmrdyc

-# 搜索（默认隐藏 encrypted 内容）
-secrets search [-n <namespace>] [--kind <kind>] [--tag <tag>] [-q <keyword>] [--show-secrets]
-# -q 匹配范围：name、namespace、kind、metadata 全文内容、tags
+# 精确定位并获取完整内容（含 secrets）
+secrets search -n refining --kind service --name gitea -o json --show-secrets

-# 开启 debug 级别日志（全局参数，位于子命令之前）
-secrets --verbose <subcommand>
-secrets -v <subcommand>
-# 或通过环境变量控制：RUST_LOG=secrets=trace secrets search
+# 直接提取字段值（最短路径，-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 update -n <namespace> --kind <kind> --name <name> \
-  [--add-tag <tag>]...        # 添加标签（不影响已有标签）
-  [--remove-tag <tag>]...     # 移除标签
-  [-m key=value]...           # 新增或覆盖 metadata 字段（不影响其他字段）
-  [--remove-meta <key>]...    # 删除 metadata 字段
-  [-s key=value]...           # 新增或覆盖 encrypted 字段（不影响其他字段）
-  [--remove-secret <key>]...  # 删除 encrypted 字段
+# 模糊关键词搜索
+secrets search -q mqtt
+secrets search -q grafana
+secrets search -q 47.117

-# 删除
-secrets delete -n <namespace> --kind <kind> --name <name>
+# 按条件过滤
+secrets search -n refining --kind service
+secrets search -n ricnsmart --kind server
+secrets search --tag hongkong
+secrets search --tag aliyun --summary

-# 配置（持久化 database_url，设置一次即可）
-secrets config set-db <url>
-secrets config show
-secrets config path
+# 分页
+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 \
@@ -142,30 +183,101 @@ 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 \
-  -s token=<token>
+  -m url=https://gitea.refining.dev -m default_org=refining -m username=voson \
+  -s token=<token> -s runner_token=<runner_token>

-# 搜索含 mqtt 的所有记录
-secrets search -q mqtt
+# 从文件读取 token
+secrets add -n ricnsmart --kind service --name mqtt \
+  -m host=mqtt.ricnsmart.com -m port=1883 \
+  -s password=@./mqtt_password.txt
+```

-# 查看 refining 的全部服务配置（显示 secrets）
-secrets search -n refining --kind service --show-secrets
+---

-# 按 tag 筛选
-secrets search --tag hongkong
+### update — 增量更新（记录必须已存在）

-# 只更新一个 IP（不影响其他 metadata/secrets/tags）
+只有传入的字段才会变动，其余全部保留。
+
+```bash
+# 参数说明（带典型值）
+#   -n / --namespace   refining | ricnsmart
+#   --kind             server | service
+#   --name             gitea | i-uf63f2uookgs5uxmrdyc
+#   --add-tag          production | backup（不影响已有 tag，可重复）
+#   --remove-tag       staging | deprecated（可重复）
+#   -m / --meta        ip=10.0.0.1 | desc="新描述"（新增或覆盖，可重复）
+#   --remove-meta      old_port | legacy_key（删除 metadata 字段，可重复）
+#   -s / --secret      token=<new> | ssh_key=@./new.pem（新增或覆盖，可重复）
+#   --remove-secret    old_password | deprecated_key（删除 secret 字段，可重复）
+
+# 更新单个 metadata 字段
 secrets update -n refining --kind server --name i-uf63f2uookgs5uxmrdyc \
  -m ip=10.0.0.1

-# 给一条记录新增 tag 并轮换密码
+# 轮换 token
+secrets update -n refining --kind service --name gitea \
+  -s token=<new-token>
+
+# 新增 tag 并轮换 token
 secrets update -n refining --kind service --name gitea \
  --add-tag production \
  -s token=<new-token>

-# 移除一个废弃的 metadata 字段
+# 移除废弃字段
 secrets update -n refining --kind service --name mqtt \
-  --remove-meta old_port
+  --remove-meta old_port --remove-secret old_password
+
+# 移除 tag
+secrets update -n refining --kind service --name gitea --remove-tag staging
+```
+
+---
+
+### delete — 删除记录
+
+```bash
+# 参数说明（带典型值）
+#   -n / --namespace   refining | ricnsmart
+#   --kind             server | service
+#   --name             gitea | i-uf63f2uookgs5uxmrdyc（必须精确匹配）
+
+# 删除服务凭据
+secrets delete -n refining --kind service --name legacy-mqtt
+
+# 删除服务器记录
+secrets delete -n ricnsmart --kind server --name i-old-server-id
+```
+
+---
+
+### 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
 ```

 ## 代码规范
@@ -174,9 +286,10 @@ secrets update -n refining --kind service --name mqtt \
 - 异步：全程 `tokio`，数据库操作 `sqlx` async
 - SQL：使用 `sqlx::query` / `sqlx::query_as` 绑定参数，禁止字符串拼接（搜索的动态 WHERE 子句除外，需使用参数绑定 `$1/$2`）
 - 新增 `kind` 类型时：只需在 `add` 调用时传入，无需改代码
- 字段命名：CLI 短标志 `-n`=namespace，`-m`=meta，`-s`=secret，`-q`=query，`-v`=verbose
+- 字段命名：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 不中断
+- 输出：读命令通过 `OutputMode` 支持 text/json/json-compact/env；写命令 `add` 同样支持 `-o json`

 ## 提交前检查（必须全部通过）

@@ -194,7 +307,7 @@ grep '^version' Cargo.toml
 git tag -l 'secrets-*'
 ```

-若当前版本已被 tag（例如已有 `secrets-0.1.0` 且 `Cargo.toml` 仍为 `0.1.0`），则应在 `Cargo.toml` 中 bump 版本号后再提交，以便 CI 自动打新 Tag 并发布 Release。
+若当前版本已被 tag（例如已有 `secrets-0.3.0` 且 `Cargo.toml` 仍为 `0.3.0`），则应在 `Cargo.toml` 中 bump 版本号后再提交，以便 CI 自动打新 Tag 并发布 Release。

 ### 2. 格式、Lint、测试

--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,6 +2,41 @@
 # It is not intended for manual editing.
 version = 4

+[[package]]
+name = "aead"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
+dependencies = [
+ "crypto-common",
+ "generic-array",
+]
+
+[[package]]
+name = "aes"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
+dependencies = [
+ "cfg-if",
+ "cipher",
+ "cpufeatures 0.2.17",
+]
+
+[[package]]
+name = "aes-gcm"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
+dependencies = [
+ "aead",
+ "aes",
+ "cipher",
+ "ctr",
+ "ghash",
+ "subtle",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -82,6 +117,18 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"

+[[package]]
+name = "argon2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+dependencies = [
+ "base64ct",
+ "blake2",
+ "cpufeatures 0.2.17",
+ "password-hash",
+]
+
 [[package]]
 name = "atoi"
 version = "2.0.0"
@@ -118,6 +165,15 @@ dependencies = [
 "serde_core",
 ]

+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -161,6 +217,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"

+[[package]]
+name = "chacha20"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.0",
+]
+
 [[package]]
 name = "chrono"
 version = "0.4.44"
@@ -175,6 +242,16 @@ dependencies = [
 "windows-link",
 ]

+[[package]]
+name = "cipher"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
+dependencies = [
+ "crypto-common",
+ "inout",
+]
+
 [[package]]
 name = "clap"
 version = "4.6.0"
@@ -236,6 +313,26 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"

+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
@@ -251,6 +348,15 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc"
 version = "3.4.0"
@@ -288,9 +394,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
 "generic-array",
+ "rand_core 0.6.4",
 "typenum",
 ]

+[[package]]
+name = "ctr"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
+dependencies = [
+ "cipher",
+]
+
 [[package]]
 name = "der"
 version = "0.7.10"
@@ -532,10 +648,21 @@ dependencies = [
 "cfg-if",
 "libc",
 "r-efi",
+ "rand_core 0.10.0",
 "wasip2",
 "wasip3",
 ]

+[[package]]
+name = "ghash"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
+dependencies = [
+ "opaque-debug",
+ "polyval",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -745,6 +872,15 @@ dependencies = [
 "serde_core",
 ]

+[[package]]
+name = "inout"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
@@ -767,6 +903,18 @@ dependencies = [
 "wasm-bindgen",
 ]

+[[package]]
+name = "keyring"
+version = "3.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
+dependencies = [
+ "log",
+ "security-framework 2.11.1",
+ "security-framework 3.7.0",
+ "zeroize",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -893,7 +1041,7 @@ dependencies = [
 "num-integer",
 "num-iter",
 "num-traits",
- "rand",
+ "rand 0.8.5",
 "smallvec",
 "zeroize",
 ]
@@ -940,6 +1088,12 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"

+[[package]]
+name = "opaque-debug"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
+
 [[package]]
 name = "option-ext"
 version = "0.2.0"
@@ -975,6 +1129,17 @@ dependencies = [
 "windows-link",
 ]

+[[package]]
+name = "password-hash"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
+dependencies = [
+ "base64ct",
+ "rand_core 0.6.4",
+ "subtle",
+]
+
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
@@ -1029,6 +1194,18 @@ version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"

+[[package]]
+name = "polyval"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "opaque-debug",
+ "universal-hash",
+]
+
 [[package]]
 name = "potential_utf"
 version = "0.1.4"
@@ -1089,7 +1266,18 @@ checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
 dependencies = [
 "libc",
 "rand_chacha",
- "rand_core",
+ "rand_core 0.6.4",
+]
+
+[[package]]
+name = "rand"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.2",
+ "rand_core 0.10.0",
 ]

 [[package]]
@@ -1099,7 +1287,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
 dependencies = [
 "ppv-lite86",
- "rand_core",
+ "rand_core 0.6.4",
 ]

 [[package]]
@@ -1111,6 +1299,12 @@ dependencies = [
 "getrandom 0.2.17",
 ]

+[[package]]
+name = "rand_core"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -1171,6 +1365,17 @@ dependencies = [
 "windows-sys 0.52.0",
 ]

+[[package]]
+name = "rpassword"
+version = "7.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66d4c8b64f049c6721ec8ccec37ddfc3d641c4a7fca57e8f2a89de509c73df39"
+dependencies = [
+ "libc",
+ "rtoolbox",
+ "windows-sys 0.59.0",
+]
+
 [[package]]
 name = "rsa"
 version = "0.9.10"
@@ -1184,13 +1389,23 @@ dependencies = [
 "num-traits",
 "pkcs1",
 "pkcs8",
- "rand_core",
+ "rand_core 0.6.4",
 "signature",
 "spki",
 "subtle",
 "zeroize",
 ]

+[[package]]
+name = "rtoolbox"
+version = "0.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7cc970b249fbe527d6e02e0a227762c9108b2f49d81094fe357ffc6d14d7f6f"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "rustls"
 version = "0.23.36"
@@ -1245,12 +1460,17 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"

 [[package]]
 name = "secrets"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
+ "aes-gcm",
 "anyhow",
+ "argon2",
 "chrono",
 "clap",
 "dirs",
+ "keyring",
+ "rand 0.10.0",
+ "rpassword",
 "serde",
 "serde_json",
 "sqlx",
@@ -1261,6 +1481,42 @@ dependencies = [
 "uuid",
 ]

+[[package]]
+name = "security-framework"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
+dependencies = [
+ "bitflags",
+ "core-foundation 0.9.4",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags",
+ "core-foundation 0.10.1",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.27"
@@ -1338,7 +1594,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
 dependencies = [
 "cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 "digest",
 ]

@@ -1349,7 +1605,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
 "cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 "digest",
 ]

@@ -1385,7 +1641,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
 "digest",
- "rand_core",
+ "rand_core 0.6.4",
 ]

 [[package]]
@@ -1551,7 +1807,7 @@ dependencies = [
 "memchr",
 "once_cell",
 "percent-encoding",
- "rand",
+ "rand 0.8.5",
 "rsa",
 "serde",
 "sha1",
@@ -1591,7 +1847,7 @@ dependencies = [
 "md-5",
 "memchr",
 "once_cell",
- "rand",
+ "rand 0.8.5",
 "serde",
 "serde_json",
 "sha2",
@@ -1914,6 +2170,16 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"

+[[package]]
+name = "universal-hash"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
+dependencies = [
+ "crypto-common",
+ "subtle",
+]
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -2188,6 +2454,15 @@ dependencies = [
 "windows-targets 0.52.6",
 ]

+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,13 +1,18 @@
 [package]
 name = "secrets"
-version = "0.3.0"
+version = "0.5.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"] }
 dirs = "6.0.0"
+keyring = { version = "3.6.3", features = ["apple-native"] }
+rand = "0.10.0"
+rpassword = "7.4.0"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
 sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
--- a/README.md
+++ b/README.md
@@ -14,60 +14,116 @@ cargo build --release
 配置数据库连接（首次使用需执行一次，之后在该设备上持久生效）：

 ```bash
-secrets config set-db "postgres://postgres:<password>@<host>:5432/secrets"
+secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 ```

-## 使用
+## AI Agent 快速指南
+
+这个 CLI 以 AI 使用优先设计。核心路径只有一条：**读取用 `search`，写入用 `add` / `update`**。
+
+### 第一步：发现有哪些数据

 ```bash
-# 查看版本
-secrets -V
-secrets --version
+# 列出所有记录摘要（默认最多 50 条，安全起步）
+secrets search --summary --limit 20

-# 查看帮助
+# 按 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 search --help
+secrets add --help
+secrets update --help
+secrets delete --help
+secrets config --help

-# 查看子命令帮助
-secrets help config
-secrets help add
-secrets help search
-secrets help delete
-secrets help update
+# ── search ──────────────────────────────────────────────────────────────────
+secrets search --summary --limit 20                        # 发现概览
+secrets search -n refining --kind service                  # 按 namespace + kind
+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" \
-  -s username=root \
-  -s ssh_key=@./keys/my.pem
+  -m ip=47.117.131.22 -m desc="Aliyun Shanghai ECS" \
+  -s username=root -s ssh_key=@./keys/server.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>

-# 搜索（默认隐藏敏感字段）
-secrets search
-secrets search -n refining --kind server
-secrets search --tag hongkong
-secrets search -q mqtt              # 关键词匹配 name / metadata / tags
-secrets search -n refining --kind service --name gitea --show-secrets
-
-# 开启 debug 级别日志（--verbose / -v，全局参数）
-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
-
-# 增量更新已有记录（合并语义，记录不存在则报错）
+# ── update ───────────────────────────────────────────────────────────────────
 secrets update -n refining --kind server --name my-server -m ip=10.0.0.1
-secrets update -n refining --kind service --name gitea --add-tag production -s token=<new-token>
+secrets update -n refining --kind service --name gitea --add-tag production -s token=<new>
 secrets update -n refining --kind service --name mqtt --remove-meta old_port --remove-secret old_key

-# 删除
-secrets delete -n refining --kind server --name my-server
+# ── delete ───────────────────────────────────────────────────────────────────
+secrets delete -n refining --kind service --name legacy-mqtt
+
+# ── config ───────────────────────────────────────────────────────────────────
+secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
+secrets config show    # 密码脱敏展示
+secrets config path    # 打印配置文件路径
+
+# ── 调试 ──────────────────────────────────────────────────────────────────────
+secrets --verbose search -q mqtt
+RUST_LOG=secrets=trace secrets search
 ```

 ## 数据模型
@@ -101,15 +157,16 @@ LIMIT 20;

 ```
 src/
-  main.rs          # CLI 入口（clap）
+  main.rs          # CLI 入口（clap），含各子命令 after_help 示例
+  output.rs        # OutputMode 枚举 + TTY 检测
  config.rs        # 配置读写（~/.config/secrets/config.toml）
  db.rs            # 连接池 + auto-migrate（secrets + audit_log）
  models.rs        # Secret 结构体
  audit.rs         # 审计日志写入（audit_log 表）
  commands/
-    add.rs         # upsert
+    add.rs         # upsert，支持 -o json
    config.rs      # config set-db/show/path
-    search.rs      # 多条件查询
+    search.rs      # 多条件查询，支持 -f/-o/--summary/--limit/--offset/--sort
    delete.rs      # 删除
    update.rs      # 增量更新（合并 tags/metadata/encrypted）
 scripts/
--- a/src/commands/add.rs
+++ b/src/commands/add.rs
@@ -3,6 +3,9 @@ use serde_json::{Map, Value, json};
 use sqlx::PgPool;
 use std::fs;

+use crate::crypto;
+use crate::output::OutputMode;
+
 /// Parse "key=value" entries. Value starting with '@' reads from file.
 pub(crate) fn parse_kv(entry: &str) -> Result<(String, String)> {
    let (key, raw_val) = entry.split_once('=').ok_or_else(|| {
@@ -22,7 +25,7 @@ pub(crate) fn parse_kv(entry: &str) -> Result<(String, String)> {
    Ok((key.to_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)?;
@@ -31,19 +34,24 @@ fn build_json(entries: &[String]) -> Result<Value> {
    Ok(Value::Object(map))
 }

-pub async fn run(
-    pool: &PgPool,
-    namespace: &str,
-    kind: &str,
-    name: &str,
-    tags: &[String],
-    meta_entries: &[String],
-    secret_entries: &[String],
-) -> Result<()> {
-    let metadata = build_json(meta_entries)?;
-    let encrypted = build_json(secret_entries)?;
+pub struct AddArgs<'a> {
+    pub namespace: &'a str,
+    pub kind: &'a str,
+    pub name: &'a str,
+    pub tags: &'a [String],
+    pub meta_entries: &'a [String],
+    pub secret_entries: &'a [String],
+    pub output: OutputMode,
+}

-    tracing::debug!(namespace, kind, name, "upserting record");
+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)?;
+
+    // Encrypt the secret JSON before storing
+    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
+
+    tracing::debug!(args.namespace, args.kind, args.name, "upserting record");

    sqlx::query(
        r#"
@@ -57,20 +65,22 @@ pub async fn run(
            updated_at = NOW()
        "#,
    )
-    .bind(namespace)
-    .bind(kind)
-    .bind(name)
-    .bind(tags)
+    .bind(args.namespace)
+    .bind(args.kind)
+    .bind(args.name)
+    .bind(args.tags)
    .bind(&metadata)
-    .bind(&encrypted)
+    .bind(&encrypted_bytes)
    .execute(pool)
    .await?;

-    let meta_keys: Vec<&str> = meta_entries
+    let meta_keys: Vec<&str> = args
+        .meta_entries
        .iter()
        .filter_map(|s| s.split_once('=').map(|(k, _)| k))
        .collect();
-    let secret_keys: Vec<&str> = secret_entries
+    let secret_keys: Vec<&str> = args
+        .secret_entries
        .iter()
        .filter_map(|s| s.split_once('=').map(|(k, _)| k))
        .collect();
@@ -78,26 +88,46 @@ pub async fn run(
    crate::audit::log(
        pool,
        "add",
-        namespace,
-        kind,
-        name,
+        args.namespace,
+        args.kind,
+        args.name,
        json!({
-            "tags": tags,
+            "tags": args.tags,
            "meta_keys": meta_keys,
            "secret_keys": secret_keys,
        }),
    )
    .await;

-    println!("Added: [{}/{}] {}", namespace, kind, name);
-    if !tags.is_empty() {
-        println!("  tags:     {}", tags.join(", "));
-    }
-    if !meta_entries.is_empty() {
-        println!("  metadata: {}", meta_keys.join(", "));
-    }
-    if !secret_entries.is_empty() {
-        println!("  secrets:  {}", secret_keys.join(", "));
+    let result_json = json!({
+        "action": "added",
+        "namespace": args.namespace,
+        "kind": args.kind,
+        "name": args.name,
+        "tags": args.tags,
+        "meta_keys": meta_keys,
+        "secret_keys": secret_keys,
+    });
+
+    match args.output {
+        OutputMode::Json => {
+            println!("{}", serde_json::to_string_pretty(&result_json)?);
+        }
+        OutputMode::JsonCompact => {
+            println!("{}", serde_json::to_string(&result_json)?);
+        }
+        _ => {
+            println!("Added: [{}/{}] {}", args.namespace, args.kind, args.name);
+            if !args.tags.is_empty() {
+                println!("  tags:     {}", args.tags.join(", "));
+            }
+            if !args.meta_entries.is_empty() {
+                println!("  metadata: {}", meta_keys.join(", "));
+            }
+            if !args.secret_entries.is_empty() {
+                println!("  secrets:  {}", secret_keys.join(", "));
+            }
+        }
    }

    Ok(())
--- a/src/commands/init.rs
+++ b/src/commands/init.rs
@@ -0,0 +1,62 @@
+use anyhow::{Context, Result};
+use rand::RngExt;
+use sqlx::PgPool;
+
+use crate::{crypto, db};
+
+pub async fn run(pool: &PgPool) -> Result<()> {
+    println!("Initializing secrets master key...");
+    println!();
+
+    // Read password (no echo)
+    let password =
+        rpassword::prompt_password("Enter master password: ").context("failed to read password")?;
+    if password.is_empty() {
+        anyhow::bail!("Master password must not be empty.");
+    }
+    let confirm = rpassword::prompt_password("Confirm master password: ")
+        .context("failed to read password confirmation")?;
+    if password != confirm {
+        anyhow::bail!("Passwords do not match.");
+    }
+
+    // Get or create Argon2id salt
+    let salt = match db::load_argon2_salt(pool).await? {
+        Some(existing) => {
+            println!("Found existing salt in database (not the first device).");
+            existing
+        }
+        None => {
+            println!("Generating new Argon2id salt and storing in database...");
+            let mut salt = vec![0u8; 16];
+            rand::rng().fill(&mut salt[..]);
+            db::store_argon2_salt(pool, &salt).await?;
+            salt
+        }
+    };
+
+    // Derive master key
+    print!("Deriving master key (Argon2id, this takes a moment)... ");
+    let master_key = crypto::derive_master_key(&password, &salt)?;
+    println!("done.");
+
+    // Store in OS Keychain
+    crypto::store_master_key(&master_key)?;
+
+    // Self-test: encrypt and decrypt a canary value
+    let canary = b"secrets-cli-canary";
+    let enc = crypto::encrypt(&master_key, canary)?;
+    let dec = crypto::decrypt(&master_key, &enc)?;
+    if dec != canary {
+        anyhow::bail!("Self-test failed: encryption roundtrip mismatch");
+    }
+
+    println!();
+    println!("Master key stored in OS Keychain.");
+    println!("You can now use `secrets add` / `secrets search` commands.");
+    println!();
+    println!("IMPORTANT: Remember your master password — it is not stored anywhere.");
+    println!("           On a new device, run `secrets init` with the same password.");
+
+    Ok(())
+}
--- a/src/commands/migrate_encrypt.rs
+++ b/src/commands/migrate_encrypt.rs
@@ -0,0 +1,85 @@
+use anyhow::Result;
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use crate::crypto;
+
+/// Row fetched for migration
+#[derive(sqlx::FromRow)]
+struct MigrateRow {
+    id: Uuid,
+    namespace: String,
+    kind: String,
+    name: String,
+    encrypted: Vec<u8>,
+}
+
+/// Encrypt any records whose `encrypted` column contains raw (unencrypted) bytes.
+///
+/// After the schema migration, old JSONB rows were stored as raw UTF-8 bytes.
+/// A valid AES-256-GCM blob is always at least 28 bytes (12 nonce + 16 tag).
+/// We attempt to decrypt each row; if decryption fails, we assume it's plaintext
+/// JSON and re-encrypt it.
+pub async fn run(pool: &PgPool, master_key: &[u8; 32]) -> Result<()> {
+    println!("Scanning for unencrypted secret rows...");
+
+    let rows: Vec<MigrateRow> =
+        sqlx::query_as("SELECT id, namespace, kind, name, encrypted FROM secrets")
+            .fetch_all(pool)
+            .await?;
+
+    let total = rows.len();
+    let mut migrated = 0usize;
+    let mut already_encrypted = 0usize;
+    let mut skipped_empty = 0usize;
+
+    for row in rows {
+        if row.encrypted.is_empty() {
+            skipped_empty += 1;
+            continue;
+        }
+
+        // Try to decrypt; success → already encrypted, skip
+        if crypto::decrypt_json(master_key, &row.encrypted).is_ok() {
+            already_encrypted += 1;
+            continue;
+        }
+
+        // Treat as plaintext JSON bytes (from schema migration copy)
+        let json_str = String::from_utf8(row.encrypted.clone()).map_err(|_| {
+            anyhow::anyhow!(
+                "Row [{}/{}/{}]: encrypted column contains non-UTF-8 bytes that are also not valid ciphertext. Manual inspection required.",
+                row.namespace, row.kind, row.name
+            )
+        })?;
+
+        let value: serde_json::Value = serde_json::from_str(&json_str).map_err(|e| {
+            anyhow::anyhow!(
+                "Row [{}/{}/{}]: failed to parse as JSON: {}",
+                row.namespace,
+                row.kind,
+                row.name,
+                e
+            )
+        })?;
+
+        let encrypted_bytes = crypto::encrypt_json(master_key, &value)?;
+
+        sqlx::query("UPDATE secrets SET encrypted = $1, updated_at = NOW() WHERE id = $2")
+            .bind(&encrypted_bytes)
+            .bind(row.id)
+            .execute(pool)
+            .await?;
+
+        println!("  Encrypted: [{}/{}] {}", row.namespace, row.kind, row.name);
+        migrated += 1;
+    }
+
+    println!();
+    println!(
+        "Done. Total: {total}, encrypted this run: {migrated}, \
+         already encrypted: {already_encrypted}, empty (skipped): {skipped_empty}"
+    );
+
+    Ok(())
+}
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -1,5 +1,7 @@
 pub mod add;
 pub mod config;
 pub mod delete;
+pub mod init;
+pub mod migrate_encrypt;
 pub mod search;
 pub mod update;
--- a/src/commands/search.rs
+++ b/src/commands/search.rs
@@ -1,36 +1,52 @@
 use anyhow::Result;
+use serde_json::{Value, json};
 use sqlx::PgPool;

+use crate::crypto;
 use crate::models::Secret;
+use crate::output::OutputMode;

-pub async fn run(
-    pool: &PgPool,
-    namespace: Option<&str>,
-    kind: Option<&str>,
-    tag: Option<&str>,
-    query: Option<&str>,
-    show_secrets: bool,
-) -> Result<()> {
+pub struct SearchArgs<'a> {
+    pub namespace: Option<&'a str>,
+    pub kind: Option<&'a str>,
+    pub name: Option<&'a str>,
+    pub tag: Option<&'a str>,
+    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 mut conditions: Vec<String> = Vec::new();
    let mut idx: i32 = 1;

-    if namespace.is_some() {
+    if args.namespace.is_some() {
        conditions.push(format!("namespace = ${}", idx));
        idx += 1;
    }
-    if kind.is_some() {
+    if args.kind.is_some() {
        conditions.push(format!("kind = ${}", idx));
        idx += 1;
    }
-    if tag.is_some() {
+    if args.name.is_some() {
+        conditions.push(format!("name = ${}", idx));
+        idx += 1;
+    }
+    if args.tag.is_some() {
        conditions.push(format!("tags @> ARRAY[${}]", idx));
        idx += 1;
    }
-    if query.is_some() {
+    if args.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}))",
            i = idx
        ));
+        idx += 1;
    }

    let where_clause = if conditions.is_empty() {
@@ -39,74 +55,290 @@ pub async fn run(
        format!("WHERE {}", conditions.join(" AND "))
    };

+    let order = match args.sort {
+        "updated" => "updated_at DESC",
+        "created" => "created_at DESC",
+        _ => "namespace, kind, name",
+    };
+
    let sql = format!(
-        "SELECT * FROM secrets {} ORDER BY namespace, kind, name",
-        where_clause
+        "SELECT * FROM secrets {} ORDER BY {} LIMIT ${} OFFSET ${}",
+        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) = args.namespace {
        q = q.bind(v);
    }
-    if let Some(v) = kind {
+    if let Some(v) = args.kind {
        q = q.bind(v);
    }
-    if let Some(v) = tag {
+    if let Some(v) = args.name {
        q = q.bind(v);
    }
-    if let Some(v) = query {
+    if let Some(v) = args.tag {
+        q = q.bind(v);
+    }
+    if let Some(v) = args.query {
        q = q.bind(format!("%{}%", v));
    }
+    q = q.bind(args.limit as i64).bind(args.offset as i64);

    let rows = q.fetch_all(pool).await?;

-    if rows.is_empty() {
-        println!("No records found.");
-        return Ok(());
+    // -f/--field: extract specific field values directly
+    if !args.fields.is_empty() {
+        return print_fields(&rows, args.fields, master_key);
    }

-    for row in &rows {
-        println!("[{}/{}] {}", row.namespace, row.kind, row.name,);
-        println!("  id:       {}", row.id);
+    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() {
+                print_env(row, args.show_secrets, master_key)?;
+            } 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(())
+}
+
+/// Decrypt the encrypted blob for a row. Returns an empty object on empty blobs.
+/// Returns an error value on decrypt failure (so callers can decide how to handle).
+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, "_key_count": encrypted_key_count(row, master_key)})
+    };
+
+    json!({
+        "id": row.id,
+        "namespace": row.namespace,
+        "kind": row.kind,
+        "name": row.name,
+        "tags": row.tags,
+        "metadata": row.metadata,
+        "secrets": secrets_val,
+        "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(),
+    })
+}
+
+/// Return the number of keys in the encrypted JSON (decrypts to count; 0 on failure).
+fn encrypted_key_count(row: &Secret, master_key: Option<&[u8; 32]>) -> usize {
+    if row.encrypted.is_empty() {
+        return 0;
+    }
+    let Some(key) = master_key else { return 0 };
+    match crypto::decrypt_json(key, &row.encrypted) {
+        Ok(Value::Object(m)) => m.len(),
+        _ => 0,
+    }
+}
+
+fn print_text(
+    row: &Secret,
+    show_secrets: bool,
+    summary: bool,
+    master_key: Option<&[u8; 32]>,
+) -> Result<()> {
+    println!("[{}/{}] {}", row.namespace, row.kind, row.name);
+    if summary {
+        let desc = row
+            .metadata
+            .get("desc")
+            .or_else(|| row.metadata.get("url"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("-");
+        if !row.tags.is_empty() {
+            println!("  tags:    [{}]", row.tags.join(", "));
+        }
+        println!("  desc:    {}", desc);
+        println!(
+            "  updated: {}",
+            row.updated_at.format("%Y-%m-%d %H:%M:%S UTC")
+        );
+    } else {
+        println!("  id:       {}", row.id);
        if !row.tags.is_empty() {
            println!("  tags:     [{}]", row.tags.join(", "));
        }
-
        if row.metadata.as_object().is_some_and(|m| !m.is_empty()) {
            println!(
                "  metadata: {}",
                serde_json::to_string_pretty(&row.metadata)?
            );
        }
-
-        if show_secrets {
-            println!(
-                "  secrets:  {}",
-                serde_json::to_string_pretty(&row.encrypted)?
-            );
-        } 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(", ")
-                );
+        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!(
            "  created:  {}",
            row.created_at.format("%Y-%m-%d %H:%M:%S UTC")
        );
-        println!();
    }
-    println!("{} record(s) found.", rows.len());
+    println!();
    Ok(())
 }
+
+fn print_env(row: &Secret, show_secrets: bool, master_key: Option<&[u8; 32]>) -> Result<()> {
+    let prefix = row.name.to_uppercase().replace(['-', '.'], "_");
+    if let Some(meta) = row.metadata.as_object() {
+        for (k, v) in meta {
+            let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
+            println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+        }
+    }
+    if show_secrets {
+        let decrypted = try_decrypt(row, master_key)?;
+        if let Some(enc) = decrypted.as_object() {
+            for (k, v) in enc {
+                let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
+                println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+            }
+        }
+    }
+    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 {
+        // Decrypt once per row if any field requires it
+        let decrypted: Option<Value> = if fields
+            .iter()
+            .any(|f| f.starts_with("secret") || f.starts_with("encrypted"))
+        {
+            Some(try_decrypt(row, master_key)?)
+        } else {
+            None
+        };
+
+        for field in fields {
+            let val = extract_field(row, field, decrypted.as_ref())?;
+            println!("{}", val);
+        }
+    }
+    Ok(())
+}
+
+fn extract_field(row: &Secret, field: &str, decrypted: Option<&Value>) -> Result<String> {
+    let (section, key) = field.split_once('.').ok_or_else(|| {
+        anyhow::anyhow!(
+            "Invalid field path '{}'. Use metadata.<key> or secret.<key>",
+            field
+        )
+    })?;
+
+    let obj = match section {
+        "metadata" | "meta" => &row.metadata,
+        "secret" | "secrets" | "encrypted" => {
+            decrypted.ok_or_else(|| anyhow::anyhow!("secret field requires master key"))?
+        }
+        other => anyhow::bail!(
+            "Unknown field section '{}'. Use 'metadata' or 'secret'",
+            other
+        ),
+    };
+
+    obj.get(key)
+        .and_then(|v| {
+            v.as_str()
+                .map(|s| s.to_string())
+                .or_else(|| Some(v.to_string()))
+        })
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "Field '{}' not found in record [{}/{}/{}]",
+                field,
+                row.namespace,
+                row.kind,
+                row.name
+            )
+        })
+}
--- a/src/commands/update.rs
+++ b/src/commands/update.rs
@@ -4,13 +4,14 @@ use sqlx::{FromRow, PgPool};
 use uuid::Uuid;

 use super::add::parse_kv;
+use crate::crypto;

 #[derive(FromRow)]
 struct UpdateRow {
    id: Uuid,
    tags: Vec<String>,
    metadata: Value,
-    encrypted: Value,
+    encrypted: Vec<u8>,
 }

 pub struct UpdateArgs<'a> {
@@ -25,7 +26,7 @@ pub struct UpdateArgs<'a> {
    pub remove_secrets: &'a [String],
 }

-pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
+pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
    let row: Option<UpdateRow> = sqlx::query_as(
        r#"
        SELECT id, tags, metadata, encrypted
@@ -71,8 +72,13 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
    }
    let metadata = Value::Object(meta_map);

-    // Merge encrypted
-    let mut enc_map: Map<String, Value> = match row.encrypted {
+    // 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(),
    };
@@ -83,7 +89,8 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
    for key in args.remove_secrets {
        enc_map.remove(key);
    }
-    let encrypted = Value::Object(enc_map);
+    let secret_json = Value::Object(enc_map);
+    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;

    tracing::debug!(
        namespace = args.namespace,
@@ -101,7 +108,7 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
    )
    .bind(&tags)
    .bind(metadata)
-    .bind(encrypted)
+    .bind(encrypted_bytes)
    .bind(row.id)
    .execute(pool)
    .await?;
--- a/src/crypto.rs
+++ b/src/crypto.rs
@@ -0,0 +1,192 @@
+use aes_gcm::{
+    Aes256Gcm, Key, Nonce,
+    aead::{Aead, AeadCore, KeyInit, OsRng},
+};
+use anyhow::{Context, Result, bail};
+use argon2::{Argon2, Params, Version};
+use serde_json::Value;
+
+const KEYRING_SERVICE: &str = "secrets-cli";
+const KEYRING_USER: &str = "master-key";
+const NONCE_LEN: usize = 12;
+
+// ─── Argon2id key derivation ─────────────────────────────────────────────────
+
+/// Derive a 32-byte Master Key from a password and salt using Argon2id.
+/// Parameters: m=65536 KiB (64 MB), t=3, p=4 — OWASP recommended.
+pub fn derive_master_key(password: &str, salt: &[u8]) -> Result<[u8; 32]> {
+    let params = Params::new(65536, 3, 4, Some(32)).context("invalid Argon2id params")?;
+    let argon2 = Argon2::new(argon2::Algorithm::Argon2id, Version::V0x13, params);
+    let mut key = [0u8; 32];
+    argon2
+        .hash_password_into(password.as_bytes(), salt, &mut key)
+        .map_err(|e| anyhow::anyhow!("Argon2id derivation failed: {}", e))?;
+    Ok(key)
+}
+
+// ─── AES-256-GCM encrypt / decrypt ───────────────────────────────────────────
+
+/// Encrypt plaintext bytes with AES-256-GCM.
+/// Returns `nonce (12 B) || ciphertext+tag`.
+pub fn encrypt(master_key: &[u8; 32], plaintext: &[u8]) -> Result<Vec<u8>> {
+    let key = Key::<Aes256Gcm>::from_slice(master_key);
+    let cipher = Aes256Gcm::new(key);
+    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
+    let ciphertext = cipher
+        .encrypt(&nonce, plaintext)
+        .map_err(|e| anyhow::anyhow!("AES-256-GCM encryption failed: {}", e))?;
+    let mut out = Vec::with_capacity(NONCE_LEN + ciphertext.len());
+    out.extend_from_slice(&nonce);
+    out.extend_from_slice(&ciphertext);
+    Ok(out)
+}
+
+/// Decrypt `nonce (12 B) || ciphertext+tag` with AES-256-GCM.
+pub fn decrypt(master_key: &[u8; 32], data: &[u8]) -> Result<Vec<u8>> {
+    if data.len() < NONCE_LEN {
+        bail!(
+            "encrypted data too short ({}B); possibly corrupted",
+            data.len()
+        );
+    }
+    let (nonce_bytes, ciphertext) = data.split_at(NONCE_LEN);
+    let key = Key::<Aes256Gcm>::from_slice(master_key);
+    let cipher = Aes256Gcm::new(key);
+    let nonce = Nonce::from_slice(nonce_bytes);
+    cipher
+        .decrypt(nonce, ciphertext)
+        .map_err(|_| anyhow::anyhow!("decryption failed — wrong master key or corrupted data"))
+}
+
+// ─── JSON helpers ─────────────────────────────────────────────────────────────
+
+/// Serialize a JSON Value and encrypt it. Returns the encrypted blob.
+pub fn encrypt_json(master_key: &[u8; 32], value: &Value) -> Result<Vec<u8>> {
+    let bytes = serde_json::to_vec(value).context("serialize JSON for encryption")?;
+    encrypt(master_key, &bytes)
+}
+
+/// Decrypt an encrypted blob and deserialize it as a JSON Value.
+pub fn decrypt_json(master_key: &[u8; 32], data: &[u8]) -> Result<Value> {
+    let bytes = decrypt(master_key, data)?;
+    serde_json::from_slice(&bytes).context("deserialize decrypted JSON")
+}
+
+// ─── OS Keychain ──────────────────────────────────────────────────────────────
+
+/// Load the Master Key from the OS Keychain.
+/// Returns an error with a helpful message if it hasn't been initialized.
+pub fn load_master_key() -> Result<[u8; 32]> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let hex = entry.get_password().map_err(|_| {
+        anyhow::anyhow!("Master key not found in keychain. Run `secrets init` first.")
+    })?;
+    let bytes = hex::decode_hex(&hex)?;
+    if bytes.len() != 32 {
+        bail!(
+            "stored master key has unexpected length {}; re-run `secrets init`",
+            bytes.len()
+        );
+    }
+    let mut key = [0u8; 32];
+    key.copy_from_slice(&bytes);
+    Ok(key)
+}
+
+/// Store the Master Key in the OS Keychain (overwrites any existing value).
+pub fn store_master_key(key: &[u8; 32]) -> Result<()> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let hex = hex::encode_hex(key);
+    entry
+        .set_password(&hex)
+        .map_err(|e| anyhow::anyhow!("keychain write failed: {}", e))?;
+    Ok(())
+}
+
+/// Delete the Master Key from the OS Keychain (used by tests / reset).
+#[cfg(test)]
+pub fn delete_master_key() -> Result<()> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let _ = entry.delete_credential();
+    Ok(())
+}
+
+// ─── Minimal hex helpers (avoid extra dep) ────────────────────────────────────
+
+mod hex {
+    use anyhow::{Result, bail};
+
+    pub fn encode_hex(bytes: &[u8]) -> String {
+        bytes.iter().map(|b| format!("{:02x}", b)).collect()
+    }
+
+    pub fn decode_hex(s: &str) -> Result<Vec<u8>> {
+        if !s.len().is_multiple_of(2) {
+            bail!("hex string has odd length");
+        }
+        (0..s.len())
+            .step_by(2)
+            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).map_err(|e| anyhow::anyhow!("{}", e)))
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn roundtrip_encrypt_decrypt() {
+        let key = [0x42u8; 32];
+        let plaintext = b"hello world";
+        let enc = encrypt(&key, plaintext).unwrap();
+        let dec = decrypt(&key, &enc).unwrap();
+        assert_eq!(dec, plaintext);
+    }
+
+    #[test]
+    fn encrypt_produces_different_ciphertexts() {
+        let key = [0x42u8; 32];
+        let plaintext = b"hello world";
+        let enc1 = encrypt(&key, plaintext).unwrap();
+        let enc2 = encrypt(&key, plaintext).unwrap();
+        // Different nonces → different ciphertexts
+        assert_ne!(enc1, enc2);
+    }
+
+    #[test]
+    fn wrong_key_fails_decryption() {
+        let key1 = [0x42u8; 32];
+        let key2 = [0x43u8; 32];
+        let enc = encrypt(&key1, b"secret").unwrap();
+        assert!(decrypt(&key2, &enc).is_err());
+    }
+
+    #[test]
+    fn json_roundtrip() {
+        let key = [0x42u8; 32];
+        let value = serde_json::json!({"token": "abc123", "password": "hunter2"});
+        let enc = encrypt_json(&key, &value).unwrap();
+        let dec = decrypt_json(&key, &enc).unwrap();
+        assert_eq!(dec, value);
+    }
+
+    #[test]
+    fn derive_master_key_deterministic() {
+        let salt = b"fixed_test_salt_";
+        let k1 = derive_master_key("password", salt).unwrap();
+        let k2 = derive_master_key("password", salt).unwrap();
+        assert_eq!(k1, k2);
+    }
+
+    #[test]
+    fn derive_master_key_different_passwords() {
+        let salt = b"fixed_test_salt_";
+        let k1 = derive_master_key("password1", salt).unwrap();
+        let k2 = derive_master_key("password2", salt).unwrap();
+        assert_ne!(k1, k2);
+    }
+}
--- a/src/db.rs
+++ b/src/db.rs
@@ -23,7 +23,7 @@ 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',
            created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
            updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
            UNIQUE(namespace, kind, name)
@@ -35,11 +35,37 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
        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 (not yet re-encrypted); run `secrets migrate-encrypt`
+        -- to encrypt them with the master key.
+        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,
@@ -60,3 +86,25 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
    tracing::debug!("migrations complete");
    Ok(())
 }
+
+/// Load the Argon2id salt from the database.
+/// Returns None if not yet initialized.
+pub async fn load_argon2_salt(pool: &PgPool) -> Result<Option<Vec<u8>>> {
+    let row: Option<(Vec<u8>,)> =
+        sqlx::query_as("SELECT value FROM kv_config WHERE key = 'argon2_salt'")
+            .fetch_optional(pool)
+            .await?;
+    Ok(row.map(|(v,)| v))
+}
+
+/// Store the Argon2id salt in the database (only called once on first device init).
+pub async fn store_argon2_salt(pool: &PgPool, salt: &[u8]) -> Result<()> {
+    sqlx::query(
+        "INSERT INTO kv_config (key, value) VALUES ('argon2_salt', $1) \
+         ON CONFLICT (key) DO NOTHING",
+    )
+    .bind(salt)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,18 +1,37 @@
 mod audit;
 mod commands;
 mod config;
+mod crypto;
 mod db;
 mod models;
+mod output;

 use anyhow::Result;
 use clap::{Parser, Subcommand};
 use tracing_subscriber::EnvFilter;

+use output::resolve_output_mode;
+
 #[derive(Parser)]
 #[command(
    name = "secrets",
    version,
-    about = "Secrets & config manager backed by PostgreSQL"
+    about = "Secrets & config manager backed by PostgreSQL — optimised for AI agents",
+    after_help = "QUICK START:
+  # First time setup (run 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, overrides saved config (one-time override)
@@ -29,72 +48,199 @@ struct Cli {

 #[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.
+    #[command(after_help = "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,
+
+    /// Encrypt any pre-existing plaintext records in the database.
+    ///
+    /// Run this once after upgrading from a version that stored secrets as
+    /// plaintext JSONB. Requires `secrets init` to have been run first.
+    MigrateEncrypt,
+
+    /// 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)]
+        name: Option<String>,
+        /// Filter by tag, e.g. --tag aliyun
        #[arg(long)]
        tag: Option<String>,
-        /// Search by keyword (matches name, namespace, kind)
+        /// 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,
    },

-    /// Incrementally update an existing record (merge semantics)
+    /// Incrementally update an existing record (merge semantics; record must exist).
+    ///
+    /// Only the fields you pass are changed — everything else is preserved.
+    /// Use --add-tag / --remove-tag to modify tags without touching other fields.
+    #[command(after_help = "EXAMPLES:
+  # Update a single metadata field (all other fields unchanged)
+  secrets update -n refining --kind server --name my-server -m ip=10.0.0.1
+
+  # Rotate a secret token
+  secrets update -n refining --kind service --name gitea -s token=<new-token>
+
+  # Add a tag and rotate password at the same time
+  secrets update -n refining --kind service --name gitea \\
+    --add-tag production -s token=<new-token>
+
+  # Remove a deprecated metadata field and a stale secret key
+  secrets update -n refining --kind service --name mqtt \\
+    --remove-meta old_port --remove-secret old_password
+
+  # Remove a tag
+  secrets update -n refining --kind service --name gitea --remove-tag staging")]
    Update {
-        /// Namespace (e.g. refining, ricnsmart)
+        /// Namespace, e.g. refining, ricnsmart
        #[arg(short, long)]
        namespace: String,
-        /// Kind of record (server, service, key, ...)
+        /// Kind of record: server, service, key, ...
        #[arg(long)]
        kind: String,
-        /// Human-readable name
+        /// Human-readable unique name
        #[arg(long)]
        name: String,
-        /// Add a tag (repeatable)
+        /// Add a tag (repeatable; does not affect existing tags)
        #[arg(long = "add-tag")]
        add_tags: Vec<String>,
        /// Remove a tag (repeatable)
@@ -103,18 +249,27 @@ enum Commands {
        /// Set or overwrite a metadata field: key=value (repeatable, @file supported)
        #[arg(long = "meta", short = 'm')]
        meta: Vec<String>,
-        /// Remove a metadata field by key (repeatable)
+        /// Delete a metadata field by key (repeatable)
        #[arg(long = "remove-meta")]
        remove_meta: Vec<String>,
        /// Set or overwrite a secret field: key=value (repeatable, @file supported)
        #[arg(long = "secret", short = 's')]
        secrets: Vec<String>,
-        /// Remove a secret field by key (repeatable)
+        /// Delete a secret field by key (repeatable)
        #[arg(long = "remove-secret")]
        remove_secrets: Vec<String>,
    },

    /// 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,
@@ -125,12 +280,12 @@ enum Commands {
 enum ConfigAction {
    /// Save database URL to config file (~/.config/secrets/config.toml)
    SetDb {
-        /// PostgreSQL connection string
+        /// PostgreSQL connection string, e.g. postgres://user:pass@<host>:<port>/dbname
        url: String,
    },
-    /// Show current configuration
+    /// Show current configuration (password masked)
    Show,
-    /// Print path to config file
+    /// Print path to the config file
    Path,
 }

@@ -148,7 +303,7 @@ async fn main() -> Result<()> {
        .with_target(false)
        .init();

-    // config 子命令不需要数据库连接，提前处理
+    // config subcommand needs no database or master key
    if let Commands::Config { action } = &cli.command {
        let cmd_action = match action {
            ConfigAction::SetDb { url } => {
@@ -164,7 +319,21 @@ async fn main() -> Result<()> {
    let pool = db::create_pool(&db_url).await?;
    db::migrate(&pool).await?;

+    // 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
+    let master_key = crypto::load_master_key()?;
+
    match &cli.command {
+        Commands::Init | Commands::Config { .. } => unreachable!(),
+
+        Commands::MigrateEncrypt => {
+            commands::migrate_encrypt::run(&pool, &master_key).await?;
+        }
+
        Commands::Add {
            namespace,
            kind,
@@ -172,29 +341,65 @@ async fn main() -> Result<()> {
            tags,
            meta,
            secrets,
+            output,
        } => {
            let _span =
                tracing::info_span!("cmd", command = "add", %namespace, %kind, %name).entered();
-            commands::add::run(&pool, namespace, kind, name, tags, meta, secrets).await?;
-        }
-        Commands::Search {
-            namespace,
-            kind,
-            tag,
-            query,
-            show_secrets,
-        } => {
-            let _span = tracing::info_span!("cmd", command = "search").entered();
-            commands::search::run(
+            let out = resolve_output_mode(output.as_deref())?;
+            commands::add::run(
                &pool,
-                namespace.as_deref(),
-                kind.as_deref(),
-                tag.as_deref(),
-                query.as_deref(),
-                *show_secrets,
+                commands::add::AddArgs {
+                    namespace,
+                    kind,
+                    name,
+                    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 _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(),
+                    tag: tag.as_deref(),
+                    query: query.as_deref(),
+                    show_secrets: show,
+                    fields,
+                    summary: *summary,
+                    limit: *limit,
+                    offset: *offset,
+                    sort,
+                    output: out,
+                },
+                Some(&master_key),
+            )
+            .await?;
+        }
+
        Commands::Delete {
            namespace,
            kind,
@@ -204,6 +409,7 @@ async fn main() -> Result<()> {
                tracing::info_span!("cmd", command = "delete", %namespace, %kind, %name).entered();
            commands::delete::run(&pool, namespace, kind, name).await?;
        }
+
        Commands::Update {
            namespace,
            kind,
@@ -230,10 +436,10 @@ async fn main() -> Result<()> {
                    secret_entries: secrets,
                    remove_secrets,
                },
+                &master_key,
            )
            .await?;
        }
-        Commands::Config { .. } => unreachable!(),
    }

    Ok(())
--- a/src/models.rs
+++ b/src/models.rs
@@ -11,7 +11,9 @@ 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 created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
 }
--- a/src/output.rs
+++ b/src/output.rs
@@ -0,0 +1,47 @@
+use std::io::IsTerminal;
+use std::str::FromStr;
+
+/// Output format for all commands.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub enum OutputMode {
+    /// Human-readable text (default when stdout is a TTY)
+    #[default]
+    Text,
+    /// Pretty-printed JSON
+    Json,
+    /// Single-line JSON (default when stdout is NOT a TTY, e.g. piped to jq)
+    JsonCompact,
+    /// KEY=VALUE pairs suitable for `source` or `.env` files
+    Env,
+}
+
+impl FromStr for OutputMode {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "text" => Ok(Self::Text),
+            "json" => Ok(Self::Json),
+            "json-compact" => Ok(Self::JsonCompact),
+            "env" => Ok(Self::Env),
+            other => Err(anyhow::anyhow!(
+                "Unknown output format '{}'. Valid: text, json, json-compact, env",
+                other
+            )),
+        }
+    }
+}
+
+/// Resolve the effective output mode.
+/// - Explicit value from `--output` takes priority.
+/// - TTY → text; non-TTY (piped/redirected) → json-compact.
+pub fn resolve_output_mode(explicit: Option<&str>) -> anyhow::Result<OutputMode> {
+    if let Some(s) = explicit {
+        return s.parse();
+    }
+    if std::io::stdout().is_terminal() {
+        Ok(OutputMode::Text)
+    } else {
+        Ok(OutputMode::JsonCompact)
+    }
+}
Author	SHA1	Message	Date
voson	8fdb6db87b	feat: 客户端加密 encrypted 字段，数据库只存密文 (v0.5.0) Some checks failed Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 1m27s Details Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m14s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Failing after 11m1s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 新增 src/crypto.rs：AES-256-GCM 加解密 + Argon2id 密钥派生 + OS Keychain 读写 - 新增 `secrets init` 命令：输入 Master Password，派生 Master Key 存入 Keychain - 新增 `secrets migrate-encrypt` 命令：将旧明文 JSONB 数据批量加密 - 修改 db.rs：encrypted 列 JSONB → BYTEA，新增 kv_config 表（存 Argon2id salt） - 修改 models.rs：encrypted 字段类型 Value → Vec<u8> - 修改 add/update：写入前 encrypt_json，update 读取后 decrypt → 合并 → 重新加密 - 修改 search：按需解密，未解密时显示 _encrypted:true/_key_count:N - 通过 6 个 crypto 单元测试（加解密、JSON roundtrip、Argon2id 确定性） Made-with: Cursor	2026-03-18 20:10:13 +08:00
voson	1f7984d798	feat: AI 优先的 search 增强与结构化输出 (v0.4.0) Some checks failed Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 57s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 33s Details Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 44s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - search: 新增 --name、-f/--field、-o/--output、--summary、--limit、--offset、--sort - search: 非 TTY 自动输出 json-compact，便于 AI 解析 - search: -f secret.* 自动解锁 secrets - add: 支持 -o json/json-compact 输出 - add: 重构为 AddArgs 结构体 - 全局: 各子命令 after_help 补充典型值示例 - output.rs: OutputMode 枚举 + TTY 检测 - 文档: README/AGENTS 面向 AI 的用法，连接串改为 <host>:<port> Made-with: Cursor	2026-03-18 17:17:43 +08:00
voson	140162f39a	ci(secrets): 飞书通知分散到各构建 job，放宽超时与构建条件 Some checks failed Secrets CLI - Build & Release / 版本 & Release (push) Successful in 2s Details Secrets CLI - Build & Release / 质量检查 (fmt / clippy / test) (push) Successful in 29s Details Secrets CLI - Build & Release / Build (aarch64-apple-darwin) (push) Successful in 45s Details Secrets CLI - Build & Release / Build (x86_64-unknown-linux-musl) (push) Successful in 1m18s Details Secrets CLI - Build & Release / 发布草稿 Release (push) Successful in 2s Details Secrets CLI - Build & Release / Build (x86_64-pc-windows-msvc) (push) Has been cancelled Details - 各 build job 超时 10→15min，publish-release 2→5min - 移除 build-macos/build-windows 的 if 条件，默认全平台构建 - 删除独立 notify job，在各 build job 内增加飞书单 job 通知 - 汇总通知并入 publish-release，用 needs 取状态不再调 API - publish-release 增加 if: always() 与 checkout 步骤 Made-with: Cursor	2026-03-18 16:32:45 +08:00