SearchCLI

English | 简体中文 | 日本語 | Deutsch | 한국어 | Français | Русский | Italiano | Español

Connect stable, tunable search, recommendation, and conversational retrieval to your agent system or business system.

Quick Start · AI Agent Setup · Full Agent Guide · Contributing · Security

SearchCLI is the open CLI for AI Search on Volcengine.

If your agent system or business system needs stable, tunable information distribution services, SearchCLI gives you a practical path to integrate production-grade search, recommendation, and conversational retrieval into real workflows.

With SearchCLI and its installable Viking skills, external agents can onboard data, build and validate search and recommendation flows, run conversational retrieval, tune strategy configuration, inspect bad cases, and iterate on retrieval quality in a stable, reviewable way.

What SearchCLI Is

• The command-line integration surface for AI Search on Volcengine.
• A stable path for external systems to access search, recommendation, and conversational retrieval capabilities.
• An agent-friendly workflow layer built around installable skills and automation-safe command output.
• A reviewable execution model with dry-runs, confirmation gates, and read-after-write verification.

Who It Is For

• Developers integrating AI-powered information distribution into business systems.
• Teams building agent systems that need stable, configurable search, recommendation, and retrieval workflows.
• Operators and solution teams who need a reviewable way to onboard data, configure applications, and verify runtime behavior before production use.

What It Enables

• Item and catalog search on top of structured business data.
• Recommendation flows connected to application scenes and user behavior.
• Conversational retrieval experiences grounded in application search.
• Agent workflows that can onboard data, configure applications, and validate runtime behavior with explicit review steps.

Core Capabilities

• vs item profile | plan | apply for structured item onboarding.
• vs app, vs dataset, and vs data for application and dataset management.
• vs search run, vs recommend run, and vs chat run for runtime verification.
• vs search tune query-generate | plan | run | report for first-version automated text-similarity evaluation and tuning.
• Installable Viking skills so external agents can use the same workflows.

Requirements

• Node.js 20 or newer
• git
• Volcengine AK/SK with access to AI Search

Quick Start (Human Users)

1. Install

git clone [email protected]:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh

2. Authenticate

If the current shell already has VIKING_AK and VIKING_SK:

vs auth import-env
vs auth status --json
vs doctor --json

Otherwise, run interactive login in a real terminal:

vs auth login

If you will use search tuning query generation or LLM relevance judging, configure an OpenAI-compatible LLM API without placing the API key in plain config:

vs llm login
vs llm status --json
vs search tune llm-check --live --json

If the current shell already has VIKING_LLM_BASE_URL, VIKING_LLM_API_KEY, and VIKING_LLM_MODEL, use vs llm import-env instead. The API key is stored in the local secure credential store; base URL and model are stored as non-secret config.

3. Run the First Onboarding Flow

If the user wants a new app plus bind-time config review and runtime verification, use the dataset+app path:

vs item profile --file ./items.json --pretty
vs item plan --file ./items.json --goal "Build item search"
vs item apply --plan-dir ./.viking/item-plans/<plan> --dry-run
vs item apply --plan-dir ./.viking/item-plans/<plan> --confirm-review --wait-ready --run-trials

If you only need dataset provisioning, use the dataset-only path, generate a dataset-only plan with --skip-app, and stop after dataset create + ingest:

vs item profile --file ./items.json --pretty
vs item plan --file ./items.json --goal "Build item search" --skip-app
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <dataset-id> --fields @<normalized-items-artifact>

Prefer dataset-create.json when the plan emitted it so dataset creation keeps Schema and DataFieldConfig together. The --name <dataset-name> --type item --schema @schema.json form remains the manual schema-only fallback when a full create payload is unavailable or unsuitable.

--skip-app is also accepted by vs item provision and vs item apply as an execution-time guard rail when you need to enforce the dataset-only boundary from an existing plan.

If you need a video dataset, do not rely on the default type. Always pass --type video explicitly:

For dataset+app:

vs item profile --file ./videos.jsonl --type video --pretty
vs item plan --file ./videos.jsonl --type video --goal "Build video search"
vs item apply --plan-dir ./.viking/item-plans/<plan> --dry-run
vs item apply --plan-dir ./.viking/item-plans/<plan> --confirm-review --wait-ready --run-trials

For dataset-only:

vs item profile --file ./videos.jsonl --type video --pretty
vs item plan --file ./videos.jsonl --type video --goal "Build video search" --skip-app
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <dataset-id> --fields @<normalized-items-artifact>

For video dataset-only provisioning, prefer dataset-create.json so the create request includes DataFieldConfig; --schema @schema.json alone can fail with MissingParameter.DefaultFieldStrategy.

Quick Start (AI Agents)

If an external agent needs to operate AI Search through this repository:

1. Install SearchCLI

git clone [email protected]:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh

2. Install Viking skills

npx skills add "[email protected]:volcengine/SearchCLI.git" -y -g

The default public skill bundle is:

• vs-shared
• vs-item-onboarding
• vs-search
• vs-search-tuning
• vs-chat
• vs-recommend

3. Authenticate

If the current shell already has VIKING_AK and VIKING_SK, prefer:

vs auth import-env

Otherwise:

vs auth login

4. Verify

vs --help
vs auth status --json
vs llm status --json
vs doctor --json
vs skill list

Public Command Groups

• vs auth
• vs llm
• vs doctor
• vs skill
• vs item
• vs app
• vs dataset
• vs data
• vs search
• vs chat
• vs recommend

Documentation

• Agent Quick Start
• Contributing
• Security

Maintainer Workflow

If you are maintaining the open-source repository itself, the local skill tooling is:

vs skill list
vs skill init viking-demo-skill
vs skill validate
vs skill install all

Build and run repository checks:

npm install
npm run validate:skills
npm run build
npm run test:acceptance:dist

Contribution

Please check Contributing for more details.

External contributors must complete the Contributor License Agreement (CLA) before a pull request can be accepted.

Code of Conduct

Please check Code of Conduct for more details.

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md

License

This project is licensed under the Apache-2.0 License.