byted-viking-cli

Goal

Convert the user's needs into directly executableviking-clicommands and execute them; if they cannot be covered, prompt the user. viking-cli After the user installs it, it is located in the system PATH , execute directly viking-cli。

Trigger and decision

Select the product according to the user's goal:
- Vector store management, index management, vector data create/delete/update/query, id/keyword retrieval go through vikingdb；
- Knowledge base management, document management, knowledge base retrieval, knowledge service Q&A go through knowledge；
- Memory store management, session memory writing, user memory retrieval go through memory。
If the user does not specify a product but mentions "knowledge base (Knowledge)/memory store (Memory)/vector store (VikingDB)", first choose the closest command branch according to the goal.

Install CLI

The user can complete installation with one command (no need to download a script):

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

If installation to a system directory is required (permissions may be needed):

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

Verify after installation is complete:

viking-cli version

Working principles

When complex JSON, Chinese, or nested arrays are involved, prefer recommending the file input method; if the current command does not support file input, then provide a command-line JSON example.
If the user does not specify a collection, the --collection parameter can be omitted, and the collection in the configuration file is used by default.
If the user's need exceeds the current CLI capability boundary, clearly say "the current CLI has not implemented this subcommand".

Command tree

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

Global configuration

The CLI writes viking-cli auth interactively through ~/.viking/config, and subsequent commands read AK / SK / Region / Project from the configuration file by default. Unless there are special circumstances, the command line does not need to specify the --region and --project parameters. After the user has executed the corresponding product's setup, the created collection name will be written to the configuration file, and many subsequent data plane commands no longer need to explicitly pass --collection。

Interactive configuration (recommended)

viking-cli auth

After execution, enter the following in order according to the prompts:

AccessKey (AK)
SecretKey (SK)
Cloud (volcengine、byteplus or bytecloud, default volcengine；)
Region (such as cn-beijing)
Project (such as default)

Global Flags (command-line parameters)

Currently actually supported global flags:

--cloud: cloud environment,volcengine、byteplus or bytecloud
--region: Region (used to derive the default endpoint)
--project: default project
--format: output format,json or text
--timeout: request timeout, for example 120s

JSON input strategy

Some control plane commands support:

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

This type of command first uses structured flags to assemble the payload, then merges --input-json/--input-file content.

Recommendations:

When the structure is simple, use explicit flags
When the JSON structure is complex, use --input-file
memory add-session For complex content, prefer --messages-file；metadata Optional; to pass a file use --metadata-file

Output conventions

The default output is formatted JSON; if the user needs plain text, use --format text。

Version and authentication configuration

viking-cli version
viking-cli auth

VikingDB / Setup

Automatically infer the schema from local data samples, and with one click create the collection, index, and upsert the data [Recommended].

vikingdb setup Supports default naming (allowing omission of --collection / --index）：

Default collection:viking_cli_{userid}
Default index:viking_cli_{userid}_index(i.e., <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

Create:

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>'

Full payload:

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

Query:

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

List:

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

Update:

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

Delete:

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

VikingDB / Index

Create:

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>'

Query:

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

List:

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

Update:

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

Enable / Disable:

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>

Delete:

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

VikingDB / Data

Import / Update 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

Get data:

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

Delete data:

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

Similarity search:

viking-cli --region <region> vikingdb search-by-id   --collection <collection_name>   --index <index_name>   --id '<document_id>'   --limit 10

Query or keyword search:

viking-cli --region <region> vikingdb search-by-keywords   --collection <collection_name>   --index <index_name>   --query '<search_text>'   --limit 10

Memory / Setup and Collection

Create a personal memory bank with one click, by default named viking_cli_{userid}：

viking-cli --region <region> memory setup

viking-cli --region <region> memory setup --name <collection_name>

Create:

viking-cli --region <region> memory collection create --name <collection_name>  --desc '<description>'   --cpu-quota 2

List:

viking-cli --region <region> memory collection list

Query / Update:

viking-cli --region <region> memory collection get --name <collection_name>
viking-cli --region <region> memory collection update --name <collection_name> --desc '<description>' --cpu-quota 4

Delete:

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

Memory / Session and search

Record session content:

viking-cli --region <region> memory add-session   --collection <collection_name>   --session-id '<session_id>'   --messages-file ./messages.json   [--metadata-file ./metadata.json]

messages.json Example:

[
  {"role": "user", "content": "我喜欢打篮球"},
  {"role": "assistant", "content": "好的，记下了"}
]

metadata.json structure (optional; if omitted, the CLI will generate it automatically):

{
  "default_user_id": "user_id",
  "default_user_name": "user_name",
  "default_assistant_id": "assistant_id",
  "default_assistant_name": "assistant_name"
}

filter-json structure (optional; if omitted, the CLI will generate it automatically):

{
  "memory_type": ["sys_event_v1", "sys_profile_v1"],
  "user_id": "user_id",
  "assistant_id": "assistant_id"
}

Memory search:

viking-cli --region <region> memory search --collection <collection_name> --query '打篮球' --filter-json '<json_object>' --limit 10

Knowledge / Setup and Collection

Activate the knowledge base service (supports volcengine / byteplus, idempotent: if already activated, directly return the current status; if not activated, perform activation):

viking-cli --region <region> knowledge open

Create a personal knowledge base with one click, by default named viking_cli_{userid}. Under volcengine / byteplus ,setup will first check whether the knowledge base service has been activated; if not, it will activate it automatically, then create the collection:

viking-cli --region <region> knowledge setup

viking-cli --region <region> knowledge setup --name <collection_name>

Create:

viking-cli --region <region> knowledge collection create   --name <collection_name>   --desc '<description>'   --version 4   --data-type unstructured_data

List / Query:

viking-cli --region <region> knowledge collection list
viking-cli --region <region> knowledge collection get --name <collection_name>

Delete:

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

Knowledge / Documents and search

Add document (pass URI directly):

viking-cli --region <region> knowledge add-doc   --collection <collection_name>   --uri <uri>   --doc-id <doc_id>   --doc-name '<doc_name>'   --doc-type '<doc_type>'   --desc '<description>'   --tag-list-json '<json_value>'

Upload local file:

viking-cli --region <region> knowledge add-file   --collection <collection_name>   --file /path/to/local_file.pdf

Upload directory:

viking-cli --region <region> knowledge add-dir   --collection <collection_name>   --dir /path/to/local_directory

Get / List / Update / Delete document:

viking-cli --region <region> knowledge get-doc --collection <collection_name> --doc-id <doc_id>
viking-cli --region <region> knowledge list-docs --collection <collection_name> --offset 0 --limit 10
viking-cli --region <region> knowledge update-doc --collection <collection_name> --doc-id <doc_id> --doc-name '<new_name>'
viking-cli --region <region> knowledge delete-doc --collection <collection_name> --doc-id <doc_id>

Knowledge content retrieval (perform semantic retrieval within an already created knowledge base):

viking-cli --region <region> knowledge search-knowledge   --collection <collection_name>   --query '<text_query>'   --limit 10
viking-cli --region <region> knowledge search-knowledge   --collection <collection_name>   --query '<text_query>'   --doc-filter '{"op":"must","field":"doc_id","conds":["tos_doc_id_123","tos_doc_id_456"]}'

Find matching knowledge bases (perform keyword fuzzy matching by knowledge base description, by default return 3 results):

viking-cli --region <region> knowledge search-collection   --query '<keyword>'
viking-cli --region <region> knowledge search-collection   --query '<keyword>'   --limit 5

Knowledge / Retrieval and Q&A of the knowledge service

Perform retrieval or Q&A on the knowledge service. Supports non-streaming and streaming output. Authentication uses APIKey: prioritize --api-key, otherwise read from ~/.viking/config ; after the first successful call, it will be written to the configuration file and can be reused directly thereafter.service-rid Similarly: prioritize --service-rid, otherwise read from the configuration file.

viking-cli --region <region> knowledge service-chat --api-key <api_key> --service-rid <service_rid> --content '列举 2025 Q1 财报里的三项亮点'

viking-cli --region <region> knowledge service-chat --service-rid <service_rid> --messages-file ./messages.json

viking-cli --region <region> --format text knowledge service-chat --service-rid <service_rid> --content '列举 2025 Q1 财报里的三项亮点' --stream true

viking-cli --format text knowledge service-chat --content "列举 2025 Q1 财报里的三项亮点" --stream true

viking-cli --region <region> knowledge service-chat --service-rid <service_rid> --content '列举 2025 Q1 财报里的三项亮点' --doc-filter '{"op":"must","field":"doc_id","conds":["tos_doc_id_123","tos_doc_id_456"]}'

messages.json Example:

[
  {"role": "user", "content": "列举 2025 Q1 财报里的三项亮点"}
]

Common issue diagnosis

unknown command: the user entered a subcommand not currently implemented by the CLI; guide them back to this skill's command tree.
missing --name / missing --query etc.: these are hard validations in the implementation; the fix is to supply the corresponding flag.
missing --collection: first confirm whether the corresponding product's setuphas been executed. If it has, the CLI will automatically read the default collection from the configuration file; if it has not, you need to explicitly supply --collection or prompt the user to executesetupcommand.
JSON parsing error: first check shell quotes; for complex JSON, prefer changing to --input-file、--messages-file、--metadata-file and other file inputs.
client not initialized or request initialization failed: usually viking-cli auth, or the configuration file is missing region / AK / SK.
Region-related request error: first explicitly add --region <region>, then use collection list or a similar lightweight command to verify whether the configuration takes effect.

About this skill

Goal

Trigger and decision

Install CLI

Working principles

Command tree

Global configuration

Interactive configuration (recommended)

Global Flags (command-line parameters)

JSON input strategy

Output conventions

Version and authentication configuration

VikingDB / Setup

VikingDB / Collection

VikingDB / Index

VikingDB / Data

Memory / Setup and Collection

Memory / Session and search

Knowledge / Setup and Collection

Knowledge / Documents and search

Knowledge / Retrieval and Q&A of the knowledge service

Common issue diagnosis