// Use the mxbai CLI to manage stores, upload files, search documents, ask questions, and sync directories from the terminal. Use when performing Mixedbread operations via command line, setting up CI/CD pipelines with store sync, or managing API keys.
| name | mxbai-cli |
| description | Use the mxbai CLI to manage stores, upload files, search documents, ask questions, and sync directories from the terminal. Use when performing Mixedbread operations via command line, setting up CI/CD pipelines with store sync, or managing API keys. |
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§ion=cli
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.
Resolved in priority order:
--api-key mxb_xxxxx or --saved-key <name>export MXBAI_API_KEY=mxb_xxxxxmxbai config set api_key mxb_xxxxxGet your API key at 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/**"
mxbai store uploadmxbai store sync--from-git HEAD~1 (fastest)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
For faster change detection in git repos, add --from-git HEAD~1 (requires fetch-depth: 2) or --from-git origin/main (requires fetch-depth: 0).
Key points:
--yes — CI environments are non-interactive and commands hang without it--from-git for faster change detection in git reposMXBAI_API_KEY--dry-run in a separate step to preview changes before applyingPreview before syncing:
mxbai store sync "my-docs" "docs/**" --dry-run
Manage separate API keys for staging and production.
# 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
Use a manifest file for complex uploads with per-file metadata and strategy overrides.
# 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
Create short aliases for frequently used stores:
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"
--yes in CI/CD. Without it, sync and delete commands hang waiting for interactive confirmation that never comes. CI environments don't have a TTY.--contextualization on upload/sync is deprecated since v2.2.0. Configure contextualization at store creation with mxbai store create --contextualization. The flag on upload/sync shows a warning and is ignored.--parallel max is 200. The CLI validates and rejects values above 200. Default is 100.--force sync re-uploads everything. It bypasses change detection entirely. Use sparingly — typically only for periodic full re-syncs (e.g., weekly cron).--dry-run before first sync. Preview what would be uploaded, changed, or deleted before committing.--unique on upload to skip duplicates. Prevents re-uploading files that already exist (based on content hash).| Symptom | Cause | Fix |
|---|---|---|
| "Command not found" | Node.js < 20 or not globally installed | Verify Node.js >= 20. Try npx mxbai for project-local installs. |
| "No API key" | No key configured | Run mxbai config keys add <key> or set MXBAI_API_KEY env var. |
| Sync hangs in CI | Missing --yes flag | Pass --yes for non-interactive mode. |
| Upload timeout for large files | Default multipart settings insufficient | Tune --multipart-threshold, --multipart-part-size, --multipart-concurrency. |
| Store not found | Wrong name or alias | Check aliases with mxbai config get aliases. Verify name uses valid characters. |
| Contextualization warning | Deprecated flag on upload/sync | Set contextualization at store creation instead. |
| Sync detects no changes | Hash-based detection with modified metadata only | Use --force to re-upload, or --from-git to detect changes via git. |
--from-git misses files | fetch-depth too shallow in CI | Set fetch-depth: 0 for full history, or fetch-depth: 2 minimum for HEAD~1. |
Build and query managed search indexes (Stores) using the Mixedbread Python and TypeScript SDKs. Use when creating knowledge bases, uploading documents, performing semantic or vector search, asking questions over documents, using agentic multi-step retrieval, combining store search with web results, filtering by metadata, reranking, or discovering metadata facets.
Parse documents, extract structured content, and run OCR using the Mixedbread Parsing API. Use when parsing PDFs, Word documents, PowerPoint slides, or images, extracting tables or form fields, running OCR on scanned documents, converting documents to markdown or HTML, or extracting structured chunks with element-level bounding boxes and confidence scores.