用途
该技能用于在用户需要安装 zilliz-cli、登录 Zilliz Cloud、配置凭据或设置当前集群上下文时提供指导。它也是其他技能执行数据面命令前的前置准备环节。
前置检查
在运行任何 zilliz-cli 命令前，需按顺序验证以下内容：
- CLI 是否已安装且为最新版本？运行
curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash以确保安装最新版本。 - 是否已登录？运行
zilliz auth status。若未登录，引导用户完成登录。 - 是否已设置上下文？（仅数据面操作需要）运行
zilliz context current。若无上下文，引导用户完成上下文设置。
主要能力
安装 / 升级 CLI
curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash
验证安装：
zilliz --version
认证
重要：登录命令（zilliz login、zilliz configure）需要交互式终端，不能在 Claude Code 内运行。应始终指示用户在自己的终端中运行这些命令。
检查是否已登录：
zilliz auth status
若未登录，告知用户打开自己的终端并运行以下选项之一：
选项 1：基于浏览器的登录（OAuth）——完整功能访问
zilliz login
- 打开浏览器进行认证
- 获取用户信息、组织数据和 API 密钥
- 在无头环境中使用
--no-browser（显示一个可手动访问的 URL）
选项 2a：通过 login 命令使用 API Key
zilliz login --api-key
选项 2b：通过 configure 使用 API Key（旧版）
zilliz configure
提示输入 API key（可在 Zilliz Cloud 控制台的 API Keys 下找到）。
与 OAuth 登录相比的限制：
- 无法切换组织
- 在 Serverless 集群上：数据库管理、用户/角色管理可能受限
- 某些控制面操作可能需要 OAuth 登录
选项 3：环境变量
用户可将其添加到 shell 配置文件（.zshrc / .bashrc）：
export ZILLIZ_API_KEY=<your-api-key>
用户完成认证后，运行以下命令验证：
zilliz auth status
Configure 子命令
zilliz configure # 交互式 API key 设置
zilliz configure list # 显示所有配置值
zilliz configure set <key> <value> # 设置配置值
zilliz configure get <key> # 获取配置值
zilliz configure clear # 清除所有凭据
切换组织
这些命令需要交互式终端。指示用户在自己的终端中运行：
# 交互式选择
zilliz auth switch
# 按组织 ID 直接切换
zilliz auth switch <org-id>
登出
zilliz logout
设置集群上下文
数据面命令（collection、vector、index 等）需要活动的集群上下文。
# 按集群 ID 设置（端点自动解析）
zilliz context set --cluster-id <cluster-id>
# 使用显式端点设置
zilliz context set --cluster-id <cluster-id> --endpoint <url>
# 更改数据库（默认："default"）
zilliz context set --database <db-name>
查看当前上下文
zilliz context current
输出格式
所有 zilliz-cli 命令都支持 --output json 以输出结构化、机器可读的结果。在需要以编程方式解析结果时使用：
zilliz cluster list --output json
zilliz collection describe --name <name> --output json
可用格式：json、table、text。默认为 text。
集群类型差异
不同集群类型支持的功能不同：
| 功能 | Free | Serverless | Dedicated |
|---|---|---|---|
| Collection CRUD | 是 | 是 | 是 |
| 向量搜索/查询 | 是 | 是 | 是 |
| 数据库创建/删除 | 否 | 否 | 是 |
| 用户/角色管理 | 否 | 有限 | 是 |
| 备份管理 | 否 | 是 | 是 |
| 集群修改 | 否 | 否 | 是 |
当命令因权限错误失败时，先检查集群类型——该功能可能在该集群类型上不可用。
故障排查
- 安装后出现 "command not found"：检查安装目录（例如 ~/.local/bin）是否在 PATH 中。尝试重新运行安装脚本：
curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash。 - "not authenticated" 错误：运行
zilliz auth status检查登录状态。令牌可能已过期——在自己的终端中重新运行登录。 - 上下文错误（未设置集群）：运行
zilliz context current验证。若集群已被删除或暂停，使用zilliz context set --cluster-id <id>设置新上下文。 - 权限或 "not supported" 错误：检查集群类型——某些操作仅在 Dedicated 集群上可用（见上方集群类型差异表）。
- 网络或超时错误：使用
zilliz cluster describe --cluster-id <id>验证集群处于 RUNNING 状态。已暂停的集群会拒绝数据面请求。
指导原则
- 在执行任何命令前始终检查前置条件。
- 若前置条件失败，先修复再继续——不要跳过。
- 绝不要在 Claude Code 内运行
zilliz login、zilliz configure或zilliz auth switch（不带参数）——它们需要交互式输入。始终指示用户在自己的终端中运行这些命令。 - 绝不要要求用户将 API 密钥粘贴到聊天中——这是安全风险。引导他们在自己的终端中配置凭据。
- 用户报告登录完成后，使用
zilliz auth status验证。 - 设置上下文后，使用
zilliz context current验证。 - 对于其他技能中的数据面命令，始终先验证上下文已设置。
- 当命令意外失败时，考虑集群类型或认证模式是否可能是原因。