3步快速安装SearchCLI：AI搜索命令行工具的新手认证与环境检查教程

SearchCLI 是一款把 AI 搜索、推荐与对话检索能力接入 Agent 系统和业务系统的开源命令行工具。本文带你用 3 步完成 SearchCLI 的快速安装、AK/SK 认证配置和vs doctor环境检查，新手照着做即可跑通第一条 AI 搜索链路。

环境要求：安装前先看这4项

在执行任何命令之前，请确认本地环境满足以下要求：

💡 如果 Node.js 版本过低，安装脚本会直接报错Node.js 20 or newer is required，请先升级 Node.js 再重试。

第1步：一键安装 SearchCLI 并注册 vs 命令

打开真实终端，执行以下命令克隆仓库并运行官方安装脚本：

git clone https://gitcode.com/gh_mirrors/se/SearchCLI vs cd vs bash ./scripts/install.sh

install.sh 会自动完成以下工作，无需手动干预：

1. 校验 Node.js 版本是否 ≥ 20；
2. npm install安装项目依赖；
3. 校验内置的 Viking skills 并构建产物；
4. 通过npm install --global .把vs注册为全局命令。

安装完成后，用帮助命令做一次自检：

vs --help

看到命令树列表即代表安装成功。如果提示command not found: vs，执行npm config get prefix，把返回路径下的bin目录加入PATH后重新打开终端即可。

第2步：新手认证——两种方式导入或登录 AK/SK

认证决定了vs用哪套凭据访问火山引擎 AI Search 服务。相关逻辑实现在 src/commands/auth/ 目录下。

方式 A：环境已有 VIKING_AK / VIKING_SK，直接导入

如果当前 shell 已经导出了VIKING_AK和VIKING_SK环境变量，一条命令即可导入（源码见 import-env.ts）：

vs auth import-env

方式 B：交互式登录（推荐新手）

在真实终端中执行，按提示输入 AK 和 SK：

vs auth login

源码见 login.ts。

非默认环境如何配置？

SearchCLI 目前内置 3 个固定环境，默认为「火山公有云 · 北京」，可省略所有环境参数：

如果你在后两个环境中使用，请在登录时追加参数：

vs auth login --control-plane-base-url <控制面地址> --data-plane-base-url <数据面地址> --region <REGION>

各环境的完整地址对照表参考官方安装引导文档 docs/install-guide.md。

🔐 安全提示：AK/SK 会存入本地凭据存储，请勿把密钥明文写进配置文件，更不要发到任何聊天窗口中。

可选：配置 LLM API 用于搜索调优

如果你后续要用vs search tune的查询生成或 LLM 相关性评测，建议顺手完成 LLM 登录（详见 llm/login.ts）：

vs llm login vs llm status --json

第3步：用 vs doctor 做环境检查

认证完成后，按顺序执行三条验证命令，确认环境就绪：

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

vs doctor是内置的环境体检命令，会一次性检查本地配置、认证状态和常见依赖（实现见 doctor.ts）。默认环境下，vs auth status --json应返回类似结构：

{ "activeProfile": "default", "profiles": { "default": { "region": "cn-beijing", "environmentId": "volc-cn-beijing", "service": "aisearch" } } }

环境检查失败怎么办？

小结：3步跑通 SearchCLI 安装认证

回顾一下本教程的完整路径：

1. 安装：git clone+bash ./scripts/install.sh，注册全局vs命令；
2. 认证：vs auth import-env或vs auth login导入火山引擎 AK/SK；
3. 体检：vs auth status --json+vs doctor --json双重确认环境就绪。

完成后，你就可以用vs item profile、vs search run、vs chat run等命令开始构建自己的 AI 搜索与推荐工作流了。更多命令说明见 docs/COMMANDS.md 与 docs/agent-quick-start.md。