Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(ov): harden CLI configuration and command behavior (#3552)

Hao Zhec4d2b27c6415
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.md
index f001c3732..043174c9a 100644
--- a/crates/ov_cli/README.md
+++ b/crates/ov_cli/README.md
@@ -175,7 +175,7 @@ Run `ov --help` and `ov <command> --help` for the exact command surface of your
- `observer vikingdb` - VikingDB status.
- `observer models` - VLM, embedding, and rerank model status.
- `observer retrieval` - Retrieval quality metrics.
-- `observer fs` - Filesystem operation metrics.
+- `observer filesystem` - Filesystem operation metrics.
- `observer system` - Overall system status.
### Configuration
@@ -269,8 +269,8 @@ ov glob "**/*.md" --uri viking://resources
# Session workflow
SESSION=$(ov -o json session new | jq -r '.result.session_id')
-ov session add-message --session-id "$SESSION" --role user --content "Hello"
-ov session commit --session-id "$SESSION"
+ov session add-message "$SESSION" --role user --content "Hello"
+ov session commit "$SESSION"
# Watch task management
ov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60
diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.md
index 1caf66101..a264caead 100644
--- a/crates/ov_cli/README_CN.md
+++ b/crates/ov_cli/README_CN.md
@@ -175,7 +175,7 @@ ov grep "openviking" --uri viking://resources
- `observer vikingdb` - VikingDB 状态。
- `observer models` - VLM、embedding 和 rerank 模型状态。
- `observer retrieval` - 检索质量指标。
-- `observer fs` - 文件系统操作指标。
+- `observer filesystem` - 文件系统操作指标。
- `observer system` - 整体系统状态。
### 配置
@@ -269,8 +269,8 @@ ov glob "**/*.md" --uri viking://resources
# Session 工作流
SESSION=$(ov -o json session new | jq -r '.result.session_id')
-ov session add-message --session-id "$SESSION" --role user --content "Hello"
-ov session commit --session-id "$SESSION"
+ov session add-message "$SESSION" --role user --content "Hello"
+ov session commit "$SESSION"
# Watch 任务管理
ov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60
diff --git a/crates/ov_cli/src/commands/compile.rs b/crates/ov_cli/src/commands/compile.rs
index cf36d28f6..753a3bcf5 100644
--- a/crates/ov_cli/src/commands/compile.rs
+++ b/crates/ov_cli/src/commands/compile.rs
@@ -18,8 +18,10 @@ pub async fn run(
compact: bool,
) -> Result<()> {
let sources = normalize_sources(from_uris)?;
- if timeout.is_some_and(|seconds| !seconds.is_finite() || seconds <= 0.0) {
- return Err(Error::Client("--timeout must be a positive number".into()));
+ if timeout.is_some_and(|seconds| !crate::config::timeout_is_valid(seconds)) {
+ return Err(Error::Client(
+ "--timeout must be a positive finite number of seconds".into(),
+ ));
}
let reason = reason
.as_deref()
diff --git a/crates/ov_cli/src/commands/content.rs b/crates/ov_cli/src/commands/content.rs
index 3035bfd4e..b9b43e2a4 100644
--- a/crates/ov_cli/src/commands/content.rs
+++ b/crates/ov_cli/src/commands/content.rs
@@ -3,7 +3,6 @@ use crate::error::Result;
use crate::output::OutputFormat;
use serde_json::{Value, json};
use std::collections::BTreeSet;
-use std::fs::File;
use std::io::Write;
use std::path::Path;
@@ -100,7 +99,7 @@ pub async fn get(client: &HttpClient, uri: &str, local_path: &str) -> Result<()>
let bytes = client.get_bytes(uri).await?;
// Write to local file
- let mut file = File::create(path)?;
+ let mut file = create_download_target(path, local_path)?;
file.write_all(&bytes)?;
file.flush()?;
@@ -108,6 +107,20 @@ pub async fn get(client: &HttpClient, uri: &str, local_path: &str) -> Result<()>
Ok(())
}
+fn create_download_target(path: &Path, local_path: &str) -> Result<std::fs::File> {
+ std::fs::OpenOptions::new()
+ .write(true)
+ .create_new(true)
+ .open(path)
+ .map_err(|error| {
+ if error.kind() == std::io::ErrorKind::AlreadyExists {
+ crate::error::Error::Client(format!("File already exists: {local_path}"))
+ } else {
+ crate::error::Error::Io(error)
+ }
+ })
+}
+
fn output_content_result(result: Value, output_format: OutputFormat, compact: bool) -> Result<()> {
match output_format {
OutputFormat::Json => crate::output::output_success(result, output_format, compact),
@@ -193,6 +206,7 @@ fn render_set_tags_result_for_table(result: &Value) -> Option<String> {
#[cfg(test)]
mod tests {
+ use crate::error::Error;
use serde_json::json;
fn strip_ansi(input: &str) -> String {
@@ -272,4 +286,20 @@ mod tests {
)
);
}
+
+ #[test]
+ fn download_target_creation_does_not_truncate_an_existing_file() {
+ let dir = tempfile::tempdir().expect("tempdir should be created");
+ let path = dir.path().join("result.bin");
+ std::fs::write(&path, b"existing").expect("fixture should be written");
+
+ let error = super::create_download_target(&path, &path.to_string_lossy())
+ .expect_err("existing targets must be rejected atomically");
+
+ assert!(matches!(error, Error::Client(_)));
+ assert_eq!(
+ std::fs::read(&path).expect("existing file should remain readable"),
+ b"existing"
+ );
+ }
}
diff --git a/crates/ov_cli/src/commands/snapshot.rs b/crates/ov_cli/src/commands/snapshot.rs
index 4f8f32d16..9944f17fa 100644
--- a/crates/ov_cli/src/commands/snapshot.rs
+++ b/crates/ov_cli/src/commands/snapshot.rs
@@ -213,11 +213,11 @@ fn handle_show(
SnapshotShowResult::Blob { oid, bytes, size } => {
if matches!(output_format, OutputFormat::Json) {
let envelope = serde_json::json!({"oid": oid, "size": size});
- output_success(&envelope, output_format, compact);
if let Some(path) = out_path {
let mut f = std::fs::File::create(&path)?;
f.write_all(&bytes)?;
}
+ output_success(&envelope, output_format, compact);
return Ok(());
}
match out_path {
@@ -272,3 +272,51 @@ fn print_log(value: &Value, output_format: OutputFormat, compact: bool) {
.collect();
output_success(&rows, OutputFormat::Table, compact);
}
+
+#[cfg(test)]
+mod tests {
+ use super::handle_show;
+ use crate::client::SnapshotShowResult;
+ use crate::output::OutputFormat;
+
+ #[test]
+ fn json_blob_show_writes_requested_output_file() {
+ let dir = tempfile::tempdir().expect("tempdir should be created");
+ let path = dir.path().join("blob.bin");
+
+ handle_show(
+ SnapshotShowResult::Blob {
+ oid: "abc123".to_string(),
+ bytes: b"snapshot-bytes".to_vec(),
+ size: 14,
+ },
+ Some(path.clone()),
+ OutputFormat::Json,
+ true,
+ )
+ .expect("blob output should be written");
+
+ assert_eq!(
+ std::fs::read(path).expect("blob output should be readable"),
+ b"snapshot-bytes"
+ );
+ }
+
+ #[test]
+ fn json_blob_show_propagates_output_file_errors() {
+ let dir = tempfile::tempdir().expect("tempdir should be created");
+
+ let result = handle_show(
+ SnapshotShowResult::Blob {
+ oid: "abc123".to_string(),
+ bytes: b"snapshot-bytes".to_vec(),
+ size: 14,
+ },
+ Some(dir.path().to_path_buf()),
+ OutputFormat::Json,
+ true,
+ );
+
+ assert!(result.is_err());
+ }
+}
diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rs
index 6b6b04425..7c3545613 100644
--- a/crates/ov_cli/src/config.rs
+++ b/crates/ov_cli/src/config.rs
@@ -105,6 +105,23 @@ fn default_timeout() -> f64 {
60.0
}
+pub(crate) fn timeout_is_valid(timeout: f64) -> bool {
+ timeout > 0.0 && std::time::Duration::try_from_secs_f64(timeout).is_ok()
+}
+
+pub(crate) fn parse_positive_timeout(value: &str) -> std::result::Result<f64, String> {
+ let timeout = value
+ .parse::<f64>()
+ .map_err(|_| format!("invalid timeout {value:?}: expected a positive number of seconds"))?;
+ if timeout_is_valid(timeout) {
+ Ok(timeout)
+ } else {
+ Err(format!(
+ "invalid timeout {value:?}: expected a positive finite number of seconds"
+ ))
+ }
+}
+
fn default_output_format() -> String {
"table".to_string()
}
@@ -308,6 +325,22 @@ impl Config {
Ok(())
}
+ pub(crate) fn validate_runtime_values(&self) -> Result<()> {
+ if !timeout_is_valid(self.timeout) {
+ return Err(Error::Config(format!(
+ "Invalid timeout value {}: timeout must be a positive finite number of seconds",
+ self.timeout
+ )));
+ }
+ if !matches!(self.output.as_str(), "table" | "json") {
+ return Err(Error::Config(format!(
+ "Invalid output value {:?}: expected table or json",
+ self.output
+ )));
+ }
+ Ok(())
+ }
+
pub(crate) fn effective_auth_with_overrides(
&self,
api_key_override: Option<String>,
@@ -458,6 +491,49 @@ mod tests {
assert!(error.to_string().contains("actor_peer_id cannot be used"));
}
+ #[test]
+ fn runtime_validation_rejects_invalid_timeout_values() {
+ for timeout in [-1.0, 0.0, f64::INFINITY, f64::NAN, 1e300] {
+ let config = Config {
+ timeout,
+ ..Config::default()
+ };
+ let error = config
+ .validate_runtime_values()
+ .expect_err("invalid timeout should fail runtime validation");
+ assert!(error.to_string().contains("Invalid timeout value"));
+ }
+ }
+
+ #[test]
+ fn config_file_with_invalid_timeout_still_loads_for_repair() {
+ let dir = tempfile::tempdir().expect("tempdir should be created");
+ let path = dir.path().join("ovcli.conf");
+ std::fs::write(&path, r#"{"timeout": -1}"#).expect("config file should be written");
+
+ let config =
+ Config::from_file(&path.to_string_lossy()).expect("repair commands must load the file");
+
+ assert_eq!(config.timeout, -1.0);
+ assert!(config.validate_runtime_values().is_err());
+ }
+
+ #[test]
+ fn config_file_with_invalid_output_still_loads_for_repair() {
+ let dir = tempfile::tempdir().expect("tempdir should be created");
+ let path = dir.path().join("ovcli.conf");
+ std::fs::write(&path, r#"{"output": "yaml"}"#).expect("config file should be written");
+
+ let config =
+ Config::from_file(&path.to_string_lossy()).expect("repair commands must load the file");
+
+ assert_eq!(config.output, "yaml");
+ let error = config
+ .validate_runtime_values()
+ .expect_err("normal commands must reject an invalid output format");
+ assert!(error.to_string().contains("Invalid output value \"yaml\""));
+ }
+
#[test]
fn config_deserializes_root_api_key() {
let config: Config = serde_json::from_str(
diff --git a/crates/ov_cli/src/config_wizard/store.rs b/crates/ov_cli/src/config_wizard/store.rs
index 393cb9fda..5ca559a08 100644
--- a/crates/ov_cli/src/config_wizard/store.rs
+++ b/crates/ov_cli/src/config_wizard/store.rs
@@ -574,6 +574,8 @@ pub(crate) async fn validate_candidate_config_with_role(
config: &Config,
require_api_key: bool,
) -> Result<Option<ApiKeyRole>> {
+ config.validate_runtime_values()?;
+
let api_key = non_empty_option(config.api_key.as_deref());
if require_api_key && api_key.is_none() {
return Err(Error::Config("API key is required".to_string()));
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index e49aa1bd9..93b2a6ca7 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -37,6 +37,7 @@ pub async fn handle_add_resource(
) -> Result<()> {
let is_url =
path.starts_with("http://") || path.starts_with("https://") || path.starts_with("git@");
+ validate_watch_source(is_url, watch_interval)?;
// A declared Connector add_type sends the path verbatim to the server;
// it is never a local file, so skip local-path existence validation.
@@ -130,6 +131,16 @@ pub async fn handle_add_resource(
.await
}
+fn validate_watch_source(is_remote: bool, watch_interval: f64) -> Result<()> {
+ if !is_remote && watch_interval > 0.0 {
+ return Err(Error::Client(
+ "A local path cannot be watched. Use a URL, sitemap, or RSS source, or re-import the local content when it changes."
+ .to_string(),
+ ));
+ }
+ Ok(())
+}
+
/// Single-resource `--args` go to the server as parser options; a manifest-run
/// key here almost always means a forgotten `-m`. Fail instead of forwarding —
/// the server treats unknown args keys of shared Connector sources by silently
@@ -1816,3 +1827,17 @@ mod config_switch_prompt_tests {
output
}
}
+
+#[cfg(test)]
+mod add_resource_validation_tests {
+ #[test]
+ fn local_watch_is_rejected_before_upload() {
+ let error =
+ super::validate_watch_source(false, 1.0).expect_err("local watch should be rejected");
+
+ assert!(error.to_string().contains("local path cannot be watched"));
+ assert!(super::validate_watch_source(false, 0.0).is_ok());
+ assert!(super::validate_watch_source(false, -1.0).is_ok());
+ assert!(super::validate_watch_source(true, 1.0).is_ok());
+ }
+}
diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rs
index b35115dd5..e56b2e31c 100644
--- a/crates/ov_cli/src/help_ui.rs
+++ b/crates/ov_cli/src/help_ui.rs
@@ -547,7 +547,7 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[
description: "Compare one file between two snapshots.",
},
HelpItem {
- label: "ov snapshot restore viking://projects/acme <commit> --dry-run",
+ label: "ov snapshot restore <commit> viking://projects/acme --dry-run",
description: "Preview restoring a directory to a past snapshot.",
},
],
@@ -585,11 +585,11 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[
purpose: "Restore a project directory to a past snapshot via a forward commit.",
examples: &[
HelpItem {
- label: "ov snapshot restore viking://projects/acme <commit> --dry-run",
+ label: "ov snapshot restore <commit> viking://projects/acme --dry-run",
description: "Preview which files would change.",
},
HelpItem {
- label: "ov snapshot restore viking://projects/acme <commit> -m \"rollback\"",
+ label: "ov snapshot restore <commit> viking://projects/acme -m \"rollback\"",
description: "Apply the restore as a new commit.",
},
],
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index bddf371d2..76607af15 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -119,12 +119,11 @@ struct Cli {
short,
long,
value_enum,
- default_value = "table",
global = true,
hide = true,
value_name = "table|json"
)]
- output: OutputFormat,
+ output: Option<OutputFormat>,
/// Use compact table/JSON rendering
#[arg(
@@ -349,7 +348,12 @@ enum Commands {
#[arg(long, help_heading = "Common options")]
wait: bool,
/// Wait timeout in seconds (only used with --wait)
- #[arg(long, value_name = "seconds", help_heading = "Common options")]
+ #[arg(
+ long,
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds",
+ help_heading = "Common options"
+ )]
timeout: Option<f64>,
/// Enable strict mode for directory scanning (fail if any unsupported files found)
#[arg(
@@ -414,7 +418,12 @@ enum Commands {
#[arg(long, help_heading = "Common options")]
wait: bool,
/// Wait timeout in seconds
- #[arg(long, value_name = "seconds", help_heading = "Common options")]
+ #[arg(
+ long,
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds",
+ help_heading = "Common options"
+ )]
timeout: Option<f64>,
/// Parent skill root URI (e.g. viking://agent/skills); defaults to user-private skills
#[arg(
@@ -462,6 +471,7 @@ enum Commands {
short = 'n',
alias = "limit",
default_value = "256",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -490,6 +500,7 @@ enum Commands {
short = 'n',
alias = "limit",
default_value = "256",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -526,7 +537,12 @@ enum Commands {
#[arg(long, help_heading = "Common options")]
wait: bool,
/// Wait timeout in seconds (only used with --wait)
- #[arg(long, value_name = "seconds", help_heading = "Common options")]
+ #[arg(
+ long,
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds",
+ help_heading = "Common options"
+ )]
timeout: Option<f64>,
},
/// [Data] Move or rename resource
@@ -604,7 +620,12 @@ enum Commands {
#[arg(long, default_value = "false", help_heading = "Common options")]
wait: bool,
/// Optional wait timeout in seconds
- #[arg(long, value_name = "seconds", help_heading = "Common options")]
+ #[arg(
+ long,
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds",
+ help_heading = "Common options"
+ )]
timeout: Option<f64>,
},
/// [Data] Update explicit retrieval tags metadata for a file or directory
@@ -658,6 +679,7 @@ enum Commands {
long = "node-limit",
alias = "limit",
default_value = "10",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -726,6 +748,7 @@ enum Commands {
long = "node-limit",
alias = "limit",
default_value = "10",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -795,6 +818,7 @@ enum Commands {
long = "node-limit",
alias = "limit",
default_value = "256",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -829,6 +853,7 @@ enum Commands {
long = "node-limit",
alias = "limit",
default_value = "256",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n",
help_heading = "Common options"
)]
@@ -1013,7 +1038,12 @@ enum Commands {
#[arg(long)]
wait: bool,
/// Local wait timeout in seconds; does not cancel the task
- #[arg(long, requires = "wait", value_name = "seconds")]
+ #[arg(
+ long,
+ requires = "wait",
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds"
+ )]
timeout: Option<f64>,
},
@@ -1021,7 +1051,12 @@ enum Commands {
/// [Status] Wait for queued async processing to complete
Wait {
/// Wait timeout in seconds
- #[arg(long, value_name = "seconds", help_heading = "Common options")]
+ #[arg(
+ long,
+ value_parser = config::parse_positive_timeout,
+ value_name = "seconds",
+ help_heading = "Common options"
+ )]
timeout: Option<f64>,
},
/// [Status] Track async resource processing tasks
@@ -1247,7 +1282,7 @@ enum SystemCommands {
/// Wait for queued async processing to complete
Wait {
/// Wait timeout in seconds
- #[arg(long, value_name = "seconds")]
+ #[arg(long, value_parser = config::parse_positive_timeout, value_name = "seconds")]
timeout: Option<f64>,
},
/// Show component status
@@ -1301,6 +1336,7 @@ enum ObserverCommands {
/// Get retrieval quality metrics
Retrieval,
/// Get filesystem operation metrics
+ #[command(alias = "fs")]
Filesystem,
/// Get overall system status
System,
@@ -1406,6 +1442,7 @@ enum SkillCommands {
long = "node-limit",
alias = "limit",
default_value = "1000",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n"
)]
node_limit: i32,
@@ -1424,6 +1461,7 @@ enum SkillCommands {
long = "node-limit",
alias = "limit",
default_value = "10",
+ value_parser = clap::value_parser!(i32).range(0..),
value_name = "n"
)]
node_limit: i32,
@@ -1771,6 +1809,10 @@ impl Commands {
} | Commands::Version
)
}
+
+ fn allows_invalid_runtime_config(&self) -> bool {
+ matches!(self, Commands::Config { .. })
+ }
}
#[derive(Subcommand)]
@@ -2634,11 +2676,39 @@ fn language_command_can_run_picker(has_language_value: bool, is_interactive: boo
has_language_value || is_interactive
}
+fn resolve_output_format(cli_output: Option<OutputFormat>, config: &Config) -> OutputFormat {
+ cli_output.unwrap_or_else(|| OutputFormat::from(config.output.as_str()))
+}
+
+fn render_pre_language_help_request(args: &[OsString]) -> Option<String> {
+ if !args
+ .iter()
+ .skip(1)
+ .any(|arg| matches!(arg.to_str(), Some("-h" | "--help")))
+ {
+ return None;
+ }
+
+ let error = Cli::try_parse_from(args).err()?;
+ if error.kind() != clap::error::ErrorKind::DisplayHelp {
+ return None;
+ }
+
+ if help_ui::is_top_level_help_request(args) {
+ return Some(help_ui::render_top_level_help());
+ }
+ help_ui::render_command_help_request(args).or_else(|| Some(error.to_string()))
+}
+
#[tokio::main]
async fn main() {
let args = preprocess_cli_args(std::env::args_os().collect());
let command_display = error_ui::display_command(&args);
let (pre_parse_output_format, pre_parse_compact) = pre_parse_output_options(&args);
+ if let Some(help) = render_pre_language_help_request(&args) {
+ print!("{help}");
+ return;
+ }
match ensure_language_selected_before_command(&args).await {
Ok(true) => {}
Ok(false) => return,
@@ -2699,7 +2769,7 @@ async fn main() {
}
};
- let output_format = cli.output;
+ let output_override = cli.output;
let compact = cli.compact;
let legacy_upload_options = UploadCliOptions {
progress: cli.progress,
@@ -2762,7 +2832,7 @@ async fn main() {
error_ui::print_runtime_error(
&command_display,
&e,
- output_format,
+ pre_parse_output_format,
compact,
cli.verbose,
);
@@ -2785,13 +2855,20 @@ async fn main() {
error_ui::print_runtime_error(
&command_display,
&e,
- output_format,
+ pre_parse_output_format,
compact,
cli.verbose,
);
std::process::exit(2);
}
};
+ let output_format = resolve_output_format(output_override, &config);
+ if !cli.command.allows_invalid_runtime_config()
+ && let Err(e) = config.validate_runtime_values()
+ {
+ error_ui::print_runtime_error(&command_display, &e, output_format, compact, cli.verbose);
+ std::process::exit(2);
+ }
let ctx = CliContext::from_config(
config,
output_format,
@@ -3418,11 +3495,12 @@ async fn main() {
mod tests {
use super::{
Cli, CliContext, Commands, ConfigAddTarget, ConfigCommands, LanguageGateAction,
- PrivacyCommands, SkillCommands, SnapshotCmd, UploadCliOptions, find_command_index,
- first_command_token, is_language_command_request, language_command_can_run_picker,
- language_gate_action, language_required_message, legacy_upload_option_error,
- plain_help_misuse, pre_parse_output_options, pre_parse_requires_cli_config_file,
- preprocess_cli_args, preprocess_privacy_args,
+ ObserverCommands, PrivacyCommands, SkillCommands, SnapshotCmd, UploadCliOptions,
+ find_command_index, first_command_token, is_language_command_request,
+ language_command_can_run_picker, language_gate_action, language_required_message,
+ legacy_upload_option_error, plain_help_misuse, pre_parse_output_options,
+ pre_parse_requires_cli_config_file, preprocess_cli_args, preprocess_privacy_args,
+ render_pre_language_help_request, resolve_output_format,
};
use crate::config::{Config, DEFAULT_CUSTOM_URL};
use crate::output::OutputFormat;
@@ -4312,7 +4390,7 @@ mod tests {
let show_global_output =
Cli::try_parse_from(["ov", "skills", "show", "code-review", "-o", "json"])
.expect("skills show should accept global -o after the subcommand");
- assert_eq!(show_global_output.output, OutputFormat::Json);
+ assert_eq!(show_global_output.output, Some(OutputFormat::Json));
let remove = Cli::try_parse_from(["ov", "skills", "remove", "foo", "bar", "--yes"])
.expect("skills remove --yes should parse");
@@ -4465,6 +4543,154 @@ mod tests {
}
}
+ #[test]
+ fn all_timeout_options_require_positive_finite_seconds() {
+ let command_prefixes = [
+ vec!["ov", "add-resource", "https://example.com", "--timeout"],
+ vec!["ov", "add-skill", "skill", "--timeout"],
+ vec!["ov", "rm", "viking://resources/item", "--timeout"],
+ vec![
+ "ov",
+ "write",
+ "viking://resources/item",
+ "--content",
+ "value",
+ "--timeout",
+ ],
+ vec![
+ "ov",
+ "compile",
+ "--from",
+ "viking://resources/source",
+ "--to",
+ "viking://resources/target",
+ "--skill",
+ "viking://user/skills/compiler",
+ "--wait",
+ "--timeout",
+ ],
+ vec!["ov", "wait", "--timeout"],
+ vec!["ov", "system", "wait", "--timeout"],
+ ];
+
+ for prefix in command_prefixes {
+ for invalid in ["0", "-1", "inf", "NaN", "1e300"] {
+ let mut args = prefix.clone();
+ args.push(invalid);
+ assert!(
+ Cli::try_parse_from(&args).is_err(),
+ "{args:?} should reject an invalid timeout"
+ );
+ }
+
+ let mut args = prefix;
+ args.push("0.1");
+ assert!(
+ Cli::try_parse_from(&args).is_ok(),
+ "{args:?} should accept a positive finite timeout"
+ );
+ }
+ }
+
+ #[test]
+ fn all_node_limit_options_accept_zero_and_reject_negative_values() {
+ let command_prefixes = [
+ vec!["ov", "ls", "--node-limit"],
+ vec!["ov", "tree", "viking://resources", "--node-limit"],
+ vec!["ov", "find", "query", "--node-limit"],
+ vec!["ov", "search", "query", "--node-limit"],
+ vec!["ov", "grep", "query", "--node-limit"],
+ vec!["ov", "glob", "**/*", "--node-limit"],
+ vec!["ov", "skills", "list", "--node-limit"],
+ vec!["ov", "skills", "find", "query", "--node-limit"],
+ ];
+
+ for prefix in command_prefixes {
+ let mut negative_args = prefix.clone();
+ negative_args.push("-1");
+ assert!(
+ Cli::try_parse_from(&negative_args).is_err(),
+ "{negative_args:?} should reject a negative node limit"
+ );
+
+ let mut zero_args = prefix.clone();
+ zero_args.push("0");
+ assert!(
+ Cli::try_parse_from(&zero_args).is_ok(),
+ "{zero_args:?} should preserve the established zero-limit semantics"
+ );
+
+ let mut args = prefix;
+ args.push("1");
+ assert!(
+ Cli::try_parse_from(&args).is_ok(),
+ "{args:?} should accept a positive node limit"
+ );
+ }
+ }
+
+ #[test]
+ fn config_commands_can_load_invalid_runtime_values_for_repair() {
+ let cli = Cli::try_parse_from(["ov", "config", "show"]).expect("config show should parse");
+ assert!(cli.command.allows_invalid_runtime_config());
+
+ let status = Cli::try_parse_from(["ov", "status"]).expect("status should parse");
+ assert!(!status.command.allows_invalid_runtime_config());
+ }
+
+ #[test]
+ fn configured_output_is_used_unless_cli_overrides_it() {
+ let config = Config {
+ output: "json".to_string(),
+ ..Config::default()
+ };
+
+ assert_eq!(resolve_output_format(None, &config), OutputFormat::Json);
+ assert_eq!(
+ resolve_output_format(Some(OutputFormat::Table), &config),
+ OutputFormat::Table
+ );
+ let cli = Cli::try_parse_from(["ov", "status"]).unwrap();
+ assert_eq!(cli.output, None);
+
+ let invalid_config = Config {
+ output: "yaml".to_string(),
+ ..Config::default()
+ };
+ assert_eq!(
+ resolve_output_format(None, &invalid_config),
+ OutputFormat::Table,
+ "repair commands need a safe fallback for invalid persisted output"
+ );
+ }
+
+ #[test]
+ fn only_explicit_clap_help_bypasses_language_setup() {
+ for args in [
+ ["ov", "--help"].as_slice(),
+ ["ov", "-h"].as_slice(),
+ ["ov", "status", "--help"].as_slice(),
+ ["ov", "system", "wait", "-h"].as_slice(),
+ ] {
+ assert!(
+ render_pre_language_help_request(&os_args(args)).is_some(),
+ "{args:?} should render before language setup"
+ );
+ }
+
+ for args in [
+ ["ov", "status"].as_slice(),
+ ["ov", "task"].as_slice(),
+ ["ov", "-help"].as_slice(),
+ ["ov", "--account", "--help", "status"].as_slice(),
+ ] {
+ assert!(
+ render_pre_language_help_request(&os_args(args)).is_none(),
+ "{args:?} should keep the language gate"
+ );
+ }
+ }
+
#[test]
fn language_gate_detects_language_command_after_global_flags() {
assert!(is_language_command_request(&os_args(&["ov", "language"])));
@@ -4849,6 +5075,36 @@ mod tests {
assert_eq!(client.api_key(), Some("root-key"));
}
+ #[test]
+ fn observer_alias_and_snapshot_restore_examples_parse() {
+ let observer = Cli::try_parse_from(["ov", "observer", "fs"]).unwrap();
+ assert!(matches!(
+ observer.command,
+ Commands::Observer {
+ action: ObserverCommands::Filesystem
+ }
+ ));
+
+ let snapshot = Cli::try_parse_from([
+ "ov",
+ "snapshot",
+ "restore",
+ "abc123",
+ "viking://projects/acme",
+ ])
+ .unwrap();
+ assert!(matches!(
+ snapshot.command,
+ Commands::Snapshot {
+ cmd: SnapshotCmd::Restore {
+ source_commit,
+ project_dir,
+ ..
+ }
+ } if source_commit == "abc123" && project_dir.as_deref() == Some("viking://projects/acme")
+ ));
+ }
+
#[test]
fn cli_write_rejects_removed_semantic_flags() {
let result = Cli::try_parse_from([
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index 5a393b6e0..a876481ca 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -191,7 +191,7 @@ client.initialize()
#### HTTP Call Examples
- CLI, `SyncHTTPClient`, and `AsyncHTTPClient` automatically upload local files or directories before calling the server API.
-- Python HTTP client and CLI can also opt into shared temporary uploads via client config (`ovcli.conf` -> `upload.mode = "shared"`).
+- Python HTTP clients can opt into shared temporary uploads through `ovcli.conf` (`upload.mode = "shared"`). The Rust `ov` CLI does not read that field; set `OPENVIKING_UPLOAD_MODE=shared` for `ov` instead.
- Raw HTTP calls don't get this convenience layer. When using `curl` or other HTTP clients, you need to first call `POST /api/v1/resources/temp_upload`, then pass the returned `temp_file_id` to the target API.
- `temp_upload` defaults to `upload_mode=local`. Use `upload_mode=shared` only when you explicitly want distributed shared temporary uploads.
- For raw HTTP imports of local directories, you need to first zip them into a `.zip` file and upload using the above method; the server does not accept direct host directory paths.
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index 662904b68..8d0bfe930 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -183,7 +183,7 @@ Skills are a special type of resource that define actions or tools agents can pe
- Send structured skill data directly in `data`
- Send raw `SKILL.md` content in `data`
- First call `POST /api/v1/resources/temp_upload` to upload a local `SKILL.md` file/zip directory, then call `POST /api/v1/skills` with `temp_file_id`
- - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. In Python HTTP client / CLI flows, this can also be driven by `ovcli.conf` via `upload.mode = "shared"`
+ - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. Python HTTP clients can set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI instead uses `OPENVIKING_UPLOAD_MODE=shared`
- `POST /api/v1/skills` does not accept direct host filesystem paths in `data`.
- **Targeting**:
diff --git a/docs/en/api/99-api-doc-writing-guide.md b/docs/en/api/99-api-doc-writing-guide.md
index c1fdee53a..26a411dff 100644
--- a/docs/en/api/99-api-doc-writing-guide.md
+++ b/docs/en/api/99-api-doc-writing-guide.md
@@ -30,7 +30,7 @@ Explain the purpose of this API, point to the corresponding code entry, and brie
**Code Entry**:
- `openviking/<module>/<file>.py:<ClassName>.<MethodName>` - Core implementation
- `openviking/server/routers/<router-file>.py` - HTTP router
-- `openviking_cli/commands/<command-file>.py` - CLI command
+- `crates/ov_cli/src/commands/<command-file>.rs` - CLI command
#### 2. Interface and Parameter Description
@@ -180,10 +180,11 @@ Add resources to the knowledge base, supporting various sources such as local fi
5. Build vector index
**Code Entry**:
-- `openviking/core/client.py:OpenViking.add_resource()` - SDK entry
-- `openviking/resource/importer.py:ResourceImporter.import_resource()` - Core implementation
-- `openviking/server/routers/resources.py` - HTTP router
-- `openviking_cli/commands/resources.py` - CLI command
+- `openviking/async_client.py:AsyncOpenViking.add_resource()` - Async SDK entry
+- `openviking/sync_client.py:SyncOpenViking.add_resource()` - Sync SDK entry
+- `openviking/service/resource_service.py:ResourceService.add_resource()` - Core implementation
+- `openviking/server/routers/resources.py:add_resource()` - HTTP router
+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI handler
#### 2. Interface and Parameter Description
diff --git a/docs/en/concepts/04-viking-uri.md b/docs/en/concepts/04-viking-uri.md
index 9d8b8d518..28d841969 100644
--- a/docs/en/concepts/04-viking-uri.md
+++ b/docs/en/concepts/04-viking-uri.md
@@ -204,7 +204,7 @@ ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}
ov read "viking://resources/logs/{calendar:yesterday}/app.log"
# Prep tomorrow's tasks
-ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "Plan the day"
+ov write "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "Plan the day"
# Upload monthly report, --parent-auto-create can be shortened to -p
ov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdf
diff --git a/docs/en/concepts/10-encryption.md b/docs/en/concepts/10-encryption.md
index db36dd366..6b49a3388 100644
--- a/docs/en/concepts/10-encryption.md
+++ b/docs/en/concepts/10-encryption.md
@@ -85,7 +85,7 @@ Suitable for development and single-node deployments:
**Initialization command**:
```bash
-ov system crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
```
### Vault (HashiCorp Vault)
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index edb1cec85..80b0e9dd9 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -13,7 +13,7 @@ openviking-server doctor
## Configuration File
-Create `~/.openviking/ov.conf` in your project directory:
+Create `~/.openviking/ov.conf` in your home configuration directory:
```json
{
@@ -1402,7 +1402,7 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t
| `upload.ignore_dirs` | Default directory ignore list for `add-resource` (CSV) | `null` |
| `upload.include` | Default include patterns for `add-resource` (CSV) | `null` |
| `upload.exclude` | Default exclude patterns for `add-resource` (CSV) | `null` |
-| `upload.mode` | Temporary upload backend: `"local"` (per-instance disk) or `"shared"` (distributed shared store, required when consumer requests can land on a different server instance than the upload). Per-call override via `OPENVIKING_UPLOAD_MODE`. | `null` (server's `temp_upload.default_mode`, which itself defaults to `"local"`) |
+| `upload.mode` | Python HTTP-client temporary upload backend: `"local"` (per-instance disk) or `"shared"` (distributed shared store). The Rust `ov` CLI does not read this field; set `OPENVIKING_UPLOAD_MODE=shared` for shared uploads. | `null` (server's `temp_upload.default_mode`, which itself defaults to `"local"`) |
Local directory uploads respect `.gitignore` files (root and nested). `ignore_dirs/include/exclude` apply on top of that.
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index 5eb57b059..c51448849 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -170,7 +170,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
Then use the CLI:
```bash
-python -m openviking ls viking://resources/
+ov ls viking://resources/
```
### curl
diff --git a/docs/en/guides/07-operation-telemetry.md b/docs/en/guides/07-operation-telemetry.md
index 4595ec6ed..a8c55a217 100644
--- a/docs/en/guides/07-operation-telemetry.md
+++ b/docs/en/guides/07-operation-telemetry.md
@@ -120,7 +120,7 @@ curl -X POST http://localhost:1933/api/v1/resources/temp_upload \
```
This endpoint currently accepts the boolean form only.
-`upload_mode` is also a form field for this endpoint; it defaults to `local` and should only be set to `shared` when you explicitly need distributed shared temporary uploads. Python HTTP client / CLI users can alternatively drive the same behavior with `ovcli.conf` -> `upload.mode = "shared"`.
+`upload_mode` is also a form field for this endpoint; it defaults to `local` and should only be set to `shared` when you explicitly need distributed shared temporary uploads. Python HTTP clients can alternatively set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI uses `OPENVIKING_UPLOAD_MODE=shared` instead.
## Common summary groups
diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.md
index 1c226b385..5700b632e 100644
--- a/docs/en/guides/08-encryption.md
+++ b/docs/en/guides/08-encryption.md
@@ -31,7 +31,7 @@ See the [Multi-Write Storage Guide](./13-multi-write-storage.md) for more multi-
### 1. Initialize Root Key (Local Mode)
```bash
-ov system crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
```
### 2. Configure Encryption
@@ -176,10 +176,10 @@ For maximum API key protection, you can enable Argon2id one-way hashing:
```bash
# Generate and save to specified path
-ov system crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
# Or use short option
-ov system crypto init-key -o ~/.openviking/master.key
+ov system crypto init-key -f ~/.openviking/master.key
```
**Output example**:
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index e775110cb..905d7132e 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -186,7 +186,7 @@ client.initialize()
#### HTTP 调用示例
- CLI、`SyncHTTPClient`、`AsyncHTTPClient` 遇到本地文件或目录时,会先自动上传,再调用服务端 API。
-- Python HTTP client 和 CLI 也可以通过客户端配置启用 shared 临时上传(`ovcli.conf` 中设置 `upload.mode = "shared"`)。
+- Python HTTP client 可以通过 `ovcli.conf` 启用 shared 临时上传(设置 `upload.mode = "shared"`)。Rust `ov` CLI 不读取这个字段;使用 `ov` 时请设置 `OPENVIKING_UPLOAD_MODE=shared`。
- 裸 HTTP 调用没有这层封装。使用 `curl` 或其他 HTTP 客户端时,需要先调用 `POST /api/v1/resources/temp_upload`,再把返回的 `temp_file_id` 传给目标 API。
- `temp_upload` 默认使用 `upload_mode=local`。只有在你显式需要分布式共享临时上传时,才应传 `upload_mode=shared`。
- 裸 HTTP 如果导入本地目录,需要先自行打成 `.zip` 再通过上述方法上传;服务端不接受直接传宿主机目录路径。
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index 5385796ba..cd75b579c 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -183,7 +183,7 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio
1. 在 `data` 中直接传结构化 skill 数据
2. 在 `data` 中直接传原始 `SKILL.md` 内容
3. 先调用 `POST /api/v1/resources/temp_upload` 上传本地 `SKILL.md` 文件/zip 目录,再调用 `POST /api/v1/skills` 并传入 `temp_file_id`
- 4. `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。在 Python HTTP client / CLI 流程里,也可以通过 `ovcli.conf` 的 `upload.mode = "shared"` 驱动这一行为
+ 4. `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。Python HTTP client 可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`
- `POST /api/v1/skills` 不接受在 `data` 中直接传宿主机本地路径。
- **目标规则**:
diff --git a/docs/zh/api/99-api-doc-writing-guide.md b/docs/zh/api/99-api-doc-writing-guide.md
index f94884a20..6d486112a 100644
--- a/docs/zh/api/99-api-doc-writing-guide.md
+++ b/docs/zh/api/99-api-doc-writing-guide.md
@@ -30,7 +30,7 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号
**代码入口**:
- `openviking/<模块>/<文件>.py:<类名>.<方法名>` - 核心实现
- `openviking/server/routers/<路由文件>.py` - HTTP 路由
-- `openviking_cli/commands/<命令文件>.py` - CLI 命令
+- `crates/ov_cli/src/commands/<命令文件>.rs` - CLI 命令
#### 2. 接口和参数说明
@@ -174,10 +174,11 @@ API 文档应按 API 模块和具体接口组织,而不是按客户端语言
5. 建立向量索引
**代码入口**:
-- `openviking/core/client.py:OpenViking.add_resource()` - SDK 入口
-- `openviking/resource/importer.py:ResourceImporter.import_resource()` - 核心实现
-- `openviking/server/routers/resources.py` - HTTP 路由
-- `openviking_cli/commands/resources.py` - CLI 命令
+- `openviking/async_client.py:AsyncOpenViking.add_resource()` - 异步 SDK 入口
+- `openviking/sync_client.py:SyncOpenViking.add_resource()` - 同步 SDK 入口
+- `openviking/service/resource_service.py:ResourceService.add_resource()` - 核心实现
+- `openviking/server/routers/resources.py:add_resource()` - HTTP 路由
+- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - CLI 处理函数
#### 2. 接口和参数说明
diff --git a/docs/zh/concepts/04-viking-uri.md b/docs/zh/concepts/04-viking-uri.md
index c0b61fa34..715e9bb44 100644
--- a/docs/zh/concepts/04-viking-uri.md
+++ b/docs/zh/concepts/04-viking-uri.md
@@ -201,7 +201,7 @@ ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}
ov read "viking://resources/logs/{calendar:yesterday}/app.log"
# 准备明天的任务
-ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "规划一天"
+ov write "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "规划一天"
# 上传月度报告 --parent-auto-create 可以简写为 -p
ov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdf
diff --git a/docs/zh/concepts/10-encryption.md b/docs/zh/concepts/10-encryption.md
index abe479f9b..34566e6b9 100644
--- a/docs/zh/concepts/10-encryption.md
+++ b/docs/zh/concepts/10-encryption.md
@@ -85,7 +85,7 @@ OpenViking 支持三种密钥提供程序,适应不同的部署场景:
**初始化命令**:
```bash
-ov crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
```
### Vault(HashiCorp Vault)
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 05dda0ca8..b16ed5fb4 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -13,7 +13,7 @@ openviking-server doctor
## 快速开始
-在项目目录创建 `~/.openviking/ov.conf`:
+在用户配置目录 `~/.openviking/` 下创建 `ov.conf`:
```json
{
@@ -1368,7 +1368,7 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
| `upload.ignore_dirs` | `add-resource` 默认忽略目录列表(CSV) | `null` |
| `upload.include` | `add-resource` 默认包含模式(CSV) | `null` |
| `upload.exclude` | `add-resource` 默认排除模式(CSV) | `null` |
-| `upload.mode` | 临时上传后端:`"local"`(仅当前实例本地磁盘)或 `"shared"`(分布式共享存储,当消费请求可能落到不同实例时必需)。可通过 `OPENVIKING_UPLOAD_MODE` 单次覆盖。 | `null`(使用服务端 `temp_upload.default_mode`,默认仍为 `"local"`) |
+| `upload.mode` | Python HTTP client 的临时上传后端:`"local"`(仅当前实例本地磁盘)或 `"shared"`(分布式共享存储)。Rust `ov` CLI 不读取这个字段;如需 shared 上传,请设置 `OPENVIKING_UPLOAD_MODE=shared`。 | `null`(使用服务端 `temp_upload.default_mode`,默认仍为 `"local"`) |
本地目录上传会默认遵循 `.gitignore`(根目录和子目录,含 `!` 反向规则)。`ignore_dirs/include/exclude` 会在此基础上进一步过滤。
diff --git a/docs/zh/guides/07-operation-telemetry.md b/docs/zh/guides/07-operation-telemetry.md
index 5a5e4acb5..ef44541e9 100644
--- a/docs/zh/guides/07-operation-telemetry.md
+++ b/docs/zh/guides/07-operation-telemetry.md
@@ -120,7 +120,7 @@ curl -X POST http://localhost:1933/api/v1/resources/temp_upload \
```
这个接口当前只支持布尔形态的表单参数。
-这个接口的 `upload_mode` 也是表单字段;默认值为 `local`,只有在明确需要分布式共享临时上传时,才应设置为 `shared`。Python HTTP client / CLI 用户也可以通过 `ovcli.conf` 的 `upload.mode = "shared"` 达到同样效果。
+这个接口的 `upload_mode` 也是表单字段;默认值为 `local`,只有在明确需要分布式共享临时上传时,才应设置为 `shared`。Python HTTP client 也可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`。
## 常见 summary 分组
diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.md
index da12b8d5d..166ee5aeb 100644
--- a/docs/zh/guides/08-encryption.md
+++ b/docs/zh/guides/08-encryption.md
@@ -31,7 +31,7 @@ OpenViking 提供透明的静态数据加密,确保多租户环境下的数据
### 1. 初始化根密钥(Local 模式)
```bash
-ov system crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
```
### 2. 配置加密
@@ -176,10 +176,10 @@ OpenViking 提供两层加密保护:
```bash
# 生成并保存到指定路径
-ov system crypto init-key --output ~/.openviking/master.key
+ov system crypto init-key --output-file ~/.openviking/master.key
# 或者使用简短命令
-ov system crypto init-key -o ~/.openviking/master.key
+ov system crypto init-key -f ~/.openviking/master.key
```
**输出示例**: