Mixedbread

Introduction

The mxbai CLI provides a powerful command-line interface for managing Mixedbread stores and files directly from your terminal.

Overview

The mxbai CLI is a comprehensive tool for managing 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.

New to Mixedbread? Check out our API documentation to understand the underlying services that power the CLI.

Key Features

Store Management

Create, list, update, and manage your stores with comprehensive control.

File Upload & Processing

Upload files with intelligent processing strategies, metadata, and batch operations.

Semantic Search

Search through your stores using natural language queries with advanced filtering.

Question Answering

Ask questions and get AI-powered answers based on your store content.

Intelligent Sync

Sync files with Git-based change detection and intelligent processing strategies.

Shell Completion

Set up tab completion for commands and subcommands to improve your CLI experience.

Quick Start

Install the CLI

npm install -g @mixedbread/cli

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

Create a store

mxbai store create "my-knowledge-base"

Upload files

# Basic upload
mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf"

# Upload with high-quality processing
mxbai store upload "my-knowledge-base" "**/*.md" --strategy high_quality

Search your content

mxbai store search "my-knowledge-base" "how to get started"

Command Structure

The mxbai CLI is organized around store operations using the store 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 store names

Store Management

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

File Operations

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

Search & Query

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

Intelligent Sync

  • mxbai store 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_BASE_URL - Custom API base URL
  • 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 store upload "My Docs" "*.md" --saved-key work
mxbai store search "Knowledge Base" "query" --saved-key personal

# Or use an actual API key directly
mxbai store 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 store commands
mxbai store --help

# Help for specific commands
mxbai store create --help
mxbai store upload --help
mxbai store search --help

On this page

OverviewKey FeaturesQuick Start1Install the CLI2Set your API key3Install shell completion (optional but recommended)4Create a store5Upload files6Search your contentCommand StructureConfiguration ManagementShell CompletionStore ManagementFile OperationsSearch & QueryIntelligent SyncGlobal OptionsEnvironment VariablesAuthenticationMulti-Organization SupportGetting Help