SearchCLI: a Volcengine CLI that wraps AI Search for agents and business systems

The integration gap SearchCLI is trying to close

Most teams that want search or recommendations inside an agent do not want to write a retrieval stack. They want to point at their own records, get a working index, and then tune it. The README frames the problem as "stable, tunable information distribution services" and positions SearchCLI as "the command-line integration surface for AI Search on Volcengine". That phrasing matters: this is a client for a hosted service, not the service itself. The repository is TypeScript, licensed Apache-2.0, and exposes a single binary named `vs`. The stated audience is developers integrating AI-powered information distribution into business systems, teams building agent systems, and operators who need a reviewable way to onboard data and verify runtime behaviour before production. The last group is the interesting one. SearchCLI is explicitly built for the person who has to prove that an index was created correctly and that a query returns what it should, rather than for someone who just wants a one-line SDK call.

How the vs command groups map to a retrieval pipeline

The public command groups listed in the README are `vs auth`, `vs llm`, `vs doctor`, `vs skill`, `vs item`, `vs app`, `vs dataset`, `vs data`, `vs search`, `vs chat` and `vs recommend`. Read them as a pipeline rather than a flat list. `vs dataset` and `vs data` handle ingestion and schema. `vs app` binds a dataset to an application. `vs search run`, `vs recommend run` and `vs chat run` are the runtime verification surface, which is why they are described as being for runtime verification rather than for production traffic. `vs search tune` is a separate loop with four subcommands: `query-generate`, `plan`, `run` and `report`. The README calls this "first-version automated text-similarity evaluation and tuning", and the word "first-version" is doing real work. It tells you the tuning path is young and that you should expect to read the output yourself rather than trust a score. The `vs skill` group is the agent-facing layer: installable Viking skills that let an external agent drive the same workflows a human would type.

Getting from a JSONL file to a running app

The README's onboarding example is the clearest statement of the intended data flow. You start with `vs dataset import-url --file-name items.jsonl`, which returns a `FileUrl`; you then upload the file yourself with `curl -X PUT --data-binary "@./items.jsonl" "<FileUrl from previous step>"`. SearchCLI does not perform the upload, it hands you a URL. Next comes `vs dataset infer-schema --tos-key <FileKey> --type multi_modal --theme e_commerce --language zh --name <dataset-name>`, followed by `vs dataset infer-result --task-id <TaskID> --render-schema`. Only then do you create the dataset with `vs dataset create --data @dataset-create.json`, write rows with `vs data write --dataset-id <DatasetId> --fields @items.jsonl`, create the app with `vs app create --name <app-name> --industry e_commerce --language zh`, and attach the dataset with `vs app attach-dataset --data @attach.json`. Two details stand out. The schema is inferred by a backend task, not declared by you, which is why there is an `infer-schema` and a separate `infer-result` step to poll. And the README notes that for user-event datasets you use `--type user_event` and omit `--theme`, so the type flag changes which parameters are valid.

Install, credentials and the LLM side channel

Installation is a clone plus a script: `git clone git@github.com:volcengine/SearchCLI.git vs`, `cd vs`, `bash ./scripts/install.sh`. The repository name is cloned to a directory called `vs`, which matches the binary name and is worth respecting, since the README's paths assume it. Requirements are Node.js 20 or newer, `git`, and Volcengine AK/SK with access to AI Search. Authentication has two paths. If `VIKING_AK` and `VIKING_SK` are already in the shell, `vs auth import-env` picks them up; otherwise `vs auth login` runs an interactive flow that the README says needs a real terminal. Search tuning query generation and LLM relevance judging need a second credential, an OpenAI-compatible LLM API, configured with `vs llm login`. The README is specific about how that key is handled: it goes into the local secure credential store, while base URL and model are stored as non-secret config. If `VIKING_LLM_BASE_URL`, `VIKING_LLM_API_KEY` and `VIKING_LLM_MODEL` are already set, `vs llm import-env` is the alternative. That separation of secret from non-secret config is a deliberate design choice and one of the more defensible parts of the tool.

The review gates: dry-runs, confirmation and read-after-write

