mxbai-cli

mxbai CLI

mxbai CLI では、ターミナルからストアの管理、ファイルのアップロード、セマンティック検索、ディレクトリとMixedbreadの同期を行えます。

ドキュメント：https://www.mixedbread.com/cli.md エージェント向けドキュメント：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

API キーは https://platform.mixedbread.com/platform?next=api-keys で取得してください。

クイックスタート

# 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/**"

選択ガイド

• アップロードと同期のどちらを選ぶか？
  • 1回限り、または手動でのアップロード → mxbai store upload
  • 継続的な更新（特にCI/CD） → mxbai store sync
• 同期の変更検出方法は？
  • 既知のベースコミットがあるGitリポジトリ内 → --from-git HEAD~1（最速）
  • Gitの外部、または正確な比較が必要 → ハッシュベースの検出（デフォルト。コンテンツハッシュを比較）
• CLIとSDKのどちらを選ぶか？
  • シェルスクリプト、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 を使用するか、git 経由で変更を検出するには --from-git を使用してください。
--from-git でファイルが検出されない	CI での fetch-depth が浅すぎます	全履歴を取得するには fetch-depth: 0 を設定してください。または、HEAD~1 に必要な最小値として fetch-depth: 2 を設定してください。