refactor: 消除冗余、统一设计，bump 0.9.1

- 提取 EntryRow/SecretFieldRow 到 models.rs
- 提取 current_actor()、print_json() 公共函数
- ExportFormat::from_extension 复用 from_str
- fetch_entries 默认 limit 100k（export/inject/run 不再截断）
- history 独立为 history.rs 模块
- delete 改用 DeleteArgs 结构体
- config_dir 改为 Result，Argon2id 参数提取常量
- Cargo 依赖 ^ 前缀、tokio 精简 features
- 更新 AGENTS.md 项目结构

Made-with: Cursor

AGENTS.md

@@ -28,9 +28,12 @@ secrets/
       search.rs          # search 命令：多条件查询，展示 secrets 字段 schema（无需 master_key）
       delete.rs          # delete 命令：事务化，CASCADE 删除 secrets，含历史快照
       update.rs          # update 命令：增量更新，secrets 行级 UPSERT/DELETE，CAS 并发保护
-      rollback.rs        # rollback / history 命令：按 entry_version 恢复 entry + secrets
+      rollback.rs        # rollback 命令：按 entry_version 恢复 entry + secrets
+      history.rs         # history 命令：查看 entry 变更历史列表
       run.rs             # inject / run 命令：逐字段解密 + key_ref 引用解析
       upgrade.rs         # upgrade 命令：检查、校验摘要并下载最新版本，自动替换二进制
+      export_cmd.rs      # export 命令：批量导出记录，支持 JSON/TOML/YAML，含解密明文
+      import_cmd.rs      # import 命令：批量导入记录，冲突检测，dry-run，重新加密写入
   scripts/
     release-check.sh        # 发版前检查版本号/tag 是否重复，并执行 fmt/clippy/test
     setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
@@ -493,6 +496,75 @@ secrets upgrade
 
 ---
 
