Skip to content

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

docs(cli): update ov cli readme (#3388)

Jiahui Zhou4295dfdef0e8
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.md
index 2fda33a2f..f001c3732 100644
--- a/crates/ov_cli/README.md
+++ b/crates/ov_cli/README.md
@@ -1,26 +1,83 @@
# OpenViking CLI
-Command-line interface for [OpenViking](https://github.com/volcengine/OpenViking) - an Agent-native context database.
+Command-line interface for [OpenViking](https://github.com/volcengine/OpenViking), an Agent-native context database.
+
+This package builds the native `ov` binary. Use it to configure an OpenViking endpoint, import resources, browse `viking://` paths, retrieve context, inspect server status, manage sessions, and run administrative workflows.
+
+中文文档见 [README_CN.md](README_CN.md).
## Installation
-### Install from npm (macOS/Linux/Windows)
+### Install from npm
```bash
npm i -g @openviking/cli
```
-### From Source
+The npm package installs the platform-specific `ov` binary for macOS, Linux, or Windows.
+
+### Install from source
```bash
-# openviking need rust >= 1.91.1, please upgrade it if necessary
-# brew upgrade rust
+# OpenViking requires Rust >= 1.91.1.
cargo install --path crates/ov_cli
```
+If you are developing inside this crate:
+
+```bash
+cd crates/ov_cli
+cargo install --path .
+```
+
## Configuration
-Create `~/.openviking/ovcli.conf`:
+The recommended setup path is the interactive config manager:
+
+```bash
+ov config
+```
+
+`ov config` can add, edit, delete, validate, and switch saved configs. It writes the active client config to `~/.openviking/ovcli.conf`. Saved named configs are stored as `~/.openviking/ovcli.conf.<name>`, and `ov config switch <name>` copies the selected saved config to the active config path.
+
+Recent CLI versions require a saved display language before most commands run in non-interactive shells:
+
+```bash
+ov language en
+# or
+ov language zh-CN
+```
+
+For scripts and agents, prefer deterministic config commands and pass secrets through stdin or existing environment variables:
+
+```bash
+# OpenViking Service
+printf '%s' "$OPENVIKING_API_KEY" | \
+ ov config add ov-service --name prod --api-key-stdin --activate -o json
+
+# Custom local server without auth
+ov config add custom --name local --url http://127.0.0.1:1933 --activate -o json
+
+# Custom remote server with a user API key
+printf '%s' "$OPENVIKING_API_KEY" | \
+ ov config add custom --name remote --url https://ov.example.com --api-key-stdin --activate -o json
+```
+
+Validate the active config:
+
+```bash
+ov config show
+ov config list -o json
+ov config validate
+ov health
+ov status
+```
+
+`ov config show` redacts secrets. Avoid printing raw `~/.openviking/ovcli.conf` unless you understand it may contain API keys.
+
+### Manual config file
+
+Manual editing is still supported. A minimal custom-server config looks like:
```json
{
@@ -31,109 +88,170 @@ Create `~/.openviking/ovcli.conf`:
}
```
-`role` defaults to `user` and only applies in `trusted` mode. In `api_key` mode the server ignores it and derives the effective role from the API key. `account` and `user` are optional with a regular user key because the server can derive them from the key. They are recommended when you use `trusted` auth mode or a root key against tenant-scoped APIs.
+`account` and `user` are usually optional when using a regular user API key because the server can derive identity from the key. They are recommended for `trusted` auth mode and tenant-scoped operations. They are required for root-key-only configs because a root key has no built-in tenant identity.
+
+For more setup details, see [docs/en/getting-started/05-cli-setup.md](../../docs/en/getting-started/05-cli-setup.md).
## Quick Start
```bash
-# Add a resource
+# Check connectivity
+ov health
+ov status
+
+# Add a resource and wait for processing
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/docs/en/about/01-about-us.md --wait
-# List contents
+# Browse context
ov ls viking://resources
+ov tree viking://resources -L 2
+ov read viking://resources/...
-# Semantic search
+# Retrieve context
ov find "what is openviking"
-
-# Get file tree
-ov tree viking://resources
-
-# Read content
-ov read viking://resources/...
+ov grep "openviking" --uri viking://resources
```
+Run `ov --help` and `ov <command> --help` for the exact command surface of your installed version.
+
## Command Groups
### Resource Management
-- `add-resource` - Import local files or URLs
-- `add-skill` - Add a skill
-- `export` - Export as .ovpack
-- `import` - Import .ovpack
-### Relations
-- `relations` - List relations
-- `link` - Create relation links
-- `unlink` - Remove relation
+- `add-resource` - Import local files, directories, URLs, Git repositories, and supported document sources.
+- `add-skill` - Add a skill from a directory, `SKILL.md`, or raw content.
+- `skills` - List, find, show, update, remove, and validate installed skills.
+- `export` / `import` - Export or import context as `.ovpack`.
+- `backup` / `restore` - Back up and restore public OpenViking scopes as restore-only `.ovpack` files.
### Filesystem
-- `ls` - List directory contents
-- `tree` - Get directory tree
-- `mkdir` - Create directory
-- `rm` - Remove resource
-- `mv` - Move/rename
-- `stat` - Get metadata
+
+- `ls` - List directory contents.
+- `tree` - Show a hierarchical tree.
+- `mkdir` - Create a directory.
+- `rm` - Remove a resource or directory.
+- `mv` - Move or rename a resource.
+- `stat` - Show resource metadata.
+- `attrs` - Get logical extended attributes.
+- `get` - Download a file to a local path.
### Content Access
-- `read` - Read L2 (full content)
-- `abstract` - Read L0 (abstract)
-- `overview` - Read L1 (overview)
+
+- `read` - Read L2 full content.
+- `abstract` - Read L0 abstract content.
+- `overview` - Read L1 overview content.
+- `write` - Replace, append, or create text content.
### Search
-- `find` - Semantic retrieval
-- `search` - Context-aware retrieval
-- `grep` - Content pattern search
-- `glob` - File glob pattern
-
-### System
-- `system wait` - Wait for async processing
-- `system status` - Component status
-- `system health` - Health check
-- `observer queue` - Queue status
-- `observer vikingdb` - VikingDB status
-- `observer vlm` - VLM status
-
-### Session
-- `session new` - Create session
-- `session list` - List sessions
-- `session get` - Get session details
-- `session delete` - Delete session
-- `session add-message` - Add message
-- `session commit` - Commit and extract memories
-
-### Config
-- `config show` - Show configuration
-- `config validate` - Validate config
+
+- `find` - Semantic retrieval.
+- `search` - Context-aware retrieval. Experimental.
+- `grep` - Content pattern search.
+- `glob` - File glob pattern search.
+
+### Sessions And Memory
+
+- `session new` - Create a session.
+- `session list` - List sessions.
+- `session get` - Get session details.
+- `session get-session-context` - Get merged session context.
+- `session add-message` / `session add-messages` - Add messages to a session.
+- `session commit` - Archive messages and extract memories.
+- `add-memory` - Create a session, add messages, and commit in one shot. Experimental.
+
+### Interactive
+
+- `tui` - Interactive file explorer.
+- `chat` - Chat with the vikingbot agent.
+
+### Status And Observability
+
+- `health` - Quick health check.
+- `status` - Aggregated server component status.
+- `wait` - Wait for queued async processing.
+- `task status` / `task list` - Track async tasks.
+- `task watch` - Manage auto-refresh watch tasks.
+- `observer queue` - Queue status.
+- `observer vikingdb` - VikingDB status.
+- `observer models` - VLM, embedding, and rerank model status.
+- `observer retrieval` - Retrieval quality metrics.
+- `observer fs` - Filesystem operation metrics.
+- `observer system` - Overall system status.
+
+### Configuration
+
+- `config` - Interactive config manager.
+- `config show` - Show the active config with secrets redacted.
+- `config validate` - Validate the active config.
+- `config list` - List saved configs.
+- `config switch` - Switch the active config.
+- `config add` - Add a saved config non-interactively.
+- `config edit` - Edit a saved config non-interactively.
+- `config delete` - Delete a saved config.
+- `language` / `lang` - Choose CLI display language (`en` or `zh-CN`).
+- `version` - Show CLI version.
+
+### Versioned Workspace Snapshots
+
+- `snapshot commit` - Create a workspace snapshot.
+- `snapshot restore` - Restore a path or workspace to a previous snapshot.
+- `snapshot show` - Show commit metadata or blob content.
+- `snapshot log` - Walk snapshot history.
+- `snapshot ignore-get` / `snapshot ignore-set` / `snapshot ignore-delete` - Manage account `.ovgitignore`.
+
+### Relations And Privacy
+
+- `relations` - List resource relations. Experimental.
+- `link` - Create relation links. Experimental.
+- `unlink` - Remove a relation link. Experimental.
+- `privacy` - Manage privacy configuration categories, targets, versions, and active config.
### Admin
-- `admin create-account` - Create an account and first admin user
-- `admin register-user` - Register a user
-- `admin regenerate-key` - Rotate a user's API key
-### Display
-- `language` (`lang`) - Choose CLI display language (`en` / `zh-CN`)
+Use `--sudo` for commands that require the configured `root_api_key`.
+
+- `admin create-account` - Create an account and first admin user.
+- `admin list-accounts` - List accounts. ROOT only.
+- `admin delete-account` - Delete an account. ROOT only.
+- `admin register-user` - Register a user.
+- `admin list-users` - List users in an account.
+- `admin remove-user` - Remove a user.
+- `admin set-role` - Change a user's role. ROOT only.
+- `admin regenerate-key` - Rotate a user's API key.
+- `admin migrate` - Migrate legacy agent/session data. ROOT only.
+- `system` - Administrative system utility commands.
+- `reindex` - Rebuild semantic and vector artifacts for a URI.
## Output Formats
+The default output is human-readable table/card rendering. Use JSON for scripts:
+
```bash
-ov --output json ls
-ov --output table ls
-ov -o json ls # Compact JSON wrapper for scripts
+ov -o json ls viking://resources
+ov -o json config list
```
+Some command help may also show the long `--output json` form. `-o json` is the compact form used throughout tests and automation examples.
+
## Examples
```bash
# Add URL and wait for processing
ov add-resource https://example.com/docs --wait --timeout 60
-# Add local directory with advanced options
+# Add a local directory with filters
ov add-resource ./dir \
--wait --timeout 600 \
- --ignore-dirs "subdir-a,subdir-b/subsubdir-c" \
+ --ignore-dirs "node_modules,dist" \
+ --include "*.md,*.py" \
--exclude "*.tmp,*.log"
-# Search with threshold
+# Import into a predictable parent path
+ov add-resource ./docs -p "viking://resources/docs/{calendar:today}" --wait
+
+# Search with filters
ov find "API authentication" --threshold 0.7 --limit 5
+ov find "authentication" --uri viking://resources/project --level 0,1
# Recursive list
ov ls viking://resources --recursive
@@ -141,7 +259,7 @@ ov ls viking://resources --recursive
# Temporarily override identity from CLI flags
ov --account acme --user alice ls viking://
-# Create predictable API keys from a seed
+# Use a root API key for administrative commands
ov --sudo admin create-account acme --admin alice --seed alice-seed
ov admin register-user acme bob --role user --seed bob-seed
ov admin regenerate-key acme bob --seed bob-new-seed
@@ -151,8 +269,13 @@ ov glob "**/*.md" --uri viking://resources
# Session workflow
SESSION=$(ov -o json session new | jq -r '.result.session_id')
-ov session add-message --session-id $SESSION --role user --content "Hello"
-ov session commit --session-id $SESSION
+ov session add-message --session-id "$SESSION" --role user --content "Hello"
+ov session commit --session-id "$SESSION"
+
+# Watch task management
+ov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60
+ov task watch ls
+ov task watch trigger viking://resources/docs
```
## Development
@@ -163,7 +286,7 @@ cargo build --release
# Smoke the exact binary that was built
target/release/ov --version
-target/release/ov -o json system health
+target/release/ov -o json health
# Run tests
cargo test
@@ -172,5 +295,4 @@ cargo test
cargo install --path .
```
-When driving external e2e harnesses, point them at `target/release/ov` explicitly
-instead of relying on an older `ov` that may already be installed on `PATH`.
+When driving external e2e harnesses, point them at `target/release/ov` explicitly instead of relying on an older `ov` that may already be installed on `PATH`.
diff --git a/crates/ov_cli/README_CN.md b/crates/ov_cli/README_CN.md
new file mode 100644
index 000000000..1caf66101
--- /dev/null
+++ b/crates/ov_cli/README_CN.md
@@ -0,0 +1,298 @@
+# OpenViking CLI
+
+[OpenViking](https://github.com/volcengine/OpenViking) 的命令行客户端。OpenViking 是面向 Agent 的上下文数据库。
+
+本目录构建原生 `ov` 二进制。你可以用它配置 OpenViking 连接、导入资源、浏览 `viking://` 路径、检索上下文、查看服务状态、管理 session,以及执行管理员操作。
+
+English documentation: [README.md](README.md).
+
+## 安装
+
+### 通过 npm 安装
+
+```bash
+npm i -g @openviking/cli
+```
+
+npm 包会安装适配 macOS、Linux 或 Windows 的平台二进制。
+
+### 从源码安装
+
+```bash
+# OpenViking 要求 Rust >= 1.91.1。
+cargo install --path crates/ov_cli
+```
+
+如果你正在本 crate 内开发:
+
+```bash
+cd crates/ov_cli
+cargo install --path .
+```
+
+## 配置
+
+推荐使用交互式配置管理器:
+
+```bash
+ov config
+```
+
+`ov config` 可以新增、编辑、删除、校验和切换配置。CLI 会把当前 active 客户端配置写到 `~/.openviking/ovcli.conf`。命名配置会保存为 `~/.openviking/ovcli.conf.<name>`,`ov config switch <name>` 会把选中的命名配置复制为 active 配置。
+
+较新的 CLI 版本在非交互式 shell 中运行大多数命令前,需要先保存显示语言:
+
+```bash
+ov language en
+# 或
+ov language zh-CN
+```
+
+脚本和 Agent 场景建议使用确定性的配置命令,并通过 stdin 或已有环境变量传递密钥:
+
+```bash
+# OpenViking Service
+printf '%s' "$OPENVIKING_API_KEY" | \
+ ov config add ov-service --name prod --api-key-stdin --activate -o json
+
+# 本地无鉴权自定义服务
+ov config add custom --name local --url http://127.0.0.1:1933 --activate -o json
+
+# 使用 user API key 的远程自定义服务
+printf '%s' "$OPENVIKING_API_KEY" | \
+ ov config add custom --name remote --url https://ov.example.com --api-key-stdin --activate -o json
+```
+
+验证 active 配置:
+
+```bash
+ov config show
+ov config list -o json
+ov config validate
+ov health
+ov status
+```
+
+`ov config show` 会隐藏密钥。除非你明确知道 `~/.openviking/ovcli.conf` 可能包含 API Key,否则不要直接打印原始配置文件。
+
+### 手动配置文件
+
+仍然支持手动编辑配置。一个最小的自定义服务配置示例如下:
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "your-api-key",
+ "account": "acme",
+ "user": "alice"
+}
+```
+
+使用普通 user API key 时,`account` 和 `user` 通常可以省略,因为服务端可以从 key 推导身份。使用 `trusted` 鉴权或租户级操作时,建议显式配置它们。仅 root key 的配置必须显式配置 `account` 和 `user`,因为 root key 本身不包含租户身份。
+
+更完整的配置说明见 [docs/zh/getting-started/05-cli-setup.md](../../docs/zh/getting-started/05-cli-setup.md)。
+
+## 快速开始
+
+```bash
+# 检查连接
+ov health
+ov status
+
+# 添加资源并等待处理完成
+ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/docs/en/about/01-about-us.md --wait
+
+# 浏览上下文
+ov ls viking://resources
+ov tree viking://resources -L 2
+ov read viking://resources/...
+
+# 检索上下文
+ov find "what is openviking"
+ov grep "openviking" --uri viking://resources
+```
+
+当前安装版本的准确命令面以 `ov --help` 和 `ov <command> --help` 为准。
+
+## 命令分组
+
+### 资源管理
+
+- `add-resource` - 导入本地文件、目录、URL、Git 仓库和支持的文档源。
+- `add-skill` - 从目录、`SKILL.md` 或原始内容添加 skill。
+- `skills` - 列出、检索、查看、更新、删除和校验已安装 skills。
+- `export` / `import` - 以 `.ovpack` 格式导出或导入上下文。
+- `backup` / `restore` - 把公共 OpenViking scope 备份或恢复为 restore-only `.ovpack`。
+
+### 文件系统
+
+- `ls` - 列出目录内容。
+- `tree` - 显示目录树。
+- `mkdir` - 创建目录。
+- `rm` - 删除资源或目录。
+- `mv` - 移动或重命名资源。
+- `stat` - 查看资源元数据。
+- `attrs` - 获取逻辑扩展属性。
+- `get` - 下载文件到本地路径。
+
+### 内容访问
+
+- `read` - 读取 L2 全量内容。
+- `abstract` - 读取 L0 摘要。
+- `overview` - 读取 L1 概览。
+- `write` - 替换、追加或创建文本内容。
+
+### 搜索
+
+- `find` - 语义检索。
+- `search` - 上下文感知检索,实验特性。
+- `grep` - 内容模式搜索。
+- `glob` - 文件 glob 搜索。
+
+### Session 与记忆
+
+- `session new` - 创建 session。
+- `session list` - 列出 sessions。
+- `session get` - 查看 session 详情。
+- `session get-session-context` - 获取合并后的 session 上下文。
+- `session add-message` / `session add-messages` - 向 session 添加消息。
+- `session commit` - 归档消息并抽取记忆。
+- `add-memory` - 一次性创建 session、添加消息并提交,实验特性。
+
+### 交互式工具
+
+- `tui` - 交互式文件浏览器。
+- `chat` - 与 vikingbot agent 对话。
+
+### 状态与可观测性
+
+- `health` - 快速健康检查。
+- `status` - 聚合服务组件状态。
+- `wait` - 等待异步处理队列完成。
+- `task status` / `task list` - 跟踪异步任务。
+- `task watch` - 管理自动刷新 watch 任务。
+- `observer queue` - 队列状态。
+- `observer vikingdb` - VikingDB 状态。
+- `observer models` - VLM、embedding 和 rerank 模型状态。
+- `observer retrieval` - 检索质量指标。
+- `observer fs` - 文件系统操作指标。
+- `observer system` - 整体系统状态。
+
+### 配置
+
+- `config` - 交互式配置管理器。
+- `config show` - 显示 active 配置并隐藏密钥。
+- `config validate` - 校验 active 配置。
+- `config list` - 列出命名配置。
+- `config switch` - 切换 active 配置。
+- `config add` - 非交互式新增命名配置。
+- `config edit` - 非交互式编辑命名配置。
+- `config delete` - 删除命名配置。
+- `language` / `lang` - 选择 CLI 显示语言(`en` 或 `zh-CN`)。
+- `version` - 显示 CLI 版本。
+
+### 工作区快照
+
+- `snapshot commit` - 创建工作区快照。
+- `snapshot restore` - 把路径或工作区恢复到历史快照。
+- `snapshot show` - 显示 commit 元数据或 blob 内容。
+- `snapshot log` - 查看快照历史。
+- `snapshot ignore-get` / `snapshot ignore-set` / `snapshot ignore-delete` - 管理 account `.ovgitignore`。
+
+### 关系与隐私
+
+- `relations` - 列出资源关系,实验特性。
+- `link` - 创建关系链接,实验特性。
+- `unlink` - 删除关系链接,实验特性。
+- `privacy` - 管理隐私配置分类、目标、版本和 active 配置。
+
+### 管理员命令
+
+需要 `root_api_key` 的命令使用 `--sudo`。
+
+- `admin create-account` - 创建 account 和首个 admin 用户。
+- `admin list-accounts` - 列出 accounts,仅 ROOT。
+- `admin delete-account` - 删除 account,仅 ROOT。
+- `admin register-user` - 注册用户。
+- `admin list-users` - 列出 account 内用户。
+- `admin remove-user` - 移除用户。
+- `admin set-role` - 修改用户角色,仅 ROOT。
+- `admin regenerate-key` - 轮转用户 API key。
+- `admin migrate` - 迁移 legacy agent/session 数据,仅 ROOT。
+- `system` - 管理类系统工具命令。
+- `reindex` - 为 URI 重建语义和向量产物。
+
+## 输出格式
+
+默认输出是面向人的表格或卡片渲染。脚本中建议使用 JSON:
+
+```bash
+ov -o json ls viking://resources
+ov -o json config list
+```
+
+部分帮助文本也可能展示长参数 `--output json`。`-o json` 是测试和自动化示例中常用的紧凑写法。
+
+## 示例
+
+```bash
+# 添加 URL 并等待处理完成
+ov add-resource https://example.com/docs --wait --timeout 60
+
+# 添加本地目录并过滤文件
+ov add-resource ./dir \
+ --wait --timeout 600 \
+ --ignore-dirs "node_modules,dist" \
+ --include "*.md,*.py" \
+ --exclude "*.tmp,*.log"
+
+# 导入到可预测的父路径
+ov add-resource ./docs -p "viking://resources/docs/{calendar:today}" --wait
+
+# 带过滤条件的搜索
+ov find "API authentication" --threshold 0.7 --limit 5
+ov find "authentication" --uri viking://resources/project --level 0,1
+
+# 递归列目录
+ov ls viking://resources --recursive
+
+# 临时通过 CLI 参数覆盖身份
+ov --account acme --user alice ls viking://
+
+# 使用 root API key 执行管理员命令
+ov --sudo admin create-account acme --admin alice --seed alice-seed
+ov admin register-user acme bob --role user --seed bob-seed
+ov admin regenerate-key acme bob --seed bob-new-seed
+
+# Glob 搜索
+ov glob "**/*.md" --uri viking://resources
+
+# Session 工作流
+SESSION=$(ov -o json session new | jq -r '.result.session_id')
+ov session add-message --session-id "$SESSION" --role user --content "Hello"
+ov session commit --session-id "$SESSION"
+
+# Watch 任务管理
+ov add-resource https://example.com/docs --to viking://resources/docs --watch-interval 60
+ov task watch ls
+ov task watch trigger viking://resources/docs
+```
+
+## 开发
+
+```bash
+# 构建
+cargo build --release
+
+# 使用刚构建出的精确二进制做 smoke
+target/release/ov --version
+target/release/ov -o json health
+
+# 运行测试
+cargo test
+
+# 本地安装
+cargo install --path .
+```
+
+驱动外部 e2e harness 时,请显式指向 `target/release/ov`,避免误用 `PATH` 中已经安装的旧版 `ov`。