The README describes "a reviewable execution model with dry-runs, confirmation gates, and read-after-write verification". This is the design decision that most distinguishes SearchCLI from a thin API wrapper, and it is also the one the README explains least. It does not enumerate which commands support `--dry-run`, what the confirmation prompt looks like, or which writes are followed by a read-back. What you can confirm is the shape of the workflow: the onboarding sequence is deliberately broken into small steps with identifiers passed between them (`FileUrl`, `FileKey`, `TaskID`, `DatasetId`), so each stage is inspectable before the next one runs. That is a real cost as well as a benefit. A pipeline that would be one SDK call becomes eight commands, and the operator has to carry four identifiers by hand. For a one-off migration that is fine. For a CI job that provisions indexes on every merge, it is friction you will end up scripting around.

Where SearchCLI is the wrong tool

The hard boundary is the backend. Every meaningful command targets Volcengine AI Search, and the README's requirements list Volcengine AK/SK with access to AI Search as a prerequisite, not an option. If your data cannot leave your infrastructure, or you need a retrieval layer you can self-host and swap out, SearchCLI does not help you, because there is nothing underneath it to run locally. A second limitation is the tuning surface. `vs search tune` is described as first-version and as text-similarity evaluation, which is a narrower claim than relevance tuning in general. Teams with an existing labelled evaluation set and their own ranking metrics should expect to keep that harness rather than replace it. Third, the LLM-dependent features are gated on an OpenAI-compatible endpoint. If your organisation has not approved one, query generation and LLM relevance judging are simply unavailable, and the rest of the tuning loop loses most of its value. Finally, the README gives no release history and no versioning scheme, so you cannot tell from the supplied material how stable the CLI surface is between updates.

How this differs from a generic RAG framework

The obvious comparison is a retrieval framework such as LangChain or LlamaIndex, and the difference is where the state lives. A framework like LlamaIndex runs in your process: you choose the embedding model, you own the vector store, you write the chunking and reranking logic, and the index is a file or a database you control. SearchCLI inverts that. The index, the application configuration and the retrieval strategy live in Volcengine, and the CLI is the control plane you drive them with. You get less control over ranking internals and you inherit the vendor's schema inference, but you also get recommendation and conversational retrieval as first-class command groups (`vs recommend run`, `vs chat run`) rather than as things you assemble from primitives. The honest framing is that these are not competitors. A framework is the right choice when retrieval quality is your product. SearchCLI is the right choice when retrieval is a feature of someone else's product and you want it configured and verified quickly.

Skills, licence and the cost of keeping up

The agent integration path is a single command: `npx skills add "git@github.com:volcengine/SearchCLI.git" -y -g`, which installs the default bundle of `vs-shared`, `vs-item-onboarding`, `vs-search`, `vs-search-tuning`, `vs-chat` and `vs-recommend`. Maintainers get a separate toolchain (`vs skill init viking-demo-skill`, `vs skill validate`, `vs skill install all`) and a build-and-check sequence of `npm install`, `npm run validate:skills`, `npm run build`, `npm run test:acceptance:dist`. That acceptance step runs against `dist`, so it validates the built artifact rather than the sources. On licence, Apache-2.0 permits commercial use and modification and includes a patent grant, but it also requires that you preserve copyright and licence notices in redistributed copies. The README also states that external contributors must sign a Contributor License Agreement before a pull request is accepted, so this is a project that expects contributions to come with paperwork. On maintenance cost, the honest assessment from the material available is that SearchCLI is a client, so its upgrade burden is tied to the Volcengine API surface rather than to a dependency graph you control, and the absence of published releases means you should pin a commit rather than track `main`.

Editorial conclusion

Adopt SearchCLI if you already hold Volcengine AK/SK with AI Search access and want a scriptable, reviewable path from a JSONL file to a running search or recommendation app. Skip it if you need a self-hosted or vendor-neutral retrieval stack, because every command depends on the Volcengine control plane. Verify first that `vs doctor --json` and `vs auth status --json` both return clean, and that the `--type multi_modal` schema inference path accepts your data shape.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. volcengine/SearchCLI on GitHub