+### export — 批量导出记录
+
+将匹配的记录（含解密后的明文 secrets）导出到文件或 stdout。支持 JSON、TOML、YAML 三种格式，文件格式由扩展名自动推断。使用 `--no-secrets` 时无需主密钥。
+
+```bash
+# 参数说明
+# -n / --namespace refining | ricnsmart
+# --kind server | service
+# --name gitea | i-uf63f2uookgs5uxmrdyc
+# --tag aliyun | production（可重复）
+# -q / --query 模糊关键词
+# --file <path>   输出文件路径，格式由扩展名推断（.json / .toml / .yaml / .yml）
+# --format json | toml | yaml   显式指定格式（输出到 stdout 时必须指定）
+# --no-secrets    不导出 secrets，无需主密钥
+
+# 全量导出到 JSON 文件
+secrets export --file backup.json
+
+# 按 namespace 导出为 TOML
+secrets export -n refining --file refining.toml
+
+# 按 kind 导出为 YAML
+secrets export -n refining --kind service --file services.yaml
+
+# 按 tag 过滤导出
+secrets export --tag production --file prod.json
+
+# 模糊关键词导出
+secrets export -q mqtt --file mqtt.json
+
+# 仅导出 schema（不含 secrets，无需主密钥）
+secrets export --no-secrets --file schema.json
+
+# 输出到 stdout（必须指定 --format）
+secrets export -n refining --format yaml
+secrets export --format json | jq '.'
+```
+
+---
+
+### import — 批量导入记录
+
+从导出文件读取记录并写入数据库，自动重新加密 secrets。支持 JSON、TOML、YAML 三种格式，文件格式由扩展名自动推断。
+
+```bash
+# 参数说明
+# <file>        必选，输入文件路径（格式由扩展名推断）
+# --force       冲突时覆盖已有记录（默认：报错并停止）
+# --dry-run     预览将执行的操作，不写入数据库
+# -o / --output text | json | json-compact
+
+# 导入 JSON 文件（遇到已存在记录报错）
+secrets import backup.json
+
+# 导入 TOML 文件，冲突时覆盖
+secrets import --force refining.toml
+
+# 导入 YAML 文件，冲突时覆盖
+secrets import --force services.yaml
+
+# 预览将执行的操作（不写入）
+secrets import --dry-run backup.json
+
+# JSON 格式输出导入摘要
+secrets import backup.json -o json
+```
+
+---
+
 ### config — 配置管理（无需主密钥）
 
 ```bash

Cargo.lock

@@ -1836,7 +1836,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "secrets"
-version = "0.8.0"
+version = "0.9.1"
 dependencies = [
  "aes-gcm",
  "anyhow",
@@ -1853,6 +1853,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
+ "serde_yaml",
  "sha2",
  "sqlx",
  "tar",
@@ -1982,6 +1983,19 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -2434,7 +2448,6 @@ dependencies = [
  "bytes",
  "libc",
  "mio",
- "parking_lot",
  "pin-project-lite",
  "signal-hook-registry",
  "socket2",
@@ -2681,6 +2694,12 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"

Cargo.toml

@@ -1,31 +1,32 @@
 [package]
 name = "secrets"
-version = "0.8.0"
+version = "0.9.1"
 edition = "2024"
 
 [dependencies]
-aes-gcm = "0.10.3"
-anyhow = "1.0.102"
-argon2 = { version = "0.5.3", features = ["std"] }
-chrono = { version = "0.4.44", features = ["serde"] }
-clap = { version = "4.6.0", features = ["derive"] }
-dirs = "6.0.0"
-flate2 = "1.1.9"
-keyring = { version = "3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
-rand = "0.10.0"
-reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
-rpassword = "7.4.0"
-self-replace = "1.5.0"
-semver = "1.0.27"
-serde = { version = "1.0.228", features = ["derive"] }
-serde_json = "1.0.149"
-sha2 = "0.10.9"
-sqlx = { version = "0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
-tar = "0.4.44"
-tempfile = "3.19"
-tokio = { version = "1.50.0", features = ["full"] }
-toml = "1.0.7"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-uuid = { version = "1.22.0", features = ["serde"] }
-zip = { version = "8.2.0", default-features = false, features = ["deflate"] }
+aes-gcm = "^0.10.3"
+anyhow = "^1.0.102"
+argon2 = { version = "^0.5.3", features = ["std"] }
+chrono = { version = "^0.4.44", features = ["serde"] }
+clap = { version = "^4.6.0", features = ["derive"] }
+dirs = "^6.0.0"
+flate2 = "^1.1.9"
+keyring = { version = "^3.6.3", features = ["apple-native", "windows-native", "linux-native"] }
+rand = "^0.10.0"
+reqwest = { version = "^0.12", default-features = false, features = ["rustls-tls", "json"] }
+rpassword = "^7.4.0"
+self-replace = "^1.5.0"
+semver = "^1.0.27"
+serde = { version = "^1.0.228", features = ["derive"] }
+serde_json = "^1.0.149"
+serde_yaml = "^0.9"
+sha2 = "^0.10.9"
+sqlx = { version = "^0.8.6", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "json", "chrono"] }
+tar = "^0.4.44"
+tempfile = "^3.19"
+tokio = { version = "^1.50.0", features = ["rt-multi-thread", "macros", "fs", "io-util", "process", "signal"] }
+toml = "^1.0.7"
+tracing = "^0.1"
+tracing-subscriber = { version = "^0.3", features = ["env-filter"] }
+uuid = { version = "^1.22.0", features = ["serde"] }
+zip = { version = "^8.2.0", default-features = false, features = ["deflate"] }

README.md

@@ -103,6 +103,8 @@ secrets update --help
 secrets delete --help
 secrets config --help
 secrets upgrade --help     # 检查并更新 CLI 版本
+secrets export --help      # 批量导出（JSON/TOML/YAML）
+secrets import --help      # 批量导入（JSON/TOML/YAML）
 
 # ── search ──────────────────────────────────────────────────────────────────
 secrets search --summary --limit 20                        # 发现概览
@@ -158,6 +160,20 @@ secrets config path    # 打印配置文件路径
 secrets upgrade --check   # 仅检查是否有新版本
 secrets upgrade           # 下载、校验 SHA-256 并安装最新版（从 Gitea Release）
 
+# ── export ────────────────────────────────────────────────────────────────────
+secrets export --file backup.json                        # 全量导出到 JSON
+secrets export -n refining --file refining.toml          # 按 namespace 导出为 TOML
+secrets export -n refining --kind service --file svc.yaml   # 按 kind 导出为 YAML
+secrets export --tag production --file prod.json         # 按 tag 过滤
+secrets export -q mqtt --file mqtt.json                   # 模糊搜索导出
+secrets export --no-secrets --file schema.json           # 仅导出 schema（无需主密钥）
+secrets export -n refining --format yaml                  # 输出到 stdout，指定格式
+
+# ── import ────────────────────────────────────────────────────────────────────
+secrets import backup.json                               # 导入（冲突时报错）
+secrets import --force refining.toml                     # 冲突时覆盖已有记录
+secrets import --dry-run backup.yaml                     # 预览将要执行的操作（不写入）
+
 # ── 调试 ──────────────────────────────────────────────────────────────────────
 secrets --verbose search -q mqtt
 RUST_LOG=secrets=trace secrets search
@@ -297,6 +313,8 @@ src/
     rollback.rs    # rollback / history：按 entry_version 恢复
     run.rs         # inject / run，逐字段解密 + key_ref 引用解析
     upgrade.rs     # 从 Gitea Release 自更新
+    export_cmd.rs  # export：批量导出，支持 JSON/TOML/YAML，含解密明文
+    import_cmd.rs  # import：批量导入，冲突检测，dry-run，重新加密写入
 scripts/
   setup-gitea-actions.sh  # 配置 Gitea Actions 变量与 Secrets
 ```

src/audit.rs

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

src/commands/add.rs

@@ -5,7 +5,8 @@ use std::fs;
 
 use crate::crypto;
 use crate::db;
-use crate::output::OutputMode;
+use crate::models::EntryRow;
+use crate::output::{OutputMode, print_json};
 
 // ── Key/value parsing helpers (shared with update.rs) ───────────────────────
 
@@ -228,13 +229,6 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
     let mut tx = pool.begin().await?;
 
     // Upsert the entry row (tags + metadata).
-    #[derive(sqlx::FromRow)]
-    struct EntryRow {
-        id: uuid::Uuid,
-        version: i64,
-        tags: Vec<String>,
-        metadata: Value,
-    }
     let existing: Option<EntryRow> = sqlx::query_as(
         "SELECT id, version, tags, metadata FROM entries \
          WHERE namespace = $1 AND kind = $2 AND name = $3",
@@ -383,11 +377,8 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Res
     });
 
     match args.output {
-        OutputMode::Json => {
-            println!("{}", serde_json::to_string_pretty(&result_json)?);
-        }
-        OutputMode::JsonCompact => {
-            println!("{}", serde_json::to_string(&result_json)?);
+        OutputMode::Json | OutputMode::JsonCompact => {
+            print_json(&result_json, &args.output)?;
         }
         _ => {
             println!("Added: [{}/{}] {}", args.namespace, args.kind, args.name);

src/commands/config.rs

@@ -15,7 +15,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
                 database_url: Some(url.clone()),
             };
             config::save_config(&cfg)?;
-            println!("Database URL saved to: {}", config_path().display());
+            println!("Database URL saved to: {}", config_path()?.display());
             println!("  {}", mask_password(&url));
         }
         crate::ConfigAction::Show => {
@@ -23,7 +23,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
             match cfg.database_url {
                 Some(url) => {
                     println!("database_url = {}", mask_password(&url));
-                    println!("config file:  {}", config_path().display());
+                    println!("config file:  {}", config_path()?.display());
                 }
                 None => {
                     println!("Database URL not configured.");
@@ -32,7 +32,7 @@ pub async fn run(action: crate::ConfigAction) -> Result<()> {
             }
         }
         crate::ConfigAction::Path => {
-            println!("{}", config_path().display());
+            println!("{}", config_path()?.display());
         }
     }
     Ok(())

src/commands/delete.rs

@@ -1,35 +1,20 @@
 use anyhow::Result;
-use serde_json::{Value, json};
-use sqlx::{FromRow, PgPool};
-use uuid::Uuid;
+use serde_json::json;
+use sqlx::PgPool;
 
 use crate::db;
-use crate::output::OutputMode;
+use crate::models::{EntryRow, SecretFieldRow};
+use crate::output::{OutputMode, print_json};
 
-#[derive(FromRow)]
-struct EntryRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
+pub struct DeleteArgs<'a> {
+    pub namespace: &'a str,
+    pub kind: &'a str,
+    pub name: &'a str,
+    pub output: OutputMode,
 }
 
-#[derive(FromRow)]
-struct SecretFieldRow {
-    id: Uuid,
-    field_name: String,
-    field_type: String,
-    value_len: i32,
-    encrypted: Vec<u8>,
-}
-
-pub async fn run(
-    pool: &PgPool,
-    namespace: &str,
-    kind: &str,
-    name: &str,
-    output: OutputMode,
-) -> Result<()> {
+pub async fn run(pool: &PgPool, args: DeleteArgs<'_>) -> Result<()> {
+    let (namespace, kind, name) = (args.namespace, args.kind, args.name);
     tracing::debug!(namespace, kind, name, "deleting entry");
 
     let mut tx = pool.begin().await?;
@@ -48,20 +33,10 @@ pub async fn run(
     let Some(row) = row else {
         tx.rollback().await?;
         tracing::warn!(namespace, kind, name, "entry not found for deletion");
-        match output {
-            OutputMode::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(
-                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
-                )?
-            ),
-            OutputMode::JsonCompact => println!(
-                "{}",
-                serde_json::to_string(
-                    &json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name})
-                )?
-            ),
-            _ => println!("Not found: [{}/{}] {}", namespace, kind, name),
+        let v = json!({"action":"not_found","namespace":namespace,"kind":kind,"name":name});
+        match args.output {
+            OutputMode::Text => println!("Not found: [{}/{}] {}", namespace, kind, name),
+            ref mode => print_json(&v, mode)?,
         }
         return Ok(());
     };
@@ -124,20 +99,10 @@ pub async fn run(
 
     tx.commit().await?;
 
-    match output {
-        OutputMode::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(
-                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
-            )?
-        ),
-        OutputMode::JsonCompact => println!(
-            "{}",
-            serde_json::to_string(
-                &json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name})
-            )?
-        ),
-        _ => println!("Deleted: [{}/{}] {}", namespace, kind, name),
+    let v = json!({"action":"deleted","namespace":namespace,"kind":kind,"name":name});
+    match args.output {
+        OutputMode::Text => println!("Deleted: [{}/{}] {}", namespace, kind, name),
+        ref mode => print_json(&v, mode)?,
     }
 
     Ok(())

src/commands/export_cmd.rs

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

src/commands/history.rs

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

src/commands/import_cmd.rs

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

src/commands/mod.rs

@@ -1,6 +1,9 @@
 pub mod add;
 pub mod config;
 pub mod delete;
+pub mod export_cmd;
+pub mod history;
+pub mod import_cmd;
 pub mod init;
 pub mod rollback;
 pub mod run;

src/commands/rollback.rs

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

src/commands/search.rs

@@ -121,7 +121,12 @@ struct PagedFetchArgs<'a> {
     offset: u32,
 }
 
