Mixedbread

Introduction

Overview

The mxbai CLI is a comprehensive tool for managing vector stores, uploading documents, and performing AI-powered search and question-answering operations. Built on top of the Mixedbread SDK, it provides an efficient command-line interface for all core platform features.

Key Features

Quick Start

1. Install the CLI

npm install -g @mixedbread/cli

2. Set your API key

# Option 1: Environment variable
export MXBAI_API_KEY=mxb_xxxxx

# Option 2: Config file (persistent)
mxbai config keys add mxb_xxxxx
mxbai completion install

4. Create a vector store

mxbai vs create "My Documents"

5. Upload files

# Basic upload
mxbai vs upload "My Documents" "*.md" "docs/**/*.pdf"

# Upload with high-quality processing and contextualization
mxbai vs upload "My Documents" "**/*.md" --strategy high_quality --contextualization

6. Search your content

mxbai vs search "My Documents" "how to get started"

Command Structure

The mxbai CLI is organized around vector store operations using the vs subcommand:

Configuration Management

  • mxbai config set <key> <value> - Set configuration values
  • mxbai config get [key] - Get configuration values
  • mxbai config keys add <key> [name] - Add a new API key
  • mxbai config keys list - List all API keys
  • mxbai config keys remove <name> - Remove an API key
  • mxbai config keys set-default <name> - Set the default API key

Shell Completion

  • mxbai completion install - Install shell completion
  • mxbai completion uninstall - Uninstall shell completion
  • mxbai completion refresh - Refresh completion cache for vector store names

Vector Store Management

  • mxbai vs list - List all vector stores
  • mxbai vs create <name> - Create a new vector store
  • mxbai vs get <name-or-id> - Get vector store details
  • mxbai vs update <name-or-id> - Update vector store settings
  • mxbai vs delete <name-or-id> - Delete a vector store

File Operations

  • mxbai vs upload <name-or-id> <patterns...> - Upload files
  • mxbai vs files list <name-or-id> - List files in vector store
  • mxbai vs files get <name-or-id> <file-id> - Get file details
  • mxbai vs files delete <name-or-id> <file-id> - Delete a file

Search & Query

  • mxbai vs search <name-or-id> <query> - Search vector store
  • mxbai vs qa <name-or-id> <question> - Ask questions about content

Intelligent Sync

  • mxbai vs sync <name-or-id> <patterns...> - Intelligent sync with change detection

Global Options

All commands support these global options:

  • --api-key <key> - Actual API key for authentication
  • --saved-key <name> - Name of saved API key from config
  • --base-url <url> - Custom API base URL
  • --format <format> - Output format: table, json, or csv (default: table)
  • --debug - Enable debug output (equivalent to MXBAI_DEBUG=true)
  • --help - Show help information for commands

Environment Variables

The CLI supports the following environment variables:

  • MXBAI_API_KEY - API key for authentication (must start with mxb_)
  • MXBAI_DEBUG - Enable debug output (set to true or 1)
  • MXBAI_CONFIG_PATH - Override default config file location

Authentication

The CLI looks for your API key in this order:

  1. --api-key or --saved-key command line flags
  2. MXBAI_API_KEY environment variable
  3. Default API key from config file (platform-specific location):
    • Linux/Unix: ~/.config/mixedbread/config.json (or $XDG_CONFIG_HOME/mixedbread/config.json)
    • macOS: ~/Library/Application Support/mixedbread/config.json
    • Windows: %APPDATA%\mixedbread\config.json
    • Custom: Set MXBAI_CONFIG_PATH environment variable to override

Multi-Organization Support

The CLI supports multiple API keys for different organizations or environments:

# Add API keys with descriptive names
mxbai config keys add mxb_xxxxx work
mxbai config keys add mxb_xxxxx personal

# Use a specific saved API key for a command
mxbai vs upload "My Docs" "*.md" --saved-key work
mxbai vs search "Knowledge Base" "query" --saved-key personal

# Or use an actual API key directly
mxbai vs upload "My Docs" "*.md" --api-key mxb_xxxxx

# The last added key becomes default automatically
# Or explicitly set a default
mxbai config keys set-default personal

Getting Help

Use the --help flag to get detailed information about any command:

# General help
mxbai --help

# Help for vector store commands
mxbai vs --help

# Help for specific commands
mxbai vs create --help
mxbai vs upload --help
mxbai vs search --help
Installation & Setup
Install the mxbai CLI on your system and get started with Mixedbread's AI services.

Last updated: August 26, 2025