mxbai-cli

mxbai CLI

The mxbai CLI manages stores, uploads files, performs semantic search, and syncs directories with Mixedbread from the terminal.

Docs: https://www.mixedbread.com/cli.md Agent-readable docs: https://www.mixedbread.com/docs/llms.txt Latest docs search: https://www.mixedbread.com/question?q=cli&section=cli

Installation

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

Requires Node.js >= 20.0. Verify with mxbai --version.

Authentication

Resolved in priority order:

1. Flag: --api-key mxb_xxxxx or --saved-key <name>
2. Environment variable: export MXBAI_API_KEY=mxb_xxxxx
3. Config file: mxbai config set api_key mxb_xxxxx

Get your API key at https://platform.mixedbread.com/platform?next=api-keys

Quick Start

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

Decision Tree

• Upload vs Sync?
  • One-time or manual upload → mxbai store upload
  • Ongoing updates (especially CI/CD) → mxbai store sync
• Which change detection for sync?
  • In a git repo with known base commit → --from-git HEAD~1 (fastest)
  • Outside git or need exact comparison → hash-based detection (default, compares content hashes)
• CLI vs SDK?
  • Shell scripts, CI/CD, one-off tasks → CLI
  • Application code, custom logic, programmatic access → Python/TypeScript SDK

Workflows

CI/CD Documentation Sync

Sync documentation to a store on every push using the default hash-based change detection.

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