Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(cli): expose hidden help options (#2574)
Zayn Jarvisd5bb3b8df7d5
diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rsindex fc7602dc7..6191fc726 100644--- a/crates/ov_cli/src/help_ui.rs+++ b/crates/ov_cli/src/help_ui.rs@@ -1,9 +1,11 @@use std::ffi::OsString;+use clap::{Arg, ArgAction, Command, CommandFactory};use colored::Colorize;use unicode_width::UnicodeWidthStr;use crate::{+ Cli,i18n::{Language, copy},theme,};@@ -12,12 +14,17 @@ const BOX_WIDTH: usize = 74;const COMMAND_WIDTH: usize = 16;const DESCRIPTION_WIDTH: usize = BOX_WIDTH - COMMAND_WIDTH - 5;const COMMAND_HELP_LEFT_WIDTH: usize = 34;+const START_HERE_DESCRIPTION_WIDTH: usize = 56;#[derive(Debug, Clone, Copy)]struct HelpCommand {name: &'static str,- description: &'static str,- badge: Option<&'static str>,+}++macro_rules! help_commands {+ ($($name:literal),+ $(,)?) => {+ &[$(HelpCommand { name: $name }),+]+ };}#[derive(Debug, Clone, Copy)]@@ -32,275 +39,59 @@ struct HelpItem {description: &'static str,}+#[derive(Debug, Clone)]+struct RenderedHelpItem {+ label: String,+ description: String,+}++#[derive(Debug, Clone)]+struct RenderedHelpSection {+ title: String,+ items: Vec<RenderedHelpItem>,+}+#[derive(Debug, Clone, Copy)]struct CommandHelpSpec {path: &'static [&'static str],purpose: &'static str,- usage: &'static str,examples: &'static [HelpItem],- arguments: &'static [HelpItem],- common_options: &'static [HelpItem],- advanced_options: &'static [HelpItem],- subcommands: &'static [HelpItem],next_steps: &'static [HelpItem],}-const CORE_WORKFLOW: &[HelpCommand] = &[- HelpCommand {- name: "add-resource",- description: "Add files, folders, URLs, or repos into OpenViking",- badge: None,- },- HelpCommand {- name: "add-skill",- description: "Add a skill into OpenViking",- badge: None,- },- HelpCommand {- name: "find",- description: "Retrieve relevant context semantically",- badge: None,- },- HelpCommand {- name: "read",- description: "Read exact resource content",- badge: None,- },- HelpCommand {- name: "write",- description: "Update an existing resource",- badge: None,- },- HelpCommand {- name: "add-memory",- description: "Add a memory directly",- badge: None,- },+const CORE_WORKFLOW: &[HelpCommand] = help_commands![+ "add-resource",+ "add-skill",+ "skills",+ "find",+ "read",+ "write",+ "add-memory",];-const FILESYSTEM: &[HelpCommand] = &[- HelpCommand {- name: "ls",- description: "List directory contents",- badge: None,- },- HelpCommand {- name: "tree",- description: "Show a scoped resource tree",- badge: None,- },- HelpCommand {- name: "mkdir",- description: "Create a directory",- badge: None,- },- HelpCommand {- name: "rm",- description: "Remove a resource",- badge: None,- },- HelpCommand {- name: "mv",- description: "Move or rename a resource",- badge: None,- },- HelpCommand {- name: "stat",- description: "Show resource metadata",- badge: None,- },- HelpCommand {- name: "get",- description: "Download a file",- badge: None,- },-];+const FILESYSTEM: &[HelpCommand] = help_commands!["ls", "tree", "mkdir", "rm", "mv", "stat", "get"];-const SEARCH_CONTEXT: &[HelpCommand] = &[- HelpCommand {- name: "find",- description: "Semantic retrieval",- badge: None,- },- HelpCommand {- name: "search",- description: "Context-aware retrieval",- badge: Some("experimental"),- },- HelpCommand {- name: "grep",- description: "Pattern search",- badge: None,- },- HelpCommand {- name: "glob",- description: "Glob search",- badge: None,- },- HelpCommand {- name: "abstract",- description: "Read Level 0 abstract",- badge: None,- },- HelpCommand {- name: "overview",- description: "Read Level 1 overview",- badge: None,- },- HelpCommand {- name: "read",- description: "Read Level 2 content",- badge: None,- },+const SEARCH_CONTEXT: &[HelpCommand] = help_commands![+ "find", "search", "grep", "glob", "abstract", "overview", "read"];-const CONFIG_STATUS: &[HelpCommand] = &[- HelpCommand {- name: "config",- description: "Manage configs",- badge: None,- },- HelpCommand {- name: "config show",- description: "Show active config",- badge: None,- },- HelpCommand {- name: "config validate",- description: "Validate active config",- badge: None,- },- HelpCommand {- name: "config switch",- description: "Switch active config",- badge: None,- },- HelpCommand {- name: "config add",- description: "Add a config non-interactively",- badge: None,- },- HelpCommand {- name: "config list",- description: "List saved configs",- badge: None,- },- HelpCommand {- name: "config delete",- description: "Delete a saved config",- badge: None,- },- HelpCommand {- name: "language",- description: "Choose CLI display language (alias: lang)",- badge: None,- },- HelpCommand {- name: "health",- description: "Quick health check",- badge: None,- },- HelpCommand {- name: "status",- description: "Full server status",- badge: None,- },- HelpCommand {- name: "observer",- description: "Inspect server subsystems",- badge: None,- },- HelpCommand {- name: "wait",- description: "Wait for async work",- badge: None,- },- HelpCommand {- name: "task",- description: "Track async tasks",- badge: None,- },- HelpCommand {- name: "version",- description: "Show CLI version",- badge: None,- },+const CONFIG_STATUS: &[HelpCommand] = help_commands![+ "config", "language", "health", "status", "observer", "wait", "task", "version",];-const IMPORT_EXPORT_SESSIONS: &[HelpCommand] = &[- HelpCommand {- name: "import",- description: "Import .ovpack",- badge: None,- },- HelpCommand {- name: "export",- description: "Export context as .ovpack",- badge: None,- },- HelpCommand {- name: "backup",- description: "Create restore-only backup",- badge: None,- },- HelpCommand {- name: "restore",- description: "Restore backup",- badge: None,- },- HelpCommand {- name: "session",- description: "Manage sessions",- badge: None,- },- HelpCommand {- name: "privacy",- description: "Manage privacy config",- badge: None,- },+const IMPORT_EXPORT_SESSIONS: &[HelpCommand] = help_commands![+ "import", "export", "backup", "restore", "session", "privacy"];-const INTERACTIVE_ADMIN: &[HelpCommand] = &[- HelpCommand {- name: "tui",- description: "Interactive file explorer",- badge: None,- },- HelpCommand {- name: "chat",- description: "Chat with vikingbot",- badge: None,- },- HelpCommand {- name: "admin",- description: "Account and user management",- badge: None,- },- HelpCommand {- name: "system",- description: "System utilities",- badge: None,- },- HelpCommand {- name: "reindex",- description: "Reindex semantic/vector artifacts",- badge: None,- },- HelpCommand {- name: "relations",- description: "List resource relations",- badge: Some("experimental"),- },- HelpCommand {- name: "link",- description: "Create relation links",- badge: Some("experimental"),- },- HelpCommand {- name: "unlink",- description: "Remove relation links",- badge: Some("experimental"),- },+const INTERACTIVE_ADMIN: &[HelpCommand] = help_commands![+ "tui",+ "chat",+ "admin",+ "system",+ "reindex",+ "relations",+ "link",+ "unlink"];const HELP_SECTIONS: &[HelpSection] = &[@@ -330,30 +121,10 @@ const HELP_SECTIONS: &[HelpSection] = &[},];-const GLOBAL_OPTIONS: &[HelpItem] = &[- HelpItem {- label: "-o, --output <table|json>",- description: "Choose human table output or machine-readable JSON.",- },- HelpItem {- label: "-c, --compact <bool>",- description: "Use compact table/JSON rendering.",- },- HelpItem {- label: "--account <account>",- description: "Override X-OpenViking-Account for this command.",- },- HelpItem {- label: "--user <user>",- description: "Override X-OpenViking-User for this command.",- },-];-const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["add-resource"],purpose: "Import a local file, folder, URL, or repository into OpenViking.",- usage: "ov add-resource <path-or-url> [--parent <uri>|--to <uri>] [--wait]",examples: &[HelpItem {label: "ov add-resource ./docs --parent viking://projects/acme --wait",@@ -364,55 +135,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Import a URL to an exact target URI.",},],- arguments: &[HelpItem {- label: "<path-or-url>",- description: "Local path, URL, or repository to import.",- }],- common_options: &[- HelpItem {- label: "--parent <uri>",- description: "Import under an existing directory URI.",- },- HelpItem {- label: "-p, --parent-auto-create <uri>",- description: "Create the parent directory if missing.",- },- HelpItem {- label: "--to <uri>",- description: "Import to an exact new resource URI.",- },- HelpItem {- label: "--wait",- description: "Wait until indexing/processing completes.",- },- HelpItem {- label: "--include / --exclude",- description: "Filter files during folder import.",- },- ],- advanced_options: &[- HelpItem {- label: "--reason <text>",- description: "Attach an import reason.",- },- HelpItem {- label: "--instruction <text>",- description: "Attach processing instructions.",- },- HelpItem {- label: "--watch-interval <minutes>",- description: "Set automatic refresh cadence.",- },- HelpItem {- label: "--progress / --no-progress",- description: "Override local upload progress display.",- },- HelpItem {- label: "-v, --verbose",- description: "Print upload diagnostics.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov task list",@@ -431,7 +153,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["add-skill"],purpose: "Import a skill directory, SKILL.md file, or raw skill content.",- usage: "ov add-skill <skill-path-or-content> [--wait]",examples: &[HelpItem {label: "ov add-skill ./skills/my-skill --wait",@@ -442,46 +163,44 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Import a single skill definition.",},],- arguments: &[HelpItem {- label: "<skill-path-or-content>",- description: "Skill folder, SKILL.md path, or raw content.",- }],- common_options: &[+ next_steps: &[HelpItem {- label: "--wait",- description: "Wait until skill processing completes.",+ label: "ov find \"skill topic\"",+ description: "Search imported skill context.",},HelpItem {- label: "--timeout <seconds>",- description: "Maximum wait time when using --wait.",+ label: "ov task list",+ description: "Check processing status.",},],- advanced_options: &[+ },+ CommandHelpSpec {+ path: &["skills"],+ purpose: "Manage installed agent skills.",+ examples: &[HelpItem {- label: "--progress / --no-progress",- description: "Override local upload progress display.",+ label: "ov skills list",+ description: "List installed skills.",},HelpItem {- label: "-v, --verbose",- description: "Print upload diagnostics.",+ label: "ov skills find \"code review\"",+ description: "Search installed skills semantically.",},],- subcommands: &[],next_steps: &[HelpItem {- label: "ov find \"skill topic\"",- description: "Search imported skill context.",+ label: "ov skills <subcommand> --help",+ description: "Show exact arguments for a skill operation.",},HelpItem {- label: "ov task list",- description: "Check processing status.",+ label: "ov add-skill ./skills/my-skill",+ description: "Import a new skill.",},],},CommandHelpSpec {path: &["ls"],purpose: "List resources under a Viking URI.",- usage: "ov ls [uri] [--recursive] [--all]",examples: &[HelpItem {label: "ov ls",@@ -492,33 +211,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "List a subtree recursively.",},],- arguments: &[HelpItem {- label: "[uri]",- description: "Directory URI to list. Defaults to viking://.",- }],- common_options: &[- HelpItem {- label: "-r, --recursive",- description: "List nested directories recursively.",- },- HelpItem {- label: "-s, --simple",- description: "Print only paths.",- },- HelpItem {- label: "-a, --all",- description: "Include hidden files.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Limit number of listed nodes.",- },- ],- advanced_options: &[HelpItem {- label: "-l, --abs-limit <n>",- description: "Limit abstract text in agent-oriented output.",- }],- subcommands: &[],next_steps: &[HelpItem {label: "ov tree <uri>",@@ -533,34 +225,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["tree"],purpose: "Show a hierarchical view of resources under a URI.",- usage: "ov tree <uri> [--level-limit <n>] [--node-limit <n>]",examples: &[HelpItem {label: "ov tree viking://projects/acme -L 4",description: "Show a project tree up to depth 4.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "Directory URI to inspect.",- }],- common_options: &[- HelpItem {- label: "-L, --level-limit <n>",- description: "Maximum traversal depth.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Maximum number of nodes.",- },- HelpItem {- label: "-a, --all",- description: "Include hidden files.",- },- ],- advanced_options: &[HelpItem {- label: "-l, --abs-limit <n>",- description: "Limit abstract text in agent-oriented output.",- }],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",@@ -575,21 +243,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["mkdir"],purpose: "Create a directory in OpenViking.",- usage: "ov mkdir <uri> [--description <text>]",examples: &[HelpItem {label: "ov mkdir viking://projects/acme --description \"ACME project context\"",description: "Create a project folder with a description.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "Directory URI to create.",- }],- common_options: &[HelpItem {- label: "--description <text>",- description: "Initial directory description.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov add-resource ./docs --parent <uri>",description: "Import content into the new directory.",@@ -598,7 +255,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["rm"],purpose: "Remove a resource from OpenViking.",- usage: "ov rm <uri> [--recursive]",examples: &[HelpItem {label: "ov rm viking://scratch/old-note.md",@@ -609,16 +265,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Remove a directory subtree.",},],- arguments: &[HelpItem {- label: "<uri>",- description: "Resource URI to remove.",- }],- common_options: &[HelpItem {- label: "-r, --recursive",- description: "Required for directory/subtree removal.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov ls <parent-uri>",@@ -633,24 +279,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["mv"],purpose: "Move or rename a resource.",- usage: "ov mv <from-uri> <to-uri>",examples: &[HelpItem {label: "ov mv viking://notes/draft.md viking://notes/final.md",description: "Rename a file resource.",}],- arguments: &[- HelpItem {- label: "<from-uri>",- description: "Existing resource URI.",- },- HelpItem {- label: "<to-uri>",- description: "Destination URI.",- },- ],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov stat <to-uri>",@@ -665,18 +297,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["stat"],purpose: "Show metadata for one resource.",- usage: "ov stat <uri>",examples: &[HelpItem {label: "ov stat viking://projects/acme/spec.md",description: "Inspect resource metadata.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "Resource URI to inspect.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",@@ -691,18 +315,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["read"],purpose: "Read exact Level 2 file content from a Viking URI.",- usage: "ov read <uri>",examples: &[HelpItem {label: "ov read viking://projects/acme/spec.md",description: "Print exact file content.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "File resource URI.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov write <uri> --content \"...\"",@@ -717,18 +333,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["abstract"],purpose: "Read Level 0 abstract content for a directory.",- usage: "ov abstract <directory-uri>",examples: &[HelpItem {label: "ov abstract viking://projects/acme",description: "Read the compact directory abstract.",}],- arguments: &[HelpItem {- label: "<directory-uri>",- description: "Directory URI.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov overview <directory-uri>",description: "Read a richer Level 1 overview.",@@ -737,18 +345,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["overview"],purpose: "Read Level 1 overview content for a directory.",- usage: "ov overview <directory-uri>",examples: &[HelpItem {label: "ov overview viking://projects/acme",description: "Read the directory overview.",}],- arguments: &[HelpItem {- label: "<directory-uri>",- description: "Directory URI.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <file-uri>",description: "Open exact Level 2 content.",@@ -757,7 +357,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["write"],purpose: "Update text content in an existing resource.",- usage: "ov write <uri> (--content <text>|--from-file <path>) [--append|--mode <mode>]",examples: &[HelpItem {label: "ov write viking://notes/todo.md --content \"Ship config UX\"",@@ -768,33 +367,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Write from disk and wait for processing.",},],- arguments: &[HelpItem {- label: "<uri>",- description: "Existing resource URI.",- }],- common_options: &[- HelpItem {- label: "--content <text>",- description: "Inline replacement content.",- },- HelpItem {- label: "--from-file <path>",- description: "Read replacement content from disk.",- },- HelpItem {- label: "--append",- description: "Append instead of replacing.",- },- HelpItem {- label: "--wait",- description: "Wait for async processing.",- },- ],- advanced_options: &[HelpItem {- label: "--mode <replace|append|create>",- description: "Explicit write mode.",- }],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",@@ -809,24 +381,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["get"],purpose: "Download a file resource to a local path.",- usage: "ov get <uri> <local-path>",examples: &[HelpItem {label: "ov get viking://assets/logo.png ./logo.png",description: "Download a binary or text file.",}],- arguments: &[- HelpItem {- label: "<uri>",- description: "File resource URI.",- },- HelpItem {- label: "<local-path>",- description: "Destination path that does not already exist.",- },- ],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov stat <uri>",description: "Inspect source metadata.",@@ -835,7 +393,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["find"],purpose: "Retrieve relevant OpenViking context semantically.",- usage: "ov find <query> [--uri <uri>] [--node-limit <n>]",examples: &[HelpItem {label: "ov find \"deployment rollback steps\"",@@ -846,39 +403,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Search a subtree and include overview/file results.",},],- arguments: &[HelpItem {- label: "<query>",- description: "Natural-language search query.",- }],- common_options: &[- HelpItem {- label: "-u, --uri <uri>",- description: "Limit search to a subtree.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Maximum final results returned.",- },- HelpItem {- label: "-t, --threshold <score>",- description: "Minimum relevance score.",- },- HelpItem {- label: "-L, --level <0,1,2>",- description: "Filter abstract, overview, or file results.",- },- ],- advanced_options: &[- HelpItem {- label: "--after <time>",- description: "Only include newer results, e.g. 48h or 2026-03-10.",- },- HelpItem {- label: "--before <time>",- description: "Only include older results, e.g. 24h or ISO-8601.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",@@ -893,44 +417,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["search"],purpose: "Run experimental context-aware retrieval, optionally scoped to a session.",- usage: "ov search <query> [--session-id <id>] [--uri <uri>]",examples: &[HelpItem {label: "ov search \"what changed last time?\" --session-id abc123",description: "Search with session context.",}],- arguments: &[HelpItem {- label: "<query>",- description: "Natural-language search query.",- }],- common_options: &[- HelpItem {- label: "--session-id <id>",- description: "Session context for retrieval.",- },- HelpItem {- label: "-u, --uri <uri>",- description: "Limit search to a subtree.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Maximum results per search pass. Search may merge multiple passes.",- },- ],- advanced_options: &[- HelpItem {- label: "-t, --threshold <score>",- description: "Minimum relevance score.",- },- HelpItem {- label: "--after / --before",- description: "Time-bound results.",- },- HelpItem {- label: "-L, --level <0,1,2>",- description: "Filter by context level.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov session get-session-context <id>",description: "Inspect the session context directly.",@@ -939,40 +429,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["grep"],purpose: "Search resource content with a text pattern.",- usage: "ov grep <pattern> [--uri <uri>] [--ignore-case]",examples: &[HelpItem {label: "ov grep \"TODO\" -u viking://projects/acme -i",description: "Find case-insensitive matches in a subtree.",}],- arguments: &[HelpItem {- label: "<pattern>",- description: "Text pattern to search for.",- }],- common_options: &[- HelpItem {- label: "-u, --uri <uri>",- description: "Search root. Defaults to viking://.",- },- HelpItem {- label: "-i, --ignore-case",- description: "Match case-insensitively.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Maximum number of results.",- },- ],- advanced_options: &[- HelpItem {- label: "-x, --exclude-uri <uri>",- description: "Skip matches under a URI prefix.",- },- HelpItem {- label: "-L, --level-limit <n>",- description: "Maximum traversal depth.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",description: "Open a matching resource.",@@ -981,27 +441,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["glob"],purpose: "Find resources by glob pattern.",- usage: "ov glob <pattern> [--uri <uri>]",examples: &[HelpItem {label: "ov glob \"**/*.md\" -u viking://projects/acme",description: "Find Markdown files in a project.",}],- arguments: &[HelpItem {- label: "<pattern>",- description: "Glob pattern to match resource paths.",- }],- common_options: &[- HelpItem {- label: "-u, --uri <uri>",- description: "Search root. Defaults to viking://.",- },- HelpItem {- label: "-n, --node-limit <n>",- description: "Maximum number of results.",- },- ],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov read <uri>",description: "Read one matched file.",@@ -1010,7 +453,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["session"],purpose: "Manage sessions, messages, archives, and committed session context.",- usage: "ov session <subcommand>",examples: &[HelpItem {label: "ov session new",@@ -1021,35 +463,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Append a message.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "new",- description: "Create a session.",- },- HelpItem {- label: "list",- description: "List sessions.",- },- HelpItem {- label: "get <id>",- description: "Show session details.",- },- HelpItem {- label: "get-session-context <id>",- description: "Read merged session context.",- },- HelpItem {- label: "add-message <id>",- description: "Append one message.",- },- HelpItem {- label: "commit <id>",- description: "Archive messages and extract memories.",- },- ],next_steps: &[HelpItem {label: "ov session <subcommand> --help",description: "Show exact arguments for a session operation.",@@ -1058,7 +471,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["add-memory"],purpose: "Add a memory directly from text or JSON messages.",- usage: "ov add-memory <content>",examples: &[HelpItem {label: "ov add-memory \"The deployment owner is Alice\"",@@ -1069,13 +481,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Add one structured message.",},],- arguments: &[HelpItem {- label: "<content>",- description: "Plain text, one JSON message, or a JSON message array.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov find \"memory topic\"",description: "Verify the memory is retrievable.",@@ -1084,7 +489,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["privacy"],purpose: "Manage privacy config categories, targets, versions, and activation.",- usage: "ov privacy <subcommand>",examples: &[HelpItem {label: "ov privacy categories",@@ -1095,31 +499,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Show active values for one target.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "categories",- description: "List categories.",- },- HelpItem {- label: "list <category>",- description: "List targets.",- },- HelpItem {- label: "get <category> <target>",- description: "Show active config.",- },- HelpItem {- label: "upsert <category> <target>",- description: "Update values.",- },- HelpItem {- label: "versions / version / activate",- description: "Inspect or activate versions.",- },- ],next_steps: &[HelpItem {label: "ov privacy <subcommand> --help",description: "Show exact arguments for a privacy operation.",@@ -1128,18 +507,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["relations"],purpose: "List relation links for one resource. Experimental.",- usage: "ov relations <uri>",examples: &[HelpItem {label: "ov relations viking://projects/acme/spec.md",description: "Inspect linked resources.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "Source resource URI.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov link <from-uri> <to-uri>",@@ -1154,27 +525,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["link"],purpose: "Create one or more relation links between resources. Experimental.",- usage: "ov link <from-uri> <to-uri>... [--reason <text>]",examples: &[HelpItem {label: "ov link viking://a.md viking://b.md --reason \"related design\"",description: "Link two resources with a reason.",}],- arguments: &[- HelpItem {- label: "<from-uri>",- description: "Source resource URI.",- },- HelpItem {- label: "<to-uri>...",- description: "One or more target URIs.",- },- ],- common_options: &[HelpItem {- label: "--reason <text>",- description: "Why these resources are linked.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov relations <from-uri>",description: "Confirm the relation.",@@ -1183,24 +537,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["unlink"],purpose: "Remove one relation link between resources. Experimental.",- usage: "ov unlink <from-uri> <to-uri>",examples: &[HelpItem {label: "ov unlink viking://a.md viking://b.md",description: "Remove a relation.",}],- arguments: &[- HelpItem {- label: "<from-uri>",- description: "Source resource URI.",- },- HelpItem {- label: "<to-uri>",- description: "Target URI to unlink.",- },- ],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov relations <from-uri>",description: "Confirm the relation is gone.",@@ -1209,27 +549,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["export"],purpose: "Export context from a URI as an .ovpack file.",- usage: "ov export <uri> <output.ovpack> [--include-vectors]",examples: &[HelpItem {label: "ov export viking://projects/acme ./acme.ovpack",description: "Export a project subtree.",}],- arguments: &[- HelpItem {- label: "<uri>",- description: "Source URI to export.",- },- HelpItem {- label: "<output.ovpack>",- description: "Output file path.",- },- ],- common_options: &[HelpItem {- label: "--include-vectors",- description: "Include compatible dense vector snapshots.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov import ./file.ovpack <target-uri>",description: "Import the exported pack elsewhere.",@@ -1238,21 +561,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["backup"],purpose: "Create a restore-only backup .ovpack for public OpenViking scopes.",- usage: "ov backup <output.ovpack> [--include-vectors]",examples: &[HelpItem {label: "ov backup ./openviking-backup.ovpack --include-vectors",description: "Create a backup with vectors when compatible.",}],- arguments: &[HelpItem {- label: "<output.ovpack>",- description: "Backup file path.",- }],- common_options: &[HelpItem {- label: "--include-vectors",- description: "Include compatible dense vector snapshots.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov restore ./openviking-backup.ovpack",description: "Restore this backup later.",@@ -1261,33 +573,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["import"],purpose: "Import an .ovpack into a target URI.",- usage: "ov import <file.ovpack> <target-uri> [--on-conflict <policy>]",examples: &[HelpItem {label: "ov import ./acme.ovpack viking://imports/acme --on-conflict skip",description: "Import while keeping existing resources.",}],- arguments: &[- HelpItem {- label: "<file.ovpack>",- description: "Input pack file.",- },- HelpItem {- label: "<target-uri>",- description: "Target parent URI.",- },- ],- common_options: &[- HelpItem {- label: "--on-conflict <fail|overwrite|skip>",- description: "Choose how to handle existing resources.",- },- HelpItem {- label: "--vector-mode <auto|recompute|require>",- description: "Choose vector snapshot handling.",- },- ],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov tree <target-uri>",@@ -1302,31 +591,14 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["restore"],purpose: "Restore a backup .ovpack to its original public scope roots.",- usage: "ov restore <backup.ovpack> [--on-conflict <policy>]",examples: &[HelpItem {label: "ov restore ./openviking-backup.ovpack --on-conflict fail",description: "Restore only if there are no conflicts.",}],- arguments: &[HelpItem {- label: "<backup.ovpack>",- description: "Backup pack file.",- }],- common_options: &[+ next_steps: &[HelpItem {- label: "--on-conflict <fail|overwrite|skip>",- description: "Choose how to handle existing resources.",- },- HelpItem {- label: "--vector-mode <auto|recompute|require>",- description: "Choose vector snapshot handling.",- },- ],- advanced_options: &[],- subcommands: &[],- next_steps: &[- HelpItem {- label: "ov status",- description: "Check service health after restore.",+ label: "ov status",+ description: "Check service health after restore.",},HelpItem {label: "ov tree viking://",@@ -1337,18 +609,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["tui"],purpose: "Open the interactive file explorer.",- usage: "ov tui [uri]",examples: &[HelpItem {label: "ov tui viking://projects/acme",description: "Browse a project subtree interactively.",}],- arguments: &[HelpItem {- label: "[uri]",- description: "Start URI. Defaults to /.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov tree <uri>",description: "Use a non-interactive tree view instead.",@@ -1357,7 +621,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["chat"],purpose: "Chat with the vikingbot agent.",- usage: "ov chat [--message <text>] [--session <id>]",examples: &[HelpItem {label: "ov chat",@@ -1368,36 +631,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Send one message.",},],- arguments: &[],- common_options: &[- HelpItem {- label: "-m, --message <text>",- description: "Send one message instead of interactive input.",- },- HelpItem {- label: "-s, --session <id>",- description: "Use a specific chat session.",- },- HelpItem {- label: "--no-format",- description: "Disable rich formatting.",- },- ],- advanced_options: &[- HelpItem {- label: "--sender <id>",- description: "Set sender ID.",- },- HelpItem {- label: "--stream <bool>",- description: "Enable or disable streaming.",- },- HelpItem {- label: "--no-history",- description: "Disable command history.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov find \"topic\"",description: "Search context directly.",@@ -1406,18 +639,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["wait"],purpose: "Wait for queued async processing to complete.",- usage: "ov wait [--timeout <seconds>]",examples: &[HelpItem {label: "ov wait --timeout 120",description: "Wait up to two minutes.",}],- arguments: &[],- common_options: &[HelpItem {- label: "--timeout <seconds>",- description: "Maximum wait time.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov task list",@@ -1432,7 +657,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["task"],purpose: "Inspect and manage async processing tasks.",- usage: "ov task <subcommand>",examples: &[HelpItem {label: "ov task list --status failed",@@ -1443,32 +667,38 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Inspect one task.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[+ next_steps: &[HelpItem {+ label: "ov wait",+ description: "Wait for queued work.",+ }],+ },+ CommandHelpSpec {+ path: &["task", "watch"],+ purpose: "Inspect and manage automatic resource refresh subscriptions.",+ examples: &[HelpItem {- label: "status <task-id>",- description: "Show one task.",+ label: "ov task watch ls",+ description: "List watch subscriptions.",},HelpItem {- label: "list",- description: "List tracked tasks.",+ label: "ov task watch update <task-or-uri> --interval 30",+ description: "Change a watch refresh interval.",+ },+ ],+ next_steps: &[+ HelpItem {+ label: "ov task watch <subcommand> --help",+ description: "Show exact arguments for a watch operation.",},HelpItem {- label: "watch <subcommand>",- description: "Manage auto-refresh subscriptions.",+ label: "ov task list",+ description: "Inspect async processing tasks.",},],- next_steps: &[HelpItem {- label: "ov wait",- description: "Wait for queued work.",- }],},CommandHelpSpec {path: &["status"],purpose: "Show OpenViking server readiness and component status.",- usage: "ov status [--verbose]",examples: &[HelpItem {label: "ov status",@@ -1479,13 +709,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Show full component tables.",},],- arguments: &[],- common_options: &[HelpItem {- label: "--verbose",- description: "Show full component tables instead of the curated diagnostic view.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov health",@@ -1500,7 +723,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["observer"],purpose: "Inspect specific OpenViking server subsystems.",- usage: "ov observer <subcommand>",examples: &[HelpItem {label: "ov observer models",@@ -1511,27 +733,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Inspect queue status.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "queue",- description: "Queue status.",- },- HelpItem {- label: "models",- description: "Model status.",- },- HelpItem {- label: "transaction",- description: "Transaction system status.",- },- HelpItem {- label: "filesystem / retrieval / system",- description: "Operational metrics.",- },- ],next_steps: &[HelpItem {label: "ov status",description: "Return to the full status view.",@@ -1540,15 +741,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["health"],purpose: "Run a quick server reachability check.",- usage: "ov health",examples: &[HelpItem {label: "ov health",description: "Check whether the active server is reachable.",}],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config validate",@@ -1563,7 +759,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config"],purpose: "Add, edit, delete, show, validate, or switch OpenViking CLI configs.",- usage: "ov config [show|validate|switch|list|add|edit|delete]",examples: &[HelpItem {label: "ov config",@@ -1582,39 +777,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Probe the active config.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "show",- description: "Print active config with secrets redacted.",- },- HelpItem {- label: "validate",- description: "Probe the active server/auth config.",- },- HelpItem {- label: "switch",- description: "Switch the active saved config interactively or by name.",- },- HelpItem {- label: "list",- description: "List saved configs.",- },- HelpItem {- label: "add",- description: "Add an OpenViking Service or custom config without prompts.",- },- HelpItem {- label: "edit",- description: "Edit a saved config without prompts.",- },- HelpItem {- label: "delete",- description: "Delete a saved config without prompts.",- },- ],next_steps: &[HelpItem {label: "ov config validate",@@ -1629,15 +791,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "show"],purpose: "Print the active CLI config with secrets redacted.",- usage: "ov config show",examples: &[HelpItem {label: "ov config show",description: "Show the active server URL, config name, and safe fields.",}],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config",@@ -1652,15 +809,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "validate"],purpose: "Parse the active config and probe the configured OpenViking server.",- usage: "ov config validate",examples: &[HelpItem {label: "ov config validate",description: "Check active URL, auth, and server reachability.",}],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config",@@ -1675,7 +827,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "switch"],purpose: "Switch the active CLI config to a saved config.",- usage: "ov config switch [name]",examples: &[HelpItem {label: "ov config switch",@@ -1686,13 +837,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Activate a saved config without prompts.",},],- arguments: &[HelpItem {- label: "name",- description: "Optional saved config name. Omit it for the interactive picker.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config show",@@ -1707,7 +851,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "list"],purpose: "List saved CLI configs and mark which one is active.",- usage: "ov config list",examples: &[HelpItem {label: "ov config list",@@ -1718,10 +861,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Return saved configs as JSON for automation.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config switch <name>",@@ -1736,7 +875,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "add"],purpose: "Create a saved CLI config without opening the interactive wizard.",- usage: "ov config add <ov-service|custom> [options]",examples: &[HelpItem {label: "printf '%s' \"$OV_KEY\" | ov config add ov-service --api-key-stdin --activate",@@ -1747,19 +885,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Create and activate a local custom config.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "ov-service",- description: "Use the fixed OpenViking Service endpoint.",- },- HelpItem {- label: "custom",- description: "Use a local or hosted custom endpoint.",- },- ],next_steps: &[HelpItem {label: "ov config add ov-service --help",@@ -1774,7 +899,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "add", "ov-service"],purpose: "Create an OpenViking Service config without prompts.",- usage: "ov config add ov-service [--name <name>] (--api-key-stdin|--api-key-env <env>) [--account <account> --user <user>] [--activate] [--force]",examples: &[HelpItem {label: "printf '%s' \"$OV_KEY\" | ov config add ov-service --name prod --api-key-stdin --activate",@@ -1785,40 +909,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Read the API key from an environment variable and print JSON.",},],- arguments: &[],- common_options: &[- HelpItem {- label: "--name <name>",- description: "Saved config name. Generated if omitted.",- },- HelpItem {- label: "--api-key-stdin",- description: "Read the API key from stdin.",- },- HelpItem {- label: "--api-key-env <env>",- description: "Read the API key from an environment variable.",- },- HelpItem {- label: "--activate",- description: "Also write the active ovcli.conf.",- },- HelpItem {- label: "--force",- description: "Replace an existing saved config.",- },- ],- advanced_options: &[- HelpItem {- label: "--account <account>",- description: "Optional account identity override.",- },- HelpItem {- label: "--user <user>",- description: "Optional user identity override.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov config validate",@@ -1833,7 +923,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "add", "custom"],purpose: "Create a custom config without prompts.",- usage: "ov config add custom [--name <name>] [--url <url>] [--api-key-stdin|--api-key-env <env>] [--root-api-key-stdin|--root-api-key-env <env>] [--account <account>] [--user <user>] [--activate] [--force]",examples: &[HelpItem {label: "ov config add custom --name local --url http://127.0.0.1:1933 --activate",@@ -1844,44 +933,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Create a hosted custom config with an API key.",},],- arguments: &[],- common_options: &[- HelpItem {- label: "--name <name>",- description: "Saved config name. Generated if omitted.",- },- HelpItem {- label: "--url <url>",- description: "Server URL. Defaults to http://127.0.0.1:1933.",- },- HelpItem {- label: "--api-key-stdin / --api-key-env <env>",- description: "Read a normal API key from stdin or an environment variable.",- },- HelpItem {- label: "--root-api-key-stdin / --root-api-key-env <env>",- description: "Read a root API key from stdin or an environment variable.",- },- HelpItem {- label: "--activate",- description: "Also write the active ovcli.conf.",- },- HelpItem {- label: "--force",- description: "Replace an existing saved config.",- },- ],- advanced_options: &[- HelpItem {- label: "--account <account>",- description: "Account identity. Required when only a root key is supplied.",- },- HelpItem {- label: "--user <user>",- description: "User identity. Required when only a root key is supplied.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov config validate",@@ -1896,7 +947,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "edit"],purpose: "Edit a saved CLI config without prompts.",- usage: "ov config edit <name> [--new-name <name>] [--url <url>] [key options] [identity options] [--activate] [--force]",examples: &[HelpItem {label: "ov config edit prod --new-name production --activate",@@ -1911,47 +961,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Remove a normal API key from a saved config.",},],- arguments: &[HelpItem {- label: "name",- description: "Existing saved config name.",- }],- common_options: &[- HelpItem {- label: "--new-name <name>",- description: "Rename the saved config.",- },- HelpItem {- label: "--url <url>",- description: "Replace the custom server URL.",- },- HelpItem {- label: "--api-key-stdin / --api-key-env <env> / --clear-api-key",- description: "Replace or clear the normal API key.",- },- HelpItem {- label: "--root-api-key-stdin / --root-api-key-env <env> / --clear-root-api-key",- description: "Replace or clear the root API key.",- },- HelpItem {- label: "--activate",- description: "Also make the edited config active.",- },- HelpItem {- label: "--force",- description: "Replace an existing target name when renaming.",- },- ],- advanced_options: &[- HelpItem {- label: "--account <account>",- description: "Replace account identity.",- },- HelpItem {- label: "--user <user>",- description: "Replace user identity.",- },- ],- subcommands: &[],next_steps: &[HelpItem {label: "ov config validate",@@ -1966,7 +975,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["config", "delete"],purpose: "Delete a saved CLI config without prompts.",- usage: "ov config delete <name> [--force]",examples: &[HelpItem {label: "ov config delete old-local",@@ -1977,16 +985,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Return a JSON no-op if the config is already absent.",},],- arguments: &[HelpItem {- label: "name",- description: "Saved config name to delete.",- }],- common_options: &[HelpItem {- label: "--force",- description: "Reserved for future destructive delete behavior.",- }],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config list",@@ -2001,7 +999,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["language"],purpose: "Choose the OpenViking CLI display language.",- usage: "ov language [en|zh-CN]",examples: &[HelpItem {label: "ov language",@@ -2016,13 +1013,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Use the short alias to switch display text to English.",},],- arguments: &[HelpItem {- label: "language",- description: "Optional language code: en or zh-CN.",- }],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov config",description: "Open the config manager.",@@ -2031,15 +1021,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["version"],purpose: "Print the OpenViking CLI version.",- usage: "ov version",examples: &[HelpItem {label: "ov version",description: "Show the installed CLI version.",}],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov --help",description: "See all commands.",@@ -2048,7 +1033,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["admin"],purpose: "Manage accounts, users, roles, and API keys. Admin/root access required.",- usage: "ov admin <subcommand> [--sudo]",examples: &[HelpItem {label: "ov admin list-accounts --sudo",@@ -2059,30 +1043,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Register a user in an account.",},],- arguments: &[],- common_options: &[HelpItem {- label: "--sudo",- description: "Use root_api_key for root-only admin commands.",- }],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "create-account / delete-account",- description: "Create or remove an account.",- },- HelpItem {- label: "list-accounts",- description: "List accounts.",- },- HelpItem {- label: "register-user / remove-user",- description: "Manage account users.",- },- HelpItem {- label: "set-role / regenerate-key",- description: "Manage roles and API keys.",- },- ],next_steps: &[HelpItem {label: "ov config show",@@ -2097,7 +1057,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["system"],purpose: "Run server utility, health, consistency, backend sync, and crypto commands.",- usage: "ov system <subcommand>",examples: &[HelpItem {label: "ov system health",@@ -2112,27 +1071,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Inspect multi-write backend sync lag.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "wait / status / health",- description: "Operational checks.",- },- HelpItem {- label: "consistency <uri>",- description: "Check subtree consistency.",- },- HelpItem {- label: "backend <subcommand>",- description: "Inspect or repair multi-write backend sync state.",- },- HelpItem {- label: "crypto <subcommand>",- description: "Key management commands.",- },- ],next_steps: &[HelpItem {label: "ov status",description: "Use the standard status view.",@@ -2141,7 +1079,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["system", "backend"],purpose: "Inspect and repair multi-write backend sync state.",- usage: "ov system backend <subcommand>",examples: &[HelpItem {label: "ov system backend sync-status viking://resources",@@ -2152,19 +1089,6 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Retry lagging backend sync targets.",},],- arguments: &[],- common_options: &[],- advanced_options: &[],- subcommands: &[- HelpItem {- label: "sync-status <uri>",- description: "Show multi-write backend sync status for a subtree.",- },- HelpItem {- label: "sync-retry <uri>",- description: "Retry pending multi-write backend sync work.",- },- ],next_steps: &[HelpItem {label: "ov system backend sync-status <uri>",description: "Inspect the subtree again after retry.",@@ -2173,31 +1097,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[CommandHelpSpec {path: &["reindex"],purpose: "Reindex semantic/vector artifacts for a URI.",- usage: "ov reindex <uri> [--mode <mode>] [--wait <bool>] [--sudo]",examples: &[HelpItem {label: "ov reindex viking://projects/acme --mode vectors_only --wait true",description: "Rebuild vector artifacts and wait.",}],- arguments: &[HelpItem {- label: "<uri>",- description: "Subtree URI to reindex.",- }],- common_options: &[- HelpItem {- label: "--mode <mode>",- description: "Reindex mode. Defaults to vectors_only.",- },- HelpItem {- label: "--wait <bool>",- description: "Wait for completion. Defaults to true.",- },- HelpItem {- label: "--sudo",- description: "Use root API key when required.",- },- ],- advanced_options: &[],- subcommands: &[],next_steps: &[HelpItem {label: "ov task list",@@ -2234,6 +1137,8 @@ pub(crate) fn render_top_level_help() -> String {pub(crate) fn render_top_level_help_with_language(language: Language) -> String {let mut lines = Vec::new();+ let mut root = Cli::command();+ root.build();lines.push(format!("{} {}",@@ -2260,34 +1165,15 @@ pub(crate) fn render_top_level_help_with_language(language: Language) -> String"{}",theme::strong(copy(language, "Start here:", "从这里开始:"))));- lines.push(start_here_line(- "ov config",- copy(- language,- "Add, edit, or delete configs",- "添加、编辑或删除配置",- ),- ));- lines.push(start_here_line(- "ov health",- copy(language, "Check server reachability", "检查服务器连接"),- ));- lines.push(start_here_line(- "ov status",- copy(language, "Inspect server status", "查看服务器状态"),- ));- lines.push(start_here_line(- "ov tui",- copy(- language,- "Browse OpenViking interactively",- "交互式浏览 OpenViking",- ),- ));+ for command in ["config", "health", "status", "tui"] {+ if let Some(line) = top_level_start_here_line(&root, command, language) {+ lines.push(line);+ }+ }lines.push(String::new());for section in HELP_SECTIONS {- lines.extend(section_lines(section));+ lines.extend(section_lines(section, &root, language));lines.push(String::new());}@@ -2295,38 +1181,9 @@ pub(crate) fn render_top_level_help_with_language(language: Language) -> String"{}",theme::strong(copy(language, "Global options:", "全局选项:"))));- lines.push(option_line(- "-o, --output <table|json>",- copy(language, "Output format", "输出格式"),- ));- lines.push(option_line(- "-c, --compact",- copy(language, "Compact output", "紧凑输出"),- ));- lines.push(option_line(- "--account <account>",- copy(language, "Override account", "覆盖账户"),- ));- lines.push(option_line(- "--user <user>",- copy(language, "Override user", "覆盖用户"),- ));- lines.push(option_line(- "--sudo",- copy(- language,- "Use root API key for admin commands",- "管理命令使用 root API Key",- ),- ));- lines.push(option_line(- "-h, --help",- copy(language, "Show help", "显示帮助"),- ));- lines.push(option_line(- "-V, --version",- copy(language, "Show version", "显示版本"),- ));+ for item in top_level_global_options(&root, language) {+ lines.push(option_line(&item.label, &item.description));+ }lines.push(String::new());lines.push(format!("{}",@@ -2341,64 +1198,326 @@ pub(crate) fn render_top_level_help_with_language(language: Language) -> Stringcopy(language, "Configure the CLI", "配置 CLI"),));- format!("{}\n", lines.join("\n"))+ format!("{}\n", lines.join("\n"))+}++fn render_command_help(spec: &CommandHelpSpec) -> String {+ let mut lines = Vec::new();+ let language = Language::current();+ let command = command_display(spec.path);+ let clap_command = clap_command_for_path(spec.path)+ .unwrap_or_else(|| panic!("curated help path missing from clap: {command}"));++ lines.push(format!(+ "{} {} {}",+ theme::brand_title("OpenViking").bold(),+ theme::version(version()),+ theme::muted(format!("· {command}"))+ ));+ lines.push(theme::body(localized_command_purpose(spec, language)).to_string());+ lines.push(String::new());+ lines.push(format!(+ "{}",+ theme::warning(copy(language, "Usage:", "用法:")).bold()+ ));+ let usage = usage_for_command(clap_command.clone(), spec.path);+ lines.push(format!(" {}", theme::strong(usage)));+ push_section(+ &mut lines,+ copy(language, "Examples", "示例"),+ spec.examples,+ );+ let argument_items = arguments_from_command(&clap_command);+ push_dynamic_section(+ &mut lines,+ copy(language, "Arguments", "参数"),+ &argument_items,+ );+ let subcommand_items = subcommands_from_command(&clap_command);+ push_dynamic_section(+ &mut lines,+ copy(language, "Subcommands", "子命令"),+ &subcommand_items,+ );+ for section in option_sections_from_command(&clap_command) {+ push_dynamic_section(+ &mut lines,+ localized_option_section_title(§ion.title, language),+ §ion.items,+ );+ }+ let global_items = global_options_for(spec);+ push_dynamic_section(+ &mut lines,+ copy(language, "Global options", "全局选项"),+ &global_items,+ );+ push_section(+ &mut lines,+ copy(language, "Next", "下一步"),+ spec.next_steps,+ );++ format!("{}\n", lines.join("\n"))+}++fn clap_command_for_path(path: &[&str]) -> Option<Command> {+ let mut root = Cli::command();+ root.build();++ let mut current = &root;+ for token in path {+ current = current.find_subcommand(token)?;+ }+ Some(current.clone())+}++fn usage_for_command(mut command: Command, path: &[&str]) -> String {+ let usage = command.render_usage().to_string();+ let usage = usage+ .trim()+ .strip_prefix("Usage:")+ .unwrap_or(usage.trim())+ .trim();++ if let Some(rest) = usage.strip_prefix("openviking") {+ return format!("ov{rest}");+ }++ let command_name = command.get_name();+ if let Some(rest) = usage.strip_prefix(command_name) {+ return format!("{}{}", command_display(path), rest);+ }++ usage.to_string()+}++fn arguments_from_command(command: &Command) -> Vec<RenderedHelpItem> {+ command+ .get_positionals()+ .filter(|arg| is_visible_help_arg(arg))+ .map(|arg| RenderedHelpItem {+ label: positional_label(arg),+ description: arg_help(arg),+ })+ .collect()+}++fn subcommands_from_command(command: &Command) -> Vec<RenderedHelpItem> {+ command+ .get_subcommands()+ .filter(|subcommand| !subcommand.is_hide_set() && subcommand.get_name() != "help")+ .map(|subcommand| RenderedHelpItem {+ label: subcommand_label(subcommand),+ description: command_about(subcommand),+ })+ .collect()+}++fn option_sections_from_command(command: &Command) -> Vec<RenderedHelpSection> {+ let mut sections = Vec::<RenderedHelpSection>::new();++ for arg in command+ .get_arguments()+ .filter(|arg| is_visible_help_arg(arg) && !arg.is_positional() && !arg.is_global_set())+ {+ let title = arg.get_help_heading().unwrap_or("Options").to_string();+ let item = RenderedHelpItem {+ label: option_label(arg),+ description: arg_help(arg),+ };++ if let Some(section) = sections.iter_mut().find(|section| section.title == title) {+ section.items.push(item);+ } else {+ sections.push(RenderedHelpSection {+ title,+ items: vec![item],+ });+ }+ }++ sections+}++fn global_options_for(spec: &CommandHelpSpec) -> Vec<RenderedHelpItem> {+ let include_identity = !matches!(+ spec.path,+ ["config", "add", "ov-service"] | ["config", "add", "custom"] | ["config", "edit"]+ );+ let include_sudo = matches!(+ spec.path,+ ["admin"] | ["system"] | ["system", "backend"] | ["reindex"]+ );++ let mut root = Cli::command();+ root.build();++ let mut ids = vec!["output", "compact"];+ if include_identity {+ ids.extend(["account", "user"]);+ }+ if include_sudo {+ ids.push("sudo");+ }++ rendered_global_options(&root, &ids, None)+}++fn is_visible_help_arg(arg: &Arg) -> bool {+ !arg.is_hide_set()+ && !matches!(+ arg.get_action(),+ ArgAction::Help | ArgAction::HelpShort | ArgAction::HelpLong | ArgAction::Version+ )+}++fn positional_label(arg: &Arg) -> String {+ let value = value_label(arg);+ let mut label = if arg.is_required_set() {+ format!("<{value}>")+ } else {+ format!("[{value}]")+ };+ if accepts_multiple_values(arg) {+ label.push_str("...");+ }+ label+}++fn subcommand_label(command: &Command) -> String {+ let mut names = vec![command.get_name().to_string()];+ names.extend(command.get_visible_aliases().map(ToString::to_string));+ let mut label = names.join(" / ");++ let mut arguments: Vec<String> = command+ .get_positionals()+ .filter(|arg| is_visible_help_arg(arg))+ .map(positional_label)+ .collect();++ if arguments.is_empty()+ && command+ .get_subcommands()+ .any(|subcommand| !subcommand.is_hide_set() && subcommand.get_name() != "help")+ {+ arguments.push("<COMMAND>".to_string());+ }++ if !arguments.is_empty() {+ label.push(' ');+ label.push_str(&arguments.join(" "));+ }++ label+}++fn option_label(arg: &Arg) -> String {+ let takes_value = takes_value(arg);+ let value = if takes_value {+ Some(value_label(arg))+ } else {+ None+ };++ let mut parts = Vec::new();+ if let Some(short) = arg.get_short() {+ parts.push(format!("-{short}"));+ }++ if let Some(long) = arg.get_long() {+ parts.push(format!("--{long}{}", option_value_suffix(value.as_deref())));+ }++ let mut label = if parts.is_empty() {+ arg.get_id().to_string()+ } else {+ parts.join(", ")+ };++ if let Some(aliases) = arg.get_all_aliases() {+ for alias in aliases {+ label.push_str(" / ");+ label.push_str(&format!(+ "--{alias}{}",+ option_value_suffix(value.as_deref())+ ));+ }+ }++ label}-fn render_command_help(spec: &CommandHelpSpec) -> String {- let mut lines = Vec::new();- let language = Language::current();- let command = command_display(spec.path);+fn option_value_suffix(value: Option<&str>) -> String {+ value.map(|value| format!(" <{value}>")).unwrap_or_default()+}- lines.push(format!(- "{} {} {}",- theme::brand_title("OpenViking").bold(),- theme::version(version()),- theme::muted(format!("· {command}"))- ));- lines.push(theme::body(localized_command_purpose(spec, language)).to_string());- lines.push(String::new());- lines.push(format!(- "{}",- theme::warning(copy(language, "Usage:", "用法:")).bold()- ));- lines.push(format!(" {}", theme::strong(spec.usage)));- push_section(- &mut lines,- copy(language, "Examples", "示例"),- spec.examples,- );- push_section(- &mut lines,- copy(language, "Arguments", "参数"),- spec.arguments,- );- push_section(- &mut lines,- copy(language, "Subcommands", "子命令"),- spec.subcommands,- );- push_section(- &mut lines,- copy(language, "Common options", "常用选项"),- spec.common_options,- );- push_section(- &mut lines,- copy(language, "Advanced options", "高级选项"),- spec.advanced_options,- );- push_section(- &mut lines,- copy(language, "Global options", "全局选项"),- GLOBAL_OPTIONS,- );- push_section(- &mut lines,- copy(language, "Next", "下一步"),- spec.next_steps,- );+fn value_label(arg: &Arg) -> String {+ if let Some(possible_values) = possible_value_label(arg) {+ return possible_values;+ }- format!("{}\n", lines.join("\n"))+ if let Some(value_names) = arg.get_value_names()+ && let Some(value_name) = value_names.first()+ {+ return normalize_value_name(value_name.as_str());+ }++ normalize_value_name(arg.get_id().as_str())+}++fn possible_value_label(arg: &Arg) -> Option<String> {+ let values: Vec<_> = arg+ .get_possible_values()+ .into_iter()+ .filter(|value| !value.is_hide_set())+ .map(|value| value.get_name().to_string())+ .collect();++ if values.is_empty() || values.len() > 6 {+ None+ } else {+ Some(values.join("|"))+ }+}++fn normalize_value_name(value: &str) -> String {+ value.to_ascii_lowercase().replace('_', "-")+}++fn takes_value(arg: &Arg) -> bool {+ arg.get_num_args().unwrap_or_default().takes_values()+ && !matches!(arg.get_action(), ArgAction::SetTrue | ArgAction::SetFalse)+}++fn accepts_multiple_values(arg: &Arg) -> bool {+ arg.get_num_args()+ .map(|range| range.max_values() > 1)+ .unwrap_or(false)+}++fn arg_help(arg: &Arg) -> String {+ arg.get_help()+ .or_else(|| arg.get_long_help())+ .map(ToString::to_string)+ .unwrap_or_default()+}++fn command_about(command: &Command) -> String {+ command+ .get_about()+ .or_else(|| command.get_long_about())+ .map(ToString::to_string)+ .unwrap_or_default()+}++fn localized_option_section_title(title: &str, language: Language) -> &str {+ match title {+ "Common options" => copy(language, "Common options", "常用选项"),+ "Advanced options" => copy(language, "Advanced options", "高级选项"),+ "Options" => copy(language, "Options", "选项"),+ _ => title,+ }}fn push_section(lines: &mut Vec<String>, title: &str, items: &[HelpItem]) {@@ -2413,20 +1532,36 @@ fn push_section(lines: &mut Vec<String>, title: &str, items: &[HelpItem]) {}}+fn push_dynamic_section(lines: &mut Vec<String>, title: &str, items: &[RenderedHelpItem]) {+ if items.is_empty() {+ return;+ }++ lines.push(String::new());+ lines.push(format!("{}", theme::heading(title).bold()));+ for item in items {+ lines.push(help_item_line_parts(&item.label, &item.description));+ }+}+fn help_item_line(item: &HelpItem) -> String {let language = Language::current();let description = localized_help_item_description(item.label, item.description, language);- if display_width(item.label) > COMMAND_HELP_LEFT_WIDTH {+ help_item_line_parts(item.label, description)+}++fn help_item_line_parts(label: &str, description: &str) -> String {+ if display_width(label) > COMMAND_HELP_LEFT_WIDTH {return format!(" {}\n {}",- theme::command(item.label),+ theme::command(label),theme::body(description));}format!(" {} {}",- theme::command(pad_to_display_width(item.label, COMMAND_HELP_LEFT_WIDTH)),+ theme::command(pad_to_display_width(label, COMMAND_HELP_LEFT_WIDTH)),theme::body(description))}@@ -2516,6 +1651,7 @@ fn localized_help_item_description<'a>(}fn start_here_line(command: &str, description: &str) -> String {+ let description = truncate_to_display_width(description, START_HERE_DESCRIPTION_WIDTH);format!(" {} {}",theme::command(pad_to_display_width(command, 22)).bold(),@@ -2531,9 +1667,67 @@ fn option_line(option: &str, description: &str) -> String {)}-fn section_lines(section: &HelpSection) -> Vec<String> {+fn top_level_start_here_line(+ root: &Command,+ command_name: &str,+ language: Language,+) -> Option<String> {+ let command = root.find_subcommand(command_name)?;+ Some(start_here_line(+ &format!("ov {command_name}"),+ &top_level_command_description(command, language),+ ))+}++fn top_level_global_options(root: &Command, language: Language) -> Vec<RenderedHelpItem> {+ let mut items = rendered_global_options(+ root,+ &["output", "compact", "account", "user", "sudo"],+ Some(language),+ );++ items.push(RenderedHelpItem {+ label: "-h, --help".to_string(),+ description: copy(language, "Show help", "显示帮助").to_string(),+ });+ items.push(RenderedHelpItem {+ label: "-V, --version".to_string(),+ description: copy(language, "Show version", "显示版本").to_string(),+ });++ items+}++fn rendered_global_options(+ root: &Command,+ ids: &[&str],+ language: Option<Language>,+) -> Vec<RenderedHelpItem> {+ ids.iter()+ .filter_map(|id| {+ let id = *id;+ root.get_arguments()+ .find(|arg| arg.get_id().as_str() == id)+ .map(|arg| {+ let description = arg_help(arg);+ let description = language+ .map(|language| {+ localized_global_option_description(id, &description, language)+ .to_string()+ })+ .unwrap_or(description);++ RenderedHelpItem {+ label: option_label(arg),+ description,+ }+ })+ })+ .collect()+}++fn section_lines(section: &HelpSection, root: &Command, language: Language) -> Vec<String> {let mut lines = Vec::new();- let language = Language::current();let title_text = localized_section_title(section.title, language);let title = format!("─ {title_text} ");let fill = BOX_WIDTH.saturating_sub(2 + display_width(&title));@@ -2546,7 +1740,9 @@ fn section_lines(section: &HelpSection) -> Vec<String> {));for command in section.commands {- lines.push(command_line(command));+ if let Some(clap_command) = root.find_subcommand(command.name) {+ lines.push(command_line(command.name, clap_command, language));+ }}lines.push(format!(@@ -2558,42 +1754,155 @@ fn section_lines(section: &HelpSection) -> Vec<String> {lines}-fn command_line(command: &HelpCommand) -> String {- let language = Language::current();- let command_description =- localized_command_description(command.name, command.description, language);- let description = match command.badge {+fn command_line(command_name: &str, command: &Command, language: Language) -> String {+ let command_description = top_level_command_description(command, language);+ let badge = top_level_command_badge(command);+ let description = match badge.as_deref() {Some(badge) => {- let used = display_width(command_description)- + display_width(localized_badge(badge, language));+ let badge = localized_badge(badge, language);+ let description_width = DESCRIPTION_WIDTH.saturating_sub(display_width(badge) + 1);+ let command_description =+ truncate_to_display_width(&command_description, description_width);+ let used = display_width(&command_description) + display_width(badge);let spacer = DESCRIPTION_WIDTH.saturating_sub(used).max(1);format!("{}{}{}",command_description," ".repeat(spacer),- theme::muted(localized_badge(badge, language))+ theme::muted(badge)+ )+ }+ None => {+ let command_description =+ truncate_to_display_width(&command_description, DESCRIPTION_WIDTH);+ format!(+ "{}{}",+ command_description,+ " ".repeat(DESCRIPTION_WIDTH.saturating_sub(display_width(&command_description))))}- None => format!(- "{}{}",- command_description,- " ".repeat(DESCRIPTION_WIDTH.saturating_sub(display_width(command_description)))- ),};format!("{} {} {} {}",theme::border("│"),- theme::command(pad_to_display_width(command.name, COMMAND_WIDTH)).bold(),+ theme::command(pad_to_display_width(command_name, COMMAND_WIDTH)).bold(),theme::body(description),theme::border("│"))}+fn top_level_command_description(command: &Command, language: Language) -> String {+ let description = command_about_without_tags(command);+ let mut description =+ localized_command_description(command.get_name(), &description, language).to_string();+ let aliases: Vec<_> = command.get_all_aliases().collect();++ if !aliases.is_empty() {+ description.push_str(&format!(+ " ({}: {})",+ copy(language, "alias", "别名"),+ aliases.join(", ")+ ));+ }++ description+}++fn top_level_command_badge(command: &Command) -> Option<String> {+ let about = command_about(command);+ if command_about_tags(&about)+ .iter()+ .any(|tag| tag.eq_ignore_ascii_case("Experimental"))+ {+ Some("experimental".to_string())+ } else {+ None+ }+}++fn command_about_without_tags(command: &Command) -> String {+ let about = command_about(command);+ strip_command_tags(&about).to_string()+}++fn command_about_tags(about: &str) -> Vec<&str> {+ let mut tags = Vec::new();+ let mut rest = about.trim_start();++ while let Some(after_open) = rest.strip_prefix('[') {+ let Some((tag, after_close)) = after_open.split_once(']') else {+ break;+ };+ tags.push(tag);+ rest = after_close.trim_start();+ }++ tags+}++fn strip_command_tags(about: &str) -> &str {+ let mut rest = about.trim_start();++ while let Some(after_open) = rest.strip_prefix('[') {+ let Some((_, after_close)) = after_open.split_once(']') else {+ break;+ };+ rest = after_close.trim_start();+ }++ rest+}++fn localized_global_option_description<'a>(+ id: &str,+ description: &'a str,+ language: Language,+) -> &'a str {+ if language == Language::En {+ return description;+ }++ match id {+ "output" => "输出格式",+ "compact" => "紧凑输出",+ "account" => "覆盖账户",+ "user" => "覆盖用户",+ "sudo" => "admin、system 和 reindex 使用 root API Key",+ _ => description,+ }+}+fn display_width(value: &str) -> usize {UnicodeWidthStr::width(value)}+fn truncate_to_display_width(value: &str, width: usize) -> String {+ if display_width(value) <= width {+ return value.to_string();+ }++ if width <= 3 {+ return ".".repeat(width);+ }++ let target = width - 3;+ let mut truncated = String::new();+ let mut used = 0;++ for ch in value.chars() {+ let ch_width = display_width(&ch.to_string());+ if used + ch_width > target {+ break;+ }+ truncated.push(ch);+ used += ch_width;+ }++ truncated.push_str("...");+ truncated+}+fn pad_to_display_width(value: &str, width: usize) -> String {format!("{}{}",@@ -2635,6 +1944,7 @@ fn localized_command_description<'a>(match name {"add-resource" => "添加文件、文件夹、URL 或仓库","add-skill" => "添加技能到 OpenViking",+ "skills" => "管理已安装技能","find" => "语义检索相关上下文","read" => "读取精确资源内容","write" => "更新已有资源",@@ -2727,8 +2037,13 @@ fn command_help_path(args: &[OsString]) -> Option<Vec<String>> {if is_help_flag(next) {// Explicit help for this top-level command.} else if !next.starts_with('-') {- if has_help_flag && path.len() == 1 && allows_curated_nested(&path[0]) {- path.push(canonical_command_token(next));+ if has_help_flag && path.len() == 1 && is_bare_group_help_command(&path[0]) {+ let nested_path = command_path_until_help_flag(&tokens, i + 1, path);+ return if command_spec(&nested_path).is_some() {+ Some(nested_path)+ } else {+ None+ };}return if has_help_flag { Some(path) } else { None };} else {@@ -2749,6 +2064,35 @@ fn command_help_path(args: &[OsString]) -> Option<Vec<String>> {}}+fn command_path_until_help_flag(+ tokens: &[String],+ mut i: usize,+ mut path: Vec<String>,+) -> Vec<String> {+ while i < tokens.len() {+ let token = &tokens[i];+ if is_help_flag(token) {+ break;+ }+ if token == "--sudo" || token == "--progress" || token == "--no-progress" || token == "-v" {+ i += 1;+ continue;+ }+ if consumes_value(token) {+ i += if token.contains('=') { 1 } else { 2 };+ continue;+ }+ if token.starts_with('-') {+ i += 1;+ continue;+ }++ path.push(canonical_command_token(token));+ i += 1;+ }+ path+}+fn config_help_path(tokens: &[String]) -> Option<Vec<String>> {let mut i = 1;while i < tokens.len() {@@ -2905,14 +2249,10 @@ fn version() -> String {format!("v{}", env!("OPENVIKING_CLI_VERSION"))}-fn allows_curated_nested(command: &str) -> bool {- matches!(command, "config")-}-fn is_bare_group_help_command(command: &str) -> bool {matches!(command,- "task" | "session" | "privacy" | "admin" | "system" | "observer"+ "task" | "skills" | "session" | "privacy" | "admin" | "system" | "observer")}@@ -2937,6 +2277,8 @@ mod tests {render_command_help_request, render_top_level_help,};use super::{command_spec, is_top_level_help_request};+ use crate::Cli;+ use clap::CommandFactory;use std::ffi::OsString;fn os_args(args: &[&str]) -> Vec<OsString> {@@ -2992,6 +2334,8 @@ mod tests {assert!(rendered.contains("ov health"));assert!(rendered.contains("ov status"));assert!(rendered.contains("ov tui"));+ assert!(rendered.contains("-c, --compact <true|false>"));+ assert!(rendered.contains("Use root API key for admin, system, and reindex"));}#[test]@@ -3010,11 +2354,40 @@ mod tests {}assert!(rendered.contains("search"));+ assert!(rendered.contains("skills"));assert!(rendered.contains("experimental"));assert!(rendered.contains("ov <command> --help"));assert!(!rendered.contains("Commands:\n add-resource"));}+ #[test]+ fn top_level_help_lists_only_top_level_commands() {+ for command in HELP_SECTIONS+ .iter()+ .flat_map(|section| section.commands.iter().map(|command| command.name))+ {+ assert!(+ !command.contains(' '),+ "top-level help must not list nested command {command}"+ );+ }++ let rendered = strip_ansi(&render_top_level_help());+ for nested in [+ "config show",+ "config validate",+ "config switch",+ "config add",+ "config list",+ "config delete",+ ] {+ assert!(+ !rendered.contains(nested),+ "top-level help leaked nested command {nested}"+ );+ }+ }+#[test]fn boxed_sections_have_stable_width_after_ansi_is_removed() {let rendered = strip_ansi(&render_top_level_help());@@ -3027,11 +2400,10 @@ mod tests {}#[test]- fn every_top_level_command_in_help_map_has_command_help() {+ fn every_curated_top_level_command_in_help_map_has_command_help() {for command in HELP_SECTIONS.iter().flat_map(|section| section.commands.iter().map(|command| command.name))- .filter(|name| !name.contains(' ')){assert!(command_spec(&[command.to_string()]).is_some(),@@ -3059,11 +2431,26 @@ mod tests {}let rendered = strip_ansi(&render_top_level_help());- for expected in ["add-skill", "observer", "version", "alias: lang"] {+ for expected in ["add-skill", "skills", "observer", "version", "alias: lang"] {assert!(rendered.contains(expected), "missing {expected}");}}+ #[test]+ fn top_level_help_exposes_all_visible_clap_commands() {+ let rendered = strip_ansi(&render_top_level_help());+ let mut command = Cli::command();+ command.build();++ for subcommand in command+ .get_subcommands()+ .filter(|subcommand| !subcommand.is_hide_set() && subcommand.get_name() != "help")+ {+ let name = subcommand.get_name();+ assert!(rendered.contains(name), "missing clap command {name}");+ }+ }+#[test]fn renders_curated_find_help() {let rendered = strip_ansi(@@ -3072,13 +2459,34 @@ mod tests {);assert!(rendered.contains("OpenViking v"));- assert!(rendered.contains("ov find <query>"));+ assert!(rendered.contains("ov find [OPTIONS] <query>"));assert!(rendered.contains("Examples"));assert!(rendered.contains("Common options"));assert!(rendered.contains("Next"));assert!(rendered.contains("ov read <uri>"));}+ #[test]+ fn curated_help_preserves_common_and_advanced_option_sections() {+ for args in [+ &["ov", "add-resource", "--help"][..],+ &["ov", "find", "--help"][..],+ &["ov", "config", "add", "custom", "--help"][..],+ ] {+ let rendered = strip_ansi(+ &render_command_help_request(&os_args(&args)).expect("help should render"),+ );+ assert!(+ rendered.contains("Common options"),+ "missing Common options in:\n{rendered}"+ );+ assert!(+ rendered.contains("Advanced options"),+ "missing Advanced options in:\n{rendered}"+ );+ }+ }+#[test]fn find_and_search_help_explain_node_limit_semantics() {let find_help = strip_ansi(@@ -3090,9 +2498,9 @@ mod tests {.expect("search help should render"),);- assert!(find_help.contains("Maximum final results returned."));+ assert!(find_help.contains("Maximum final results returned"));assert!(search_help.contains("Maximum results per search pass."));- assert!(search_help.contains("Search may merge multiple passes."));+ assert!(search_help.contains("Search may merge multiple passes"));}#[test]@@ -3103,7 +2511,7 @@ mod tests {);assert!(rendered.contains("OpenViking v"));- assert!(rendered.contains("ov find <query>"));+ assert!(rendered.contains("ov find [OPTIONS] <query>"));assert!(rendered.contains("Usage:"));}@@ -3114,11 +2522,77 @@ mod tests {.expect("status help should render"),);- assert!(rendered.contains("ov status [--verbose]"));+ assert!(rendered.contains("ov status [OPTIONS]"));assert!(rendered.contains("ov status --verbose"));assert!(rendered.contains("Show full component tables"));}+ #[test]+ fn curated_help_lists_timeout_for_waiting_commands() {+ for args in [+ ["ov", "add-resource", "--help"],+ ["ov", "add-skill", "--help"],+ ["ov", "write", "--help"],+ ] {+ let rendered = strip_ansi(+ &render_command_help_request(&os_args(&args)).expect("help should render"),+ );+ assert!(+ rendered.contains("--timeout <seconds>"),+ "missing timeout option in:\n{rendered}"+ );+ assert!(+ rendered.contains("seconds"),+ "missing timeout description in:\n{rendered}"+ );+ }+ }++ #[test]+ fn curated_help_lists_upload_filters_peer_id_and_limit_aliases() {+ let add_resource = strip_ansi(+ &render_command_help_request(&os_args(&["ov", "add-resource", "--help"]))+ .expect("add-resource help should render"),+ );+ for needle in [+ "--strict",+ "--ignore-dirs <dirs>",+ "--include <pattern>",+ "--exclude <pattern>",+ "--no-directly-upload-media",+ "--progress",+ "--no-progress",+ "-v, --verbose",+ ] {+ assert!(+ add_resource.contains(needle),+ "missing {needle} in:\n{add_resource}"+ );+ }++ for command in ["ls", "tree", "find", "search", "grep", "glob"] {+ let rendered = strip_ansi(+ &render_command_help_request(&os_args(&["ov", command, "--help"]))+ .expect("help should render"),+ );+ assert!(+ rendered.contains("--limit <n>"),+ "missing --limit alias for {command} in:\n{rendered}"+ );+ }++ for command in ["find", "search"] {+ let rendered = strip_ansi(+ &render_command_help_request(&os_args(&["ov", command, "--help"]))+ .expect("help should render"),+ );+ assert!(+ rendered.contains("--peer-id <id>"),+ "missing --peer-id for {command} in:\n{rendered}"+ );+ }+ }+#[test]fn renders_curated_config_switch_help_from_both_help_forms() {for args in [@@ -3142,7 +2616,7 @@ mod tests {&render_command_help_request(&os_args(&["ov", "config", "add", "--help"])).expect("config add help should render"),);- assert!(config.contains("ov config add <ov-service|custom>"));+ assert!(config.contains("ov config add"));assert!(config.contains("ov-service"));assert!(config.contains("custom"));@@ -3167,6 +2641,9 @@ mod tests {assert!(custom.contains("ov config add custom"));assert!(custom.contains("--root-api-key-stdin"));assert!(!custom.contains("--use-root-key-for-normal-commands"));+ assert!(custom.contains("--account <account>"));+ assert!(!custom.contains("Override X-OpenViking-Account"));+ assert!(custom.contains("-o, --output <table|json>"));assert!(render_command_help_request(&os_args(&["ov", "config", "add", "cloud", "--help"])).is_none()@@ -3186,7 +2663,7 @@ mod tests {&render_command_help_request(&os_args(&["ov", "config", "edit", "prod", "--help"])).expect("config edit help should render"),);- assert!(edit.contains("ov config edit <name>"));+ assert!(edit.contains("ov config edit [OPTIONS] <name>"));assert!(edit.contains("--clear-api-key"));assert!(!edit.contains("--use-root-key-for-normal-commands"));@@ -3194,7 +2671,8 @@ mod tests {&render_command_help_request(&os_args(&["ov", "config", "delete", "prod", "--help"])).expect("config delete help should render"),);- assert!(delete.contains("ov config delete <name>"));+ assert!(delete.contains("ov config delete [OPTIONS] <name>"));+ assert!(delete.contains("Delete even when the saved config file cannot be parsed"));}#[test]@@ -3219,6 +2697,29 @@ mod tests {assert!(task.contains("list"));}+ #[test]+ fn command_group_help_shows_subcommand_positional_shapes() {+ let session = strip_ansi(+ &render_command_help_request(&os_args(&["ov", "session", "--help"]))+ .expect("session help should render"),+ );++ assert!(session.contains("get <session-id>"));+ assert!(session.contains("get-session-context <session-id>"));+ assert!(session.contains("get-session-archive <session-id> <archive-id>"));+ assert!(session.contains("add-message <session-id>"));+ assert!(session.contains("add-messages <session-id> <messages-json>"));++ let watch = strip_ansi(+ &render_command_help_request(&os_args(&["ov", "task", "watch", "--help"]))+ .expect("watch help should render"),+ );++ assert!(watch.contains("show <task-or-uri>"));+ assert!(watch.contains("update <task-or-uri>"));+ assert!(watch.contains("trigger <task-or-uri>"));+ }+#[test]fn command_help_detection_allows_global_flags_before_command() {let path = command_help_path(&os_args(&[@@ -3239,6 +2740,7 @@ mod tests {fn bare_command_groups_render_curated_help() {for (command, expected) in [("task", "Inspect and manage async processing tasks."),+ ("skills", "Manage installed agent skills."),("session","Manage sessions, messages, archives, and committed session context.",@@ -3281,7 +2783,7 @@ mod tests {.expect("bare task help should render with global flags before command"),);- assert!(rendered.contains("ov task <subcommand>"));+ assert!(rendered.contains("ov task"));}#[test]@@ -3290,15 +2792,33 @@ mod tests {}#[test]- fn unsupported_nested_prefixed_help_renders_parent_group_help() {+ fn unsupported_nested_prefixed_help_falls_back_to_clap() {+ for args in [+ ["ov", "task", "list", "--help"],+ ["ov", "session", "add-message", "--help"],+ ["ov", "privacy", "upsert", "--help"],+ ["ov", "admin", "list-users", "--help"],+ ["ov", "system", "wait", "--help"],+ ] {+ assert!(+ render_command_help_request(&os_args(&args)).is_none(),+ "{args:?} should fall back to clap help"+ );+ }+ }++ #[test]+ fn supported_nested_curated_help_still_renders() {let rendered = strip_ansi(- &render_command_help_request(&os_args(&["ov", "task", "list", "--help"]))- .expect("task list help should render parent task help"),+ &render_command_help_request(&os_args(&["ov", "system", "backend", "--help"]))+ .expect("system backend help should render curated nested help"),);- assert!(rendered.contains("ov task <subcommand>"));- assert!(rendered.contains("Inspect and manage async processing tasks."));- assert!(rendered.contains("Subcommands"));+ assert!(rendered.contains("ov system backend"));+ assert!(rendered.contains("sync-status"));+ assert!(rendered.contains("sync-retry"));+ assert!(!rendered.contains("help Print this message"));+ assert!(rendered.contains("--sudo"));}#[test]@@ -3308,7 +2828,7 @@ mod tests {.expect("ls help with positional value should render curated ls help"),);- assert!(rendered.contains("ov ls [uri]"));+ assert!(rendered.contains("ov ls [OPTIONS] [uri]"));assert!(rendered.contains("List resources under a Viking URI."));}}diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 5ec672ca6..2e75a99cd 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -105,30 +105,39 @@ impl CliContext {#[command(version = env!("OPENVIKING_CLI_VERSION"))]#[command(arg_required_else_help = true)]struct Cli {- /// Output format+ /// Choose human table output or machine-readable JSON#[arg(short,long,value_enum,default_value = "table",global = true,- hide = true+ hide = true,+ value_name = "table|json")]output: OutputFormat,- /// Compact representation, defaults to true - compacts JSON output or uses simplified representation for Table output- #[arg(short, long, global = true, default_value = "true", hide = true)]+ /// Use compact table/JSON rendering+ #[arg(+ short,+ long,+ global = true,+ default_value = "true",+ hide = true,+ action = ArgAction::Set,+ value_name = "bool"+ )]compact: bool,- /// Account identifier to send as X-OpenViking-Account+ /// Override X-OpenViking-Account for this command#[arg(long, global = true, hide = true)]account: Option<String>,- /// User identifier to send as X-OpenViking-User+ /// Override X-OpenViking-User for this command#[arg(long, global = true, hide = true)]user: Option<String>,- /// Use root API key for admin commands+ /// Use root API key for admin, system, and reindex commands#[arg(long, global = true, hide = true)]sudo: bool,@@ -155,15 +164,23 @@ struct Cli {#[derive(Args, Debug, Clone, Copy, Default)]struct UploadCliOptions {/// Show local file upload progress (overrides config file)- #[arg(long, conflicts_with = "no_progress")]+ #[arg(+ long,+ conflicts_with = "no_progress",+ help_heading = "Advanced options"+ )]progress: bool,/// Disable local file upload progress (overrides config file)- #[arg(long = "no-progress", conflicts_with = "progress")]+ #[arg(+ long = "no-progress",+ conflicts_with = "progress",+ help_heading = "Advanced options"+ )]no_progress: bool,/// Print extra diagnostics during local file upload- #[arg(short, long)]+ #[arg(short, long, help_heading = "Advanced options")]verbose: bool,}@@ -221,45 +238,74 @@ enum Commands {/// [Data] Add resources into OpenVikingAddResource {/// Local path or URL to import+ #[arg(value_name = "path-or-url")]path: String,/// Exact target URI (must not exist yet) (cannot be used with --parent)- #[arg(long)]+ #[arg(long, value_name = "uri", help_heading = "Common options")]to: Option<String>,/// Target parent URI (must already exist and be a directory) (cannot be used with --to)- #[arg(long)]+ #[arg(long, value_name = "uri", help_heading = "Common options")]parent: Option<String>,/// Target parent URI (create parent directory if it does not exist) (cannot be used with --to or --parent)- #[arg(short = 'p', long = "parent-auto-create")]+ #[arg(+ short = 'p',+ long = "parent-auto-create",+ value_name = "uri",+ help_heading = "Common options"+ )]parent_auto_create: Option<String>,/// Reason for import- #[arg(long, default_value = "")]+ #[arg(+ long,+ default_value = "",+ value_name = "text",+ help_heading = "Advanced options"+ )]reason: String,/// Additional instruction- #[arg(long, default_value = "")]+ #[arg(+ long,+ default_value = "",+ value_name = "text",+ help_heading = "Advanced options"+ )]instruction: String,/// Wait until processing is complete- #[arg(long)]+ #[arg(long, help_heading = "Common options")]wait: bool,/// Wait timeout in seconds (only used with --wait)- #[arg(long)]+ #[arg(long, value_name = "seconds", help_heading = "Common options")]timeout: Option<f64>,/// Enable strict mode for directory scanning (fail if any unsupported files found)- #[arg(long = "strict", action = ArgAction::SetTrue)]+ #[arg(+ long = "strict",+ action = ArgAction::SetTrue,+ help_heading = "Advanced options"+ )]strict_mode: bool,/// Ignore directories, e.g. --ignore-dirs "node_modules,dist"- #[arg(long)]+ #[arg(long, value_name = "dirs", help_heading = "Advanced options")]ignore_dirs: Option<String>,/// Include files extensions, e.g. --include "*.pdf,*.md"- #[arg(long)]+ #[arg(long, value_name = "pattern", help_heading = "Common options")]include: Option<String>,/// Exclude files extensions, e.g. --exclude "*.tmp,*.log"- #[arg(long)]+ #[arg(long, value_name = "pattern", help_heading = "Common options")]exclude: Option<String>,/// Do not directly upload media files- #[arg(long = "no-directly-upload-media", default_value_t = false)]+ #[arg(+ long = "no-directly-upload-media",+ default_value_t = false,+ help_heading = "Advanced options"+ )]no_directly_upload_media: bool,/// Watch interval in minutes for automatic resource monitoring (0 = no monitoring)- #[arg(long, default_value = "0")]+ #[arg(+ long,+ default_value = "0",+ value_name = "minutes",+ help_heading = "Advanced options"+ )]watch_interval: f64,#[command(flatten)]upload_options: UploadCliOptions,@@ -267,12 +313,13 @@ enum Commands {/// [Data] Add a skill into OpenVikingAddSkill {/// Skill directory, SKILL.md, or raw content+ #[arg(value_name = "skill-path-or-content")]data: String,/// Wait until processing is complete- #[arg(long)]+ #[arg(long, help_heading = "Common options")]wait: bool,/// Wait timeout in seconds- #[arg(long)]+ #[arg(long, value_name = "seconds", help_heading = "Common options")]timeout: Option<f64>,#[command(flatten)]upload_options: UploadCliOptions,@@ -286,229 +333,345 @@ enum Commands {#[command(alias = "list")]Ls {/// Viking URI to list (default: viking://)- #[arg(default_value = "viking://")]+ #[arg(default_value = "viking://", value_name = "uri")]uri: String,/// Simple path output (just paths, no table)- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]simple: bool,/// List all subdirectories recursively- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]recursive: bool,/// Abstract content limit (only for agent output)- #[arg(long = "abs-limit", short = 'l', default_value = "256")]+ #[arg(+ long = "abs-limit",+ short = 'l',+ default_value = "256",+ value_name = "n",+ help_heading = "Advanced options"+ )]abs_limit: i32,/// Show all hidden files- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]all: bool,/// Maximum number of nodes to list#[arg(long = "node-limit",short = 'n',alias = "limit",- default_value = "256"+ default_value = "256",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,},/// [Data] Get directory treeTree {/// Viking URI to get tree for+ #[arg(value_name = "uri")]uri: String,/// Abstract content limit (only for agent output)- #[arg(long = "abs-limit", short = 'l', default_value = "128")]+ #[arg(+ long = "abs-limit",+ short = 'l',+ default_value = "128",+ value_name = "n",+ help_heading = "Advanced options"+ )]abs_limit: i32,/// Show all hidden files- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]all: bool,/// Maximum number of nodes to list#[arg(long = "node-limit",short = 'n',alias = "limit",- default_value = "256"+ default_value = "256",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,/// Maximum depth level to traverse (default: 3)- #[arg(short = 'L', long = "level-limit", default_value = "3")]+ #[arg(+ short = 'L',+ long = "level-limit",+ default_value = "3",+ value_name = "n",+ help_heading = "Common options"+ )]level_limit: i32,},/// [Data] Create directoryMkdir {/// Directory URI to create+ #[arg(value_name = "uri")]uri: String,/// Initial directory description- #[arg(long)]+ #[arg(long, value_name = "text", help_heading = "Common options")]description: Option<String>,},/// [Data] Remove resource#[command(alias = "del", alias = "delete")]Rm {/// Viking URI to remove+ #[arg(value_name = "uri")]uri: String,/// Remove recursively- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]recursive: bool,},/// [Data] Move or rename resource#[command(alias = "rename")]Mv {/// Source URI+ #[arg(value_name = "from-uri")]from_uri: String,/// Target URI+ #[arg(value_name = "to-uri")]to_uri: String,},/// [Data] Get resource metadataStat {/// Viking URI to get metadata for+ #[arg(value_name = "uri")]uri: String,},/// [Data] Read file content (Level 2)Read {/// Viking URI+ #[arg(value_name = "uri")]uri: String,},/// [Data] Read abstract content (Level 0)Abstract {/// Directory URI+ #[arg(value_name = "directory-uri")]uri: String,},/// [Data] Read overview content (Level 1)Overview {/// Directory URI+ #[arg(value_name = "directory-uri")]uri: String,},/// [Data] Write text content to an existing fileWrite {/// Viking URI+ #[arg(value_name = "uri")]uri: String,/// Content to write- #[arg(long, conflicts_with = "from_file")]+ #[arg(+ long,+ conflicts_with = "from_file",+ value_name = "text",+ help_heading = "Common options"+ )]content: Option<String>,/// Read content from a local file- #[arg(long = "from-file", conflicts_with = "content")]+ #[arg(+ long = "from-file",+ conflicts_with = "content",+ value_name = "path",+ help_heading = "Common options"+ )]from_file: Option<String>,/// Append instead of replacing the file- #[arg(long)]+ #[arg(long, help_heading = "Common options")]append: bool,/// Write mode: replace, append, or create (default: replace)- #[arg(long, value_name = "MODE", conflicts_with = "append")]+ #[arg(+ long,+ value_name = "replace|append|create",+ conflicts_with = "append",+ help_heading = "Advanced options"+ )]mode: Option<String>,/// Wait for async processing to finish- #[arg(long, default_value = "false")]+ #[arg(long, default_value = "false", help_heading = "Common options")]wait: bool,/// Optional wait timeout in seconds- #[arg(long)]+ #[arg(long, value_name = "seconds", help_heading = "Common options")]timeout: Option<f64>,},/// [Data] Download file to local path (supports binaries/images)Get {/// Viking URI+ #[arg(value_name = "uri")]uri: String,/// Local path (must not exist yet)+ #[arg(value_name = "local-path")]local_path: String,},/// [Data] Run semantic retrievalFind {/// Search query+ #[arg(value_name = "query")]query: String,/// Target URI- #[arg(short, long, default_value = "")]+ #[arg(+ short,+ long,+ default_value = "",+ value_name = "uri",+ help_heading = "Common options"+ )]uri: String,- /// Maximum number of results+ /// Maximum final results returned#[arg(short = 'n',long = "node-limit",alias = "limit",- default_value = "10"+ default_value = "10",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,/// Score threshold- #[arg(short, long)]+ #[arg(short, long, value_name = "score", help_heading = "Common options")]threshold: Option<f64>,/// Only include results on or after this time (e.g. 48h, 7d, 2026-03-10, ISO-8601)- #[arg(long = "after")]+ #[arg(long = "after", value_name = "time", help_heading = "Advanced options")]after: Option<String>,/// Only include results on or before this time (e.g. 24h, 2026-03-15, ISO-8601)- #[arg(long = "before")]+ #[arg(+ long = "before",+ value_name = "time",+ help_heading = "Advanced options"+ )]before: Option<String>,/// Only include results with specific level(s) (0=abstract, 1=overview, 2=file)- #[arg(short = 'L', long = "level", value_delimiter = ',')]+ #[arg(+ short = 'L',+ long = "level",+ value_delimiter = ',',+ value_name = "0,1,2",+ help_heading = "Common options"+ )]level: Option<Vec<i32>>,/// Limit memory retrieval to this peer plus the current user memory- #[arg(long = "peer-id")]+ #[arg(long = "peer-id", value_name = "id", help_heading = "Advanced options")]peer_id: Option<String>,},/// [Experimental][Data] Run context-aware retrievalSearch {/// Search query+ #[arg(value_name = "query")]query: String,/// Target URI- #[arg(short, long, default_value = "")]+ #[arg(+ short,+ long,+ default_value = "",+ value_name = "uri",+ help_heading = "Common options"+ )]uri: String,/// Session ID for context-aware search- #[arg(long)]+ #[arg(long, value_name = "id", help_heading = "Common options")]session_id: Option<String>,- /// Maximum number of results+ /// Maximum results per search pass. Search may merge multiple passes.#[arg(short = 'n',long = "node-limit",alias = "limit",- default_value = "10"+ default_value = "10",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,/// Score threshold- #[arg(short, long)]+ #[arg(short, long, value_name = "score", help_heading = "Advanced options")]threshold: Option<f64>,/// Only include results on or after this time (e.g. 48h, 7d, 2026-03-10, ISO-8601)- #[arg(long = "after")]+ #[arg(long = "after", value_name = "time", help_heading = "Advanced options")]after: Option<String>,/// Only include results on or before this time (e.g. 24h, 2026-03-15, ISO-8601)- #[arg(long = "before")]+ #[arg(+ long = "before",+ value_name = "time",+ help_heading = "Advanced options"+ )]before: Option<String>,/// Only include results with specific level(s) (0=abstract, 1=overview, 2=file)- #[arg(short = 'L', long = "level", value_delimiter = ',')]+ #[arg(+ short = 'L',+ long = "level",+ value_delimiter = ',',+ value_name = "0,1,2",+ help_heading = "Advanced options"+ )]level: Option<Vec<i32>>,/// Limit memory retrieval to this peer plus the current user memory- #[arg(long = "peer-id")]+ #[arg(long = "peer-id", value_name = "id", help_heading = "Advanced options")]peer_id: Option<String>,},/// [Data] Run content pattern searchGrep {/// Target URI- #[arg(short, long, default_value = "viking://")]+ #[arg(+ short,+ long,+ default_value = "viking://",+ value_name = "uri",+ help_heading = "Common options"+ )]uri: String,/// Excluded URI range. Any entry whose URI falls under this URI prefix is skipped- #[arg(short = 'x', long = "exclude-uri")]+ #[arg(+ short = 'x',+ long = "exclude-uri",+ value_name = "uri",+ help_heading = "Advanced options"+ )]exclude_uri: Option<String>,/// Search pattern+ #[arg(value_name = "pattern")]pattern: String,/// Case insensitive- #[arg(short, long)]+ #[arg(short, long, help_heading = "Common options")]ignore_case: bool,/// Maximum number of results#[arg(short = 'n',long = "node-limit",alias = "limit",- default_value = "256"+ default_value = "256",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,/// Maximum depth level to traverse (default: 10)- #[arg(short = 'L', long = "level-limit", default_value = "10")]+ #[arg(+ short = 'L',+ long = "level-limit",+ default_value = "10",+ value_name = "n",+ help_heading = "Advanced options"+ )]level_limit: i32,},/// [Data] Run file glob pattern searchGlob {/// Glob pattern+ #[arg(value_name = "pattern")]pattern: String,/// Search root URI- #[arg(short, long, default_value = "viking://")]+ #[arg(+ short,+ long,+ default_value = "viking://",+ value_name = "uri",+ help_heading = "Common options"+ )]uri: String,/// Maximum number of results#[arg(short = 'n',long = "node-limit",alias = "limit",- default_value = "256"+ default_value = "256",+ value_name = "n",+ help_heading = "Common options")]node_limit: i32,},@@ -522,6 +685,7 @@ enum Commands {/// Content to memorize. Plain string (treated as user message),/// JSON {"role":"...","content":"..."} for a single message,/// or JSON array of such objects for multiple messages.+ #[arg(value_name = "content")]content: String,},/// [Data] Privacy config management commands@@ -532,93 +696,139 @@ enum Commands {/// [Experimental][Data] List relations of a resourceRelations {/// Viking URI+ #[arg(value_name = "uri")]uri: String,},/// [Experimental][Data] Create relation links from one URI to one or more targetsLink {/// Source URI+ #[arg(value_name = "from-uri")]from_uri: String,/// One or more target URIs+ #[arg(value_name = "to-uri")]to_uris: Vec<String>,/// Reason for linking- #[arg(long, default_value = "")]+ #[arg(+ long,+ default_value = "",+ value_name = "text",+ help_heading = "Common options"+ )]reason: String,},/// [Experimental][Data] Remove a relation linkUnlink {/// Source URI+ #[arg(value_name = "from-uri")]from_uri: String,/// Target URI to unlink+ #[arg(value_name = "to-uri")]to_uri: String,},/// [Data] Export context as .ovpackExport {/// Source URI+ #[arg(value_name = "uri")]uri: String,/// Output .ovpack file path+ #[arg(value_name = "output.ovpack")]to: String,/// Include dense vector snapshot when compatible metadata is available- #[arg(long, default_value_t = false)]+ #[arg(long, default_value_t = false, help_heading = "Common options")]include_vectors: bool,},/// [Data] Back up public OpenViking scopes as a restore-only .ovpackBackup {/// Output .ovpack file path+ #[arg(value_name = "output.ovpack")]to: String,/// Include dense vector snapshot when compatible metadata is available- #[arg(long, default_value_t = false)]+ #[arg(long, default_value_t = false, help_heading = "Common options")]include_vectors: bool,},/// [Data] Import .ovpack into target URIImport {/// Input .ovpack file path+ #[arg(value_name = "file.ovpack")]file_path: String,/// Target parent URI+ #[arg(value_name = "target-uri")]target_uri: String,/// Conflict policy: fail, overwrite, or skip- #[arg(long, value_parser = ["fail", "overwrite", "skip"])]+ #[arg(+ long,+ value_parser = ["fail", "overwrite", "skip"],+ value_name = "policy",+ help_heading = "Common options"+ )]on_conflict: Option<String>,/// Vector handling: auto restores compatible snapshots, recompute ignores them, require fails if unavailable- #[arg(long, value_parser = ["auto", "recompute", "require"])]+ #[arg(+ long,+ value_parser = ["auto", "recompute", "require"],+ value_name = "mode",+ help_heading = "Common options"+ )]vector_mode: Option<String>,},/// [Data] Restore a backup .ovpack to original public scope rootsRestore {/// Input backup .ovpack file path+ #[arg(value_name = "backup.ovpack")]file_path: String,/// Conflict policy: fail, overwrite, or skip- #[arg(long, value_parser = ["fail", "overwrite", "skip"])]+ #[arg(+ long,+ value_parser = ["fail", "overwrite", "skip"],+ value_name = "policy",+ help_heading = "Common options"+ )]on_conflict: Option<String>,/// Vector handling: auto restores compatible snapshots, recompute ignores them, require fails if unavailable- #[arg(long, value_parser = ["auto", "recompute", "require"])]+ #[arg(+ long,+ value_parser = ["auto", "recompute", "require"],+ value_name = "mode",+ help_heading = "Common options"+ )]vector_mode: Option<String>,},// --- Interactive Tools ---/// [Interactive] Interactive TUI file explorerTui {/// Viking URI to start browsing (default: /)- #[arg(default_value = "/")]+ #[arg(default_value = "/", value_name = "uri")]uri: String,},/// [Interactive] Chat with vikingbot agentChat {/// Message to send to the agent- #[arg(short, long)]+ #[arg(short, long, value_name = "text", help_heading = "Common options")]message: Option<String>,/// Session ID (defaults to machine unique ID)- #[arg(short, long)]+ #[arg(short, long, value_name = "id", help_heading = "Common options")]session: Option<String>,/// Sender ID- #[arg(short, long, default_value = "user")]+ #[arg(+ long,+ default_value = "user",+ value_name = "id",+ help_heading = "Advanced options"+ )]sender: String,/// Stream the response (default: true)- #[arg(long, default_value_t = true)]+ #[arg(+ long,+ default_value_t = true,+ value_name = "bool",+ help_heading = "Advanced options"+ )]stream: bool,/// Disable rich formatting / markdown rendering- #[arg(long)]+ #[arg(long, help_heading = "Common options")]no_format: bool,/// Disable command history- #[arg(long)]+ #[arg(long, help_heading = "Advanced options")]no_history: bool,},@@ -626,7 +836,7 @@ enum Commands {/// [Status] Wait for queued async processing to completeWait {/// Wait timeout in seconds- #[arg(long)]+ #[arg(long, value_name = "seconds", help_heading = "Common options")]timeout: Option<f64>,},/// [Status] Track async resource processing tasks@@ -637,7 +847,7 @@ enum Commands {/// [Status] All OpenViking Server components statusStatus {/// Show full component tables- #[arg(long)]+ #[arg(long, help_heading = "Common options")]verbose: bool,},/// [Status] Observe OpenViking Server components status@@ -656,6 +866,7 @@ enum Commands {#[command(alias = "lang")]Language {/// Language code: en or zh-CN+ #[arg(value_name = "en|zh-CN")]language: Option<String>,},/// [Status] Show CLI version@@ -675,12 +886,24 @@ enum Commands {/// [Admin] Reindex semantic/vector artifacts for a URIReindex {/// Viking URI+ #[arg(value_name = "uri")]uri: String,/// Reindex mode- #[arg(long, default_value = "vectors_only")]+ #[arg(+ long,+ default_value = "vectors_only",+ value_name = "mode",+ help_heading = "Common options"+ )]mode: String,/// Wait for reindex to complete- #[arg(long, default_value_t = true, action = ArgAction::Set)]+ #[arg(+ long,+ default_value_t = true,+ action = ArgAction::Set,+ value_name = "bool",+ help_heading = "Common options"+ )]wait: bool,},}@@ -717,15 +940,16 @@ enum TaskCommands {/// Show status of a specific taskStatus {/// Task ID returned by add-resource/add-skill+ #[arg(value_name = "task-id")]task_id: String,},/// List all tracked tasksList {/// Filter by task type (e.g. add_resource, add_skill, session_commit, reindex)- #[arg(long)]+ #[arg(long, value_name = "type")]task_type: Option<String>,/// Filter by status (pending, running, completed, failed)- #[arg(long)]+ #[arg(long, value_name = "status")]status: Option<String>,},/// Watch task management (auto-refresh subscriptions)@@ -740,7 +964,7 @@ enum SystemCommands {/// Wait for queued async processing to completeWait {/// Wait timeout in seconds- #[arg(long)]+ #[arg(long, value_name = "seconds")]timeout: Option<f64>,},/// Show component status@@ -750,6 +974,7 @@ enum SystemCommands {/// Check filesystem and vector-index consistency for a URI subtreeConsistency {/// Viking URI to check+ #[arg(value_name = "uri")]uri: String,},/// Cryptographic key management commands@@ -770,12 +995,14 @@ enum SystemBackendCommands {#[command(name = "sync-status")]SyncStatus {/// Viking URI to inspect+ #[arg(value_name = "uri")]uri: String,},/// Retry pending multi-write backend sync work for a URI subtree#[command(name = "sync-retry")]SyncRetry {/// Viking URI to repair+ #[arg(value_name = "uri")]uri: String,},}@@ -807,52 +1034,61 @@ enum SessionCommands {/// Get session detailsGet {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,},/// Get full merged session contextGetSessionContext {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,/// Token budget for latest archive overview inclusion- #[arg(long = "token-budget", default_value = "128000")]+ #[arg(long = "token-budget", default_value = "128000", value_name = "tokens")]token_budget: i32,},/// Get one completed archive for a sessionGetSessionArchive {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,/// Archive ID+ #[arg(value_name = "archive-id")]archive_id: String,},/// Delete a sessionDelete {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,},/// Add one message to a sessionAddMessage {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,/// Message role, e.g. user/assistant- #[arg(long)]+ #[arg(long, value_name = "role")]role: String,/// Message content- #[arg(long)]+ #[arg(long, value_name = "content")]content: String,/// Stable interaction peer id. Omit for self memory.- #[arg(long = "peer-id")]+ #[arg(long = "peer-id", value_name = "peer-id")]peer_id: Option<String>,},/// Add multiple messages to a sessionAddMessages {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,/// Messages as JSON array of {role, content} objects+ #[arg(value_name = "messages-json")]messages: String,},/// Commit a session (archive messages and extract memories)Commit {/// Session ID+ #[arg(value_name = "session-id")]session_id: String,},}@@ -862,6 +1098,7 @@ enum SkillCommands {/// Add skills from a sourceAdd {/// Skill source+ #[arg(value_name = "source")]source: String,/// Install only the named skill(s); use '*' to install all skills in a source#[arg(short = 's', long = "skill", value_name = "NAME", num_args = 1.., value_delimiter = ',')]@@ -884,35 +1121,49 @@ enum SkillCommands {short = 'n',long = "node-limit",alias = "limit",- default_value = "1000"+ default_value = "1000",+ value_name = "n")]node_limit: i32,},/// Find installed agent skills semanticallyFind {/// Search query+ #[arg(value_name = "query")]query: String,/// Maximum number of results#[arg(short = 'n',long = "node-limit",alias = "limit",- default_value = "10"+ default_value = "10",+ value_name = "n")]node_limit: i32,/// Score threshold- #[arg(short, long)]+ #[arg(short, long, value_name = "score")]threshold: Option<f64>,/// Only include results with specific level(s) (0=abstract, 1=overview, 2=file)- #[arg(short = 'L', long = "level", value_delimiter = ',')]+ #[arg(+ short = 'L',+ long = "level",+ value_delimiter = ',',+ value_name = "0,1,2"+ )]level: Option<Vec<i32>>,},/// Show one installed skillShow {/// Skill name+ #[arg(value_name = "name")]name: String,/// Detail level to show (0=abstract, 1=overview, 2=SKILL.md content)- #[arg(short = 'L', long = "level", value_parser = clap::value_parser!(i32).range(0..=2))]+ #[arg(+ short = 'L',+ long = "level",+ value_parser = clap::value_parser!(i32).range(0..=2),+ value_name = "0|1|2"+ )]level: Option<i32>,/// Include files under the skill directory#[arg(short = 'f', long = "files")]@@ -921,7 +1172,7 @@ enum SkillCommands {#[arg(long = "source")]source: bool,/// Output format for this command- #[arg(long = "format", value_parser = ["table", "json"])]+ #[arg(long = "format", value_parser = ["table", "json"], value_name = "table|json")]format: Option<String>,/// Include full SKILL.md content (legacy alias for --level 2)#[arg(long, hide = true)]@@ -930,6 +1181,7 @@ enum SkillCommands {/// Update installed skills from their recorded sourceUpdate {/// Skill name(s) to update; omit to update all installed skills+ #[arg(value_name = "skill")]skills: Vec<String>,/// Wait until processing is complete#[arg(short = 'w', long)]@@ -942,6 +1194,7 @@ enum SkillCommands {#[command(alias = "rm", alias = "delete")]Remove {/// Skill name(s) to remove+ #[arg(value_name = "skill")]skills: Vec<String>,/// Remove all installed skills#[arg(long = "all")]@@ -953,6 +1206,7 @@ enum SkillCommands {/// Validate a local SKILL.md file or skill directoryValidate {/// SKILL.md file or skill directory path+ #[arg(value_name = "path")]path: String,/// Strict mode; warnings such as name mismatch are reported as errors#[arg(long = "strict")]@@ -971,44 +1225,50 @@ enum WatchCommands {/// Show details of a single watch taskShow {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,},/// Delete a watch taskRm {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,},/// Pause a watch task (preserves cadence, stops scheduling)Pause {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,},/// Resume a paused watch taskResume {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,},/// Update one or more mutable fields of a watch task./// At least one flag is required.Update {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,/// New refresh interval in minutes (must be > 0)- #[arg(long)]+ #[arg(long, value_name = "minutes")]interval: Option<f64>,/// Set active (true) / paused (false) — alternative to pause/resume shortcuts- #[arg(long)]+ #[arg(long, value_name = "bool")]active: Option<bool>,/// Human-readable reason for the watch task- #[arg(long)]+ #[arg(long, value_name = "text")]reason: Option<String>,/// Processing instruction forwarded to the refresh handler- #[arg(long)]+ #[arg(long, value_name = "text")]instruction: Option<String>,},/// Trigger an immediate refresh, bypassing the scheduleTrigger {/// task_id (UUID) or to_uri (viking:// URI)+ #[arg(value_name = "task-or-uri")]key: String,},}@@ -1020,60 +1280,77 @@ enum PrivacyCommands {/// List targets by categoryList {/// Privacy config category+ #[arg(value_name = "category")]category: String,},/// Get current active config for targetGet {/// Privacy config category+ #[arg(value_name = "category")]category: String,/// Privacy config target key+ #[arg(value_name = "target-key")]target_key: String,},/// Upsert privacy config valuesUpsert {/// Privacy config category+ #[arg(value_name = "category")]category: String,/// Privacy config target key+ #[arg(value_name = "target-key")]target_key: String,/// JSON object string for values- #[arg(long, conflicts_with = "values_file")]+ #[arg(long, conflicts_with = "values_file", value_name = "json")]values_json: Option<String>,/// JSON file path for values- #[arg(long = "values-file", conflicts_with = "values_json")]+ #[arg(+ long = "values-file",+ conflicts_with = "values_json",+ value_name = "path"+ )]values_file: Option<String>,/// Existing key updates in key=value format (repeatable)- #[arg(long = "key")]+ #[arg(long = "key", value_name = "key=value")]key: Vec<String>,/// Change reason- #[arg(long, default_value = "")]+ #[arg(long, default_value = "", value_name = "text")]change_reason: String,/// Optional labels JSON object string- #[arg(long = "labels-json")]+ #[arg(long = "labels-json", value_name = "json")]labels_json: Option<String>,},/// List versions for targetVersions {/// Privacy config category+ #[arg(value_name = "category")]category: String,/// Privacy config target key+ #[arg(value_name = "target-key")]target_key: String,},/// Get one version by numberVersion {/// Privacy config category+ #[arg(value_name = "category")]category: String,/// Privacy config target key+ #[arg(value_name = "target-key")]target_key: String,/// Version number+ #[arg(value_name = "version")]version: i32,},/// Activate a versionActivate {/// Privacy config category+ #[arg(value_name = "category")]category: String,/// Privacy config target key+ #[arg(value_name = "target-key")]target_key: String,/// Version number+ #[arg(value_name = "version")]version: i32,},}@@ -1083,9 +1360,10 @@ enum AdminCommands {/// Create a new account with its first admin userCreateAccount {/// Account ID to create+ #[arg(value_name = "account-id")]account_id: String,/// First admin user ID- #[arg(long = "admin")]+ #[arg(long = "admin", value_name = "user-id")]admin_user_id: String,},/// List all accounts (ROOT only)@@ -1093,53 +1371,64 @@ enum AdminCommands {/// Delete an account and all associated users (ROOT only)DeleteAccount {/// Account ID to delete+ #[arg(value_name = "account-id")]account_id: String,},/// Register a new user in an accountRegisterUser {/// Account ID+ #[arg(value_name = "account-id")]account_id: String,/// User ID to register+ #[arg(value_name = "user-id")]user_id: String,/// Role: admin or user- #[arg(long, default_value = "user")]+ #[arg(long, default_value = "user", value_name = "role")]role: String,},/// List all users in an accountListUsers {/// Account ID+ #[arg(value_name = "account-id")]account_id: String,/// Maximum number of users to list (default: 100)- #[arg(long, default_value = "100")]+ #[arg(long, default_value = "100", value_name = "n")]limit: u32,/// Filter users by name (supports wildcard * and ?)- #[arg(long)]+ #[arg(long, value_name = "pattern")]name: Option<String>,/// Filter users by role- #[arg(long)]+ #[arg(long, value_name = "role")]role: Option<String>,},/// Remove a user from an accountRemoveUser {/// Account ID+ #[arg(value_name = "account-id")]account_id: String,/// User ID to remove+ #[arg(value_name = "user-id")]user_id: String,},/// Change a user's role (ROOT only)SetRole {/// Account ID+ #[arg(value_name = "account-id")]account_id: String,/// User ID+ #[arg(value_name = "user-id")]user_id: String,/// New role: admin or user+ #[arg(value_name = "role")]role: String,},/// Regenerate a user's API key (old key immediately invalidated)RegenerateKey {/// Account ID+ #[arg(value_name = "account-id")]account_id: String,/// User ID+ #[arg(value_name = "user-id")]user_id: String,},}@@ -1173,6 +1462,7 @@ enum ConfigCommands {/// Switch between saved configsSwitch {/// Saved config name to activate. Omit to open the interactive selector.+ #[arg(value_name = "name")]name: Option<String>,},/// List saved configs@@ -1199,110 +1489,161 @@ enum ConfigAddTarget {#[derive(Args, Debug, Clone)]struct ConfigAddOvServiceArgs {/// Saved config name. Agents should pass this for idempotent retries; generated when omitted.- #[arg(long)]+ #[arg(long, value_name = "name", help_heading = "Common options")]name: Option<String>,/// Read API key from stdin- #[arg(long, conflicts_with = "api_key_env")]+ #[arg(long, conflicts_with = "api_key_env", help_heading = "Common options")]api_key_stdin: bool,/// Read API key from an environment variable- #[arg(long, conflicts_with = "api_key_stdin")]+ #[arg(+ long,+ conflicts_with = "api_key_stdin",+ value_name = "env",+ help_heading = "Common options"+ )]api_key_env: Option<String>,/// Account identifier to send as X-OpenViking-Account- #[arg(long)]+ #[arg(long, value_name = "account", help_heading = "Advanced options")]account: Option<String>,/// User identifier to send as X-OpenViking-User- #[arg(long)]+ #[arg(long, value_name = "user", help_heading = "Advanced options")]user: Option<String>,/// Make the saved config active after validation- #[arg(long)]+ #[arg(long, help_heading = "Common options")]activate: bool,/// Replace an existing saved config- #[arg(long)]+ #[arg(long, help_heading = "Common options")]force: bool,}#[derive(Args, Debug, Clone)]struct ConfigAddCustomArgs {/// Saved config name. Agents should pass this for idempotent retries; generated when omitted.- #[arg(long)]+ #[arg(long, value_name = "name", help_heading = "Common options")]name: Option<String>,/// OpenViking server URL- #[arg(long)]+ #[arg(long, value_name = "url", help_heading = "Common options")]url: Option<String>,/// Read API key from stdin- #[arg(long, conflicts_with_all = ["api_key_env", "root_api_key_stdin"])]+ #[arg(+ long,+ conflicts_with_all = ["api_key_env", "root_api_key_stdin"],+ help_heading = "Common options"+ )]api_key_stdin: bool,/// Read API key from an environment variable- #[arg(long, conflicts_with = "api_key_stdin")]+ #[arg(+ long,+ conflicts_with = "api_key_stdin",+ value_name = "env",+ help_heading = "Common options"+ )]api_key_env: Option<String>,/// Read root API key from stdin- #[arg(long, conflicts_with_all = ["root_api_key_env", "api_key_stdin"])]+ #[arg(+ long,+ conflicts_with_all = ["root_api_key_env", "api_key_stdin"],+ help_heading = "Common options"+ )]root_api_key_stdin: bool,/// Read root API key from an environment variable- #[arg(long, conflicts_with = "root_api_key_stdin")]+ #[arg(+ long,+ conflicts_with = "root_api_key_stdin",+ value_name = "env",+ help_heading = "Common options"+ )]root_api_key_env: Option<String>,/// Account identifier to send as X-OpenViking-Account- #[arg(long)]+ #[arg(long, value_name = "account", help_heading = "Advanced options")]account: Option<String>,/// User identifier to send as X-OpenViking-User- #[arg(long)]+ #[arg(long, value_name = "user", help_heading = "Advanced options")]user: Option<String>,/// Make the saved config active after validation- #[arg(long)]+ #[arg(long, help_heading = "Common options")]activate: bool,/// Replace an existing saved config- #[arg(long)]+ #[arg(long, help_heading = "Common options")]force: bool,}#[derive(Args, Debug, Clone)]struct ConfigEditArgs {/// Saved config name to edit+ #[arg(value_name = "name")]name: String,/// Rename the saved config- #[arg(long)]+ #[arg(long, value_name = "name", help_heading = "Common options")]new_name: Option<String>,/// New server URL. OpenViking Service configs use a fixed URL.- #[arg(long)]+ #[arg(long, value_name = "url", help_heading = "Common options")]url: Option<String>,/// Read replacement API key from stdin- #[arg(long, conflicts_with_all = ["api_key_env", "clear_api_key", "root_api_key_stdin"])]+ #[arg(+ long,+ conflicts_with_all = ["api_key_env", "clear_api_key", "root_api_key_stdin"],+ help_heading = "Common options"+ )]api_key_stdin: bool,/// Read replacement API key from an environment variable- #[arg(long, conflicts_with_all = ["api_key_stdin", "clear_api_key"])]+ #[arg(+ long,+ conflicts_with_all = ["api_key_stdin", "clear_api_key"],+ value_name = "env",+ help_heading = "Common options"+ )]api_key_env: Option<String>,/// Remove the API key- #[arg(long, conflicts_with_all = ["api_key_stdin", "api_key_env"])]+ #[arg(+ long,+ conflicts_with_all = ["api_key_stdin", "api_key_env"],+ help_heading = "Common options"+ )]clear_api_key: bool,/// Read replacement root API key from stdin- #[arg(long, conflicts_with_all = ["root_api_key_env", "clear_root_api_key", "api_key_stdin"])]+ #[arg(+ long,+ conflicts_with_all = ["root_api_key_env", "clear_root_api_key", "api_key_stdin"],+ help_heading = "Common options"+ )]root_api_key_stdin: bool,/// Read replacement root API key from an environment variable- #[arg(long, conflicts_with_all = ["root_api_key_stdin", "clear_root_api_key"])]+ #[arg(+ long,+ conflicts_with_all = ["root_api_key_stdin", "clear_root_api_key"],+ value_name = "env",+ help_heading = "Common options"+ )]root_api_key_env: Option<String>,/// Remove the root API key- #[arg(long, conflicts_with_all = ["root_api_key_stdin", "root_api_key_env"])]+ #[arg(+ long,+ conflicts_with_all = ["root_api_key_stdin", "root_api_key_env"],+ help_heading = "Common options"+ )]clear_root_api_key: bool,/// Account identifier to send as X-OpenViking-Account- #[arg(long)]+ #[arg(long, value_name = "account", help_heading = "Advanced options")]account: Option<String>,/// User identifier to send as X-OpenViking-User- #[arg(long)]+ #[arg(long, value_name = "user", help_heading = "Advanced options")]user: Option<String>,/// Make the saved config active after validation- #[arg(long)]+ #[arg(long, help_heading = "Common options")]activate: bool,/// Replace an existing saved config when renaming- #[arg(long)]+ #[arg(long, help_heading = "Common options")]force: bool,}#[derive(Args, Debug, Clone)]struct ConfigDeleteArgs {/// Saved config name to delete+ #[arg(value_name = "name")]name: String,- /// Delete even when the saved file cannot be parsed- #[arg(long)]+ /// Delete even when the saved config file cannot be parsed+ #[arg(long, help_heading = "Common options")]force: bool,}@@ -1422,9 +1763,11 @@ fn consumes_plain_help_value(token: &str) -> bool {| "--reason"| "--instruction"| "--timeout"+ | "--watch-interval"| "--ignore-dirs"| "--include"| "--exclude"+ | "--description"| "-n"| "--node-limit"| "--limit"@@ -1433,19 +1776,42 @@ fn consumes_plain_help_value(token: &str) -> bool {| "-L"| "--level"| "--level-limit"+ | "-t"+ | "--threshold"+ | "--after"+ | "--before"+ | "--peer-id"| "-s"| "--skill"| "--session"+ | "--session-id"+ | "-m"| "--sender"| "--message"| "--role"| "--content"+ | "--from-file"| "--mode"+ | "--stream"| "--on-conflict"| "--vector-mode"+ | "--task-type"+ | "--status"| "--token-budget"| "--interval"| "--active"+ | "--values-json"+ | "--values-file"+ | "--key"+ | "--change-reason"+ | "--labels-json"+ | "--admin"+ | "--name"+ | "--new-name"+ | "--url"+ | "--api-key-env"+ | "--root-api-key-env"+ | "--output-file"| "--format") || token.starts_with("--output=")|| token.starts_with("--compact=")@@ -1459,26 +1825,49 @@ fn consumes_plain_help_value(token: &str) -> bool {|| token.starts_with("--reason=")|| token.starts_with("--instruction=")|| token.starts_with("--timeout=")+ || token.starts_with("--watch-interval=")|| token.starts_with("--ignore-dirs=")|| token.starts_with("--include=")|| token.starts_with("--exclude=")+ || token.starts_with("--description=")|| token.starts_with("--node-limit=")|| token.starts_with("--limit=")|| token.starts_with("--abs-limit=")|| token.starts_with("--level=")|| token.starts_with("--level-limit=")+ || token.starts_with("--threshold=")+ || token.starts_with("--after=")+ || token.starts_with("--before=")+ || token.starts_with("--peer-id=")|| token.starts_with("--skill=")|| token.starts_with("--session=")+ || token.starts_with("--session-id=")|| token.starts_with("--sender=")|| token.starts_with("--message=")|| token.starts_with("--role=")|| token.starts_with("--content=")+ || token.starts_with("--from-file=")|| token.starts_with("--mode=")+ || token.starts_with("--stream=")|| token.starts_with("--on-conflict=")|| token.starts_with("--vector-mode=")+ || token.starts_with("--task-type=")+ || token.starts_with("--status=")|| token.starts_with("--token-budget=")|| token.starts_with("--interval=")|| token.starts_with("--active=")+ || token.starts_with("--values-json=")+ || token.starts_with("--values-file=")+ || token.starts_with("--key=")+ || token.starts_with("--change-reason=")+ || token.starts_with("--labels-json=")+ || token.starts_with("--admin=")+ || token.starts_with("--name=")+ || token.starts_with("--new-name=")+ || token.starts_with("--url=")+ || token.starts_with("--api-key-env=")+ || token.starts_with("--root-api-key-env=")+ || token.starts_with("--output-file=")|| token.starts_with("--format=")}@@ -2623,6 +3012,33 @@ mod tests {}}+ #[test]+ fn cli_chat_sender_uses_long_flag_and_session_keeps_short_s() {+ Cli::command().debug_assert();++ let cli = Cli::try_parse_from([+ "ov",+ "chat",+ "-s",+ "session-1",+ "--sender",+ "agent-1",+ "--message",+ "hello",+ ])+ .expect("chat flags should parse without short alias conflicts");++ match cli.command {+ Commands::Chat {+ session, sender, ..+ } => {+ assert_eq!(session.as_deref(), Some("session-1"));+ assert_eq!(sender, "agent-1");+ }+ _ => panic!("expected chat command"),+ }+ }+#[test]fn cli_parses_system_backend_sync_status() {let cli = Cli::try_parse_from(["ov", "system", "backend", "sync-status", "viking://a"])@@ -3462,6 +3878,54 @@ mod tests {.is_none());assert!(plain_help_misuse(&os_args(&["ov", "grep", "--uri", "help", "TODO",])).is_none());++ for args in [+ &["ov", "mkdir", "--description", "help", "viking://notes"][..],+ &[+ "ov",+ "write",+ "viking://notes/todo.md",+ "--from-file",+ "help",+ ],+ &[+ "ov",+ "session",+ "add-message",+ "abc",+ "--peer-id",+ "help",+ "--role",+ "user",+ "--content",+ "hi",+ ],+ &[+ "ov",+ "privacy",+ "upsert",+ "cat",+ "target",+ "--values-json",+ "help",+ ],+ &["ov", "admin", "create-account", "acct", "--admin", "help"],+ &["ov", "config", "add", "custom", "--url", "help"],+ &["ov", "task", "list", "--status", "help"],+ &[+ "ov",+ "system",+ "crypto",+ "init-key",+ "--output-file",+ "help",+ ],+ ] {+ assert!(+ plain_help_misuse(&os_args(args)).is_none(),+ "{args:?} should treat help as an option value"+ );+ }}#[test]