Introduction

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.

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

3. Install shell completion (optional but recommended)

mxbai completion install

4. Create a store

mxbai store create "my-knowledge-base"

5. Upload files

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

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

6. 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