SearchCLI
A CLI for connecting Volcengine AI Search, recommendations, and conversational retrieval to production systems and agent workflows.
Per-dimension scores and reasoning
Evidence shows: README mentions dry-runs, confirmation points, read-after-write verification, and flags like `--confirm-review`, indicating user confirmation mechanisms. Sensitive data handling is addressed by stating API keys are stored in a local secure credential store, not in plaintext config. However, there is no explicit statement on least privilege, data flow transparency is limited, external effects (e.g., network calls) are not detailed, rollback mechanisms are not mentioned, and source attribution is only partially covered via contribution guidelines and CLA requirement. Deductions: insufficient evidence for least privilege, data flow transparency, external effects, rollback, and source attribution.
Evidence shows: Command names in README and package.json are consistent (e.g., `vs item`, `vs search`), indicating good internal consistency. However, dependency availability is not assured as dependencies like `@volcengine/openapi` are not pinned or checksummed, and failure messages are not exemplified in documentation. Deductions: insufficient evidence for dependency availability and failure messages.
Evidence shows: README clearly identifies target audiences (developers, teams, operations) and use cases (search, recommendation, conversational retrieval). Capability boundaries are clear via command groups. Trigger precision is demonstrated through specific commands and parameters (e.g., `--type video`). Environment fit is addressed by requiring Node.js 20+ and git, and providing multiple installation methods. Deductions: environment fit lacks OS compatibility details, but overall evidence is sufficient.
Evidence shows: README provides clear information architecture with quick start, documentation links, and command group lists. Install notes are detailed, including clone, install script, and authentication steps. Naming stability is consistent between README and package.json, but no version history or changelog is provided. Examples and FAQ: README provides multiple example commands but lacks FAQ. Known limitations are not explicitly stated. License is Apache-2.0 with full LICENSE file. Versioning and changelog: package.json has version but no CHANGELOG. Maintenance responsibility is partially addressed via contribution guide and security policy, but maintainer info is not explicit. Deductions: insufficient evidence for naming stability, known limitations, versioning/changelog, and maintenance responsibility.
Evidence shows: README describes output formats (e.g., `--json` flag) and automation-friendly command output, indicating good output usability. Marginal value is clear as the tool provides integration for search, recommendation, and conversational retrieval. Cost-benefit is not detailed, but as a CLI tool, cost is likely low. Deductions: insufficient evidence for cost-benefit.
Evidence shows: Claims in README (e.g., feature list) are not backed by specific implementation details or test evidence, but test scripts (e.g., `test:acceptance`) and documentation links exist. Cross-source corroboration is limited to consistency between README and package.json command names, but no external validation. Fact-inference separation is not explicit; README distinguishes features from installation steps but does not clearly separate facts from inferences. Deductions: insufficient evidence for claim traceability, cross-source corroboration, and fact-inference separation.
- Publisher identity is unverified; treat as unknown and do not infer safety from brand.
- Dependencies are not pinned or checksummed, posing supply chain risk.
- Security mechanisms mentioned in docs (e.g., credential store) are not verified in code; actual review needed.
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, andvs-searchso external agents can follow the reviewed onboarding workflow. - A video-content team needs to provision a video dataset and explicitly pass
--type videoduring 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
runverification commands. - Provides
vs search tunestages 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.jsoncan fail withMissingParameter.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 vs
cd vs
bash ./scripts/install.sh
vs auth import-env
vs auth status --json
vs doctor --jsonIf 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.
FAQ
Can it run a standalone search service without Volcengine?
What credentials and permissions are required?
vs auth import-env, or use vs auth login in a real terminal.Is LLM configuration required for every workflow?
How can a team review changes before they execute?
vs item apply --plan-dir <plan-dir> --dry-run first. Actual execution requires --confirm-review, and can include --wait-ready --run-trials for readiness and runtime checks.