SearchCLI
A CLI for connecting Volcengine AI Search, recommendations, and conversational retrieval to production systems and agent workflows.
What does this agent do, and when should you use it?
SearchCLI is an open command-line integration surface for Volcengine AI Search. Its `vs item`, `vs dataset`, `vs app`, and `vs data` commands support dataset and application setup from structured business data. Runtime behavior can be checked through `vs search run`, `vs recommend run`, and `vs chat run`, while `vs search tune` supplies an initial text-similarity evaluation and tuning flow. The execution model includes dry runs, confirmation gates, and read-after-write verification, with item plans stored under `.viking/item-plans`. Installable Viking skills let external agents use the same onboarding and retrieval workflows.
SearchCLI reads JSON or JSONL item files, profiles them with vs item profile --file, and creates onboarding plans through vs item plan --file --goal. vs item apply --plan-dir can preview a plan with --dry-run, then execute it with --confirm-review --wait-ready --run-trials; dataset-only provisioning uses --skip-app, vs dataset create --data @dataset-create.json, and vs dataset ingest --dataset-id <dataset-id> --fields @<normalized-items-artifact>. vs dataset, vs app, and vs data manage the associated resources, while vs search run, vs recommend run, and vs chat run verify runtime flows. Search tuning runs through vs search tune query-generate | plan | run | report; optional query generation and LLM relevance judging are configured with vs llm login or vs llm import-env for an OpenAI-compatible LLM API.
- A commerce search team needs to onboard a structured product catalog to Volcengine AI Search and review the generated plan before application creation.
- A recommendation team needs to connect application scenes and user behavior to recommendation flows, then validate results with `vs recommend run`.
- A conversational-search team needs to test retrieval grounded in application search with `vs chat run`.
- An agent-system team wants to install public skills such as `vs-shared`, `vs-item-onboarding`, and `vs-search` so external agents can follow the reviewed onboarding workflow.
- A video-content team needs to provision a video dataset and explicitly pass `--type video` during profiling, planning, and application.
What are this agent's strengths and limitations?
- Combines profiling, planning, dry-run review, confirmed execution, and runtime verification in one CLI workflow.
- Covers structured-item search, recommendations, and conversational retrieval with dedicated `run` verification commands.
- Provides `vs search tune` stages for query generation, planning, execution, and reporting in an initial text-similarity tuning flow.
- Public Viking skills allow external agents to install and reuse the repository’s onboarding and retrieval workflows.
- Core operation depends on Volcengine AI Search and AK/SK authorized for that service, limiting provider portability.
- Adoption requires Node.js 20+, `git`, a usable shell, network access, and local credential storage.
- LLM query generation and relevance judging need separate configuration of an OpenAI-compatible API, and the API key must not be stored in plain configuration.
- Video datasets require an explicit `--type video`; schema-only creation using `--schema @schema.json` can fail with `MissingParameter.DefaultFieldStrategy`.
How do you install or deploy this agent?
Requirements are Node.js 20 or newer, git, and Volcengine AK/SK with access to AI Search. Install the CLI and import credentials already present in the shell:git clone [email protected]:volcengine/SearchCLI.git vscd vsbash ./scripts/install.shvs auth import-envvs auth status --jsonvs doctor --json
If VIKING_AK and VIKING_SK are not present, run vs auth login in a real terminal. External agents can install the public skill bundle with npx skills add "[email protected]:volcengine/SearchCLI.git" -y -g.
How do you use this agent?
For a new item-search application, run vs item profile --file ./items.json --pretty, then vs item plan --file ./items.json --goal "Build item search". Review the proposed execution with vs item apply --plan-dir ./.viking/item-plans/<plan> --dry-run, then apply and verify it with vs item apply --plan-dir ./.viking/item-plans/<plan> --confirm-review --wait-ready --run-trials. For dataset-only work, add --skip-app to the plan command, create from the emitted dataset-create.json with vs dataset create --data @dataset-create.json, and ingest fields with vs dataset ingest.