Skip to content

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

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.rs
index 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) -> String
copy(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(&section.title, language),
+ &section.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.rs
index 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 OpenViking
AddResource {
/// 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 OpenViking
AddSkill {
/// 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 tree
Tree {
/// 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 directory
Mkdir {
/// 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 metadata
Stat {
/// 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 file
Write {
/// 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 retrieval
Find {
/// 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 retrieval
Search {
/// 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 search
Grep {
/// 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 search
Glob {
/// 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 resource
Relations {
/// Viking URI
+ #[arg(value_name = "uri")]
uri: String,
},
/// [Experimental][Data] Create relation links from one URI to one or more targets
Link {
/// 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 link
Unlink {
/// 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 .ovpack
Export {
/// 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 .ovpack
Backup {
/// 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 URI
Import {
/// 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 roots
Restore {
/// 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 explorer
Tui {
/// Viking URI to start browsing (default: /)
- #[arg(default_value = "/")]
+ #[arg(default_value = "/", value_name = "uri")]
uri: String,
},
/// [Interactive] Chat with vikingbot agent
Chat {
/// 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 complete
Wait {
/// 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 status
Status {
/// 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 URI
Reindex {
/// 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 task
Status {
/// Task ID returned by add-resource/add-skill
+ #[arg(value_name = "task-id")]
task_id: String,
},
/// List all tracked tasks
List {
/// 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 complete
Wait {
/// 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 subtree
Consistency {
/// 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 details
Get {
/// Session ID
+ #[arg(value_name = "session-id")]
session_id: String,
},
/// Get full merged session context
GetSessionContext {
/// 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 session
GetSessionArchive {
/// Session ID
+ #[arg(value_name = "session-id")]
session_id: String,
/// Archive ID
+ #[arg(value_name = "archive-id")]
archive_id: String,
},
/// Delete a session
Delete {
/// Session ID
+ #[arg(value_name = "session-id")]
session_id: String,
},
/// Add one message to a session
AddMessage {
/// 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 session
AddMessages {
/// 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 source
Add {
/// 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 semantically
Find {
/// 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 skill
Show {
/// 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 source
Update {
/// 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 directory
Validate {
/// 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 task
Show {
/// task_id (UUID) or to_uri (viking:// URI)
+ #[arg(value_name = "task-or-uri")]
key: String,
},
/// Delete a watch task
Rm {
/// 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 task
Resume {
/// 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 schedule
Trigger {
/// 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 category
List {
/// Privacy config category
+ #[arg(value_name = "category")]
category: String,
},
/// Get current active config for target
Get {
/// Privacy config category
+ #[arg(value_name = "category")]
category: String,
/// Privacy config target key
+ #[arg(value_name = "target-key")]
target_key: String,
},
/// Upsert privacy config values
Upsert {
/// 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 target
Versions {
/// 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 number
Version {
/// 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 version
Activate {
/// 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 user
CreateAccount {
/// 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 account
RegisterUser {
/// 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 account
ListUsers {
/// 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 account
RemoveUser {
/// 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 configs
Switch {
/// 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]