用途
mxbai CLI 用于从终端管理 Mixedbread 的文档存储（store）：创建存储、上传文件、执行语义搜索、提问以及同步目录。根据资料，它适合 Shell 脚本、CI/CD 和一次性任务；如果需要应用代码或自定义逻辑，则建议使用 Python/TypeScript SDK。
安装与要求
全局安装：
npm install -g @mixedbread/cli
项目本地安装：
npm install --save-dev @mixedbread/cli
本地安装后使用 npx mxbai。要求 Node.js >= 20.0，可用 mxbai --version 验证。
认证
API 密钥按以下优先级解析：
- 命令行参数：--api-key mxb_xxxxx 或 --saved-key <name>
- 环境变量：export MXBAI_API_KEY=mxb_xxxxx
- 配置文件：mxbai config set api_key mxb_xxxxx
API 密钥获取地址：https://platform.mixedbread.com/platform?next=api-keys
主要能力与使用方式
快速开始示例：
# 创建存储并上传文档
mxbai store create "my-docs" --description "Product documentation"
mxbai store upload "my-docs" "docs/**/*.md"
# 搜索
mxbai store search "my-docs" "How does authentication work?"
# 同步变更文件（默认基于哈希检测）
mxbai store sync "my-docs" "docs/**"
上传与同步的选择：一次性或手动上传用 mxbai store upload；持续更新（尤其 CI/CD）用 mxbai store sync。
同步的变更检测方式：在已知基线提交的 git 仓库中用 --from-git HEAD~1（最快）；在 git 之外或需要精确比较时用基于哈希的检测（默认，比较内容哈希）。
适用场景
-
CI/CD 文档同步：在每次 push 时把文档同步到存储，使用默认的哈希变更检测。GitHub Actions 示例：
name: Sync Documentation on: push: branches: [main] paths: - 'docs/**'
jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- name: Install mxbai CLI run: npm install -g @mixedbread/cli - name: Sync docs to store env: MXBAI_API_KEY: ${{ secrets.MXBAI_API_KEY }} run: | mxbai store sync my-docs "docs/**/*.md" \ --strategy high_quality \ --yes在 git 仓库中可加 --from-git HEAD~1（需 fetch-depth: 2）或 --from-git origin/main（需 fetch-depth: 0）以加快变更检测。要点：CI 中始终传 --yes；把 API 密钥存为 MXBAI_API_KEY secret；用 --dry-run 预览变更。预览示例：mxbai store sync "my-docs" "docs/**" --dry-run
-
多环境配置：为 staging 和 production 管理独立 API 密钥。
mxbai config keys add mxb_xxxxx production mxbai config keys add mxb_xxxxx staging mxbai config keys set-default production mxbai store search staging-docs "query" --saved-key staging
-
使用清单上传：为复杂上传提供每文件元数据和策略覆盖。
upload-manifest.yaml
version: "1" defaults: strategy: fast metadata: team: engineering files: - path: docs/getting-started.md metadata: title: Getting Started Guide priority: high - path: docs/api-reference.md strategy: high_quality metadata: title: API Reference - path: reports/*.pdf metadata: category: reports
mxbai store upload "my-docs" --manifest upload-manifest.yaml
-
存储别名：为常用存储创建短别名。
mxbai config set aliases.docs "my-documentation-store" mxbai config set aliases.prod "str_abc123" mxbai store search docs "how to deploy" mxbai store upload prod "files/**/*.md"
规则与注意事项
关键：CI/CD 中始终传 --yes。否则 sync 和 delete 命令会等待交互式确认而挂起，因为 CI 环境没有 TTY。
--contextualization 在 upload/sync 上自 v2.2.0 起已弃用。应在创建存储时配置：mxbai store create --contextualization。在 upload/sync 上使用该标志会显示警告并被忽略。
重要：
- --parallel 最大为 200，CLI 会校验并拒绝超过 200 的值，默认 100。
- --force sync 会重新上传所有内容，绕过变更检测，应谨慎使用，通常只用于定期全量重同步（例如每周 cron）。
- 存储名称仅允许小写字母、数字、连字符和点号，无效名称会导致创建失败。
中等：
- 首次同步前使用 --dry-run 预览将上传、更改或删除的内容。
- 为常用存储使用别名，避免拼写错误和过长的存储名。
- 上传时用 --unique 跳过重复项，基于内容哈希避免重复上传已存在的文件。
故障排查
- "Command not found"：Node.js < 20 或未全局安装。验证 Node.js >= 20，项目本地安装可试 npx mxbai。
- "No API key"：未配置密钥。运行 mxbai config keys add <key> 或设置 MXBAI_API_KEY 环境变量。
- CI 中 sync 挂起：缺少 --yes 标志。传 --yes 进入非交互模式。
- 大文件上传超时：默认分片设置不足。调整 --multipart-threshold、--multipart-part-size、--multipart-concurrency。
- Store not found：名称或别名错误。用 mxbai config get aliases 检查别名，并确认名称字符有效。
- Contextualization warning：在 upload/sync 上使用了已弃用标志。应在创建存储时设置 contextualization。
- Sync 未检测到变更：仅修改了元数据且使用哈希检测。用 --force 重新上传，或用 --from-git 通过 git 检测变更。
- --from-git 漏掉文件：CI 中 fetch-depth 太浅。设为 fetch-depth: 0 获取完整历史，或至少为 HEAD~1 设置 fetch-depth: 2。
文档链接
- 文档：https://www.mixedbread.com/cli.md
- 供智能体阅读的文档：https://www.mixedbread.com/docs/llms.txt
- 最新文档搜索：https://www.mixedbread.com/question?q=cli§ion=cli