/byted-viking-cli

name: byted-viking-cli
description: 官方Viking CLI 命令行助手：本CLI覆盖火山引擎/BytePlus VikingDB(向量库)/Knowledge(知识库)/Memory(记忆库)的数据集管理和数据的读写及检索，
  可用于扩展Agent的知识检索边界 提升Agent的记忆能力；
  当用户对知识库/向量库提问时，使用本Skill;
  当用户要操作向量库/知识库 或 从向量库/知识库检索信息时使用本Skill；
  当用户要记忆检索和记忆存储时，使用本Skill。
version: 1.3.2
license: Apache-2.0

目标

把用户的需求转换为可直接执行的`viking-cli`命令并执行，如果覆盖不了则提示用户。 `viking-cli` 在用户安装后位于系统 `PATH` 中，直接执行 `viking-cli`。

触发与决策

• 按用户目标选择产品：
• 向量库管理、索引管理、向量数据增删改查、id/关键词检索走 `vikingdb`；
• 知识库管理、文档管理、知识库检索、知识服务问答走 `knowledge`；
• 记忆库管理、会话记忆写入、用户记忆检索走 `memory`。
• 如果用户没有明确产品 但提到“知识库(Knowledge)/记忆库(Memory)/向量库(VikingDB)”，先根据目标选择最接近的命令分支。

安装 CLI

用户可用一条命令完成安装（免下载脚本）：

curl -fsSL https://viking-skills.tos-cn-beijing.volces.com/viking-cli/install.sh | bash

如需安装到系统目录（可能需要权限）：

curl -fsSL https://viking-skills.tos-cn-beijing.volces.com/viking-cli/install.sh | sudo bash -s -- --prefix /usr/local

安装完成后验证：

viking-cli version

工作原则

• 涉及复杂 JSON、中文、嵌套数组时，优先推荐文件输入方式；如果当前命令不支持文件输入，再给命令行 JSON 示例。
• 如果用户没有指定collection，则可省略 `--collection` 的参数，默认使用配置文件中的 collection 。
• 如果用户需求超出当前 CLI 能力边界，要明确说“当前 CLI 未实现该子命令”。

命令树

• `viking-cli version`
• `viking-cli auth`
• `viking-cli vikingdb`
• `setup`
• `collection {create|get|list|update|delete}`
• `index {create|get|list|update|delete|enable|disable}`
• `upsert`
• `fetch`
• `delete`
• `search-by-id`
• `search-by-keywords`
• `viking-cli memory`
• `setup`
• `collection {create|get|list|update|delete}`
• `add-session`
• `search`
• `viking-cli knowledge`
• `open`
• `setup`
• `collection {create|get|list|delete}`
• `add-doc`
• `add-file`
• `add-dir`
• `get-doc`
• `list-docs`
• `update-doc`
• `delete-doc`
• `search-collection`
• `search-knowledge`
• `list-services`
• `service-chat`

全局配置

CLI 通过 `viking-cli auth` 交互式写入 `~/.viking/config`，后续命令默认从配置文件读取 AK / SK / Region / Project， 如无特殊情况，命令行无需指定--region和--project参数。 用户执行过对应产品的 `setup`，创建的collection name会写入配置文件，后续很多数据面命令可以不再显式传 `--collection`。

交互式配置（推荐）

viking-cli auth

执行后，根据提示依次输入：

• AccessKey (AK)
• SecretKey (SK)
• Cloud (`volcengine`、`byteplus` 或 `bytecloud`，默认 `volcengine`；)
• Region (如 `cn-beijing`)
• Project (如 `default`)

全局 Flags（命令行参数）

当前实际支持的全局 flags：

• `--cloud`：云环境，`volcengine`、`byteplus` 或 `bytecloud`
• `--region`：Region（用于推导默认 endpoint）
• `--project`：默认 project
• `--format`：输出格式，`json` 或 `text`
• `--timeout`：请求超时，例如 `120s`

JSON 输入策略

部分 control plane 命令支持：

• `--input-json '<JSON_OBJECT>'`
• `--input-file /path/to/payload.json`

这类命令会先用结构化 flags 组装 payload，再 merge `--input-json/--input-file` 的内容。

建议：

• 结构简单时，用显式 flags
• JSON 结构复杂时，用 `--input-file`
• `memory add-session` 复杂内容优先推荐 `--messages-file`；`metadata` 可选，传文件用 `--metadata-file`

输出约定

默认输出为格式化 JSON；若用户需要纯文本，使用 `--format text`。

版本与鉴权配置

viking-cli version
viking-cli auth

VikingDB / Setup

通过本地数据样本自动推断 schema，并一键创建 collection、index，并 upsert 数据 【推荐】。

`vikingdb setup` 支持默认命名（允许不传 `--collection` / `--index`）：

• 默认 collection：`viking_cli_{userid}`
• 默认 index：`viking_cli_{userid}_index`（即 `<collection>_index`）

viking-cli --region <region> vikingdb setup   --collection <collection_name>   --index <index_name>   --file data.csv   --id-field item_id

viking-cli --region <region> vikingdb setup   --collection <collection_name>   --index <index_name>   --file data.csv   --fields '[{"FieldName":"avatar","FieldType":"image"},{"FieldName":"content","FieldType":"text"}]'

viking-cli --region <region> vikingdb setup   --collection <collection_name>   --index <index_name>   --file data.jsonl   --vectorize-field content

VikingDB / Collection

创建：

viking-cli --region <region> vikingdb collection create   --name <collection_name>   --desc '<description>'   --fields-json '<json_array>'   --fulltext-json '<json_object>'   --tags-json '<json_value>'   --vectorize-json '<json_object>'

完整 payload：

viking-cli --region <region> vikingdb collection create --input-file /path/to/create_collection.json

查询：

viking-cli --region <region> vikingdb collection get --name <collection_name>

列表：

viking-cli --region <region> vikingdb collection list  --page-number 1   --page-size 10   --filter-json '<json_value>'

更新：

viking-cli --region <region> vikingdb collection update --name <collection_name>   --desc '<description>'   --fields-json '<json_value>'

删除：

viking-cli --region <region> vikingdb collection delete --name <collection_name>

VikingDB / Index

创建：

viking-cli --region <region> vikingdb index create  --name <index_name>   --collection <collection_name>   --desc '<description>'   --cpu-quota 2   --shard-count 1   --shard-policy '<policy>'   --vector-index-json '<json_object>'   --scalar-index-json '<json_value>'

查询：

viking-cli --region <region> vikingdb index get --name <index_name>   --collection <collection_name>

列表：

viking-cli --region <region> vikingdb index list --page-number 1 --page-size 10

更新：

viking-cli --region <region> vikingdb index update --name <index_name>   --collection <collection_name>   --desc '<description>'   --cpu-quota 4   --scalar-index-json '<json_value>'

启用 / 禁用：

viking-cli --region <region> vikingdb index enable --name <index_name> --collection <collection_name>
viking-cli --region <region> vikingdb index disable --name <index_name> --collection <collection_name>

删除：

viking-cli --region <region> vikingdb index delete --name <index_name> --collection <collection_name>

VikingDB / Data

导入 / 更新数据：

viking-cli --region <region> vikingdb upsert   --collection <collection_name>   --file data.csv   --id-field id   --batch-size 200

viking-cli --region <region> vikingdb upsert   --collection <collection_name>   --file data.jsonl   --batch-size 200

获取数据：

viking-cli --region <region> vikingdb fetch --collection <collection_name> --ids-json '["id1","id2"]'