searchcli-volcengine-ai-search
CLI for integrating Volcengine AI Search, recommendation, and conversational retrieval into agent and business systems
How do I install this agent skill?
npx skills add https://github.com/reason-machines/devtools-skills --skill searchcli-volcengine-ai-searchIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill integrates Volcengine AI Search and includes code examples that demonstrate executing shell commands via string interpolation, which is a pattern vulnerable to command injection. It also processes external data files that are used in LLM-based tuning workflows, creating a surface for indirect prompt injection.
- Socketwarn
1 alert: gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
SearchCLI (Volcengine AI Search)
Skill by ara.so — Devtools Skills collection.
SearchCLI is the open-source CLI for Volcengine AI Search. It provides stable, tunable search, recommendation, and conversational retrieval capabilities for agent systems and business applications. Built with TypeScript, it offers agent-friendly workflows with installable skills, dry-runs, confirmation gates, and automated quality tuning.
What It Does
- Item & Catalog Search: Build search on structured business data
- Recommendation Flows: Connect recommendations to application scenes and user behavior
- Conversational Retrieval: Create RAG-style chat experiences grounded in application search
- Agent Workflows: Onboard data, configure applications, and validate behavior with reviewable steps
- Automated Tuning: Text-similarity evaluation and query tuning with LLM-based relevance judging
Installation
Requirements
- Node.js 20 or newer
- Git
- Volcengine AK/SK with AI Search access
Install SearchCLI
git clone git@github.com:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh
Install as Agent Skills (for AI Agents)
npx skills add "git@github.com:volcengine/SearchCLI.git" -y -g
This installs bundled skills:
vs-sharedvs-item-onboardingvs-searchvs-search-tuningvs-chatvs-recommend
Authentication
Using Environment Variables
If VIKING_AK and VIKING_SK are already in your environment:
vs auth import-env
vs auth status --json
Interactive Login
vs auth login
vs auth status --json
vs doctor --json
LLM Configuration (for Search Tuning)
For query generation and LLM-based relevance judging:
# Interactive setup
vs llm login
vs llm status --json
# Or import from environment
# Requires: VIKING_LLM_BASE_URL, VIKING_LLM_API_KEY, VIKING_LLM_MODEL
vs llm import-env
vs llm status --json
Verify LLM connectivity:
vs search tune llm-check --live --json
Core Command Groups
Authentication & Setup
vs auth login # Interactive authentication
vs auth import-env # Import AK/SK from environment
vs auth status --json # Check auth status
vs llm login # Configure LLM for tuning
vs llm import-env # Import LLM config from env
vs doctor --json # System health check
Item Onboarding
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
Dataset Management
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <id> --fields @<file>
vs dataset list --json
vs dataset describe --dataset-id <id> --json
Application Management
vs app list --json
vs app describe --app-id <id> --json
vs app create --data @app-config.json
vs app update --app-id <id> --data @update.json
Search Operations
vs search run --app-id <id> --query "search term" --json
vs search tune query-generate --dataset-id <id> --output ./queries.json
vs search tune plan --queries @queries.json --dataset-id <id>
vs search tune run --plan-dir ./plan --output ./results.json
vs search tune report --results @results.json --pretty
Recommendation
vs recommend run --app-id <id> --user-id <uid> --json
Conversational Retrieval
vs chat run --app-id <id> --query "What are the best products?" --json
Workflows
Dataset + App Provisioning (Full Onboarding)
Complete workflow for creating both dataset and search application:
# 1. Profile your data
vs item profile --file ./items.json --pretty
# 2. Generate provisioning plan
vs item plan --file ./items.json --goal "Build product search"
# 3. Review plan with dry-run
vs item apply --plan-dir ./.viking/item-plans/<plan-id> --dry-run
# 4. Execute with confirmations and runtime verification
vs item apply \
--plan-dir ./.viking/item-plans/<plan-id> \
--confirm-review \
--wait-ready \
--run-trials
Dataset-Only Provisioning
When you only need data ingestion without application setup:
# Generate dataset-only plan
vs item plan --file ./items.json --goal "Ingest product data" --skip-app
# Create dataset
vs dataset create --data @dataset-create.json
# Ingest data
vs dataset ingest --dataset-id <dataset-id> --fields @<normalized-items-artifact>
The --skip-app flag works with vs item provision and vs item apply as a guardrail.
Video Dataset Provisioning
Always specify --type video explicitly for video datasets:
# 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> --confirm-review --wait-ready
# Dataset-only
vs item plan --file ./videos.jsonl --type video --goal "Video data" --skip-app
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <id> --fields @<artifact>
Important: For video datasets, prefer dataset-create.json over --schema @schema.json to include DataFieldConfig and avoid MissingParameter.DefaultFieldStrategy errors.
Search Quality Tuning
Automated evaluation and tuning workflow:
# 1. Generate evaluation queries
vs search tune query-generate \
--dataset-id <dataset-id> \
--output ./eval-queries.json
# 2. Create tuning plan
vs search tune plan \
--queries @eval-queries.json \
--dataset-id <dataset-id>
# 3. Run evaluation
vs search tune run \
--plan-dir ./.viking/search-tune-plans/<plan-id> \
--output ./results.json
# 4. Generate report
vs search tune report \
--results @results.json \
--pretty
Code Examples
TypeScript: Item Data Structure
// items.json - Product catalog
[
{
"id": "prod-001",
"name": "Wireless Headphones",
"description": "High-quality Bluetooth headphones with noise cancellation",
"category": "Electronics",
"price": 149.99,
"tags": ["audio", "bluetooth", "noise-canceling"],
"in_stock": true
},
{
"id": "prod-002",
"name": "Smart Watch",
"description": "Fitness tracking smartwatch with heart rate monitor",
"category": "Wearables",
"price": 299.99,
"tags": ["fitness", "health", "smartwatch"],
"in_stock": true
}
]
TypeScript: Dataset Create Payload
// dataset-create.json
{
"Name": "product-catalog-v1",
"Type": "item",
"Schema": {
"Fields": [
{
"FieldName": "id",
"FieldType": "String",
"IsPrimaryKey": true
},
{
"FieldName": "name",
"FieldType": "String"
},
{
"FieldName": "description",
"FieldType": "Text"
},
{
"FieldName": "price",
"FieldType": "Float"
},
{
"FieldName": "tags",
"FieldType": "List<String>"
}
]
},
"DataFieldConfig": {
"DefaultFields": {
"Title": "name",
"Body": "description"
}
}
}
TypeScript: Search Application Config
// app-config.json
{
"Name": "product-search-app",
"DatasetId": "<dataset-id>",
"SearchConfig": {
"RankingStrategy": "TextSimilarity",
"TextSimilarityConfig": {
"Fields": ["name", "description"],
"Weights": {
"name": 2.0,
"description": 1.0
}
}
}
}
Bash: Complete Onboarding Script
#!/bin/bash
set -e
# Environment check
vs doctor --json
# 1. Profile and plan
vs item profile --file ./products.json --pretty
vs item plan --file ./products.json --goal "E-commerce product search"
# Get the latest plan directory
PLAN_DIR=$(ls -dt ./.viking/item-plans/* | head -1)
# 2. Review with dry-run
vs item apply --plan-dir "$PLAN_DIR" --dry-run
# 3. Execute provisioning
vs item apply \
--plan-dir "$PLAN_DIR" \
--confirm-review \
--wait-ready \
--run-trials
echo "Onboarding complete. Check ./.viking/item-plans/ for artifacts."
TypeScript: Programmatic Search
import { execSync } from 'child_process';
function runSearch(appId: string, query: string): any {
const result = execSync(
`vs search run --app-id ${appId} --query "${query}" --json`,
{ encoding: 'utf-8' }
);
return JSON.parse(result);
}
function runRecommendation(appId: string, userId: string): any {
const result = execSync(
`vs recommend run --app-id ${appId} --user-id ${userId} --json`,
{ encoding: 'utf-8' }
);
return JSON.parse(result);
}
// Usage
const searchResults = runSearch('app-123', 'wireless headphones');
console.log('Search results:', searchResults);
const recommendations = runRecommendation('app-123', 'user-456');
console.log('Recommendations:', recommendations);
TypeScript: Evaluation Query Generation
// eval-queries.json structure
[
{
"query": "wireless bluetooth headphones",
"expectedRelevance": {
"prod-001": "high",
"prod-003": "medium"
}
},
{
"query": "fitness tracking watch",
"expectedRelevance": {
"prod-002": "high"
}
}
]
Configuration
Environment Variables
# Required for authentication
export VIKING_AK="your-access-key"
export VIKING_SK="your-secret-key"
# Optional: LLM for search tuning
export VIKING_LLM_BASE_URL="https://api.openai.com/v1"
export VIKING_LLM_API_KEY="sk-..."
export VIKING_LLM_MODEL="gpt-4"
# Then import
vs auth import-env
vs llm import-env
Credential Storage
SearchCLI stores credentials securely:
- API Keys: Local secure credential store (not plain text config)
- LLM Base URL & Model: Stored as non-secret config
- Plan Artifacts:
./.viking/directory (safe to version control after removing sensitive data)
Output Formats
Most commands support --json for machine-readable output:
vs auth status --json
vs dataset list --json
vs search run --app-id <id> --query "test" --json
Use --pretty for human-readable formatting:
vs item profile --file ./items.json --pretty
vs search tune report --results @results.json --pretty
Common Patterns
Incremental Data Updates
# Update existing dataset
vs dataset ingest --dataset-id <id> --fields @new-items.json --mode append
# Replace all data
vs dataset ingest --dataset-id <id> --fields @all-items.json --mode replace
Multi-Stage Verification
# Always use dry-run first
vs item apply --plan-dir <plan> --dry-run
# Then execute with confirmations
vs item apply --plan-dir <plan> --confirm-review
# Add runtime trials for end-to-end verification
vs item apply --plan-dir <plan> --confirm-review --run-trials
Search Result Validation
# Run search and save results
vs search run \
--app-id <app-id> \
--query "test query" \
--json > search-results.json
# Use in scripts for validation
jq '.Results | length' search-results.json
Skill-Based Agent Integration
// Agent can invoke skills directly
await agent.useSkill('vs-item-onboarding', {
file: './products.json',
goal: 'Build product search',
skipApp: false
});
await agent.useSkill('vs-search', {
appId: 'app-123',
query: 'wireless headphones'
});
Troubleshooting
Authentication Failures
# Check current auth status
vs auth status --json
# Re-authenticate
vs auth login
# Verify credentials are set
echo $VIKING_AK
echo $VIKING_SK
# Full diagnostic
vs doctor --json
Dataset Creation Errors
Error: MissingParameter.DefaultFieldStrategy (common with video datasets)
# ❌ Don't use schema-only for video datasets
vs dataset create --name video-data --type video --schema @schema.json
# ✅ Use full create payload with DataFieldConfig
vs dataset create --data @dataset-create.json
Solution: Always use dataset-create.json from the plan artifact, which includes both Schema and DataFieldConfig.
Item Ingestion Issues
# Verify dataset exists and is ready
vs dataset describe --dataset-id <id> --json
# Check item data format
vs item profile --file ./items.json --pretty
# Use normalized artifact from plan
vs dataset ingest --dataset-id <id> --fields @<normalized-artifact>
LLM Connectivity Issues
# Check LLM configuration
vs llm status --json
# Test LLM connection
vs search tune llm-check --live --json
# Reconfigure if needed
vs llm login
Plan Execution Failures
# Always start with dry-run
vs item apply --plan-dir <plan> --dry-run
# Check plan artifacts
ls -la ./.viking/item-plans/<plan>/
# Review plan.json for details
cat ./.viking/item-plans/<plan>/plan.json | jq .
Search Tuning Not Working
# Verify LLM is configured
vs llm status --json
vs search tune llm-check --live --json
# Regenerate queries if format is wrong
vs search tune query-generate --dataset-id <id> --output ./new-queries.json
# Check plan directory structure
ls -la ./.viking/search-tune-plans/<plan>/
Permission Errors
# Verify AK/SK has correct permissions
vs doctor --json
# Check specific resource access
vs dataset list --json
vs app list --json
Agent Skill Installation
# List installed skills
vs skill list
# Reinstall all skills
vs skill install all
# Validate skill definitions
vs skill validate
Best Practices
- Always use dry-run first:
--dry-runshows what will happen without executing - Use confirmation gates:
--confirm-reviewadds human review step for critical operations - Prefer dataset-create.json: Especially for video datasets, use full payloads over schema-only
- Store credentials securely: Never commit AK/SK to version control; use environment variables
- Version control plans: The
.viking/directory contains reproducible plans (clean sensitive data first) - Use JSON output for automation:
--jsonflag provides machine-readable output - Validate with runtime trials:
--run-trialsensures end-to-end functionality - Type video datasets explicitly: Always pass
--type videofor video data
Related Resources
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/devtools-skills/searchcli-volcengine-ai-search">View searchcli-volcengine-ai-search on skillZs</a>