mxbai-cli

mxbai CLI

mxbai CLI 可在终端管理存储、上传文件、执行语义搜索，以及将目录与 Mixedbread 同步。

文档：https://www.mixedbread.com/cli.md 面向 Agent 的文档：https://www.mixedbread.com/docs/llms.txt 最新文档搜索：https://www.mixedbread.com/question?q=cli&section=cli

安装

npm install -g @mixedbread/cli    # global
npm install --save-dev @mixedbread/cli  # project-local (use npx mxbai)

需要 Node.js >= 20.0。使用 mxbai --version 验证。

身份验证

按以下优先级解析：

1. 标志： --api-key mxb_xxxxx 或 --saved-key <name>
2. 环境变量： export MXBAI_API_KEY=mxb_xxxxx
3. 配置文件： mxbai config set api_key mxb_xxxxx

请在 https://platform.mixedbread.com/platform?next=api-keys 获取 API 密钥。

快速开始

# Create a store and upload docs
mxbai store create "my-docs" --description "Product documentation"
mxbai store upload "my-docs" "docs/**/*.md"

# Search
mxbai store search "my-docs" "How does authentication work?"

# Sync changed files (hash-based detection by default)
mxbai store sync "my-docs" "docs/**"

决策树

• 上传还是同步？
  • 一次性或手动上传 → mxbai store upload
  • 持续更新（尤其是 CI/CD）→ mxbai store sync
• 同步时使用哪种变更检测方式？
  • 在已知基准提交的 Git 仓库中 → --from-git HEAD~1（最快）
  • 在 Git 仓库之外，或需要精确比较 → 基于哈希的检测（默认，会比较内容哈希）
• 使用 CLI 还是 SDK？
  • Shell 脚本、CI/CD、一次性任务 → CLI
  • 应用代码、自定义逻辑、程序化访问 → Python/TypeScript SDK

工作流

CI/CD 文档同步

每次推送时，使用默认的基于哈希的变更检测方式将文档同步到存储。

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）。

要点：

• 始终传入 --yes — CI 环境采用非交互模式，不传入此参数时命令会挂起
• 在 Git 仓库中使用 --from-git，以更快地检测变更
• 通过 MXBAI_API_KEY 将 API 密钥存储为机密
• 使用单独的步骤运行 --dry-run，在应用变更前预览

同步前预览：

mxbai store sync "my-docs" "docs/**" --dry-run

多环境设置

为预发布环境和生产环境分别管理 API 密钥。

# Add keys for different environments
mxbai config keys add mxb_xxxxx production
mxbai config keys add mxb_xxxxx staging

# Set production as default
mxbai config keys set-default production

# Use staging for a specific command
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"

# Use aliases in any command
mxbai store search docs "how to deploy"
mxbai store upload prod "files/**/*.md"

规则

关键

• 在 CI/CD 中始终传入 --yes。 否则，同步和删除命令会挂起，等待永远不会出现的交互式确认。CI 环境没有 TTY。
• --contextualization 在上传/同步时自 v2.2.0 起已弃用。 使用 mxbai store create --contextualization 在创建存储时配置上下文化。上传/同步命令中的此标志会显示警告并被忽略。

高

• --parallel 的最大值为 200。 CLI 会验证并拒绝大于 200 的值。默认值为 100。
• 同步时使用 --force 会重新上传所有内容。 它会完全绕过变更检测。请谨慎使用 — 通常仅用于定期全量重新同步（例如每周的 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 中同步挂起	缺少 --yes 标志	在非交互模式下传入 --yes。
上传大文件超时	默认分片上传设置不足	调整 --multipart-threshold、--multipart-part-size、--multipart-concurrency。
未找到存储	名称或别名错误	使用 mxbai config get aliases 检查别名。确认名称使用了有效字符。
上下文化处理警告	上传/同步时使用了已弃用的标志	改为在创建存储时设置上下文化处理。
同步未检测到更改	基于哈希的检测只发现元数据已修改	使用 --force 重新上传，或使用 --from-git 通过 git 检测更改。
--from-git 未检测到文件	CI 中的 fetch-depth 太浅	将 fetch-depth: 0 设置为完整历史记录，或至少将其设为 fetch-depth: 2 以包含 HEAD~1。