+/// A very large limit used when callers need all matching records (export, inject, run).
+/// Postgres will stop scanning when this many rows are found; adjust if needed.
+pub const FETCH_ALL_LIMIT: u32 = 100_000;
+
 /// Fetch entries matching the given filters (used by search, inject, run).
+/// `limit` caps the result set; pass `FETCH_ALL_LIMIT` when you need all matching records.
 pub async fn fetch_entries(
     pool: &PgPool,
     namespace: Option<&str>,
@@ -129,6 +134,19 @@ pub async fn fetch_entries(
     name: Option<&str>,
     tags: &[String],
     query: Option<&str>,
+) -> Result<Vec<Entry>> {
+    fetch_entries_with_limit(pool, namespace, kind, name, tags, query, FETCH_ALL_LIMIT).await
+}
+
+/// Like `fetch_entries` but with an explicit limit. Used internally by `search`.
+pub(crate) async fn fetch_entries_with_limit(
+    pool: &PgPool,
+    namespace: Option<&str>,
+    kind: Option<&str>,
+    name: Option<&str>,
+    tags: &[String],
+    query: Option<&str>,
+    limit: u32,
 ) -> Result<Vec<Entry>> {
     fetch_entries_paged(
         pool,
@@ -139,7 +157,7 @@ pub async fn fetch_entries(
             tags,
             query,
             sort: "name",
-            limit: 200,
+            limit,
             offset: 0,
         },
     )

src/commands/update.rs

@@ -1,6 +1,6 @@
 use anyhow::Result;
 use serde_json::{Map, Value, json};
-use sqlx::{FromRow, PgPool};
+use sqlx::PgPool;
 use uuid::Uuid;
 
 use super::add::{
@@ -9,15 +9,8 @@ use super::add::{
 };
 use crate::crypto;
 use crate::db;
-use crate::output::OutputMode;
-
-#[derive(FromRow)]
-struct EntryRow {
-    id: Uuid,
-    version: i64,
-    tags: Vec<String>,
-    metadata: Value,
-}
+use crate::models::EntryRow;
+use crate::output::{OutputMode, print_json};
 
 pub struct UpdateArgs<'a> {
     pub namespace: &'a str,
@@ -284,11 +277,8 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) ->
     });
 
     match args.output {
-        OutputMode::Json => {
-            println!("{}", serde_json::to_string_pretty(&result_json)?);
-        }
-        OutputMode::JsonCompact => {
-            println!("{}", serde_json::to_string(&result_json)?);
+        OutputMode::Json | OutputMode::JsonCompact => {
+            print_json(&result_json, &args.output)?;
         }
         _ => {
             println!("Updated: [{}/{}] {}", args.namespace, args.kind, args.name);

src/config.rs

@@ -8,19 +8,23 @@ pub struct Config {
     pub database_url: Option<String>,
 }
 
-pub fn config_dir() -> PathBuf {
-    dirs::config_dir()
+pub fn config_dir() -> Result<PathBuf> {
+    let dir = dirs::config_dir()
         .or_else(|| dirs::home_dir().map(|h| h.join(".config")))
-        .unwrap_or_else(|| PathBuf::from(".config"))
-        .join("secrets")
+        .context(
+            "Cannot determine config directory: \
+             neither XDG_CONFIG_HOME nor HOME is set",
+        )?
+        .join("secrets");
+    Ok(dir)
 }
 
-pub fn config_path() -> PathBuf {
-    config_dir().join("config.toml")
+pub fn config_path() -> Result<PathBuf> {
+    Ok(config_dir()?.join("config.toml"))
 }
 
 pub fn load_config() -> Result<Config> {
-    let path = config_path();
+    let path = config_path()?;
     if !path.exists() {
         return Ok(Config::default());
     }
@@ -32,11 +36,11 @@ pub fn load_config() -> Result<Config> {
 }
 
 pub fn save_config(config: &Config) -> Result<()> {
-    let dir = config_dir();
+    let dir = config_dir()?;
     fs::create_dir_all(&dir)
         .with_context(|| format!("failed to create config dir: {}", dir.display()))?;
 
-    let path = config_path();
+    let path = dir.join("config.toml");
     let content = toml::to_string_pretty(config).context("failed to serialize config")?;
     fs::write(&path, &content)
         .with_context(|| format!("failed to write config file: {}", path.display()))?;

src/crypto.rs

@@ -10,12 +10,24 @@ const KEYRING_SERVICE: &str = "secrets-cli";
 const KEYRING_USER: &str = "master-key";
 const NONCE_LEN: usize = 12;
 
+// Argon2id parameters — OWASP recommended (m=64 MiB, t=3 iterations, p=4 threads, key=32 B)
+const ARGON2_M_COST: u32 = 65_536;
+const ARGON2_T_COST: u32 = 3;
+const ARGON2_P_COST: u32 = 4;
+const ARGON2_KEY_LEN: usize = 32;
+
 // ─── Argon2id key derivation ─────────────────────────────────────────────────
 
 /// Derive a 32-byte Master Key from a password and salt using Argon2id.
 /// Parameters: m=65536 KiB (64 MB), t=3, p=4 — OWASP recommended.
 pub fn derive_master_key(password: &str, salt: &[u8]) -> Result<[u8; 32]> {
-    let params = Params::new(65536, 3, 4, Some(32)).context("invalid Argon2id params")?;
+    let params = Params::new(
+        ARGON2_M_COST,
+        ARGON2_T_COST,
+        ARGON2_P_COST,
+        Some(ARGON2_KEY_LEN),
+    )
+    .context("invalid Argon2id params")?;
     let argon2 = Argon2::new(argon2::Algorithm::Argon2id, Version::V0x13, params);
     let mut key = [0u8; 32];
     argon2

src/db.rs

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

src/main.rs

@@ -436,6 +436,83 @@ EXAMPLES:
         #[arg(long)]
         check: bool,
     },
+
+    /// Export records to a file (JSON, TOML, or YAML).
+    ///
+    /// Decrypts and exports all matched records. Requires master key unless --no-secrets is used.
+    #[command(after_help = "EXAMPLES:
+  # Export everything to JSON
+  secrets export --file backup.json
+
+  # Export a specific namespace to TOML
+  secrets export -n refining --file refining.toml
+
+  # Export a specific kind
+  secrets export -n refining --kind service --file services.yaml
+
+  # Export by tag
+  secrets export --tag production --file prod.json
+
+  # Export schema only (no decryption needed)
+  secrets export --no-secrets --file schema.json
+
+  # Print to stdout in YAML
+  secrets export -n refining --format yaml")]
+    Export {
+        /// Filter by namespace
+        #[arg(short, long)]
+        namespace: Option<String>,
+        /// Filter by kind, e.g. server, service
+        #[arg(long)]
+        kind: Option<String>,
+        /// Exact name filter
+        #[arg(long)]
+        name: Option<String>,
+        /// Filter by tag (repeatable)
+        #[arg(long)]
+        tag: Vec<String>,
+        /// Fuzzy keyword search
+        #[arg(short, long)]
+        query: Option<String>,
+        /// Output file path (format inferred from extension: .json / .toml / .yaml / .yml)
+        #[arg(long)]
+        file: Option<String>,
+        /// Explicit format: json, toml, or yaml (overrides file extension; required for stdout)
+        #[arg(long)]
+        format: Option<String>,
+        /// Omit secrets from output (no master key required)
+        #[arg(long)]
+        no_secrets: bool,
+    },
+
+    /// Import records from a file (JSON, TOML, or YAML).
+    ///
+    /// Reads an export file and inserts or updates entries. Requires master key to re-encrypt secrets.
+    #[command(after_help = "EXAMPLES:
+  # Import a JSON backup (conflict = error by default)
+  secrets import backup.json
+
+  # Import and overwrite existing records
+  secrets import --force refining.toml
+
+  # Preview what would be imported (no writes)
+  secrets import --dry-run backup.yaml
+
+  # JSON output for the import summary
+  secrets import backup.json -o json")]
+    Import {
+        /// Input file path (format inferred from extension: .json / .toml / .yaml / .yml)
+        file: String,
+        /// Overwrite existing records on conflict (default: error and abort)
+        #[arg(long)]
+        force: bool,
+        /// Preview operations without writing to the database
+        #[arg(long)]
+        dry_run: bool,
+        /// Output format: text (default on TTY), json, json-compact
+        #[arg(short, long = "output")]
+        output: Option<String>,
+    },
 }
 
 #[derive(Subcommand)]
@@ -562,7 +639,16 @@ async fn main() -> Result<()> {
             let _span =
                 tracing::info_span!("cmd", command = "delete", %namespace, %kind, %name).entered();
             let out = resolve_output_mode(output.as_deref())?;
-            commands::delete::run(&pool, &namespace, &kind, &name, out).await?;
+            commands::delete::run(
+                &pool,
+                commands::delete::DeleteArgs {
+                    namespace: &namespace,
+                    kind: &kind,
+                    name: &name,
+                    output: out,
+                },
+            )
+            .await?;
         }
 
         Commands::Update {
@@ -608,7 +694,17 @@ async fn main() -> Result<()> {
             output,
         } => {
             let out = resolve_output_mode(output.as_deref())?;
-            commands::rollback::list_history(&pool, &namespace, &kind, &name, limit, out).await?;
+            commands::history::run(
+                &pool,
+                commands::history::HistoryArgs {
+                    namespace: &namespace,
+                    kind: &kind,
+                    name: &name,
+                    limit,
+                    output: out,
+                },
+            )
+            .await?;
         }
 
         Commands::Rollback {
@@ -682,6 +778,61 @@ async fn main() -> Result<()> {
             )
             .await?;
         }
+
+        Commands::Export {
+            namespace,
+            kind,
+            name,
+            tag,
+            query,
+            file,
+            format,
+            no_secrets,
+        } => {
+            let master_key = if no_secrets {
+                None
+            } else {
+                Some(crypto::load_master_key()?)
+            };
+            let _span = tracing::info_span!("cmd", command = "export").entered();
+            commands::export_cmd::run(
+                &pool,
+                commands::export_cmd::ExportArgs {
+                    namespace: namespace.as_deref(),
+                    kind: kind.as_deref(),
+                    name: name.as_deref(),
+                    tags: &tag,
+                    query: query.as_deref(),
+                    file: file.as_deref(),
+                    format: format.as_deref(),
+                    no_secrets,
+                },
+                master_key.as_ref(),
+            )
+            .await?;
+        }
+
+        Commands::Import {
+            file,
+            force,
+            dry_run,
+            output,
+        } => {
+            let master_key = crypto::load_master_key()?;
+            let _span = tracing::info_span!("cmd", command = "import").entered();
+            let out = resolve_output_mode(output.as_deref())?;
+            commands::import_cmd::run(
+                &pool,
+                commands::import_cmd::ImportArgs {
+                    file: &file,
+                    force,
+                    dry_run,
+                    output: out,
+                },
+                &master_key,
+            )
+            .await?;
+        }
     }
 
     Ok(())

src/models.rs

@@ -1,6 +1,7 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use std::collections::BTreeMap;
 use uuid::Uuid;
 
 /// A top-level entry (server, service, key, …).
@@ -36,3 +37,183 @@ pub struct SecretField {
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
 }
+
+// ── Internal query row types (shared across commands) ─────────────────────────
+
+/// Minimal entry row fetched for write operations (add / update / delete / rollback).
+#[derive(Debug, sqlx::FromRow)]
+pub struct EntryRow {
+    pub id: Uuid,
+    pub version: i64,
+    pub tags: Vec<String>,
+    pub metadata: Value,
+}
+
+/// Minimal secret field row fetched before snapshots or cascade deletes.
+#[derive(Debug, sqlx::FromRow)]
+pub struct SecretFieldRow {
+    pub id: Uuid,
+    pub field_name: String,
+    pub field_type: String,
+    pub value_len: i32,
+    pub encrypted: Vec<u8>,
+}
+
+// ── Export / Import types ──────────────────────────────────────────────────────
+
+/// Supported file formats for export/import.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum ExportFormat {
+    Json,
+    Toml,
+    Yaml,
+}
+
+impl ExportFormat {
+    /// Infer format from file extension (.json / .toml / .yaml / .yml).
+    pub fn from_extension(path: &str) -> anyhow::Result<Self> {
+        let ext = path.rsplit('.').next().unwrap_or("").to_lowercase();
+        Self::from_str(&ext).map_err(|_| {
+            anyhow::anyhow!(
+                "Cannot infer format from extension '.{}'. Use --format json|toml|yaml",
+                ext
+            )
+        })
+    }
+
+    /// Parse from --format CLI value.
+    pub fn from_str(s: &str) -> anyhow::Result<Self> {
+        match s.to_lowercase().as_str() {
+            "json" => Ok(Self::Json),
+            "toml" => Ok(Self::Toml),
+            "yaml" | "yml" => Ok(Self::Yaml),
+            other => anyhow::bail!("Unknown format '{}'. Expected: json, toml, or yaml", other),
+        }
+    }
+
+    /// Serialize ExportData to a string in this format.
+    pub fn serialize(&self, data: &ExportData) -> anyhow::Result<String> {
+        match self {
+            Self::Json => Ok(serde_json::to_string_pretty(data)?),
+            Self::Toml => {
+                let toml_val = json_to_toml_value(&serde_json::to_value(data)?)?;
+                toml::to_string_pretty(&toml_val)
+                    .map_err(|e| anyhow::anyhow!("TOML serialization failed: {}", e))
+            }
+            Self::Yaml => serde_yaml::to_string(data)
+                .map_err(|e| anyhow::anyhow!("YAML serialization failed: {}", e)),
+        }
+    }
+
+    /// Deserialize ExportData from a string in this format.
+    pub fn deserialize(&self, content: &str) -> anyhow::Result<ExportData> {
+        match self {
+            Self::Json => Ok(serde_json::from_str(content)?),
+            Self::Toml => {
+                let toml_val: toml::Value = toml::from_str(content)
+                    .map_err(|e| anyhow::anyhow!("TOML parse error: {}", e))?;
+                let json_val = toml_to_json_value(&toml_val);
+                Ok(serde_json::from_value(json_val)?)
+            }
+            Self::Yaml => serde_yaml::from_str(content)
+                .map_err(|e| anyhow::anyhow!("YAML parse error: {}", e)),
+        }
+    }
+}
+
+/// Top-level structure for export/import files.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ExportData {
+    pub version: u32,
+    pub exported_at: String,
+    pub entries: Vec<ExportEntry>,
+}
+
+/// A single entry with decrypted secrets for export/import.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ExportEntry {
+    pub namespace: String,
+    pub kind: String,
+    pub name: String,
+    #[serde(default)]
+    pub tags: Vec<String>,
+    #[serde(default)]
+    pub metadata: Value,
+    /// Decrypted secret fields. None means no secrets in this export (--no-secrets).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub secrets: Option<BTreeMap<String, Value>>,
+}
+
+// ── TOML ↔ JSON value conversion ──────────────────────────────────────────────
+
+/// Convert a serde_json Value to a toml Value.
+/// `null` values are filtered out (TOML does not support null).
+/// Mixed-type arrays are serialised as JSON strings.
+pub fn json_to_toml_value(v: &Value) -> anyhow::Result<toml::Value> {
+    match v {
+        Value::Null => anyhow::bail!("TOML does not support null values"),
+        Value::Bool(b) => Ok(toml::Value::Boolean(*b)),
+        Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Ok(toml::Value::Integer(i))
+            } else if let Some(f) = n.as_f64() {
+                Ok(toml::Value::Float(f))
+            } else {
+                anyhow::bail!("unsupported number: {}", n)
+            }
+        }
+        Value::String(s) => Ok(toml::Value::String(s.clone())),
+        Value::Array(arr) => {
+            let items: anyhow::Result<Vec<toml::Value>> =
+                arr.iter().map(json_to_toml_value).collect();
+            match items {
+                Ok(vals) => Ok(toml::Value::Array(vals)),
+                Err(e) => {
+                    tracing::debug!(error = %e, "mixed-type array; falling back to JSON string");
+                    Ok(toml::Value::String(serde_json::to_string(v)?))
+                }
+            }
+        }
+        Value::Object(map) => {
+            let mut toml_map = toml::map::Map::new();
+            for (k, val) in map {
+                if val.is_null() {
+                    // Skip null entries
+                    continue;
+                }
+                match json_to_toml_value(val) {
+                    Ok(tv) => {
+                        toml_map.insert(k.clone(), tv);
+                    }
+                    Err(e) => {
+                        tracing::debug!(key = %k, error = %e, "field not representable in TOML; falling back to JSON string");
+                        toml_map
+                            .insert(k.clone(), toml::Value::String(serde_json::to_string(val)?));
+                    }
+                }
+            }
+            Ok(toml::Value::Table(toml_map))
+        }
+    }
+}
+
+/// Convert a toml Value back to a serde_json Value.
+pub fn toml_to_json_value(v: &toml::Value) -> Value {
+    match v {
+        toml::Value::Boolean(b) => Value::Bool(*b),
+        toml::Value::Integer(i) => Value::Number((*i).into()),
+        toml::Value::Float(f) => serde_json::Number::from_f64(*f)
+            .map(Value::Number)
+            .unwrap_or(Value::Null),
+        toml::Value::String(s) => Value::String(s.clone()),
+        toml::Value::Datetime(dt) => Value::String(dt.to_string()),
+        toml::Value::Array(arr) => Value::Array(arr.iter().map(toml_to_json_value).collect()),
+        toml::Value::Table(map) => {
+            let obj: serde_json::Map<String, Value> = map
+                .iter()
+                .map(|(k, v)| (k.clone(), toml_to_json_value(v)))
+                .collect();
+            Value::Object(obj)
+        }
+    }
+}

src/output.rs

@@ -50,3 +50,16 @@ pub fn format_local_time(dt: DateTime<Utc>) -> String {
         .format("%Y-%m-%d %H:%M:%S %:z")
         .to_string()
 }
+
+/// Print a JSON value to stdout in the requested output mode.
+/// - `Json`        → pretty-printed
+/// - `JsonCompact` → single line
+/// - `Text`        → no-op (caller is responsible for the text branch)
+pub fn print_json(value: &serde_json::Value, mode: &OutputMode) -> anyhow::Result<()> {
+    match mode {
+        OutputMode::Json => println!("{}", serde_json::to_string_pretty(value)?),
+        OutputMode::JsonCompact => println!("{}", serde_json::to_string(value)?),
+        OutputMode::Text => {}
+    }
+    Ok(())
+}